مراقبة سجلات مضيف EC2 باستخدام ClickStack

التكامل مع مثيل EC2 حالي

يغطي هذا القسم تثبيت OpenTelemetry Collector على مثيلات EC2 لديك لجمع سجلات النظام وإرسالها إلى ClickStack مع إثرائها تلقائيًا ببيانات EC2 الوصفية. هذه المعمارية الموزعة جاهزة لبيئات الإنتاج وقابلة للتوسع عبر مثيلات متعددة.

إذا كنت ترغب في اختبار تكامل سجلات مضيف EC2 قبل تهيئة مثيل الإنتاج لديك، فيمكنك استخدام إعدادنا المهيأ مسبقًا والبيانات النموذجية في قسم "مجموعة البيانات التجريبية".

المتطلبات الأساسية

مثيل ClickStack قيد التشغيل (يمكن أن يكون داخل بنيتك التحتية، أو على السحابة، أو محليًا)
مثيل EC2 قيد التشغيل (Ubuntu أو Amazon Linux أو أي توزيعة Linux أخرى)
توفّر اتصال شبكي من مثيل EC2 إلى نقطة نهاية OTLP الخاصة بـ ClickStack (المنفذ 4318 لـ HTTP أو 4317 لـ gRPC)
إمكانية الوصول إلى خدمة البيانات الوصفية للمثيل EC2 (مُمكّنة افتراضيًا)

تحقّق من إمكانية الوصول إلى بيانات EC2 الوصفية

من مثيل EC2 لديك، تحقّق من إمكانية الوصول إلى خدمة البيانات الوصفية:

# Get metadata token (IMDSv2)
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

# Verify instance metadata
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/placement/region
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-type

يجب أن ترى معرّف المثيل والمنطقة ونوع المثيل. إذا لم تنجح هذه الأوامر، فتحقّق مما يلي:

أن خدمة بيانات تعريف المثيل مفعّلة
أن IMDSv2 غير محظور بواسطة مجموعات الأمان أو قوائم ACL للشبكة
أنك تشغّل هذه الأوامر من مثيل EC2 نفسه

تحقّق من وجود ملفات syslog

تحقّق من أن مثيل EC2 لديك يُنشئ ملفات syslog:

# Ubuntu instances
ls -la /var/log/syslog

# Amazon Linux / RHEL instances
ls -la /var/log/messages

# View recent entries
tail -20 /var/log/syslog
# or
tail -20 /var/log/messages

تثبيت OpenTelemetry Collector

ثبّت توزيعة OpenTelemetry Collector Contrib على مثيل EC2 الخاص بك:

# Download the latest release
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.114.0/otelcol-contrib_0.114.0_linux_amd64.tar.gz

# Extract and install
tar -xvf otelcol-contrib_0.114.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/

# Verify installation
otelcol-contrib --version

إنشاء تهيئة collector

أنشئ ملف تهيئة لـ OpenTelemetry Collector في المسار /etc/otelcol-contrib/config.yaml:

sudo mkdir -p /etc/otelcol-contrib

اختر الإعداد وفقًا لتوزيعة Linux لديك:

sudo tee /etc/otelcol-contrib/config.yaml > /dev/null << 'EOF'
receivers:
  filelog/syslog:
    include:
      - /var/log/syslog
      - /var/log/**/*.log
    start_at: end
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\S+) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999-07:00'
      
      - type: add
        field: attributes.source
        value: "ec2-host-logs"

processors:
  resourcedetection:
    detectors: [ec2, system]
    timeout: 5s
    override: false
    ec2:
      tags:
        - ^Name
        - ^Environment
        - ^Team
  
  batch:
    timeout: 10s
    send_batch_size: 10000

exporters:
  otlphttp:
    endpoint: "http://YOUR_CLICKSTACK_HOST:4318"
    headers:
      authorization: "${env:CLICKSTACK_API_KEY}"

service:
  pipelines:
    logs:
      receivers: [filelog/syslog]
      processors: [resourcedetection, batch]
      exporters: [otlphttp]
EOF

sudo tee /etc/otelcol-contrib/config.yaml > /dev/null << 'EOF'
receivers:
  filelog/syslog:
    include:
      - /var/log/messages
      - /var/log/**/*.log
    start_at: end
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\w+ \d+ \d{2}:\d{2}:\d{2}) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%b %d %H:%M:%S'
      
      - type: add
        field: attributes.source
        value: "ec2-host-logs"

processors:
  resourcedetection:
    detectors: [ec2, system]
    timeout: 5s
    override: false
    ec2:
      tags:
        - ^Name
        - ^Environment
        - ^Team
  
  batch:
    timeout: 10s
    send_batch_size: 10000

exporters:
  otlphttp:
    endpoint: "http://YOUR_CLICKSTACK_HOST:4318"
    headers:
      authorization: "${env:CLICKSTACK_API_KEY}"

service:
  pipelines:
    logs:
      receivers: [filelog/syslog]
      processors: [resourcedetection, batch]
      exporters: [otlphttp]
EOF

استبدل ما يلي في التهيئة:

YOUR_CLICKSTACK_HOST: اسم المضيف أو عنوان IP الذي يستضيف ClickStack
للاختبار المحلي، يمكنك استخدام نفق SSH (راجع قسم استكشاف الأخطاء وإصلاحها)

هذا الإعداد:

يقرأ ملفات سجلات النظام من المسارات القياسية (/var/log/syslog في Ubuntu، و/var/log/messages في Amazon Linux/RHEL)
يحلّل تنسيق syslog لاستخراج الحقول المهيكلة (الطابع الزمني، واسم المضيف، والوحدة/الخدمة، وPID، والرسالة)
يكتشف تلقائيًا بيانات EC2 الوصفية ويضيفها باستخدام المعالج resourcedetection
يتضمن اختياريًا وسوم EC2 ‏(Name وEnvironment وTeam) إن وُجدت
يرسل السجلات إلى ClickStack عبر OTLP HTTP

عيّن مفتاح API لـ ClickStack

صدّر مفتاح API لـ ClickStack كمتغير بيئة:

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

لجعل هذا مستمرًا بعد إعادة التشغيل، أضِفه إلى ملف إعدادات الصدفة:

echo 'export CLICKSTACK_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

شغّل الـ collector

ابدأ تشغيل OpenTelemetry Collector:

CLICKSTACK_API_KEY="your-api-key-here" /usr/local/bin/otelcol-contrib --config /etc/otelcol-contrib/config.yaml

التحقق من السجلات في HyperDX

بمجرد تشغيل المجمّع، سجّل الدخول إلى HyperDX وتحقّق من أن السجلات تتدفّق مع بيانات EC2 الوصفية:

انتقل إلى عرض البحث
اضبط المصدر على Logs
صفِّ حسب source:ec2-host-logs
انقر على إدخال سجل لتوسيعه
تحقّق من ظهور بيانات EC2 الوصفية ضمن سمات المورد:
- cloud.provider
- cloud.region
- host.id (معرّف المثيل)
- host.type (نوع المثيل)
- cloud.availability_zone

تفاصيل سجل EC2 التي تعرض البيانات الوصفية

مجموعة بيانات تجريبية

للمستخدمين الذين يريدون اختبار تكامل سجلات مضيف EC2 قبل تهيئة مثيلات الإنتاج لديهم، نوفّر مجموعة بيانات تجريبية تتضمن بيانات EC2 وصفية مُحاكاة.

نزّل مجموعة البيانات النموذجية

نزّل ملف السجل النموذجي:

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/host-logs/journal.log

تتضمن مجموعة البيانات ما يلي:

تسلسل إقلاع النظام
نشاط تسجيل الدخول عبر SSH (محاولات ناجحة وأخرى فاشلة)
حادثة أمنية (هجوم قوة غاشمة مع استجابة fail2ban)
صيانة مجدولة (مهام cron وanacron)
إعادة تشغيل الخدمات (rsyslog)
رسائل النواة ونشاط جدار الحماية
مزيج من العمليات الطبيعية والأحداث البارزة

أنشئ تهيئة collector للاختبار

أنشئ ملفًا باسم ec2-host-logs-demo.yaml يتضمن التهيئة التالية:

cat > ec2-host-logs-demo.yaml << 'EOF'
receivers:
  filelog/journal:
    include:
      - /tmp/host-demo/journal.log
    start_at: beginning
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\S+) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%Y-%m-%dT%H:%M:%S%z'
      
      - type: add
        field: attributes.source
        value: "ec2-demo"

processors:
  # Simulate EC2 metadata for demo (no real EC2 instance required)
  resource:
    attributes:
      - key: service.name
        value: "ec2-demo"
        action: insert
      - key: cloud.provider
        value: "aws"
        action: insert
      - key: cloud.platform
        value: "aws_ec2"
        action: insert
      - key: cloud.region
        value: "us-east-1"
        action: insert
      - key: cloud.availability_zone
        value: "us-east-1a"
        action: insert
      - key: host.id
        value: "i-0abc123def456789"
        action: insert
      - key: host.type
        value: "t3.medium"
        action: insert
      - key: host.name
        value: "prod-web-01"
        action: insert

service:
  pipelines:
    logs/ec2-demo:
      receivers: [filelog/journal]
      processors:
        - resource
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

شغّل ClickStack بإعدادات العرض التوضيحي

شغّل ClickStack باستخدام السجلات وإعدادات العرض التوضيحي:

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/ec2-host-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/journal.log:/tmp/host-demo/journal.log:ro" \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest

تحقّق من السجلات في HyperDX

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

افتح HyperDX وسجّل الدخول إلى حسابك (قد تحتاج إلى إنشاء حساب أولًا)
انتقل إلى واجهة البحث واضبط المصدر على Logs
اضبط النطاق الزمني على 2025-11-10 00:00:00 - 2025-11-13 00:00:00
صفِّ النتائج باستخدام source:ec2-demo
وسّع إدخال سجل لعرض بيانات EC2 الوصفية ضمن سمات المورد

يُفترض أن ترى سجلات تتضمن سياق EC2 مُحاكى، بما في ذلك:

معرّف المثيل: i-0abc123def456789
المنطقة: us-east-1
منطقة التوفّر: us-east-1a
نوع المثيل: t3.medium

لوحات المعلومات والتصورات

لمساعدتك على بدء مراقبة سجلات مضيف EC2 باستخدام ClickStack، نوفر تصورات أساسية تتضمن سياق السحابة.

تنزيل إعدادات لوحة المعلومات

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

استيراد لوحة المعلومات الجاهزة

افتح HyperDX وانتقل إلى قسم Dashboards
انقر على Import Dashboard في الزاوية العلوية اليمنى ضمن قائمة النقاط الثلاث

ارفع ملف host-logs-dashboard.json وانقر على Finish Import

عرض لوحة المعلومات

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

يمكنك تصفية تصورات لوحة المعلومات حسب سياق EC2:

cloud.region:us-east-1 - عرض السجلات من منطقة محددة
host.type:t3.medium - التصفية حسب نوع المثيل
host.id:i-0abc123def456 - عرض السجلات من مثيل محدد

استكشاف الأخطاء وإصلاحها

عدم ظهور البيانات الوصفية لـ EC2 في السجلات

تحقق من إمكانية الوصول إلى خدمة البيانات الوصفية لـ EC2:

# Get metadata token
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

# Test metadata endpoint
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id

إذا لم ينجح ذلك، فتحقّق مما يلي:

أن خدمة البيانات الوصفية للمثيل مُمكّنة
أن IMDSv2 غير محجوب بواسطة مجموعات الأمان
أنك تشغّل المجمّع على مثيل EC2 نفسه

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

# If running as systemd service
sudo journalctl -u otelcol-contrib -f | grep -i "ec2\|metadata\|resourcedetection"

# If running in foreground, check stdout

عدم ظهور أي سجلات في HyperDX

تحقق من وجود ملفات السجل وأنه تتم الكتابة إليها:

ls -la /var/log/syslog /var/log/messages
tail -f /var/log/syslog

تأكّد من أن المجمّع يستطيع قراءة ملفات السجل:

cat /var/log/syslog | head -20

تحقّق من اتصال الشبكة بـ ClickStack:

# Test OTLP endpoint
curl -v http://YOUR_CLICKSTACK_HOST:4318/v1/logs

# Should get a response (even if error, means endpoint is reachable)

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

# If running in foreground
# Look for error messages in stdout

# If running as systemd service
sudo journalctl -u otelcol-contrib -f | grep -i "error\|failed"

يتم تحليل السجلات بشكل غير صحيح

تحقق من تنسيق syslog لديك:

بالنسبة إلى Ubuntu 24.04+:

# Should show ISO8601 format: 2025-11-17T20:55:44.826796+00:00
tail -5 /var/log/syslog

لنظامَي Amazon Linux 2 / Ubuntu 20.04:

# Should show traditional format: Nov 17 14:16:16
tail -5 /var/log/messages

إذا لم يكن التنسيق لديك مطابقًا، فاستخدم علامة تبويب التهيئة المناسبة في قسم إنشاء تهيئة collector وفقًا للتوزيعة التي تستخدمها.

تعذّر بدء تشغيل المُجمِّع كخدمة systemd

تحقق من حالة الخدمة:

sudo systemctl status otelcol-contrib

عرض السجلات التفصيلية:

sudo journalctl -u otelcol-contrib -n 50

المشكلات الشائعة:

لم يتم تعيين مفتاح API بشكل صحيح في البيئة
أخطاء في صياغة ملف الإعدادات
مشكلات في الأذونات عند قراءة ملفات السجل

الخطوات التالية

قم بإعداد التنبيهات لأحداث النظام الحرجة (تعطل الخدمة، إخفاقات المصادقة، تحذيرات القرص)
صفِّ حسب سمات بيانات EC2 الوصفية (المنطقة، نوع المثيل، معرّف المثيل) لمراقبة موارد محددة
اربط سجلات مضيف EC2 بسجلات التطبيق لاستكشاف الأخطاء وإصلاحها بشكل شامل
أنشئ لوحات معلومات مخصصة لمراقبة الأمان (محاولات SSH، استخدام sudo، عمليات حظر جدار الحماية)

الانتقال إلى الإنتاج

يثبّت هذا الدليل مجمّع OpenTelemetry مباشرةً على مثيلات EC2، وهذا هو النمط الموصى به في بيئات الإنتاج للمراقبة على مستوى المضيف. ولإدارة مكوّنات المجمّع عبر عدد كبير من المثيلات، فكّر في استخدام أدوات إدارة التهيئة (Ansible وChef وPuppet) أو OpenTelemetry Operator في بيئات Kubernetes. راجع إرسال بيانات OpenTelemetry للاطلاع على تهيئة بيئة الإنتاج.