قياس عشرين خدمة مصغّرة يدويًا يعني عشرين 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) الشكل العام للمورد:

مكيَّفًا مع البوابة لدينا:
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.
كيف تتحقق من أن الإعداد يعمل
- الموارد موجودة وCollector يعمل:
kubectl get otelcol -A kubectl get otelinst -n boutique kubectl -n observability get pods,svc - تلقى 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_" - يصدّر Collector دون أخطاء:
kubectl -n observability logs deploy/gateway-collector | grep -iE "error|401|403" - في SaaS، داخل Notebook:
fetch spans, from: now() - 15m | filter k8s.namespace.name == "boutique" | summarize spans = count(), by: {service.name}يضيف Operator سمات مورد Kubernetes وفق الاصطلاحات الدلالية (semantic conventions)؛ فإن لم يعد المرشّح شيئًا فصفِّ بحسب
service.name. - في 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. تحقق دائمًا من القيم (المنافذ والإصدارات والأحجام) في الوثائق الرسمية الخاصة بإصدارك.