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

باختصاراجمع سجلات نظام EC2 واعرضها بصريًا في ClickStack باستخدام OpenTelemetry Collector مع إثراء تلقائي بالبيانات الوصفية لـ EC2 (معرّف المثيل، المنطقة، منطقة التوافر، نوع المثيل). يتضمن مجموعة بيانات تجريبية ولوحة معلومات مُعدّة مسبقًا.

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

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

هل يعمل ClickStack على مثيل EC2 نفسه؟إذا كان ClickStack يعمل على مثيل EC2 نفسه الذي تريد مراقبة سجلاته، فيمكنك استخدام النهج المتكامل المشابه لما هو موضح في دليل سجلات المضيف العامة. اربط /var/log بحاوية ClickStack وأضف المعالج resourcedetection إلى التهيئة المخصصة لديك لالتقاط بيانات 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 نفسه

تتوفر بيانات EC2 الوصفية على http://169.254.169.254 من داخل المثيل. يستخدم معالج OpenTelemetry resourcedetection نقطة النهاية هذه لإثراء السجلات تلقائيًا بسياق السحابة.

تحقّق من وجود ملفات 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 لديك:

إصدارات Linux الحديثة (Ubuntu 24.04+)
إصدارات Linux القديمة (Amazon Linux 2 وRHEL وإصدارات Ubuntu الأقدم)

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

إثراء البيانات الوصفية لـ EC2يضيف المعالج resourcedetection هذه السمات تلقائيًا إلى كل سجل:

cloud.provider: “aws”
cloud.platform: “aws_ec2”
cloud.region: منطقة AWS (على سبيل المثال، “us-east-1”)
cloud.availability_zone: نطاق التوفّر (على سبيل المثال، “us-east-1a”)
cloud.account.id: معرّف حساب AWS
host.id: معرّف مثيل EC2 (على سبيل المثال، “i-1234567890abcdef0”)
host.type: نوع المثيل (على سبيل المثال، “t3.medium”)
host.name: اسم مضيف المثيل

عيّن مفتاح 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

للاستخدام في بيئة الإنتاجاضبط المُجمِّع ليعمل كخدمة ضمن systemd بحيث يبدأ تلقائيًا عند الإقلاع ويُعاد تشغيله عند حدوث فشل. راجع وثائق OpenTelemetry Collector لمزيد من التفاصيل.

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

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

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

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

للمستخدمين الذين يريدون اختبار تكامل سجلات مضيف 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

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

شغّل 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 الوصفية ضمن سمات المورد

عرض المنطقة الزمنيةيعرض HyperDX الطوابع الزمنية وفقًا للمنطقة الزمنية المحلية في متصفحك. تمتد البيانات التجريبية عبر 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC). يضمن النطاق الزمني الواسع ظهور السجلات التجريبية بغض النظر عن موقعك. وبعد ظهور السجلات، يمكنك تضييق النطاق إلى فترة 24 ساعة للحصول على تصورات أوضح.

يُفترض أن ترى سجلات تتضمن سياق 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 - عرض السجلات من مثيل محدد

بالنسبة إلى مجموعة البيانات التجريبية، اضبط النطاق الزمني على 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC) (مع تعديله حسب منطقتك الزمنية المحلية). لن تتضمن لوحة المعلومات المستوردة نطاقًا زمنيًا محددًا افتراضيًا.

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

عدم ظهور البيانات الوصفية لـ 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 Collector مباشرةً على مثيلات EC2، وهو النمط الموصى به في بيئة الإنتاج للمراقبة على مستوى المضيف. ولإدارة مُجمِّعات OpenTelemetry عبر عدد كبير من المثيلات، فكّر في استخدام أدوات إدارة التهيئة (Ansible وChef وPuppet) أو OpenTelemetry Operator في بيئات Kubernetes. راجع إرسال بيانات OpenTelemetry للاطلاع على إعدادات بيئة الإنتاج.

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

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

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

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

​تثبيت OpenTelemetry Collector

​إنشاء تهيئة collector

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

​شغّل الـ collector

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

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

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

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

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

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

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

​ إعدادات لوحة المعلومات

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

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

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

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

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

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

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

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

​الانتقال إلى بيئة الإنتاج

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

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

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

تثبيت OpenTelemetry Collector

إنشاء تهيئة collector

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

شغّل الـ collector

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

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

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

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

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

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

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

إعدادات لوحة المعلومات

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

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

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

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

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

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

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

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

الانتقال إلى بيئة الإنتاج