واجهة FastAPI تبطؤ دون أن تترك أثرًا كابوس حقيقي لفريق المناوبة (on-call): السجلات تقول «200 OK» والمستخدمون يقولون «الخدمة بطيئة». يمنحك تطبيق OpenTelemetry Python FastAPI تتبعات (traces) ومقاييس وسياقًا مشتركًا دون تثبيت OneAgent على المضيف، وهو أمر يتعذر غالبًا في الحاويات المُدارة أو في بيئات serverless.
الهدف: في نهاية هذا الدرس التطبيقي ترسل خدمة FastAPI الخاصة بك وحدات span والمقاييس بصيغة OTLP إلى Dynatrace، مباشرة أو عبر Collector، وتعرف كيف تتحقق من وصول البيانات. المحتوى صالح لـ Dynatrace SaaS (تخزين Grail واستعلامات DQL) ولـ Dynatrace Managed (نقطة نهاية OTLP الخاصة بالبيئة والتحليل في الشاشات الكلاسيكية). نشير إلى الفروق في كل خطوة.
إذا لم تظهر وحدات span في النهاية، فاحتفظ بدليل التشخيص التتبعات المفقودة من OpenTelemetry في Dynatrace في متناول يدك.
المشكلة: واجهة Python معتمة
من دون قياس برمجي (instrumentation) يشبه الطلب البطيء كل الطلبات الأخرى. لا ترى استدعاء HTTP الصادر الذي يستغرق 800 ms ولا استعلام SQL الذي يفتقر إلى فهرس. ويطول MTTR لأن فريق المناوبة يعيد بناء المسار يدويًا. أما مع التتبعات فتظهر مدة كل مرحلة بنقرة واحدة، ويمكنك بناء مؤشر مستوى الخدمة (SLI) موثوق لزمن الاستجابة.
المتطلبات
- Python 3.10 أو أحدث (الحد الأدنى الذي تشترطه الإصدارات الحالية من OpenTelemetry SDK)، مع FastAPI وUvicorn.
- بيئة Dynatrace SaaS أو Managed يتوفر فيها استيعاب OTLP.
- رمز وصول API يحمل النطاقات (scopes)
openTelemetryTrace.ingestوmetrics.ingestوlogs.ingest(تأكد من الأسماء في شاشة إنشاء الرمز). - اختياريًا: OpenTelemetry Collector، وهو موصى به في الإنتاج (انظر Collector من OpenTelemetry على Kubernetes).
تطبيق OpenTelemetry Python FastAPI خطوة بخطوة
الخطوة 1: تطبيق بسيط
# main.py
from fastapi import FastAPI
import httpx
app = FastAPI()
@app.get("/health")
async def health():
return {"status": "ok"}
@app.get("/orders/{order_id}")
async def get_order(order_id: int):
async with httpx.AsyncClient() as client:
r = await client.get("https://httpbin.org/delay/1")
return {"order_id": order_id, "upstream": r.status_code}
الخطوة 2: تثبيت حزم OpenTelemetry
pip install fastapi uvicorn httpx \
opentelemetry-distro \
opentelemetry-exporter-otlp-proto-http
# installs the instrumentations matching the detected libraries
# (fastapi, httpx, requests, sqlalchemy...)
opentelemetry-bootstrap -a install
نقطة حاسمة: استخدم المُصدِّر (exporter) HTTP/protobuf. فنقطة نهاية OTLP في Dynatrace تقبل OTLP عبر HTTP، أما gRPC فيمر عبر Collector.
الخطوة 3: ضبط التصدير إلى Dynatrace
export OTEL_SERVICE_NAME="orders-api"
export OTEL_RESOURCE_ATTRIBUTES="service.version=1.4.2,deployment.environment.name=prod"
# SaaS
export OTEL_EXPORTER_OTLP_ENDPOINT="https://<environment-id>.live.dynatrace.com/api/v2/otlp"
# Managed (instead of the previous line)
# export OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-domain>/e/<environment-id>/api/v2/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token%20<your-token>"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE="delta"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="otlp"
# logs: the opentelemetry-instrumentation-logging package (installed by bootstrap)
# attaches the default handler in recent versions
ثلاثة أسطر تستحق الانتباه:
OTEL_EXPORTER_OTLP_HEADERS: المسافة بينApi-Tokenوالرمز تُرمَّز على شكل%20، وإلا قُرئ الترويس قراءة خاطئة.OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta: يتوقع Dynatrace مقاييس بزمنية دلتا (delta temporality)، أما المقاييس التراكمية (cumulative) فتُرفض. التفاصيل في زمنية مقاييس OTLP.OTEL_SERVICE_NAME: هو اسم الخدمة في Dynatrace. من دونه ستحصل علىunknown_service.
يضيف المُصدِّر بنفسه /v1/traces و/v1/metrics و/v1/logs إلى نقطة النهاية الأساسية. لا تكتبها في OTEL_EXPORTER_OTLP_ENDPOINT.
بالنسبة إلى السجلات، يفعّل المتغير القديم OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true المعالج LoggingHandler في SDK، وهو مُهمَل (deprecated) منذ opentelemetry-sdk 1.40. مع الإصدارات الحديثة اترك المتغير غير معرَّف: فالقياس البرمجي logging يثبّت معالجه الخاص (ويمكن تعطيله بـ OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION=false). أما في الإصدارات الأقدم فيظل المتغير القديم لازمًا.
الخطوة 4: تشغيل التطبيق المقيس
opentelemetry-instrument uvicorn main:app --host 0.0.0.0 --port 8000
لا تستخدم --reload مع القياس البرمجي التلقائي: فالعملية الابنة المُعاد تشغيلها لا ترث القياس دائمًا. ومع عدة عمليات عاملة (workers) في Gunicorn، هيّئ SDK بعد الاستنساخ (fork)، داخل الخطاف post_fork، وإلا لن تعمل المُصدِّرات في الخلفية عملًا سليمًا.
الخطوة 5 (بديل): قياس برمجي صريح في الشيفرة
إذا كنت تفضّل التحكم في التهيئة، كإضافة وحدات span خاصة بالأعمال مثلًا، فاضبط SDK داخل الشيفرة:
# telemetry.py
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
def setup_tracing(app):
resource = Resource.create({
"service.name": "orders-api",
"service.version": "1.4.2",
})
provider = TracerProvider(resource=resource)
# endpoint and headers are read from the OTEL_EXPORTER_OTLP_* variables
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)
FastAPIInstrumentor.instrument_app(app, excluded_urls="health")
HTTPXClientInstrumentor().instrument()
# in main.py
from opentelemetry import trace
from telemetry import setup_tracing
setup_tracing(app)
tracer = trace.get_tracer("orders")
@app.post("/orders")
async def create_order(payload: dict):
with tracer.start_as_current_span("validate-order") as span:
span.set_attribute("order.items", len(payload.get("items", [])))
return {"created": True}
السطر الحاسم: excluded_urls="health" يستبعد فحوص الصحة من التتبعات. فهي تشوّه النسب المئوية لزمن الاستجابة وتستهلك حجمًا بلا فائدة.
الخطوة 6: المرور عبر Collector في الإنتاج
وجّه التطبيق إلى Collector المحلي (http://otel-collector:4318) ودع الـ Collector يحمل الرمز. تكسب بذلك التجميع في دفعات (batching) وإعادة المحاولة (retries) ونقطة ضبط واحدة. ثم يصدّر الـ Collector باستخدام otlphttp:
exporters:
otlphttp/dynatrace:
endpoint: "https://<environment-id>.live.dynatrace.com/api/v2/otlp"
headers:
Authorization: "Api-Token ${env:DT_API_TOKEN}"
كيف تتحقق من أن كل شيء يعمل
- من جهة التطبيق: في الاختبار المحلي أضف
OTEL_TRACES_EXPORTER=otlp,console. ستظهر وحدات span في المخرجات القياسية؛ فإن ظهرت هناك ولم تظهر في Dynatrace فالمشكلة في التصدير (العنوان أو الرمز أو الوكيل proxy). - ولّد حركة مرور:
for i in $(seq 1 20); do curl -s localhost:8000/orders/$i; done. - Dynatrace SaaS: افتح تطبيق Distributed Tracing وصفِّ حسب الخدمة
orders-api، أو نفّذ في دفتر ملاحظات (notebook):fetch spans | filter service.name == "orders-api" | summarize count(), avg(duration), by: {span.name} - Dynatrace Managed: افتح عرض التتبعات الموزّعة (الاسم الدقيق يتبع إصدارك) وصفِّ حسب الخدمة. قد تستغرق خدمة OTel بضع دقائق لتظهر.
- أخطاء HTTP: يدل الرمز 401 أو 403 في سجلات المُصدِّر على رمز أو نطاق (scope) غير صحيح، ويدل 404 على عنوان نقطة نهاية خاطئ.
أفضل الممارسات
- لا تجمع OneAgent وOTel SDK في العملية نفسها دون تفكير: خطر التكرار (انظر OneAgent وOpenTelemetry: تكرار وحدات span).
- ثبّت
service.nameوservice.versionوالبيئة: فهي تجعل عمليات النشر قابلة للمقارنة وتسرّع التشخيص. - أبقِ الرمز خارج الشيفرة: متغير بيئة أو secret في Kubernetes.
- اربط سجلاتك بالتتبعات لتنتقل من الخطأ إلى طلبه: انظر سجلات OpenTelemetry مع trace_id.
- ابنِ مؤشر SLI لزمن الاستجابة على وحدات span الخاصة بالخادم، ثم أضف تنبيهًا على معدل الاستهلاك (burn rate).
الأسئلة الشائعة
هل أحتاج إلى OneAgent لأرى تطبيق FastAPI في Dynatrace؟
لا. يكفي تصدير OTLP للتتبعات والمقاييس والسجلات. يضيف OneAgent الاكتشاف التلقائي للمضيف والعمليات؛ ومن دونه يعتمد الإثراء على سمات المورد (resource attributes) التي تقدمها بنفسك.
لماذا لا تصل مقاييسي بينما تصل التتبعات؟
في الغالب بقيت الزمنية تراكمية (cumulative) أو لا يملك الرمز نطاق استيعاب المقاييس. تحقق من متغير تفضيل الزمنية ومن النطاقات.
هل يعمل القياس البرمجي التلقائي مع Gunicorn وعدة عمليات عاملة؟
نعم، بشرط تهيئة SDK في كل عملية عاملة بعد الاستنساخ (fork). تصف وثائق OpenTelemetry Python هذه الحالة؛ فاختبرها قبل الإنتاج.
الخلاصة
تكفي بضعة متغيرات بيئة وأمر تشغيل واحد لجعل واجهة FastAPI قابلة للملاحظة في Dynatrace، في SaaS كما في Managed. ابدأ بالقياس البرمجي التلقائي، وتحقق من وصول البيانات، ثم أضف وحدات span خاصة بالأعمال حيث يحتاجها فريق المناوبة. للاطلاع على تفاصيل نقاط النهاية راجع وثائق Dynatrace حول OpenTelemetry ووثائق OpenTelemetry Python.
span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. تحقق دائمًا من القيم (المنافذ والإصدارات والأحجام) في الوثائق الرسمية الخاصة بإصدارك.