تصدير OpenTelemetry

​

كيف يترابط هذا معًا

• أحداث التشخيصات هي سجلات منظمة داخل العملية تصدرها Gateway وPlugins المضمّنة لعمليات تشغيل النموذج وتدفق الرسائل والجلسات والطوابير وexec.
• يشترك Plugin diagnostics-otel في تلك الأحداث ويصدرها على هيئة OpenTelemetry metrics وtraces وlogs عبر OTLP/HTTP.
• تتلقى استدعاءات المزوّد ترويسة W3C traceparent من سياق Span الموثوق الخاص باستدعاء النموذج في OpenClaw عندما يقبل نقل المزوّد الترويسات المخصصة. ولا يتم نشر سياق التتبع الصادر عن Plugin.
• لا يتم إرفاق المصدّرات إلا عندما يكون كل من سطح التشخيصات وPlugin مفعّلين، بحيث تبقى الكلفة داخل العملية قريبة من الصفر افتراضيًا.

​

البدء السريع

{
  plugins: {
    allow: ["diagnostics-otel"],
    entries: {
      "diagnostics-otel": { enabled: true },
    },
  },
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      protocol: "http/protobuf",
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2,
      flushIntervalMs: 60000,
    },
  },
}

openclaw plugins enable diagnostics-otel

​

الإشارات المُصدّرة

​

مرجع الإعدادات

{
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      tracesEndpoint: "http://otel-collector:4318/v1/traces",
      metricsEndpoint: "http://otel-collector:4318/v1/metrics",
      logsEndpoint: "http://otel-collector:4318/v1/logs",
      protocol: "http/protobuf", // grpc is ignored
      serviceName: "openclaw-gateway",
      headers: { "x-collector-token": "..." },
      traces: true,
      metrics: true,
      logs: true,
      sampleRate: 0.2, // root-span sampler, 0.0..1.0
      flushIntervalMs: 60000, // metric export interval (min 1000ms)
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
      },
    },
  },
}

​

متغيرات البيئة

​

الخصوصية والتقاط المحتوى

• inputMessages — محتوى مطالبة المستخدم.
• outputMessages — محتوى استجابة النموذج.
• toolInputs — حمولات وسائط الأدوات.
• toolOutputs — حمولات نتائج الأدوات.
• systemPrompt — مطالبة النظام/المطوّر المجمعة.

​

أخذ العينات والتفريغ

• Traces: ‏diagnostics.otel.sampleRate (لنطاق الجذر فقط، 0.0 يسقط الكل، و1.0 يحتفظ بالكل).
• Metrics: ‏diagnostics.otel.flushIntervalMs (الحد الأدنى 1000).
• Logs: تحترم سجلات OTLP قيمة logging.level (مستوى سجل الملف). ولا ينطبق تنقيح وحدة التحكم على سجلات OTLP. ويجب على التثبيتات كبيرة الحجم أن تفضّل أخذ العينات/التصفية في مجمّع OTLP بدلًا من أخذ العينات محليًا.

​

المقاييس المُصدّرة

​

استخدام النموذج

• openclaw.tokens ‏(counter، السمات: openclaw.token وopenclaw.channel وopenclaw.provider وopenclaw.model وopenclaw.agent)
• openclaw.cost.usd ‏(counter، السمات: openclaw.channel وopenclaw.provider وopenclaw.model)
• openclaw.run.duration_ms ‏(histogram، السمات: openclaw.channel وopenclaw.provider وopenclaw.model)
• openclaw.context.tokens ‏(histogram، السمات: openclaw.context وopenclaw.channel وopenclaw.provider وopenclaw.model)
• gen_ai.client.token.usage ‏(histogram، مقياس semantic-conventions لـ GenAI، السمات: gen_ai.token.type = input/output وgen_ai.provider.name وgen_ai.operation.name وgen_ai.request.model)
• gen_ai.client.operation.duration ‏(histogram، بالثواني، مقياس semantic-conventions لـ GenAI، السمات: gen_ai.provider.name وgen_ai.operation.name وgen_ai.request.model وerror.type الاختيارية)

​

تدفق الرسائل

• openclaw.webhook.received ‏(counter، السمات: openclaw.channel وopenclaw.webhook)
• openclaw.webhook.error ‏(counter، السمات: openclaw.channel وopenclaw.webhook)
• openclaw.webhook.duration_ms ‏(histogram، السمات: openclaw.channel وopenclaw.webhook)
• openclaw.message.queued ‏(counter، السمات: openclaw.channel وopenclaw.source)
• openclaw.message.processed ‏(counter، السمات: openclaw.channel وopenclaw.outcome)
• openclaw.message.duration_ms ‏(histogram، السمات: openclaw.channel وopenclaw.outcome)
• openclaw.message.delivery.started ‏(counter، السمات: openclaw.channel وopenclaw.delivery.kind)
• openclaw.message.delivery.duration_ms ‏(histogram، السمات: openclaw.channel وopenclaw.delivery.kind وopenclaw.outcome وopenclaw.errorCategory)

​

الطوابير والجلسات

• openclaw.queue.lane.enqueue ‏(counter، السمات: openclaw.lane)
• openclaw.queue.lane.dequeue ‏(counter، السمات: openclaw.lane)
• openclaw.queue.depth ‏(histogram، السمات: openclaw.lane أو openclaw.channel=heartbeat)
• openclaw.queue.wait_ms ‏(histogram، السمات: openclaw.lane)
• openclaw.session.state ‏(counter، السمات: openclaw.state وopenclaw.reason)
• openclaw.session.stuck ‏(counter، السمات: openclaw.state)
• openclaw.session.stuck_age_ms ‏(histogram، السمات: openclaw.state)
• openclaw.run.attempt ‏(counter، السمات: openclaw.attempt)

​

دورة حياة Harness

• openclaw.harness.duration_ms ‏(histogram، السمات: openclaw.harness.id وopenclaw.harness.plugin وopenclaw.outcome وopenclaw.harness.phase عند الأخطاء)

​

Exec

• openclaw.exec.duration_ms ‏(histogram، السمات: openclaw.exec.target وopenclaw.exec.mode وopenclaw.outcome وopenclaw.failureKind)

​

باطن التشخيصات (الذاكرة وحلقة الأداة)

• openclaw.memory.heap_used_bytes ‏(histogram، السمات: openclaw.memory.kind)
• openclaw.memory.rss_bytes ‏(histogram)
• openclaw.memory.pressure ‏(counter، السمات: openclaw.memory.level)
• openclaw.tool.loop.iterations ‏(counter، السمات: openclaw.toolName وopenclaw.outcome)
• openclaw.tool.loop.duration_ms ‏(histogram، السمات: openclaw.toolName وopenclaw.outcome)

​

Spans المُصدّرة

• openclaw.model.usage
  • openclaw.channel وopenclaw.provider وopenclaw.model
  • openclaw.tokens.* ‏(input/output/cache_read/cache_write/total)
  • gen_ai.system افتراضيًا، أو gen_ai.provider.name عند الاشتراك في أحدث semantic conventions الخاصة بـ GenAI
  • gen_ai.request.model وgen_ai.operation.name وgen_ai.usage.*
• openclaw.run
  • openclaw.outcome وopenclaw.channel وopenclaw.provider وopenclaw.model وopenclaw.errorCategory
• openclaw.model.call
  • gen_ai.system افتراضيًا، أو gen_ai.provider.name عند الاشتراك في أحدث semantic conventions الخاصة بـ GenAI
  • gen_ai.request.model وgen_ai.operation.name وopenclaw.provider وopenclaw.model وopenclaw.api وopenclaw.transport
  • openclaw.provider.request_id_hash ‏(تجزئة محدودة قائمة على SHA لمعرّف طلب المزوّد في upstream؛ ولا يتم تصدير المعرّفات الخام)
• openclaw.harness.run
  • openclaw.harness.id وopenclaw.harness.plugin وopenclaw.outcome وopenclaw.provider وopenclaw.model وopenclaw.channel
  • عند الاكتمال: openclaw.harness.result_classification وopenclaw.harness.yield_detected وopenclaw.harness.items.started وopenclaw.harness.items.completed وopenclaw.harness.items.active
  • عند الخطأ: openclaw.harness.phase وopenclaw.errorCategory وopenclaw.harness.cleanup_failed الاختيارية
• openclaw.tool.execution
  • gen_ai.tool.name وopenclaw.toolName وopenclaw.errorCategory وopenclaw.tool.params.*
• openclaw.exec
  • openclaw.exec.target وopenclaw.exec.mode وopenclaw.outcome وopenclaw.failureKind وopenclaw.exec.command_length وopenclaw.exec.exit_code وopenclaw.exec.timed_out
• openclaw.webhook.processed
  • openclaw.channel وopenclaw.webhook وopenclaw.chatId
• openclaw.webhook.error
  • openclaw.channel وopenclaw.webhook وopenclaw.chatId وopenclaw.error
• openclaw.message.processed
  • openclaw.channel وopenclaw.outcome وopenclaw.chatId وopenclaw.messageId وopenclaw.reason
• openclaw.message.delivery
  • openclaw.channel وopenclaw.delivery.kind وopenclaw.outcome وopenclaw.errorCategory وopenclaw.delivery.result_count
• openclaw.session.stuck
  • openclaw.state وopenclaw.ageMs وopenclaw.queueDepth
• openclaw.context.assembled
  • openclaw.prompt.size وopenclaw.history.size وopenclaw.context.tokens وopenclaw.errorCategory (من دون محتوى المطالبة أو السجل أو الاستجابة أو مفتاح الجلسة)
• openclaw.tool.loop
  • openclaw.toolName وopenclaw.outcome وopenclaw.iterations وopenclaw.errorCategory (من دون رسائل الحلقة أو الوسائط أو مخرجات الأداة)
• openclaw.memory.pressure
  • openclaw.memory.level وopenclaw.memory.heap_used_bytes وopenclaw.memory.rss_bytes

​

كتالوج أحداث التشخيصات

• model.usage — الرموز والكلفة والمدة والسياق والمزوّد/النموذج/القناة ومعرّفات الجلسات. تمثل usage محاسبة المزوّد/الدور للكلفة والقياس؛ بينما تمثل context.used اللقطة الحالية للمطالبة/السياق وقد تكون أقل من قيمة usage.total لدى المزوّد عندما تكون هناك مدخلات مخزنة مؤقتًا أو استدعاءات ضمن حلقة الأدوات.

• webhook.received / webhook.processed / webhook.error
• message.queued / message.processed
• message.delivery.started / message.delivery.completed / message.delivery.error

• queue.lane.enqueue / queue.lane.dequeue
• session.state / session.stuck
• run.attempt
• diagnostic.heartbeat ‏(عدادات مجمعة: webhooks/queue/session)

• harness.run.started / harness.run.completed / harness.run.error — دورة الحياة لكل تشغيل لـ agent harness. وتتضمن harnessId وpluginId اختياريًا، إضافة إلى المزوّد/النموذج/القناة ومعرّف التشغيل. ويضيف الاكتمال durationMs وoutcome وresultClassification اختياريًا وyieldDetected وعدّادات itemLifecycle. وتضيف الأخطاء phase (prepare/start/send/resolve/cleanup) وerrorCategory و cleanupFailed الاختيارية.

• exec.process.completed — النتيجة النهائية والمدة والهدف والوضع ورمز الخروج ونوع الفشل. ولا يتم تضمين نص الأمر ولا أدلة العمل.

​

بدون مُصدِّر

{
  diagnostics: { enabled: true },
}

{
  diagnostics: { flags: ["telegram.http"] },
}

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

​

التعطيل

{
  diagnostics: { otel: { enabled: false } },
}

​

ذو صلة

• السجلات — ملفات السجلات ومخرجات وحدة التحكم وتتبع CLI وتبويب Logs في Control UI
• الداخلية الخاصة بسجلات Gateway — أنماط سجل WS وبادئات الأنظمة الفرعية والتقاط وحدة التحكم
• علامات التشخيصات — علامات سجلات تصحيح الأخطاء المستهدفة
• تصدير التشخيصات — أداة المشغّل الخاصة بحزمة الدعم (منفصلة عن تصدير OTEL)
• مرجع الإعدادات — المرجع الكامل لحقول diagnostics.*