رمز API في Dynatrace: استكشاف أخطاء النطاقات والأخطاء 401 و403 (OTLP وAPI v2)

رمز API في Dynatrace مرفوض؟ شخّص أخطاء 401 و403 و404 في OTLP وAPI v2: صيغة الترويسة والنطاقات وانتهاء الصلاحية وتصحيح Collector.
Token API Dynatrace : dépanner les scopes et les erreurs 401 et 403 (OTLP, API v2)

يعمل OpenTelemetry Collector لديك، لكن لا يصل شيء إلى Dynatrace. وفي سجلاته يتكرر سطر واحد: 401 Unauthorized أو 403 Forbidden. في تسع حالات من عشر يكون السبب هو رمز API في Dynatrace: صيغة ترويسة خاطئة، أو نطاق (scope) ناقص، أو رمز منتهي الصلاحية، أو مرسل إلى بيئة خاطئة.

هذا الاستكشاف مكلف في المناوبة (on-call): وأنت تبحث تضيع التتبعات والمقاييس والسجلات، وتصبح أهداف مستوى الخدمة (SLO) المحسوبة عليها خاطئة. التشخيص المنهجي يختصر هذا الوقت إلى دقائق ويخفض زمن الاستعادة (MTTR) في حوادث استيعاب البيانات.

هدف هذا الدرس: أن تحدد في أقل من عشر دقائق سبب رفض الطلب، سواء لاستيعاب OTLP أو لـ API v2. المحتوى صالح لـ Dynatrace SaaS وDynatrace Managed؛ وتُذكر فروق عناوين URL والرموز في كل خطوة.

401 أم 403: ماذا يقول الرمز فعلًا

لا يحكي الرمزان القصة نفسها. والتمييز بينهما يوفر عليك الدوران في حلقة مفرغة.

الرمز المعنى أسباب شائعة
401 المتصل غير مصادَق عليه ترويسة غائبة أو سيئة الصياغة، أو رمز مُلغى أو منتهٍ أو منسوخ خطأً أو تابع لبيئة أخرى
403 المتصل مصادَق عليه لكن لا يملك الحق نطاق ناقص في الرمز، أو رمز معطَّل في بعض الحالات، أو قيد على مستوى البيئة
404 العنوان لا يطابق شيئًا معرّف بيئة خاطئ، أو نسيان المسار /e/<env-id> في Managed

احفظ القاعدة: يُحَل الخطأ 401 على مستوى الرمز أو الترويسة، ويُحَل الخطأ 403 على مستوى النطاقات. وغالبًا ما تساعد رسالة الخطأ الدقيقة في جسم الاستجابة على الحسم: اقرأها دائمًا.

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

  • بيئة Dynatrace SaaS أو Managed، وحق إدارة الرموز (صلاحية بيئة مناسبة).
  • curl وjq على جهاز يصل إلى البيئة (أو إلى ActiveGate).
  • الرمز المراد اختباره في متغير بيئة، وليس نصًا صريحًا في ملف خاضع للإصدارات.
  • رمز وصول ثانٍ صالح لخطوة التحقق: يقبل استدعاء lookup رمزًا تقليديًا بأي نطاق (أو رمز منصة بالصلاحية api-tokens:tokens:read).

استكشاف رمز API في Dynatrace خطوة بخطوة

الخطوة 1: التحقق من عنوان URL للبيئة

قبل اتهام الرمز، تحقق من العنوان. تختلف الصيغ بحسب نمط النشر:

# Dynatrace SaaS
export DT_URL="https://<env-id>.live.dynatrace.com"

# Dynatrace Managed (cluster)
export DT_URL="https://<votre-domaine>/e/<env-id>"

# Via un Environment ActiveGate (SaaS ou Managed)
export DT_URL="https://<activegate>:9999/e/<env-id>"

export DT_API_TOKEN="dt0c01.XXXX.YYYY"

الرمز المنشأ في البيئة A لا يعمل في البيئة B. وفي Managed متعدد البيئات هذا أول أسباب 401 التي نصادفها.

الخطوة 2: فحص صيغة الترويسة

تتوقع API البيئة المخطط Api-Token وليس Bearer:

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Api-Token ${DT_API_TOKEN}" \
  "${DT_URL}/api/v2/metrics?pageSize=1"

الأسطر الحرجة: الكلمة Api-Token يليها فراغ، ثم الرمز كاملًا. يبدأ الرمز التقليدي بـ dt0c01. ويحوي نقطتَي فصل. وإذا كانت السلسلة مبتورة (نسخ من طرفية ضيقة، أو سطر جديد داخل سر Kubernetes) فستحصل على 401.

في SaaS، تُرسَل رموز المنصة وعملاء OAuth المستخدمة في التطبيقات وAPI المنصة بالمخطط Bearer. وتقبل OTLP API العائلتين، لكل منهما مخططها ونطاقاتها (openpipeline:traces:ingest وغيرها لرمز المنصة). لا تخلط بينهما: رمز المنصة المرسل بالمخطط Api-Token سيُرفض. تحقق من نوع الرمز الذي تتوقعه كل API في صفحة المصادقة في الوثائق.

الخطوة 3: قراءة النطاقات الفعلية للرمز

تتيح API v2 الاطلاع على البيانات الوصفية لرمز دون عرضه في الواجهة. يُجرى الاستدعاء بالرمز الثاني، ويُرسَل الرمز المراد فحصه في الجسم:

curl -s -X POST "${DT_URL}/api/v2/apiTokens/lookup" \
  -H "Authorization: Api-Token ${DT_ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"token\": \"${DT_API_TOKEN}\"}" | jq '{name, enabled, expirationDate, scopes}'

تبيّن الاستجابة هل الرمز نشط، وتاريخ انتهائه، وقائمة نطاقاته. ثلاث حالات شائعة:

  • enabled: false: عطّله أحدهم، غالبًا بعد تنبيه تسرّب سر؛
  • expirationDate متجاوَز: انتهت صلاحية الرمز ويجب إنشاء رمز جديد؛
  • النطاق المتوقع غائب: وهذا تفسير الخطأ 403 لديك.

الخطوة 4: مطابقة النطاق مع الاستدعاء

تتطلب كل نقطة وصول نطاقًا محددًا. هذه أشيع المطابقات؛ وتحقق من الاسم الدقيق في شاشة إنشاء الرمز، التي تعرض التسمية والمعرّف التقني معًا:

الاستخدام نقطة الوصول النطاق
تتبعات OTLP /api/v2/otlp/v1/traces openTelemetryTrace.ingest
مقاييس OTLP /api/v2/otlp/v1/metrics metrics.ingest
سجلات OTLP /api/v2/otlp/v1/logs logs.ingest
قراءة الكيانات /api/v2/entities entities.read
قراءة المشكلات /api/v2/problems problems.read
كائنات الإعداد /api/v2/settings/objects settings.read / settings.write

فخ كلاسيكي: Collector يرسل التتبعات والمقاييس والسجلات برمز واحد لا يملك إلا openTelemetryTrace.ingest. تمر التتبعات، ويُرجع المساران الآخران 403. فيصدّر Collector جزءًا فقط من القياسات عن بُعد، وهذا أصعب كشفًا من توقف كامل.

الخطوة 5: تصحيح إعداد Collector

إعداد نظيف للمُصدِّر، مع حقن الرمز عبر متغير بيئة:

exporters:
  otlphttp/dynatrace:
    endpoint: "${env:DT_URL}/api/v2/otlp"
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/dynatrace]
    metrics:
      receivers: [otlp]
      processors: [cumulativetodelta, batch]
      exporters: [otlphttp/dynatrace]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/dynatrace]

الأسطر الحرجة: ينتهي endpoint عند /api/v2/otlp (يضيف المُصدِّر /v1/traces و/v1/metrics و/v1/logs)؛ وتستعيد الترويسة المخطط Api-Token. لتفاصيل Collector راجع دليل تثبيت OpenTelemetry Collector لـ Dynatrace.

في Kubernetes، أنشئ السر دون سطر جديد طفيلي:

kubectl create secret generic dynatrace-otlp \
  --from-literal=DT_API_TOKEN="${DT_API_TOKEN}" \
  -n observability

تجنّب echo "$TOKEN" | base64 في ملف manifest: يضيف echo سطرًا جديدًا أخيرًا يُرمَّز مع الباقي، فيصبح الرمز المستلَم غير صالح.

كيف تتحقق من أن كل شيء يعمل

  1. أعد الاستدعاء في الخطوة 2: الرمز المتوقع هو 200.
  2. أرسل تتبعًا اختباريًا أدنى إلى نقطة وصول OTLP؛ لا تقبل OTLP API في Dynatrace إلا protobuf الثنائي (لا JSON)؛ ويكفي جسم protobuf فارغ لاختبار المصادقة:
    curl -s -o /dev/null -w "%{http_code}\n" -X POST \
      -H "Authorization: Api-Token ${DT_API_TOKEN}" \
      -H "Content-Type: application/x-protobuf" \
      --data-binary "" \
      "${DT_URL}/api/v2/otlp/v1/traces"

    رمز من عائلة 2xx يؤكد المصادقة والنطاق؛ أما 401 أو 403 فيُحيلانك إلى الخطوات من 2 إلى 4.

  3. في سجلات Collector يجب أن تختفي أخطاء التصدير: الأمر kubectl logs deploy/otel-collector -n observability | grep -iE "401|403" لا يُرجع شيئًا بعد ذلك.
  4. في SaaS، يؤكد استعلام DQL وصول البيانات: fetch spans, from:now()-15m | summarize count(), by:{service.name}. وفي Managed افتح عرض الخدمات أو التتبعات الموزّعة (distributed tracing) وابحث عن الخدمة المُرسِلة.

إذا غابت البيانات رغم نجاح المصادقة فالمشكلة في مكان آخر: راجع غياب تتبعات OpenTelemetry في Dynatrace.

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

  • رمز لكل استخدام: رمز استيعاب لـ Collector وآخر للأتمتة. فلا يكشف أي تسرّب إلا نطاقًا محدودًا.
  • أقل امتياز: أضف النطاقات اللازمة فقط. لا سبب لرمز استيعاب أن يكتب الإعدادات.
  • تاريخ انتهاء وتدوير مجدول، مع تنبيه قبل الموعد بدل توقف في يوم الانتهاء.
  • اسم واضح: الفريق والاستخدام والتاريخ في اسم الرمز. فيصبح الـ lookup مقروءًا فورًا.
  • مراقبة الاستيعاب: يكشف تنبيه على هبوط الحجم المستلَم رمزًا منتهيًا قبل المستخدمين. راجع مراقبة OpenTelemetry Collector.
  • في Managed، تذكّر الفصل بين رموز البيئة ورموز Cluster API، المفصّل في الأتمتة عبر Cluster API.

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

هل يمكنني إضافة نطاق إلى رمز موجود؟

بحسب الإصدار، تتيح الواجهة تعديل بعض الرموز، لكن القيمة السرية لا تُعرض مجددًا أبدًا. الممارسة الأكثر أمانًا أن تنشئ رمزًا جديدًا بالنطاقات الصحيحة، وتنشره، ثم تلغي القديم.

لماذا أحصل على 401 مع رمز يعمل في curl؟

قارن السلسلة التي يتلقاها التطبيق فعلًا: علامات اقتباس زائدة في ملف YAML، أو سطر جديد أخير في سر، أو متغير بيئة غير محلول (فيرسل Collector حرفيًا ${env:DT_API_TOKEN}). فعّل مؤقتًا سجلات debug في العميل للتحقق من الترويسة، دون الاحتفاظ بها أبدًا في الإنتاج.

هل يعمل رمز Managed بعد الترحيل إلى SaaS؟

لا. الرموز مرتبطة ببيئتها. بعد الترحيل، أعد إنشاء الرموز في بيئة SaaS وحدّث كل عميل يستخدمها.

الخلاصة

يُحَل الخطأ 401 على مستوى الرمز أو الترويسة، والخطأ 403 على مستوى النطاقات، والخطأ 404 على مستوى العنوان. وبفضل استدعاء الاختبار والـ lookup للرمز يتم التشخيص في بضعة أوامر. أضف تدويرًا مجدولًا وتنبيهًا على الحجم المستوعَب: فلن يكون الانتهاء القادم حادثة.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC. Dynatrace علامة تجارية لشركة Dynatrace LLC. تتغير أسماء النطاقات والشاشات: تحقق منها في الوثائق الرسمية الخاصة بإصدارك.

Total
0
Shares
Leave a Reply

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

Previous Post
Réduire bruit, alertes et fatigue d'astreinte : régler Davis et les profils d'alerte

تقليل ضجيج التنبيهات وإرهاق المناوبة: ضبط Davis وملفات التنبيه

Next Post
Requêtes DQL exemples : 15 requêtes prêtes à copier avec DQL summarize, filter et timeseries

أمثلة استعلامات DQL: 15 استعلامًا جاهزًا للنسخ مع DQL summarize وfilter وtimeseries

Related Posts