مراقبة CloudWatch Logs من AWS باستخدام ClickStack

يرسل OpenTelemetry Collector البيانات إلى نقطة نهاية OTLP الخاصة بـ ClickStack، والتي تتطلب المصادقة.

1. افتح HyperDX على عنوان URL الخاص بـ ClickStack (على سبيل المثال، http://localhost:8080)
2. أنشئ حسابًا أو سجّل الدخول إذا لزم الأمر
3. انتقل إلى إعدادات الفريق → مفاتيح API
4. انسخ مفتاح API للاستيعاب الخاص بك

احفظ هذا في متغير بيئة:

export CLICKSTACK_API_KEY="your-api-key-here"

صدِّر بيانات اعتماد AWS كمتغيرات بيئة. وتعتمد الطريقة على نوع authentication المستخدم لديك:

لمستخدمي AWS SSO (موصى به لمعظم organizations):

# Login to SSO
aws sso login --profile YOUR_PROFILE_NAME

# Export credentials to environment variables
eval $(aws configure export-credentials --profile YOUR_PROFILE_NAME --format env)

# Verify credentials work
aws sts get-caller-identity

استبدل YOUR_PROFILE_NAME باسم ملف تعريف AWS SSO لديك (على سبيل المثال، AccountAdministrators-123456789).

لمستخدمي IAM الذين لديهم بيانات اعتماد طويلة الأجل:

export AWS_ACCESS_KEY_ID="your-access-key-id"
export AWS_SECRET_ACCESS_KEY="your-secret-access-key"
export AWS_REGION="us-east-1"

# Verify credentials work
aws sts get-caller-identity

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

يحتاج حساب AWS المرتبط ببيانات الاعتماد هذه إلى سياسة IAM التالية لقراءة السجلات من CloudWatch Logs:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CloudWatchLogsRead",
      "Effect": "Allow",
      "Action": [
        "logs:DescribeLogGroups",
        "logs:FilterLogEvents"
      ],
      "Resource": "arn:aws:logs:*:YOUR_ACCOUNT_ID:log-group:*"
    }
  ]
}

استبدل YOUR_ACCOUNT_ID بمعرّف حساب AWS لديك.

أنشئ ملف otel-collector-config.yaml يتضمن تهيئة مستقبِل CloudWatch.

aws logs describe-log-groups --region us-east-1 \
  --query 'logGroups[].logGroupName' --output table

-------------------------------
|      DescribeLogGroups      |
+-----------------------------+
|  /aws-glue/jobs/error       |
|  /aws-glue/jobs/logs-v2     |
|  /aws-glue/jobs/output      |
|  /aws-glue/sessions/error   |
|  /aws-glue/sessions/output  |
+-----------------------------+

groups:
  named:
    /aws-glue/jobs/error:
    /aws-glue/jobs/logs-v2:
    /aws-glue/jobs/output:
    /aws-glue/sessions/error:
    /aws-glue/sessions/output:

المثال 1: مجموعات سجلات محددة بالاسم (مُوصى به)

تجمع هذه التهيئة السجلات من مجموعات سجلات محددة بالاسم:

receivers:
  awscloudwatch:
    region: us-east-1
    logs:
      poll_interval: 1m
      max_events_per_request: 100
      groups:
        named:
          /aws/lambda/my-function:
          /aws/ecs/my-service:
          /aws/eks/my-cluster/cluster:

processors:
  batch:
    timeout: 10s

exporters:
  otlphttp:
    endpoint: http://localhost:4318
    headers:
      authorization: ${CLICKSTACK_API_KEY}

service:
  pipelines:
    logs:
      receivers: [awscloudwatch]
      processors: [batch]
      exporters: [otlphttp]

مثال 2: الاكتشاف التلقائي لمجموعات السجلات ذات البادئة

تكتشف هذه التهيئة تلقائيًا ما يصل إلى 100 مجموعة سجلات تبدأ بالبادئة /aws/lambda، وتجمع السجلات منها:

receivers:
  awscloudwatch:
    region: us-east-1
    logs:
      poll_interval: 1m
      max_events_per_request: 100
      groups:
        autodiscover:
          limit: 100
          prefix: /aws/lambda

processors:
  batch:
    timeout: 10s

exporters:
  otlphttp:
    endpoint: http://localhost:4318
    headers:
      authorization: ${CLICKSTACK_API_KEY}

service:
  pipelines:
    logs:
      receivers: [awscloudwatch]
      processors: [batch]
      exporters: [otlphttp]

معلمات التهيئة:

• region: منطقة AWS التي توجد فيها مجموعات السجلات
• poll_interval: عدد مرات التحقق من السجلات الجديدة (على سبيل المثال، 1m، 5m)
• max_events_per_request: الحد الأقصى لعدد أحداث السجل التي يمكن جلبها في كل طلب
• groups.autodiscover.limit: الحد الأقصى لعدد مجموعات السجلات التي يمكن اكتشافها
• groups.autodiscover.prefix: تصفية مجموعات السجلات حسب البادئة
• groups.named: إدراج أسماء مجموعات السجلات المطلوب جمعها صراحةً

للاطلاع على مزيد من خيارات التهيئة، راجع وثائق CloudWatch receiver.

استبدل ما يلي:

• ${CLICKSTACK_API_KEY} → يستخدم متغير البيئة الذي عيّنته سابقًا
• http://localhost:4318 → نقطة نهاية ClickStack الخاصة بك (استخدم مضيف ClickStack إذا كنت تشغّله عن بُعد)
• us-east-1 → منطقة AWS الخاصة بك
• أسماء/بادئات مجموعات السجلات → مجموعات سجلات CloudWatch الفعلية لديك

أنشئ ملف docker-compose.yaml:

services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel-config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otel-config.yaml
    environment:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
      - AWS_SESSION_TOKEN
      - AWS_REGION
      - CLICKSTACK_API_KEY
    restart: unless-stopped
    extra_hosts:
      - "host.docker.internal:host-gateway"

ثم شغّل المجمِّع:

docker compose up -d

اعرض سجلات المجمِّع:

docker compose logs -f otel-collector

بمجرد تشغيل الـ collector:

1. افتح HyperDX على http://localhost:8080 (أو على عنوان URL الخاص بـ ClickStack)
2. انتقل إلى عرض السجلات
3. انتظر دقيقة إلى دقيقتين حتى تظهر السجلات (بحسب فترة الاستطلاع لديك)
4. ابحث عن السجلات القادمة من مجموعات سجلات CloudWatch الخاصة بك

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

• ResourceAttributes['aws.region']: منطقة AWS الخاصة بك (على سبيل المثال: "us-east-1")
• ResourceAttributes['cloudwatch.log.group.name']: اسم مجموعة سجلات CloudWatch
• ResourceAttributes['cloudwatch.log.stream']: اسم دفق السجل
• Body: المحتوى الفعلي لرسالة السجل

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/aws/cloudwatch/cloudwatch-logs.jsonl

تتضمن مجموعة البيانات 24 ساعة من سجلات CloudWatch من عدة خدمات:

• وظائف Lambda: معالجة المدفوعات، وإدارة الطلبات، والمصادقة
• خدمات ECS: بوابة API مع تحديد المعدل ومهلات
• المهام الخلفية: معالجة على دفعات مع أنماط إعادة المحاولة

إذا لم يكن ClickStack قيد التشغيل بالفعل:

docker run -d --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

انتظر بضع لحظات حتى يكتمل تشغيل ClickStack بالكامل.

docker exec -i clickstack clickhouse-client --query="
  INSERT INTO default.otel_logs FORMAT JSONEachRow
" < cloudwatch-logs.jsonl

يؤدي هذا إلى استيراد السجلات مباشرةً إلى جدول السجلات في ClickStack.

بعد الاستيراد:

1. افتح HyperDX على http://localhost:8080 وسجّل الدخول (أنشئ حسابًا إذا لزم الأمر)
2. انتقل إلى عرض Logs
3. اضبط النطاق الزمني على 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC)
4. ابحث عن cloudwatch-demo أو رشّح باستخدام LogAttributes['source'] = 'cloudwatch-demo'

من المفترض أن ترى سجلات من عدة مجموعات سجلات CloudWatch.

نزّل ملف إعدادات لوحة المعلومات.

1. افتح HyperDX وانتقل إلى قسم لوحات المعلومات
2. انقر على استيراد لوحة المعلومات في الزاوية العلوية اليمنى من قائمة النقاط الثلاث

3. ارفع الملف cloudwatch-logs-dashboard.json ثم انقر على إنهاء الاستيراد

ستُنشأ لوحة المعلومات مع ضبط جميع التصورات مسبقًا: