إنشاء بيانات OpenTelemetry اصطناعية باستخدام otelgen

otelgen هي أداة CLI صغيرة مكتوبة بلغة Go تُنشئ سجلات وتتبعّات ومقاييس اصطناعية بتنسيق OTLP. استخدمها للتأكد من أن ClickStack OpenTelemetry collector الحالي يستقبل البيانات وأن الأحداث تظهر في ClickStack UI.

يفترض هذا الدليل أن الـ collector يعمل بالفعل مع OTLP endpoints على 4317 ‏(gRPC) و4318 ‏(HTTP).

المتطلبات المسبقة

يفترض هذا الدليل أنك أكملت دليل Getting Started لـ Managed ClickStack، وأن لديك OpenTelemetry Collector قيد التشغيل مع إتاحة الوصول إلى نقطتَي نهاية OTLP عبر gRPC (4317) وHTTP (4318) من الجهاز الذي تشغّل عليه otelgen. وإذا كنت قد أمّنت المجمّع باستخدام OTLP_AUTH_TOKEN، فاحتفظ بهذه القيمة في متناول اليد.

تثبيت otelgen

ثبّت الأداة باستخدام Homebrew:

brew install krzko/tap/otelgen

أو ثبّتها باستخدام Go:

go install github.com/krzko/otelgen@latest

تعيين متغيرات البيئة

صدّر نقطة نهاية المجمّع، وإذا كان المجمّع مؤمّنًا، فصدّر أيضًا رمز المصادقة:

export OTEL_ENDPOINT=<host>:4317
export OTLP_AUTH_TOKEN=<your_otlp_auth_token>

استخدم اسم المضيف والمنفذ الخاصين بالمجمّع. وإذا كان المجمّع يعمل على الجهاز نفسه، فستكون القيمة localhost:4317.

توليد التتبعات

أرسل دفعة قصيرة من traces متعددة الـ spans:

otelgen --otel-exporter-otlp-endpoint ${OTEL_ENDPOINT} \
  --header "authorization=${OTLP_AUTH_TOKEN}" \
  --protocol grpc --insecure \
  --rate 2 --duration 10 \
  traces multi

يشير --rate إلى عدد traces في الثانية، ويشير --duration إلى مدة التشغيل بالثواني. ويعطّل --insecure بروتوكول TLS لاتصال gRPC، وهذا مطلوب عند توجيه otelgen إلى منفذ OTLP غير المشفّر الخاص بالمجمّع.

توليد السجلات

otelgen --otel-exporter-otlp-endpoint ${OTEL_ENDPOINT} \
  --header "authorization=${OTLP_AUTH_TOKEN}" \
  --protocol grpc --insecure \
  --rate 2 --duration 10 \
  logs multi

توليد المقاييس

لا تراعي الأوامر الفرعية الخاصة بـ metrics الخيار --duration. شغّل الأمر ثم اضغط Ctrl+C بعد بضع ثوانٍ لإيقافه.

otelgen --otel-exporter-otlp-endpoint ${OTEL_ENDPOINT} \
  --header "authorization=${OTLP_AUTH_TOKEN}" \
  --protocol grpc --insecure \
  --rate 2 \
  metrics sum

يدعم otelgen أيضًا الأوامر الفرعية gauge وhistogram وup-down-counter وexponential-histogram ضمن metrics.

التحقق في ClickStack

افتح واجهة ClickStack من ClickHouse Cloud console. في عرض Search، بدّل الـ source بين Logs وTraces للتأكد من ظهور الأحداث الجديدة. اضبط النطاق الزمني على Last 15 minutes. افتح Chart Explorer، ثم حدّد Metrics، وأنشئ chart لأحد metric names التي يُنتجها otelgen (على سبيل المثال otelgen.metrics.sum) للتحقق من استيعاب المقاييس.

المتطلبات المسبقة

يفترض هذا الدليل أنك شغّلت Open Source ClickStack باستخدام تعليمات صورة الكل في واحد، وأن نقاط نهاية OTLP (4317 لـ gRPC و4318 لـ HTTP) يمكن الوصول إليها. كما ستحتاج إلى مفتاح API للإدخال من واجهة HyperDX ضمن Team Settings > API Keys.

تثبيت otelgen

ثبّت الأداة باستخدام Homebrew:

brew install krzko/tap/otelgen

أو ثبّتها باستخدام Go:

go install github.com/krzko/otelgen@latest

تعيين متغيرات البيئة

صدّر نقطة نهاية المجمّع ومفتاح API للإدخال:

export OTEL_ENDPOINT=localhost:4317
export CLICKSTACK_API_KEY=<your_ingestion_api_key>

إنشاء التتبعات

أرسل دفعة قصيرة من التتبعات متعددة الـ span:

otelgen --otel-exporter-otlp-endpoint ${OTEL_ENDPOINT} \
  --header "authorization=${CLICKSTACK_API_KEY}" \
  --protocol grpc --insecure \
  --rate 2 --duration 10 \
  traces multi

يشير --rate إلى عدد التتبعات في الثانية، بينما يشير --duration إلى مدة التشغيل بالثواني. ويُفعّل --insecure استخدام gRPC بنص صريح مع المجمّع المحلي.

إنشاء السجلات

otelgen --otel-exporter-otlp-endpoint ${OTEL_ENDPOINT} \
  --header "authorization=${CLICKSTACK_API_KEY}" \
  --protocol grpc --insecure \
  --rate 2 --duration 10 \
  logs multi

إنشاء المقاييس

لا تدعم الأوامر الفرعية metrics الخيار --duration. شغّل الأمر ثم اضغط Ctrl+C بعد بضع ثوانٍ لإيقافه.

otelgen --otel-exporter-otlp-endpoint ${OTEL_ENDPOINT} \
  --header "authorization=${CLICKSTACK_API_KEY}" \
  --protocol grpc --insecure \
  --rate 2 \
  metrics sum

يدعم otelgen أيضًا الأوامر الفرعية gauge وhistogram وup-down-counter وexponential-histogram ضمن metrics.

التحقق في ClickStack

انتقل إلى http://localhost:8080 لفتح واجهة ClickStack. في عرض Search، بدّل الـ source بين Logs وTraces للتأكد من ظهور أحداث جديدة. اضبط النطاق الزمني على Last 15 minutes. ثم افتح Chart Explorer، واختر Metrics، وأنشئ chart لأحد أسماء المقاييس التي ينتجها otelgen (مثل otelgen.metrics.sum) للتحقق من إدخال المقاييس.