پیاده‌سازی Instrumentation با OpenTelemetry

به گزارش از وبسایت redhat

دیدگاهی تازه نسبت به توسعهٔ ابری دیگر یک تجمل نیست، بلکه یک ضرورت است. با گذار از معماری‌های یکپارچه به ریزسرویس‌های توزیع‌شده در OpenShift، پیگیری درخواست‌ها در مرزهای سرویس‌ها به‌شدت پیچیده می‌شود. قابلیت مشاهده (observability) معمولاً مانند حل کردن یک پازل با قطعات گمشده است، و در این میان OpenTelemetry (OTel) در Red Hat OpenShift به‌عنوان استاندارد طلایی برای جمع‌آوری traces، metrics و logs مطرح شده است. 🔍

این راهنما نشان می‌دهد چگونه از build Red Hat OpenTelemetry و امکانات ابزارسازی خودکار آن برای دستیابی به قابلیت مشاهدهٔ کامل پشته بدون تغییر در کد منبع برنامه‌ها استفاده کنید. نصب از مسیر اپراتور، مدیریتی کارآمد برای نگهداری و به‌روزرسانی فراهم می‌آورد. هرچند تمرکز بر تزریق بدون تغییر کد است، معماری و پیکربندی‌های جمع‌آوری که در ادامه آمده‌اند برای هر پیاده‌سازی OpenTelemetry در OpenShift — از جمله ادغام دستی SDK یا خطوط لوله تله‌متری سفارشی — نیز کاربرد دارند. 🧩

ابزارسازی خودکار نقش تعیین‌کننده‌ای دارد؛ ابزارسازی دستی برای صدها میکروسرویس در مقیاس سازمانی عملی و قابل اتکا نیست. ابزار دقیق خودکار مزایای کلیدی زیر را ارائه می‌کند:

🔄 مدیریت چرخهٔ زندگی: به‌روزرسانی‌ها و پیکربندی collector را خودکار می‌کند.

⚙️ ابزارسازی خودکار: به‌طور خودکار کتابخانه‌های OTel را به برنامه‌های Go، Java، Node.js، Python، .NET و سرور Apache HTTP (httpd) تزریق می‌کند، بدون نیاز به تغییرات دستی در کد.

✅ استانداردسازی: اطمینان می‌دهد که همهٔ تیم‌ها در سراسر سازمان از قراردادهای معنایی و پروتکل‌های صادراتی یکسان استفاده کنند.

مرحله 1: اپراتور را نصب کنید 🛠️

Red Hat build of OpenTelemetry Operator تنها یک نصاب نیست، بلکه یک موتور مدیریت است. ساده‌ترین روش شروع از طریق کنسول وب OpenShift است:

1. با امتیازات سرپرست به کنسول وب OpenShift وارد شوید.

2. به Operators > OperatorHub بروید و ساخت Red Hat OpenTelemetry را جستجو کنید.

3. Install را انتخاب کنید؛ در صفحهٔ نصب، کانال را روی stable و حالت نصب را روی All namespaces (استراتژی) قرار دهید و نصب را آغاز کنید تا وضعیت «موفق شد» نمایش داده شود.

نکته: اپراتور مدیریت گواهی را نیز نصب کنید، زیرا اپراتور OpenTelemetry از آن برای مدیریت webhookهای پذیرش استفاده می‌کند.

مرحله 2: یک نمونهٔ Collector ایجاد کنید

پس از فعال شدن اپراتور، باید یک منبع سفارشی OpenTelemetryCollector (CR) تعریف کنید که هاب مرکزی داده‌های تله‌متری شما خواهد بود. حالت استقرار (deployment) برای یک نقطهٔ شروع استاندارد پیشنهاد می‌شود؛ این حالت یک سرویس متمرکز برای دریافت، پردازش و صادرات داده‌ها فراهم می‌آورد. به‌عنوان مثال، برای راه‌اندازی گیرنده‌ای که داده‌ها را برای اشکال‌زدایی ثبت می‌کند، از پیکربندی زیر استفاده کنید:

configuration:apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: hotel
  namespace: otel-demo
spec:
  mode: deployment
  config:
    receivers:
      otlp:
        protocols:
          grpc: {}
          http: {}
    processors:
      batch: {}
    exporters:
      logging:
        verbosity: detailed
    service:
      pipelines:
        traces:
          receivers: [otlp]
          processors: [batch]
          exporters: [logging]

برای ایجاد پروژهٔ جدید می‌توانید از دستور زیر استفاده کنید:

oc new-project otel-demo

از گزارش‌های oc برای مشاهدهٔ ردیابی‌ها در طول آزمایش استفاده کنید.

مرحله 3: ابزارسازی خودکار (بخش جادویی)

یکی از قابلیت‌های کلیدی در OpenShift، منابع Instrumentation CR هستند که موتور ابزارسازی خودکار را کنترل می‌کنند. این CR مشخص می‌کند داده‌ها به کجا ارسال شوند و چگونه عوامل (agents) تزریق‌شده پیکربندی گردند. به‌جای تنظیم جداگانه برای هر برنامه، این تنظیمات را یک‌بار تعریف می‌کنید، مثلاً:

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: my-instrumentation
  namespace: otel-demo
spec:
  exporter:
    env:
      - name: OTEL_SEMCONV_STABILITY_OPT_IN
        value: http
    endpoint: http://otel-collector:4317
  propagators:
    - tracecontext
    - baggage
  sampler:
    type: parentbased_traceidratio
    argument: "1"
  dotnet:
    env:
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: 'http://otel-collector:4318'
  java:
    resources:
      limits: {}
      requests: {}
  nodejs:
    env:
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: 'http://otel-collector:4318'
      - name: OTEL_METRICS_EXPORTER
        value: otlp
  python:
    env:
      - name: OTEL_EXPORTER_OTLP_ENDPOINT
        value: http://otel-collector:4318

نکته: از متغیر محیطی OTEL_SEMCONV_STABILITY_OPT_IN برای هماهنگ نگه‌داشتن قراردادهای معنایی HTTP بین زبان‌ها استفاده می‌کنیم تا از ناسازگاری نام‌گذاری فیلدها جلوگیری گردد.

برای نسخهٔ 2 از کتابخانهٔ ابزارسازی Java می‌توانید از تصویر زیر استفاده کنید:

java:
  env:
    - name: OTEL_EXPORTER_OTLP_ENDPOINT
      value: 'http://otel-collector:4318'
  image: 'ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.23.0'

مرحله 4: استقرار چندزبانه و ابزارسازی خودکار

مزیت واقعی OTel در OpenShift زمانی نمود پیدا می‌کند که میکروسرویس‌های چندزبانه را اجرا کنید. اپراتور با اضافه کردن یک annotation به Deployment YAML، عوامل لازم را در زمان اجرا تزریق می‌کند.

برای برنامه‌های Java، اپراتور یک agent جاوا را به‌وسیلهٔ initContainer تزریق کرده و با دستکاری bytecode فریم‌ورک‌هایی مانند Spring Boot، Quarkus و Hibernate را ابزارسازی می‌کند. نمونهٔ annotation:

instrumentation.opentelemetry.io/inject-java: "true"

می‌توانید یک استقرار موجود را با دستور زیر وصله (patch) کنید:

oc patch deployment java-demo --type='json' -p='[{"op": "add", "path": "/spec/template/metadata/annotations", "value": {"instrumentation.opentelemetry.io/inject-java": "true"}}]'

برای برنامه‌های Python، اپراتور فرمان اجرا را طوری می‌بندد که کتابخانه‌های OTel قبل از اجرای برنامه بارگذاری شوند. مثال:

instrumentation.opentelemetry.io/inject-python: "true"

برای Node.js، اپراتور از فلگ –require برای بارگیری OTel SDK پیش از کد برنامه استفاده می‌کند و تماس‌های دیتابیس و HTTP را ضبط می‌نماید:

instrumentation.opentelemetry.io/inject-nodejs: "true"

اگر نمونهٔ برنامهٔ Java ندارید، می‌توانید از نمونهٔ OpenShift Java استفاده کنید یا نمونه‌های بیشتری در منابع رسمی بیابید.

مرحله 5: بررسی جریان و عیب‌یابی 🔎

برای اطمینان از عملکرد، گزارش‌های جمع‌آورنده را بررسی کنید:

oc logs deployment/otel-collector -n otel-demo

اگر ردیابی‌ها یا معیارها در لاگ‌ها چاپ می‌شوند، خط لوله فعال است. برای عیب‌یابی ساده می‌توانید یک درخواست آزمایشی به نقطهٔ پایانی OTLP/HTTP ارسال کنید:

curl -X POST http://otel-collector:4318/v1/traces 
  -H "Content-Type: application/json" 
  -d '{"resourceSpans": [{"resource": {"attributes": [{"key": "service.name", "value": {"stringValue": "test-app"}}]}, "scopeSpans": [{"spans": [{"traceId": "4bf92f3577b34da6a3ce929d0e0e4736", "spanId": "00f067aa0ba902b7", "name": "test-span", "kind": 1, "startTimeUnixNano": "1625083652223456789", "endTimeUnixNano": "1625083652233456789"}]}]}]}'

ادغام OpenTelemetry با Tempo

صادرکنندهٔ logging برای آزمایش مفید است، اما در محیط‌های تولید به یک backend قابل اعتماد نیاز دارید. Tempo یک راه‌حل مقیاس‌پذیر برای tracing توزیع‌شده است که توسط Red Hat پشتیبانی می‌شود. برای اتصال OTel به Tempo، CR جمع‌آوری را طوری به‌روزرسانی کنید که صادرکنندهٔ otlp/tempo را شامل شود.

پیش‌نیازها:

– اپراتور Tempo نصب شده باشد.

– TempoStack پیکربندی شده باشد و endpoint آن را شناسایی کرده باشید. معمولاً نقطهٔ پایانی OTLP (gRPC) سرویس داخلی از الگوی زیر پیروی می‌کند:

http://-distributor..svc:4317

نکته: در صورت فعال بودن mTLS یا احراز هویت داخلی، ممکن است لازم باشد یک token حساب سرویس یا گواهی به collector ارائه دهید.

نمونهٔ به‌روزرسانی OpenTelemetryCollector برای ارسال به Tempo:

apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  name: hotel
  namespace: otel-demo
spec:
  mode: deployment
  config:
    extensions:
      # create extension
      bearertokenauth:
        file: "/var/run/secrets/kubernetes.io/serviceaccount/token"
    receivers:
      otlp:
        protocols:
          grpc: {}
          http: {}
    processors:
      batch:
        # batching is critical for performance when sending to Tempo
        send_batch_size: 1000
        timeout: 10s
    exporters:
      otlp/tempo:
        # Replace with your actual TempoStack service name and namespace
        endpoint: "tempo-simplest-gateway.tempo-demo.svc:8090"
        tls:
          insecure: false
          ca_file: "/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt"
        auth:
          authenticator: bearertokenauth
        headers:
          X-Scope-OrgID: "dev"
    service:
      extensions: [bearertokenauth]
      pipelines:
        traces:
          receivers: [otlp]
          processors: [batch]
          exporters: [otlp/tempo]

در این مثال، TempoStack ساده‌ترین نمونه در namespace به‌نام tempo-demo فرض شده است. در صورت استفاده از RBAC، دسترسی‌های موردنیاز را به collector اعطا کنید.

جمع‌بندی 😊

استقرار build Red Hat OpenTelemetry در OpenShift و بهره‌گیری از اپراتور و Instrumentation CR امکان دستیابی به مشاهدهٔ گستردهٔ پشته را بدون تغییرات کد منبع فراهم می‌کند. این رویکرد به‌ویژه برای محیط‌های چندزبانه و سازمان‌های بزرگ که به استانداردسازی و مدیریت متمرکز نیاز دارند، بسیار موثر است. در نهایت، اتصال به بک‌اندهایی مانند Tempo تجربهٔ tracing را در سطح تولید قابل‌اطمینان و مقیاس‌پذیر می‌سازد.