زيادة مهلة Lambda: كيف تتجاوز حد الـ 3 ثوانٍ وتصل إلى الحد الأقصى

عندما تتوقف دالة Lambda فجأة بعد 3 ثوانٍ بينما المهمة تحتاج 10 ثوانٍ، فهذا ليس خطأً في الكود — بل هو إعداد المهلة الافتراضية يعمل بالضبط كما صُمِّم. المشكلة أن كثيراً من المطورين يبحثون عن الخطأ في المنطق البرمجي بينما الحل يقع في إعداد واحد بسيط في تهيئة الدالة.

ملخص سريع (TL;DR): زيادة مهلة Lambda

النقطة	التفاصيل
المهلة الافتراضية	3 ثوانٍ
الحد الأقصى للمهلة	900 ثانية (15 دقيقة)
مكان التغيير	إعدادات الدالة ← التهيئة العامة
أداة CLI	aws lambda update-function-configuration
تأثير التكلفة	يُحتسب الفوترة بناءً على مدة التنفيذ الفعلية

كيف تعمل مهلة Lambda

Lambda تُنفِّذ الكود داخل بيئة تنفيذ معزولة. عند استدعاء الدالة، يبدأ عداد المهلة فوراً. إذا لم ينتهِ الكود قبل انقضاء المهلة المحددة، تقوم Lambda بإنهاء بيئة التنفيذ قسراً وتُعيد خطأ Task timed out after X.XX seconds. لا يوجد تحذير مسبق — الإنهاء فوري.

المهلة الافتراضية هي 3 ثوانٍ، وهي مناسبة للمهام الخفيفة مثل استدعاءات API البسيطة. لكن أي مهمة تتضمن معالجة ملفات، أو استعلامات قواعد بيانات، أو تكاملات خارجية، ستحتاج إلى قيمة أعلى.

graph TD A["استدعاء الدالة"] --> B["بدء عداد المهلة"] B --> C{"هل انتهى الكود قبل المهلة؟"} C -->|"نعم"| D["إعادة الاستجابة بنجاح"] C -->|"لا"| E["إنهاء بيئة التنفيذ"] E --> F["تسجيل: Task timed out في CloudWatch Logs"] F --> G["إعادة خطأ للمستدعي"] style D fill:#2d8a4e,color:#fff style G fill:#c0392b,color:#fff style E fill:#e67e22,color:#fff

1. استدعاء الدالة: يبدأ عداد المهلة فور استلام الحدث.
2. التنفيذ الطبيعي: إذا انتهى الكود قبل المهلة، تُعيد Lambda الاستجابة بنجاح.
3. تجاوز المهلة: إذا تجاوز التنفيذ الحد المحدد، تُنهي Lambda البيئة وتُسجِّل خطأ Timeout في CloudWatch Logs.
4. الحد الأقصى: لا يمكن تجاوز 900 ثانية بأي حال — هذا حد صارم على مستوى الخدمة.

زيادة مهلة Lambda عبر AWS Console

أسرع طريقة لتغيير المهلة دون أدوات إضافية:

1. افتح AWS Lambda Console واختر الدالة المستهدفة.
2. انتقل إلى تبويب Configuration ثم General configuration.
3. انقر Edit، وابحث عن حقل Timeout.
4. أدخل القيمة المطلوبة بالصيغة دقائق : ثوانٍ — مثلاً 0 min 30 sec للمهمة التي تحتاج 10 ثوانٍ مع هامش أمان.
5. انقر Save.

القاعدة العملية: اضبط المهلة على ضعف الوقت الفعلي المتوقع للمهمة، مع حد أقصى معقول. هذا يمنع التوقف المبكر ويحمي من الحلقات اللانهائية في نفس الوقت.

زيادة مهلة Lambda عبر AWS CLI

للبيئات الآلية أو عند العمل مع بنية تحتية كأكواد (IaC)، استخدم الأمر التالي:

aws lambda update-function-configuration \
  --function-name my-function-name \
  --timeout 30 \
  --region us-east-1

القيمة --timeout تُحدَّد بالثوانٍ كعدد صحيح. للتحقق من القيمة الحالية قبل التغيير:

aws lambda get-function-configuration \
  --function-name my-function-name \
  --region us-east-1 \
  --query 'Timeout'

هذا الأمر يُعيد قيمة المهلة الحالية بالثوانٍ مباشرةً دون إخراج إضافي.

زيادة مهلة Lambda عبر AWS SAM و CloudFormation

إذا كنت تدير الدالة عبر Infrastructure as Code، التغيير يجب أن يحدث في التعريف وليس يدوياً في Console — وإلا سيُعيد النشر التالي القيمة إلى ما كانت عليه.

AWS SAM (template.yaml):

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    FunctionName: my-function-name
    Handler: index.handler
    Runtime: nodejs20.x
    Timeout: 30

CloudFormation:

MyFunction:
  Type: AWS::Lambda::Function
  Properties:
    FunctionName: my-function-name
    Handler: index.handler
    Runtime: nodejs20.x
    Role: arn:aws:iam::123456789012:role/MyLambdaRole
    Timeout: 30
    Code:
      S3Bucket: my-deployment-bucket
      S3Key: function.zip

صلاحيات IAM المطلوبة لتغيير مهلة Lambda

لتنفيذ update-function-configuration، يحتاج المستخدم أو الدور إلى الصلاحية التالية. لاحظ أن lambda:GetFunctionConfiguration مطلوبة أيضاً للقراءة والتحقق:

🔽 عرض سياسة IAM المطلوبة

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:UpdateFunctionConfiguration",
        "lambda:GetFunctionConfiguration"
      ],
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:my-function-name"
    }
  ]
}

هذه السياسة تطبق مبدأ الصلاحية الدنيا — مقيدة بدالة محددة وليست مفتوحة على جميع الدوال. إذا كنت تدير دوالاً متعددة، استبدل ARN المحدد بنمط يشمل الدوال المستهدفة فقط.

تشخيص خطأ Timeout: من الأعراض إلى الحل الصحيح

هنا يقع الخطأ الشائع: المطور يرى Task timed out after 3.00 seconds في CloudWatch Logs، ويفترض أن الكود يحتوي على حلقة لانهائية أو استدعاء API معطوب. يقضي ساعات يراجع المنطق البرمجي، ثم يكتشف أن المهمة تحتاج فعلاً 8 ثوانٍ وأن الإعداد الافتراضي هو المشكلة.

الأعراض الدقيقة التي تميز خطأ Timeout عن خطأ برمجي حقيقي:

• رسالة الخطأ تحتوي على Task timed out after X.XX seconds — هذه رسالة Lambda وليست استثناءً من الكود.
• الخطأ يحدث بشكل متسق عند نفس الوقت تقريباً في كل استدعاء.
• لا يوجد stack trace من الكود — الإنهاء خارجي.

للتحقق من سجلات CloudWatch:

aws logs filter-log-events \
  --log-group-name /aws/lambda/my-function-name \
  --filter-pattern 'Task timed out' \
  --region us-east-1

إذا ظهرت نتائج، المشكلة مهلة وليست كوداً. إذا لم تظهر نتائج، ابحث عن استثناءات في الكود نفسه.

graph LR A["Task timed out في CloudWatch"] --> B{"هل الخطأ متسق عند نفس الوقت؟"} B -->|"نعم"| C["مشكلة إعداد المهلة"] B -->|"لا"| D["خطأ في الكود أو استدعاء خارجي"] C --> E["قِس وقت التنفيذ الفعلي"] E --> F["اضبط المهلة = الوقت الفعلي × 2"] F --> G["تحقق من مهلة API Gateway أيضاً"] style C fill:#e67e22,color:#fff style D fill:#8e44ad,color:#fff style G fill:#2980b9,color:#fff

1. ظهور الخطأ: رسالة Timeout في CloudWatch تشير مباشرةً إلى مشكلة الإعداد.
2. التشخيص الخاطئ الشائع: افتراض وجود خطأ في الكود يضيع وقتاً ثميناً.
3. التشخيص الصحيح: مقارنة وقت التنفيذ الفعلي مع المهلة المضبوطة.
4. الحل: زيادة المهلة إلى قيمة تتجاوز وقت التنفيذ الفعلي بهامش مناسب.

ضبط المهلة يشبه ضبط مؤقت الفرن: إذا ضبطته أقل من وقت الطهي الفعلي، ستحصل على نتيجة غير مكتملة بغض النظر عن جودة الوصفة. الكود صحيح — الوقت المعطى له غير كافٍ.

اعتبارات عملية عند ضبط مهلة Lambda

زيادة المهلة ليست مجانية من ناحية التصميم. هناك ثلاثة جوانب يجب أخذها بالحسبان:

التكلفة: Lambda تُفوتر بناءً على مدة التنفيذ الفعلية مضروبة في الذاكرة المخصصة. مهلة أعلى لا تعني تكلفة أعلى تلقائياً — فقط إذا استخدم الكود الوقت الإضافي فعلاً. راجع صفحة تسعير Lambda الرسمية للتفاصيل الحالية.

التكاملات المتزامنة: إذا كانت Lambda تستجيب لـ API Gateway، فإن API Gateway لديها مهلة تكامل خاصة بها. زيادة مهلة Lambda وحدها لن تكفي إذا كانت API Gateway ستُنهي الاتصال قبلها. تحقق من إعدادات كلا الخدمتين معاً.

الحد الأقصى الصارم: 900 ثانية هو حد صارم على مستوى الخدمة لا يمكن رفعه بأي طريقة. إذا كانت مهمتك تحتاج أكثر من 15 دقيقة، Lambda ليست الأداة المناسبة — النظر في AWS Fargate أو AWS Batch أو Step Functions مع Lambda يكون الخيار الأنسب.

الخلاصة والخطوات التالية لضبط مهلة Lambda

تغيير مهلة Lambda إجراء بسيط — ثلاث طرق (Console، CLI، IaC) وكلها تصل إلى نفس الإعداد. الجزء الأهم هو اختيار القيمة الصحيحة: قِس وقت التنفيذ الفعلي، أضف هامش أمان معقول، ولا تضبط المهلة على الحد الأقصى تلقائياً.

• راجع توثيق Lambda - التهيئة العامة للتفاصيل الكاملة.
• إذا كانت مهمتك تتجاوز 15 دقيقة، اطلع على AWS Step Functions كبديل معماري.
• لمراقبة أوقات التنفيذ الفعلية، استخدم مقياس Duration في CloudWatch Metrics لدالتك.

مسرد المصطلحات

المصطلح	التعريف
Lambda Timeout	الحد الزمني الأقصى الذي تسمح فيه Lambda للدالة بالتنفيذ قبل إنهائها قسراً.
Task timed out	رسالة خطأ تُصدرها Lambda عند تجاوز الدالة للمهلة المحددة.
بيئة التنفيذ (Execution Environment)	البيئة المعزولة التي تُشغِّل فيها Lambda كود الدالة.
update-function-configuration	أمر AWS CLI لتحديث إعدادات دالة Lambda بما فيها المهلة والذاكرة.
IaC (Infrastructure as Code)	إدارة البنية التحتية عبر ملفات تعريف مثل CloudFormation أو SAM بدلاً من التهيئة اليدوية.

Related Posts

• 📄 حلقة Lambda اللانهائية مع S3: كيف تمنع التشغيل المتكرر؟
• 📄 استخدام متغيرات البيئة في Lambda وتشفيرها باستخدام KMS