مراقبة سجلات AWS Lambda باستخدام ClickStack وRotel

اختر طبقة Lambda التي تتوافق مع معمارية بيئة تشغيل Lambda لديك. يعتمد الحقل {version} على منطقة AWS التي تنشر إليها. راجع صفحة الإصدارات للاطلاع على أحدث أرقام الإصدارات المطابقة لمنطقتك.

المناطق المتاحة:

• us-east-2, us-west-2
• eu-central-1, eu-north-1, eu-west-3
• ca-central-1
• ap-southeast-2, ap-northeast-2
• ap-south-1
• sa-east-1

في هذه الأمثلة، استبدل {arch} و{region} و{version} بالقيم المناسبة المذكورة أعلاه.

الخيار 1: Console في AWS

1. افتح Console الخاصة بـ AWS Lambda
2. انتقل إلى دالة Lambda الخاصة بك
3. مرّر إلى قسم Layers وانقر على Add a layer
4. اختر Specify an ARN
5. أدخل ARN الخاص بطبقة Rotel:

   arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}:{version}

6. انقر على Add

الخيار 2: AWS CLI

aws lambda update-function-configuration \
  --function-name my-function \
  --layers arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}:{version}

الخيار 3: AWS SAM

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      # ... other configuration ...
      Layers:
        - arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}:{version}

يُضبط Rotel Lambda Extension باستخدام متغيرات البيئة. تحتاج إلى ضبط endpoint الخاص بمُصدِّر OTLP بحيث يشير إلى مثيل ClickStack الخاص بك. تفترض الأمثلة أن دالة AWS Lambda لديك قادرة على الوصول إلى مثيل ClickStack.

الإعداد الأساسي (متغيرات البيئة)

أضف متغيرات البيئة هذه إلى دالة Lambda الخاصة بك:

# Required: ClickStack OTLP endpoint
ROTEL_OTLP_EXPORTER_ENDPOINT=https://clickstack.example.com:4317

# Optional: Authentication headers
ROTEL_OTLP_EXPORTER_CUSTOM_HEADERS="Authorization=<YOUR_INGESTION_API_KEY>"

# Optional: Service name (defaults to Lambda function name)
ROTEL_OTEL_RESOURCE_ATTRIBUTES="service.name=my-lambda-api,service.version=1.0.0"

الإعدادات المتقدمة (باستخدام ملف .env)

لإعدادات أكثر تعقيدًا، أنشئ ملف rotel.env داخل حزمة Lambda function الخاصة بك:

rotel.env:

ROTEL_OTLP_EXPORTER_ENDPOINT=https://clickstack.example.com:4317
ROTEL_OTLP_EXPORTER_CUSTOM_HEADERS="Authorization=<YOUR_INGESTION_API_KEY>"
ROTEL_OTEL_RESOURCE_ATTRIBUTES="service.name=my-lambda-api,deployment.environment=production"

ثم عيّن متغير البيئة بحيث يشير إلى هذا الملف:

ROTEL_ENV_FILE=/var/task/rotel.env

استخدام AWS Secrets Manager أو Parameter Store

في عمليات النشر الإنتاجية، خزّن القيم الحساسة مثل مفاتيح API في AWS Secrets Manager أو Parameter Store:

مثال على AWS Secrets Manager:

ROTEL_OTLP_EXPORTER_ENDPOINT=https://clickstack.example.com:4317
ROTEL_OTLP_EXPORTER_CUSTOM_HEADERS="Authorization=${arn:aws:secretsmanager:us-east-1:123456789012:secret:clickstack-api-key-abc123}"

مثال على AWS Parameter Store:

ROTEL_OTLP_EXPORTER_ENDPOINT=https://clickstack.example.com:4317
ROTEL_OTLP_EXPORTER_CUSTOM_HEADERS="Authorization=${arn:aws:ssm:us-east-1:123456789012:parameter/clickstack-api-key}"

أذونات IAM المطلوبة:

أضِف هذه الأذونات إلى دور التنفيذ الخاص بـ Lambda:

لـ Secrets Manager:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:BatchGetSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:clickstack-api-key-*"
    }
  ]
}

في Parameter Store:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameters"
      ],
      "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/clickstack-api-key"
    }
  ]
}

استدعِ دالة Lambda الخاصة بك للتأكد من إرسال السجلات إلى ClickStack:

aws lambda invoke \
  --function-name my-function \
  --payload '{"test": "data"}' \
  response.json

تحقّق من سجلات Lambda بحثًا عن أي أخطاء:

aws logs tail /aws/lambda/my-function --follow

بعد اكتمال الإعداد، سجّل الدخول إلى HyperDX (واجهة مستخدم ClickStack) وتحقّق من وصول السجلات:

ابحث عن السمات الأساسية التالية في السجلات:

• service.name: اسم دالة Lambda الخاصة بك
• faas.name: اسم دالة AWS Lambda
• faas.invocation_id: معرّف الاستدعاء الفريد
• cloud.provider: "aws"
• cloud.platform: "aws_lambda"

1. افتح AWS Console وانتقل إلى AWS Lambda
2. انتقل إلى دالة Lambda الخاصة بك
3. حدّد Configuration → Permissions
4. انقر على اسم دور التنفيذ لفتح وحدة تحكم IAM
5. عدّل الدور وأزل أي actions من نوع logs:*:
   • إذا كنت تستخدم سياسة مخصصة، فعدّلها لإزالة logs:CreateLogGroup وlogs:CreateLogStream وlogs:PutLogEvents
   • إذا كنت تستخدم سياسة AWS المُدارة AWSLambdaBasicExecutionRole، فأزلها من الدور
6. احفظ الدور

استدعِ دالتك مرة أخرى وتحقّق مما يلي:

1. عدم إنشاء أي streams جديدة للسجلات في CloudWatch
2. استمرار ظهور السجلات في ClickStack/HyperDX

# يجب ألا يعرض هذا أي streams جديدة للسجلات بعد تغيير السياسة
aws logs describe-log-streams \
  --log-group-name /aws/lambda/my-function \
  --order-by LastEventTime \
  --descending \
  --max-items 5

توفّر AWS طبقات auto-instrumentation في OpenTelemetry لعدة لغات:

اعثر على أحدث الإصدارات في AWS OpenTelemetry Lambda repository.

أضف كلتا طبقة امتداد Rotel وطبقة auto-instrumentation:

aws lambda update-function-configuration \
  --function-name my-function \
  --layers \
    arn:aws:lambda:{region}:418653438961:layer:rotel-extension-{arch}:{version} \
    arn:aws:lambda:{region}:901920570463:layer:aws-otel-nodejs-{arch}-ver-1-30-2:1

عيّن متغير البيئة AWS_LAMBDA_EXEC_WRAPPER لتمكين auto-instrumentation:

بالنسبة إلى Node.js:

AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler

بالنسبة إلى Python:

AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument

بالنسبة إلى Java:

AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler

بعد استدعاء دالتك:

1. انتقل إلى عرض Traces في HyperDX
2. ينبغي أن تظهر لك تتبع تتضمن spans من دالة Lambda الخاصة بك
3. ستُربط تتبع مع سجل عبر السمتين trace_id و span_id