OpenTelemetry Operator Kubernetes: Collector والقياس التلقائي خطوة بخطوة

OpenTelemetry Operator Kubernetes: ثبّته بـ Helm، وأعلن Collector يصدّر إلى Dynatrace، وفعّل القياس البرمجي لـ Java أو Python بتعليق واحد.
OpenTelemetry Operator Kubernetes : Collector et auto-instrumentation pas à pas

قياس عشرين خدمة مصغّرة يدويًا يعني عشرين Dockerfile للتعديل وعشرين وكيلًا (agent) للتحديث وعشرة إعدادات تصدير متباعدة. يقلب OpenTelemetry Operator Kubernetes المنطق: تعلن مرة واحدة عن Collector وعن القياس البرمجي (instrumentation) في صورة موارد Kubernetes، فيطبّقها Operator على الـ Pods بمجرد تعليق (annotation).

هدف هذا الدرس التطبيقي: تثبيت Operator ونشر Collector بوابة يصدّر إلى Dynatrace وتفعيل القياس التلقائي لـ Java وPython بالتعليق، ثم التحقق من وصول التتبعات. المحتوى صالح لـ Dynatrace SaaS وDynatrace Managed: لا يتغير سوى عنوان OTLP.

لا تخلط بين هذا Operator وبين Dynatrace Operator الذي يدير OneAgent وActiveGate (انظر Dynatrace Operator على Kubernetes). يمكن للاثنين التعايش شريطة ألا يُقاس الـ Pod نفسه مرتين.

ما الذي يديره OpenTelemetry Operator

Operator تطبيق لنمط Operator في Kubernetes. يدير أمرين: نسخ من OpenTelemetry Collector، والقياس التلقائي للأحمال (workloads) بمكتبات OpenTelemetry. ويعتمد على أربعة موارد مخصصة:

  • OpenTelemetryCollector (opentelemetry.io/v1beta1، الاسم المختصر otelcol): Collector وإعداده، بالنمط deployment (الافتراضي) أو daemonset أو statefulset أو sidecar.
  • Instrumentation (opentelemetry.io/v1alpha1، الاسم المختصر otelinst): إعداد SDK المحقون (المُصدِّر والناشرات والعيّنة والصورة لكل لغة).
  • TargetAllocator: يوزّع أهداف جمع Prometheus بين عدة Collectors (النمطان statefulset وdaemonset).
  • OpAMPBridge: يربط Collectors بخادم OpAMP.

يغطي القياس التلقائي Apache HTTPD و.NET وGo وJava وNginx وNode.js وPython. وتكون Go وNginx معطّلتين افتراضيًا في Operator (--enable-go-instrumentation و--enable-nginx-instrumentation).

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

  • عنقود Kubernetes بالإصدار 1.24 أو أحدث (شرط مخطط Helm) والأداة kubectl.
  • Helm 4.0 أو أحدث للإصدار الحالي من المخطط، أو kubectl apply مع ملف الإصدار (release manifest).
  • شهادة لخطافات القبول (admission webhooks): cert-manager (الطريقة الافتراضية) أو شهادة موقّعة ذاتيًا يولّدها المخطط.
  • رمز Dynatrace المميّز (API token) بالنطاقات openTelemetryTrace.ingest وmetrics.ingest وlogs.ingest، وعنوان OTLP: https://<env-id>.live.dynatrace.com/api/v2/otlp في SaaS، وhttps://<votre-domaine>/e/<env-id>/api/v2/otlp في Managed.

تثبيت OpenTelemetry Operator Kubernetes

الخطوة 1: نشر Operator بـ Helm

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update
helm install opentelemetry-operator open-telemetry/opentelemetry-operator \
  --namespace opentelemetry-operator-system --create-namespace \
  --set "manager.collectorImage.repository=ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-k8s" \
  --set admissionWebhooks.certManager.enabled=false \
  --set admissionWebhooks.autoGenerateCert.enabled=true

يطلب الخياران الأخيران من Helm توليد شهادة موقّعة ذاتيًا: عملي بدون cert-manager. وإذا كان cert-manager مثبّتًا فاحذفهما. وبدون Helm، الأمر الرسمي هو kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml، وcert-manager فيه إلزامي. ولا تُحذف تعريفات CRD عند إلغاء تثبيت المخطط: تذكّر ذلك عند التنظيف.

الخطوة 2: إنشاء Collector البوابة

kubectl create namespace observability
kubectl -n observability create secret generic dynatrace-otlp \
  --from-literal=DT_ENDPOINT='https://<env-id>.live.dynatrace.com/api/v2/otlp' \
  --from-literal=DT_API_TOKEN='<token>'
apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: gateway
  namespace: observability
spec:
  mode: deployment
  replicas: 2
  envFrom:
    - secretRef:
        name: dynatrace-otlp
  config:
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
    processors:
      memory_limiter:
        check_interval: 1s
        limit_percentage: 75
        spike_limit_percentage: 15
      cumulative_to_delta: {}
    exporters:
      otlp_http:
        endpoint: ${env:DT_ENDPOINT}
        headers:
          Authorization: "Api-Token ${env:DT_API_TOKEN}"
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [memory_limiter]
          exporters: [otlp_http]
        metrics:
          receivers: [otlp]
          processors: [memory_limiter, cumulative_to_delta]
          exporters: [otlp_http]
        logs:
          receivers: [otlp]
          processors: [memory_limiter]
          exporters: [otlp_http]

ما يفعله Operator: ينشئ الـ Deployment، ولأنه يرصد في config مستقبِلات لها منافذ، ينشئ زوجًا من الخدمات (إحداهما headless) تعرضان 4317 و4318. وتسمى الخدمة الرئيسية gateway-collector. انتبه: لا يتحقق Operator من الإعداد كله؛ فقد يقبل إعدادًا غير صالح ثم ينهار Collector عند البدء. وotlp_http هو الاسم الحديث للمُصدِّر otlphttp الذي يبقى مقبولًا اسمًا بديلًا. وتتضمن الصورة opentelemetry-collector-k8s المحددة في الخطوة 1 المعالج cumulative_to_delta (فهو وارد في ملف توزيعة Kubernetes)؛ ولمكوّن آخر، راجع هذا الملف أو غيّر الصورة عبر spec.image.

ولـ Collector على كل عقدة مع إثراء k8sattributes، يرد نمط DaemonSet مفصلًا في OpenTelemetry Collector على Kubernetes.

تفعيل القياس التلقائي بالتعليق

الخطوة 3: إعلان مورد Instrumentation

تعرض وثائق مستودع Operator (ترخيص Apache 2.0) الشكل العام للمورد:

مقتطف من README القياس التلقائي في مستودع opentelemetry-operator: مورد Instrumentation v1alpha1 مع exporter endpoint، والناشرات tracecontext وbaggage وb3، والعيّنة parentbased_traceidratio بقيمة 0.25، وصورة Python

مكيَّفًا مع البوابة لدينا:

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: dynatrace
  namespace: boutique
spec:
  exporter:
    endpoint: http://gateway-collector.observability:4317
  propagators:
    - tracecontext
    - baggage
  sampler:
    type: parentbased_traceidratio
    argument: "1"
  python:
    env:
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: http://gateway-collector.observability:4318

الأسطر الحرجة: يغذي propagators المتغير OTEL_PROPAGATORS (والقيمة tracecontext من W3C لتتبع طلب بين الخدمات)؛ ويغذي sampler المتغير OTEL_TRACES_SAMPLER ووسيطه. يصدّر القياس التلقائي لـ Python (كما لـ .NET وGo) بصيغة http/protobuf افتراضيًا: فيجب أن يستهدف المنفذ 4318، ومن هنا تجاوز العنوان.

الخطوة 4: وضع تعليقات على الأحمال

spec:
  template:
    metadata:
      annotations:
        instrumentation.opentelemetry.io/inject-java: "true"

تأخذ القيمة "true" مورد Instrumentation الموجود في الـ namespace؛ ويمكنك أيضًا إعطاء اسم ("dynatrace") أو "autre-namespace/dynatrace"، وتستثني "false" صراحة. ويمكن وضع التعليق على الـ namespace لتغطية كل Pods فيه. وتتبع اللغات الأخرى النموذج نفسه: inject-python وinject-nodejs وinject-dotnet وinject-go (مع otel-go-auto-target-exe وصلاحيات مرتفعة) وinject-apache-httpd وinject-nginx. ولـ Pod متعدد الحاويات، يحدد instrumentation.opentelemetry.io/container-names الحاويات المستهدفة.

يتم الحقن عند إنشاء الـ Pod: أعد تشغيل النشر بالأمر kubectl -n boutique rollout restart deployment/panier.

كيف تتحقق من أن الإعداد يعمل

  1. الموارد موجودة وCollector يعمل:
    kubectl get otelcol -A
    kubectl get otelinst -n boutique
    kubectl -n observability get pods,svc
  2. تلقى Pod التطبيق حاوية init ومتغير الوكيل:
    kubectl -n boutique get pod -l app=panier \
      -o jsonpath='{.items[0].spec.initContainers[*].name}'
    # attendu : opentelemetry-auto-instrumentation-java
    kubectl -n boutique exec deploy/panier -- env | grep -E "JAVA_TOOL_OPTIONS|OTEL_"
  3. يصدّر Collector دون أخطاء:
    kubectl -n observability logs deploy/gateway-collector | grep -iE "error|401|403"
  4. في SaaS، داخل Notebook:
    fetch spans, from: now() - 15m
    | filter k8s.namespace.name == "boutique"
    | summarize spans = count(), by: {service.name}

    يضيف Operator سمات مورد Kubernetes وفق الاصطلاحات الدلالية (semantic conventions)؛ فإن لم يعد المرشّح شيئًا فصفِّ بحسب service.name.

  5. في Managed، افتح عرض التتبعات الموزّعة (distributed traces) وابحث عن الخدمة panier.

لا يصل شيء؟ اتبع تشخيص غياب تتبعات OpenTelemetry.

التعايش مع Dynatrace Operator

إذا كان Dynatrace Operator يحقن OneAgent أصلًا في namespace، فلا تضف إليه القياس التلقائي لـ OpenTelemetry: ستحصل على spans مكررة (انظر OneAgent وOpenTelemetry: تجنب التكرار). افصل بين النطاقات: namespaceSelector في DynaKube، وتعليقات inject-* في OpenTelemetry. ولاحظ أيضًا أن Dynatrace Operator يستطيع ضبط مُصدِّرات OTLP للـ Pods تلقائيًا (.spec.otlpExporterConfiguration)، وهو بديل إن أردت إبقاء القياس داخل الصورة.

أفضل الممارسات

  • ثبّت الإصدارات الخاصة بـ Operator والمخطط وصور القياس؛ فترقية الإصدار تغيّر وكلاء كل الـ Pods عند إعادة التشغيل التالية.
  • مورد Instrumentation واحد لكل namespace، مُدار بإصدارات Git مع ملفات التطبيق.
  • أخذ العيّنات في المكان الصحيح: 100% في الرأس، وقرار دقيق في البوابة (انظر tail sampling في OpenTelemetry).
  • حدود موارد على Collector متوافقة مع memory_limiter.
  • نشر تدريجي: namespace تجريبي، ومقارنة زمن الاستجابة قبل وبعد، ثم التعميم.

الأسئلة الشائعة

هل يلزم cert-manager؟

لا مع Helm: يولّد admissionWebhooks.autoGenerateCert.enabled=true شهادة موقّعة ذاتيًا. أما ملف الإصدار الخاص بـ kubectl apply فيفترض وجود cert-manager.

لماذا لم يُقَس الـ Pod لدي؟

غالبًا لأنه أُنشئ قبل التعليق، أو لأن مورد Instrumentation غير موجود في الـ namespace. وتحقق أيضًا من أن اللغة مفعّلة في Operator (Go وNginx معطّلتان افتراضيًا).

sidecar أم بوابة؟

يُحقن النمط sidecar بالتعليق sidecar.opentelemetry.io/inject ويعزل كل تطبيق. وتستهلك البوابة المشتركة أقل وتُدار من نقطة واحدة؛ فابدأ بها.

الخلاصة

يحوّل OpenTelemetry Operator Kubernetes القياس البرمجي إلى إعداد تصريحي: مورد Collector ومورد Instrumentation وتعليق لكل حمل. تحصل على تتبعات متجانسة دون المساس بالصور، ويزول العمل اليدوي المتكرر (toil) في تحديث الوكلاء. ابدأ بـ namespace واحد، وتحقق من الـ spans في Dynatrace، ثم وسّع.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. تتغير تعريفات CRD وخيارات المخطط وإصدارات الصور، لذا تحقق منها في وثائق OpenTelemetry Operator وفي وثائق Dynatrace. تحقق دائمًا من القيم (المنافذ والإصدارات والأحجام) في الوثائق الرسمية الخاصة بإصدارك.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
OpenTelemetry vs Prometheus (OTel vs Prometheus) : complémentaires ou concurrents ?

OpenTelemetry مقابل Prometheus (OTel vs Prometheus): متكاملان أم متنافسان؟

Next Post
Serveur MCP STDIO : contenir le risque d'exécution de commandes

خادم MCP STDIO: احتواء خطر تنفيذ الأوامر

Related Posts