Gateway

خروجی‌گیری OpenTelemetry

OpenClaw داده‌های تشخیصی را از طریق Plugin رسمی diagnostics-otel با استفاده از OTLP/HTTP (protobuf) صادر می‌کند. همچنین می‌توان لاگ‌ها را به‌صورت JSONL در stdout برای خط لوله‌های لاگ کانتینر و سندباکس نوشت. هر گردآورنده یا بک‌اندی که OTLP/HTTP را بپذیرد، بدون تغییر کد کار می‌کند. برای لاگ‌های فایل محلی، به لاگ‌گیری مراجعه کنید.

رویدادهای تشخیصی رکوردهای ساخت‌یافته و درون‌پردازه‌ای هستند که Gateway و Pluginهای همراه برای اجرای مدل، جریان پیام، نشست‌ها، صف‌ها و exec منتشر می‌کنند.
diagnostics-otel در آن رویدادها مشترک می‌شود و آن‌ها را به‌صورت سنجه‌ها، ردیابی‌ها و لاگ‌های OpenTelemetry از طریق OTLP/HTTP صادر می‌کند و می‌تواند رکوردهای لاگ را به‌صورت JSONL در stdout نیز بازتاب دهد.
فراخوانی‌های ارائه‌دهنده هنگامی که انتقال ارائه‌دهنده سرآیندهای سفارشی را می‌پذیرد، یک سرآیند W3C به نام traceparent را از زمینه span مورد اعتماد فراخوانی مدل OpenClaw دریافت می‌کنند. زمینه ردیابی منتشرشده توسط Plugin منتشر نمی‌شود.
صادرکننده‌ها فقط زمانی متصل می‌شوند که هم سطح تشخیص و هم Plugin فعال باشند؛ بنابراین هزینه درون‌پردازه‌ای به‌طور پیش‌فرض نزدیک به صفر باقی می‌ماند.

شروع سریع

bash

openclaw plugins install clawhub:@openclaw/diagnostics-otel

json5

{  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,    },  },}

یا Plugin را از طریق CLI فعال کنید: openclaw plugins enable diagnostics-otel.

سیگنال‌های صادرشده

سیگنال	محتوای آن
سنجه‌ها	شمارنده‌ها/هیستوگرام‌هایی برای مصرف توکن، هزینه، مدت اجرا، جایگزینی هنگام خرابی، استفاده از skill، جریان پیام، رویدادهای گفت‌وگو، مسیرهای صف، وضعیت/بازیابی نشست، اجرای ابزار، exec، حافظه، زنده‌بودن و سلامت صادرکننده.
ردیابی‌ها	spanهایی برای استفاده از مدل، فراخوانی‌های مدل، چرخه عمر هارنس، استفاده از skill، اجرای ابزار، exec، پردازش webhook/پیام، مونتاژ زمینه و حلقه‌های ابزار.
لاگ‌ها	رکوردهای ساخت‌یافته `logging.file` که هنگام فعال بودن `diagnostics.otel.logs` از طریق OTLP یا JSONL در stdout صادر می‌شوند؛ بدنه لاگ‌ها ارائه نمی‌شود، مگر اینکه ضبط محتوا صریحاً فعال شده باشد.

traces، metrics و logs را مستقل از یکدیگر تغییر دهید. هنگامی که diagnostics.otel.enabled برابر با true است، ردیابی‌ها و سنجه‌ها به‌طور پیش‌فرض روشن‌اند؛ لاگ‌ها به‌طور پیش‌فرض خاموش‌اند و فقط هنگامی صادر می‌شوند که diagnostics.otel.logs صریحاً true باشد. صدور لاگ به‌طور پیش‌فرض از OTLP استفاده می‌کند؛ برای JSONL در stdout، مقدار diagnostics.otel.logsExporter را روی stdout و برای هر دو روی both تنظیم کنید.

مرجع پیکربندی

json5

{  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 صدور OTLP را غیرفعال می‌کند      serviceName: "openclaw-gateway", // در صورت تنظیم‌نبودن، ابتدا از OTEL_SERVICE_NAME و سپس "openclaw" استفاده می‌شود      headers: { "x-collector-token": "..." },      traces: true,      metrics: true,      logs: true,      logsExporter: "otlp", // otlp | stdout | both      sampleRate: 0.2, // نمونه‌بردار span ریشه، 0.0..1.0      flushIntervalMs: 60000, // بازه صدور سنجه (حداقل 1000ms)      captureContent: {        enabled: false,        inputMessages: false,        outputMessages: false,        toolInputs: false,        toolOutputs: false,        systemPrompt: false,        toolDefinitions: false,      },    },  },}

متغیرهای محیطی

متغیر	هدف
`OTEL_EXPORTER_OTLP_ENDPOINT`	مقدار جایگزین برای `diagnostics.otel.endpoint` هنگامی که کلید پیکربندی تنظیم نشده است.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	مقادیر جایگزین نقطه پایانی ویژه هر سیگنال که هنگام تنظیم‌نبودن کلید پیکربندی متناظر `diagnostics.otel.*Endpoint` استفاده می‌شوند. پیکربندی ویژه سیگنال بر متغیر محیطی ویژه سیگنال اولویت دارد و آن نیز بر نقطه پایانی مشترک اولویت دارد.
`OTEL_SERVICE_NAME`	مقدار جایگزین برای `diagnostics.otel.serviceName` هنگامی که کلید پیکربندی تنظیم نشده است. نام پیش‌فرض سرویس `openclaw` است.
`OTEL_EXPORTER_OTLP_PROTOCOL`	مقدار جایگزین برای پروتکل انتقال هنگامی که `diagnostics.otel.protocol` تنظیم نشده است. فقط `http/protobuf` صدور را فعال می‌کند.
`OTEL_SEMCONV_STABILITY_OPT_IN`	برای انتشار جدیدترین ساختار span استنتاج GenAI، آن را روی `gen_ai_latest_experimental` تنظیم کنید: نام spanهای `{gen_ai.operation.name} {gen_ai.request.model}`، نوع span برابر با `CLIENT` و `gen_ai.provider.name` به‌جای `gen_ai.system` قدیمی. سنجه‌های GenAI در هر صورت همیشه از ویژگی‌های محدود و کم‌کاردینالیتی استفاده می‌کنند.
`OPENCLAW_OTEL_PRELOADED`	هنگامی که پیش‌بارگذاری یا پردازش میزبان دیگری از قبل SDK سراسری OpenTelemetry را ثبت کرده است، آن را روی `1` تنظیم کنید. در این حالت Plugin چرخه عمر NodeSDK خود را نادیده می‌گیرد، اما همچنان شنونده‌های تشخیصی را متصل می‌کند و `traces`/`metrics`/`logs` را رعایت می‌کند.

حریم خصوصی و ضبط محتوا

محتوای خام مدل/ابزار به‌طور پیش‌فرض صادر نمی‌شود. spanها شناسه‌های محدودشده (کانال، ارائه‌دهنده، مدل، دسته خطا، شناسه‌های درخواست فقط به‌صورت هش، منبع ابزار، مالک ابزار، نام/منبع skill) را حمل می‌کنند و هرگز شامل متن پرامپت، متن پاسخ، ورودی‌های ابزار، خروجی‌های ابزار، مسیر فایل‌های skill یا کلیدهای نشست نیستند. مقادیری که شبیه کلیدهای نشست عامل با دامنه مشخص هستند (برای مثال با agent: شروع می‌شوند)، در ویژگی‌های کم‌کاردینالیتی با unknown جایگزین می‌شوند. رکوردهای لاگ OTLP به‌طور پیش‌فرض شدت، لاگر، مکان کد، زمینه ردیابی مورد اعتماد و ویژگی‌های پاک‌سازی‌شده را نگه می‌دارند؛ بدنه پیام خام لاگ فقط زمانی صادر می‌شود که diagnostics.otel.captureContent مقدار بولی true داشته باشد. زیرکلیدهای جزئی captureContent.* هرگز بدنه لاگ‌ها را فعال نمی‌کنند. سنجه‌های گفت‌وگو فقط فراداده محدودشده رویداد (حالت، انتقال، ارائه‌دهنده، نوع رویداد) را صادر می‌کنند؛ نه رونوشت‌ها، محموله‌های صوتی، شناسه‌های نشست، شناسه‌های نوبت، شناسه‌های تماس، شناسه‌های اتاق یا توکن‌های واگذاری.

درخواست‌های خروجی مدل ممکن است شامل یک سرآیند W3C به نام traceparent باشند که فقط از زمینه ردیابی تشخیصی متعلق به OpenClaw برای فراخوانی فعال مدل تولید می‌شود. سرآیندهای traceparent موجود که فراخواننده ارائه کرده است جایگزین می‌شوند؛ بنابراین Pluginها یا گزینه‌های سفارشی ارائه‌دهنده نمی‌توانند تبار ردیابی میان‌سرویسی را جعل کنند.

فقط هنگامی diagnostics.otel.captureContent.* را روی true تنظیم کنید که گردآورنده و سیاست نگهداری شما برای متن پرامپت، پاسخ، ابزار یا پرامپت سیستم تأیید شده باشند. هر زیرکلید مستقل است:

inputMessages - محتوای پرامپت کاربر.
outputMessages - محتوای پاسخ مدل.
toolInputs - محموله آرگومان‌های ابزار.
toolOutputs - محموله نتایج ابزار.
systemPrompt - پرامپت مونتاژشده سیستم/توسعه‌دهنده.
toolDefinitions - نام‌ها، توضیحات و شِماهای ابزار مدل.

هنگامی که هر زیرکلیدی فعال باشد، spanهای مدل و ابزار فقط ویژگی‌های محدودشده و ویرایش‌شده openclaw.content.* را برای همان دسته دریافت می‌کنند.

محتوای toolInputs/toolOutputs برای اجرای ابزار در زمان اجرای عامل داخلی ضبط می‌شود (openclaw.content.tool_input و gen_ai.tool.call.arguments در spanهای تکمیل‌شده/خطادار؛ openclaw.content.tool_output و gen_ai.tool.call.result در spanهای تکمیل‌شده). نام‌های openclaw.content.* همچنان نام‌های پایدار ویژگی OpenClaw باقی می‌مانند؛ نسخه‌های gen_ai.tool.call.* برای نمایشگرهای بومی semconv آن‌ها را بازتاب می‌دهند. فراخوانی‌های ابزار هارنس خارجی (Codex، Claude CLI)، spanهای tool.execution.* را بدون محموله محتوا منتشر می‌کنند. محتوای ضبط‌شده در یک کانال مورد اعتماد و مختص شنونده جابه‌جا می‌شود و هرگز روی گذرگاه عمومی رویدادهای تشخیصی قرار نمی‌گیرد.

نمونه‌برداری و تخلیه

ردیابی‌ها: diagnostics.otel.sampleRate یک TraceIdRatioBasedSampler را فقط روی span ریشه تنظیم می‌کند (0.0 همه را حذف می‌کند، 1.0 همه را نگه می‌دارد). در صورت تنظیم‌نبودن، از پیش‌فرض SDK مربوط به OpenTelemetry استفاده می‌شود (همیشه فعال).
متریک‌ها: diagnostics.otel.flushIntervalMs (با حداقل مقدار 1000 محدود می‌شود)؛ در صورت تنظیم‌نبودن، از پیش‌فرض صدور دوره‌ای SDK استفاده می‌شود.
لاگ‌ها: لاگ‌های OTLP از logging.level (سطح لاگ فایل) پیروی می‌کنند و به‌جای قالب‌بندی کنسول، از مسیر حذف اطلاعات حساس رکوردهای لاگ تشخیصی استفاده می‌کنند. نصب‌های پرترافیک باید نمونه‌برداری/فیلترکردن گردآورنده OTLP را به نمونه‌برداری محلی ترجیح دهند. وقتی پلتفرم شما از قبل stdout/stderr را به یک پردازشگر لاگ ارسال می‌کند و گردآورنده لاگ OTLP ندارید، diagnostics.otel.logsExporter: "stdout" را تنظیم کنید. رکوردهای stdout در هر خط یک شیء JSON هستند که شامل ts، signal، service.name، شدت، بدنه، ویژگی‌های حذف‌شده از اطلاعات حساس و در صورت وجود، فیلدهای ردیابی مورداعتماد است.
هم‌بستگی لاگ فایل: لاگ‌های فایل JSONL هنگامی که فراخوانی لاگ دارای زمینه ردیابی تشخیصی معتبر باشد، traceId، spanId، parentSpanId و traceFlags را در سطح بالا شامل می‌شوند؛ بنابراین پردازشگرهای لاگ می‌توانند خطوط لاگ محلی را به spanهای صادرشده متصل کنند.
هم‌بستگی درخواست: درخواست‌های HTTP و فریم‌های WebSocket در Gateway یک دامنه ردیابی درخواست داخلی ایجاد می‌کنند. لاگ‌ها و رویدادهای تشخیصی درون آن دامنه به‌طور پیش‌فرض ردیابی درخواست را به ارث می‌برند، درحالی‌که spanهای اجرای عامل و فراخوانی مدل به‌عنوان فرزند ایجاد می‌شوند تا سرآیندهای traceparent ارائه‌دهنده روی همان ردیابی باقی بمانند.
هم‌بستگی فراخوانی مدل: spanهای openclaw.model.call به‌طور پیش‌فرض اندازه‌های امن مؤلفه‌های پرامپت و، هنگامی که نتیجه ارائه‌دهنده اطلاعات مصرف را ارائه کند، ویژگی‌های توکن هر فراخوانی را شامل می‌شوند. openclaw.model.usage همچنان span حسابداری سطح اجرا برای هزینه تجمیعی، زمینه و داشبوردهای کانال است و هنگامی که محیط اجرای صادرکننده دارای زمینه ردیابی مورداعتماد باشد، روی همان ردیابی تشخیصی باقی می‌ماند.

متریک‌های صادرشده

مصرف مدل

openclaw.tokens (شمارنده، ویژگی‌ها: openclaw.token، openclaw.channel، openclaw.provider، openclaw.model، openclaw.agent)
openclaw.cost.usd (شمارنده، ویژگی‌ها: openclaw.channel، openclaw.provider، openclaw.model)
openclaw.run.duration_ms (هیستوگرام، ویژگی‌ها: openclaw.channel، openclaw.provider، openclaw.model)
openclaw.context.tokens (هیستوگرام، ویژگی‌ها: openclaw.context، openclaw.channel، openclaw.provider، openclaw.model)
gen_ai.client.token.usage (هیستوگرام، متریک قراردادهای معنایی GenAI، ویژگی‌ها: gen_ai.token.type = input/output، gen_ai.provider.name، gen_ai.operation.name، gen_ai.request.model)
gen_ai.client.operation.duration (هیستوگرام، ثانیه، متریک قراردادهای معنایی GenAI، ویژگی‌ها: gen_ai.provider.name، gen_ai.operation.name، gen_ai.request.model، error.type اختیاری)
openclaw.model_call.duration_ms (هیستوگرام، ویژگی‌ها: openclaw.provider، openclaw.model، openclaw.api، openclaw.transport، به‌علاوه openclaw.errorCategory و openclaw.failureKind برای خطاهای طبقه‌بندی‌شده)
openclaw.model_call.request_bytes (هیستوگرام، اندازه بایتی UTF-8 بار درخواست نهایی مدل؛ بدون محتوای خام بار)
openclaw.model_call.response_bytes (هیستوگرام، اندازه بایتی UTF-8 بار قطعه‌های پاسخ جریانی؛ متن پرتکرار، تفکر و تغییرات فراخوانی ابزار فقط بایت‌های افزایشی delta را می‌شمارند؛ بدون محتوای خام پاسخ)
openclaw.model_call.time_to_first_byte_ms (هیستوگرام، زمان سپری‌شده پیش از نخستین رویداد پاسخ جریانی)
openclaw.model.failover (شمارنده، ویژگی‌ها: openclaw.provider، openclaw.model، openclaw.failover.to_provider، openclaw.failover.to_model، openclaw.failover.reason، openclaw.failover.suspended، openclaw.lane)
openclaw.skill.used (شمارنده، ویژگی‌ها: openclaw.skill.name، openclaw.skill.source، openclaw.skill.activation، openclaw.agent اختیاری، openclaw.toolName اختیاری)

جریان پیام

openclaw.webhook.received (شمارنده، ویژگی‌ها: openclaw.channel، openclaw.webhook)
openclaw.webhook.error (شمارنده، ویژگی‌ها: openclaw.channel، openclaw.webhook)
openclaw.webhook.duration_ms (هیستوگرام، ویژگی‌ها: openclaw.channel، openclaw.webhook)
openclaw.message.queued (شمارنده، ویژگی‌ها: openclaw.channel، openclaw.source)
openclaw.message.received (شمارنده، ویژگی‌ها: openclaw.channel، openclaw.source)
openclaw.message.dispatch.started (شمارنده، ویژگی‌ها: openclaw.channel، openclaw.source)
openclaw.message.dispatch.completed (شمارنده، ویژگی‌ها: openclaw.channel، openclaw.outcome، openclaw.reason، openclaw.source)
openclaw.message.dispatch.duration_ms (هیستوگرام، ویژگی‌ها: openclaw.channel، openclaw.outcome، openclaw.reason، openclaw.source)
openclaw.message.processed (شمارنده، ویژگی‌ها: openclaw.channel، openclaw.outcome)
openclaw.message.duration_ms (هیستوگرام، ویژگی‌ها: openclaw.channel، openclaw.outcome)
openclaw.message.delivery.started (شمارنده، ویژگی‌ها: openclaw.channel، openclaw.delivery.kind)
openclaw.message.delivery.duration_ms (هیستوگرام، ویژگی‌ها: openclaw.channel، openclaw.delivery.kind، openclaw.outcome، openclaw.errorCategory)

گفت‌وگو

openclaw.talk.event (شمارنده، ویژگی‌ها: openclaw.talk.event_type، openclaw.talk.mode، openclaw.talk.transport، openclaw.talk.brain، openclaw.talk.provider)
openclaw.talk.event.duration_ms (هیستوگرام، ویژگی‌ها: همانند openclaw.talk.event؛ هنگامی صادر می‌شود که یک رویداد گفت‌وگو مدت‌زمان را گزارش کند)
openclaw.talk.audio.bytes (هیستوگرام، ویژگی‌ها: همانند openclaw.talk.event؛ برای رویدادهای فریم صوتی گفت‌وگو که طول بایتی را گزارش می‌کنند صادر می‌شود)

صف‌ها و نشست‌ها

openclaw.queue.lane.enqueue (شمارنده، ویژگی‌ها: openclaw.lane)
openclaw.queue.lane.dequeue (شمارنده، ویژگی‌ها: openclaw.lane)
openclaw.queue.depth (هیستوگرام، ویژگی‌ها: openclaw.lane یا openclaw.channel=heartbeat)
openclaw.queue.wait_ms (هیستوگرام، ویژگی‌ها: openclaw.lane)
openclaw.session.state (شمارنده، ویژگی‌ها: openclaw.state، openclaw.reason)
openclaw.session.stuck (شمارنده، ویژگی‌ها: openclaw.state؛ برای ثبت وضعیت منقضی‌شده اما قابل‌بازیابی نشست صادر می‌شود)
openclaw.session.stuck_age_ms (هیستوگرام، ویژگی‌ها: openclaw.state؛ برای ثبت وضعیت منقضی‌شده اما قابل‌بازیابی نشست صادر می‌شود)
openclaw.session.turn.created (شمارنده، ویژگی‌ها: openclaw.agent، openclaw.channel، openclaw.trigger)
openclaw.session.recovery.requested (شمارنده، ویژگی‌ها: openclaw.state، openclaw.action، openclaw.active_work_kind، openclaw.reason)
openclaw.session.recovery.completed (شمارنده، ویژگی‌ها: openclaw.state، openclaw.action، openclaw.status، openclaw.active_work_kind، openclaw.reason)
openclaw.session.recovery.age_ms (هیستوگرام، ویژگی‌ها: همانند شمارنده بازیابی متناظر)
openclaw.run.attempt (شمارنده، ویژگی‌ها: openclaw.attempt)

تله‌متری زنده‌بودن نشست

diagnostics.stuckSessionWarnMs آستانه سنِ بدون پیشرفت برای تشخیص زنده‌بودن نشست است. تا زمانی که OpenClaw پیشرفت پاسخ، ابزار، وضعیت، بلوک یا محیط اجرای ACP را مشاهده کند، سن یک نشست processing به‌سمت این آستانه افزایش نمی‌یابد. سیگنال‌های زنده‌نگه‌داشتن تایپ به‌عنوان پیشرفت محسوب نمی‌شوند، بنابراین همچنان می‌توان یک مدل یا چارچوب اجرایی ساکت را تشخیص داد.

OpenClaw نشست‌ها را بر اساس کاری که همچنان می‌تواند مشاهده کند طبقه‌بندی می‌کند:

session.long_running: کار تعبیه‌شده فعال، فراخوانی‌های مدل یا فراخوانی‌های ابزار همچنان در حال پیشرفت‌اند. فراخوانی‌های مدل تحت مالکیت که پس از diagnostics.stuckSessionWarnMs ساکت می‌مانند نیز پیش از diagnostics.stuckSessionAbortMs به‌صورت طولانی‌مدت گزارش می‌شوند تا ارائه‌دهندگان مدل کند یا غیرجریانی، تا زمانی که امکان مشاهده لغو وجود دارد، شبیه نشست‌های متوقف‌شده Gateway به نظر نرسند.
session.stalled: کار فعال وجود دارد، اما اجرای فعال پیشرفت اخیر را گزارش نکرده است. فراخوانی‌های مدل تحت مالکیت در diagnostics.stuckSessionAbortMs یا پس از آن از session.long_running به session.stalled تغییر می‌کنند؛ فعالیت منقضی‌شده مدل/ابزار بدون مالک به‌عنوان کار طولانی‌مدت بی‌ضرر تلقی نمی‌شود. اجراهای تعبیه‌شده متوقف‌شده در ابتدا فقط تحت مشاهده باقی می‌مانند، سپس پس از diagnostics.stuckSessionAbortMs بدون پیشرفت، فرایند لغو و تخلیه را انجام می‌دهند تا نوبت‌های صف‌شده پشت مسیر بتوانند از سر گرفته شوند. در صورت تنظیم‌نبودن، آستانه لغو به‌طور پیش‌فرض پنجره امن‌تر و طولانی‌تری برابر با حداقل ۵ دقیقه و ۳ برابر diagnostics.stuckSessionWarnMs دارد.
session.stuck: ثبت وضعیت منقضی‌شده نشست بدون کار فعال، یا یک نشست صف‌شده بیکار با فعالیت منقضی‌شده مدل/ابزار بدون مالک. پس از عبور از دروازه‌های بازیابی، مسیر نشست متأثر بلافاصله آزاد می‌شود.

بازیابی رویدادهای ساختاریافته session.recovery.requested و session.recovery.completed را صادر می‌کند. وضعیت تشخیصی نشست فقط پس از یک نتیجه بازیابی تغییردهنده (aborted یا released) و تنها در صورتی بیکار علامت‌گذاری می‌شود که همان نسل پردازش همچنان جاری باشد.

فقط session.stuck شمارنده openclaw.session.stuck، هیستوگرام openclaw.session.stuck_age_ms و span‏ openclaw.session.stuck را صادر می‌کند. تا زمانی که نشست بدون تغییر باقی بماند، تشخیص‌های تکراری session.stuck با فاصله افزایشی انجام می‌شوند؛ بنابراین داشبوردها باید به‌جای هر تیک Heartbeat، روی افزایش‌های پایدار هشدار دهند. برای گزینه پیکربندی و مقادیر پیش‌فرض، به مرجع پیکربندی مراجعه کنید.

هشدارهای زنده‌بودن همچنین موارد زیر را صادر می‌کنند:

openclaw.liveness.warning (شمارنده، ویژگی‌ها: openclaw.liveness.reason)
openclaw.liveness.event_loop_delay_p99_ms (هیستوگرام، ویژگی‌ها: openclaw.liveness.reason)
openclaw.liveness.event_loop_delay_max_ms (هیستوگرام، ویژگی‌ها: openclaw.liveness.reason)
openclaw.liveness.event_loop_utilization (هیستوگرام، ویژگی‌ها: openclaw.liveness.reason)
openclaw.liveness.cpu_core_ratio (هیستوگرام، ویژگی‌ها: openclaw.liveness.reason)

چرخه عمر چارچوب اجرایی

openclaw.harness.duration_ms (هیستوگرام، ویژگی‌ها: openclaw.harness.id، openclaw.harness.plugin، openclaw.outcome، و هنگام خطا openclaw.harness.phase)

اجرای ابزار و تشخیص حلقه

openclaw.tool.execution.duration_ms (هیستوگرام، ویژگی‌ها: gen_ai.tool.name، openclaw.toolName، openclaw.tool.source، openclaw.tool.owner، openclaw.tool.params.kind، به‌علاوه openclaw.errorCategory هنگام خطا)
openclaw.tool.execution.blocked (شمارنده، ویژگی‌ها: gen_ai.tool.name، openclaw.toolName، openclaw.tool.source، openclaw.tool.owner، openclaw.tool.params.kind، openclaw.deniedReason)
openclaw.tool.loop (شمارنده، ویژگی‌ها: openclaw.toolName، openclaw.loop.level، openclaw.loop.action، openclaw.loop.detector، openclaw.loop.count، openclaw.loop.paired_tool اختیاری؛ هنگامی صادر می‌شود که یک حلقه تکراری فراخوانی ابزار تشخیص داده شود)

اجرا

openclaw.exec.duration_ms (هیستوگرام، ویژگی‌ها: openclaw.exec.target، openclaw.exec.mode، openclaw.outcome، openclaw.failureKind)

جزئیات داخلی تشخیص (حافظه، بارها، سلامت صادرکننده)

openclaw.payload.large (شمارنده، ویژگی‌ها: openclaw.payload.surface، openclaw.payload.action، openclaw.channel، openclaw.plugin، openclaw.reason)
openclaw.payload.large_bytes (هیستوگرام، ویژگی‌ها: همانند openclaw.payload.large)
openclaw.memory.rss_bytes / openclaw.memory.heap_used_bytes / openclaw.memory.heap_total_bytes / openclaw.memory.external_bytes / openclaw.memory.array_buffers_bytes (هیستوگرام‌ها، بدون ویژگی؛ نمونه‌های حافظه فرایند)
openclaw.memory.pressure (شمارنده، ویژگی‌ها: openclaw.memory.level، openclaw.memory.reason)
openclaw.diagnostic.async_queue.dropped (شمارنده، ویژگی‌ها: openclaw.diagnostic.async_queue.drop_class؛ حذف‌های ناشی از پس‌فشار صف تشخیصی داخلی)
openclaw.telemetry.exporter.events (شمارنده، ویژگی‌ها: openclaw.exporter، openclaw.signal، openclaw.status، openclaw.reason اختیاری، openclaw.errorCategory اختیاری؛ خودتله‌متری چرخه عمر/خرابی صادرکننده)

spanهای صادرشده

openclaw.model.usage
- openclaw.channel، openclaw.provider، openclaw.model
- openclaw.tokens.* (input/output/cache_read/cache_write/total)
- به‌طور پیش‌فرض gen_ai.system، یا هنگامی که جدیدترین قراردادهای معنایی GenAI فعال شده‌اند، gen_ai.provider.name
- 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، یا هنگامی که جدیدترین قراردادهای معنایی GenAI فعال شده‌اند، gen_ai.provider.name
- gen_ai.request.model، gen_ai.operation.name، openclaw.provider، openclaw.model، openclaw.api، openclaw.transport
- در صورت بروز خطا، openclaw.errorCategory، error.type و openclaw.failureKind اختیاری
- openclaw.model_call.request_bytes، openclaw.model_call.response_bytes، openclaw.model_call.time_to_first_byte_ms
- openclaw.model_call.prompt.input_messages_count، openclaw.model_call.prompt.input_messages_chars، openclaw.model_call.prompt.system_prompt_chars، openclaw.model_call.prompt.tool_definitions_count، openclaw.model_call.prompt.tool_definitions_chars، openclaw.model_call.prompt.total_chars (فقط اندازه‌های امن مؤلفه‌ها، بدون متن پرامپت)
- هنگامی که نتیجه فراخوانی مدل شامل مصرف ارائه‌دهنده برای همان فراخوانی منفرد باشد، openclaw.model_call.usage.* و gen_ai.usage.*
- هنگامی که نتیجه ارائه‌دهنده بالادستی یک شناسه درخواست ارائه کند، رویداد Span با نام openclaw.provider.request و ویژگی openclaw.upstreamRequestIdHash (محدودشده و مبتنی بر هش)؛ شناسه‌های خام هرگز صادر نمی‌شوند
- با OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental، Spanهای فراخوانی مدل به‌جای openclaw.model.call از جدیدترین نام Span استنتاج GenAI، یعنی {gen_ai.operation.name} {gen_ai.request.model}، و نوع Span برابر با CLIENT استفاده می‌کنند.
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، gen_ai.operation.name (execute_tool)، openclaw.toolName، openclaw.tool.source، gen_ai.tool.call.id اختیاری، openclaw.tool.owner، openclaw.tool.params.*
- در صورت بروز خطا، openclaw.errorCategory/openclaw.errorCode اختیاری؛ و هنگامی که سیاست یا محیط ایزوله دسترسی را رد کند، openclaw.deniedReason و openclaw.outcome=blocked
openclaw.exec
- openclaw.exec.target، openclaw.exec.mode، openclaw.outcome، openclaw.failureKind، openclaw.exec.command_length، openclaw.exec.exit_code، openclaw.exec.exit_signal، openclaw.exec.timed_out
openclaw.webhook.processed
- openclaw.channel، openclaw.webhook
openclaw.webhook.error
- openclaw.channel، openclaw.webhook، openclaw.error
openclaw.message.processed
- openclaw.channel، openclaw.outcome، 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.loop.level، openclaw.loop.action، openclaw.loop.detector، openclaw.loop.count، و openclaw.loop.paired_tool اختیاری (بدون پیام‌های حلقه، پارامترها یا خروجی ابزار)
openclaw.memory.pressure
- openclaw.memory.level، openclaw.memory.reason، openclaw.memory.rss_bytes، openclaw.memory.heap_used_bytes، openclaw.memory.heap_total_bytes، openclaw.memory.external_bytes، openclaw.memory.array_buffers_bytes، و openclaw.memory.threshold_bytes/openclaw.memory.rss_growth_bytes/openclaw.memory.window_ms اختیاری

هنگامی که ثبت محتوا به‌صراحت فعال باشد، Spanهای مدل و ابزار می‌توانند برای کلاس‌های محتوایی مشخصی که فعال کرده‌اید، شامل ویژگی‌های محدودشده و ویرایش‌شده openclaw.content.* نیز باشند.

فهرست رویدادهای تشخیصی

رویدادهای زیر پشتوانه معیارها و Spanهای بالا هستند. Pluginها همچنین می‌توانند بدون صدور OTLP مستقیماً مشترک آن‌ها شوند.

مصرف مدل

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.long_running / session.stalled / session.stuck
run.attempt / run.progress
diagnostic.heartbeat (شمارنده‌های تجمیعی: Webhookها/صف/نشست)

چرخه حیات مهار

harness.run.started / harness.run.completed / harness.run.error - چرخه حیات هر اجرا برای مهار عامل. شامل harnessId، pluginId اختیاری، ارائه‌دهنده/مدل/کانال و شناسه اجرا است. تکمیل، durationMs، outcome، resultClassification اختیاری، yieldDetected و شمارش‌های itemLifecycle را اضافه می‌کند. خطاها phase (prepare/start/send/resolve/cleanup)، errorCategory و cleanupFailed اختیاری را اضافه می‌کنند.

اجرا

exec.process.completed - نتیجه نهایی ترمینال، مدت‌زمان، مقصد، حالت، کد خروج و نوع خرابی. متن فرمان و پوشه‌های کاری درج نمی‌شوند.
exec.approval.followup_suppressed - پیگیری تأیید منقضی‌شده که پس از اتصال مجدد نشست کنار گذاشته شده است. شامل approvalId، reason (session_rebound)، phase (direct_delivery یا gateway_preflight) و مُهر زمانی توزیع‌کننده است. کلیدهای نشست، مسیرها و متن فرمان درج نمی‌شوند.

بدون صادرکننده

بدون اجرای diagnostics-otel، رویدادهای تشخیصی را برای Pluginها یا مقصدهای سفارشی در دسترس نگه دارید:

json5

{  diagnostics: { enabled: true },}

برای خروجی اشکال‌زدایی هدفمند بدون افزایش logging.level، از پرچم‌های تشخیصی استفاده کنید. پرچم‌ها به بزرگی و کوچکی حروف حساس نیستند و از نویسه‌های عام (telegram.* یا *) پشتیبانی می‌کنند:

json5

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

یا به‌عنوان بازنویسی یک‌باره متغیر محیطی:

bash

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway

خروجی پرچم در فایل گزارش استاندارد (logging.file) نوشته می‌شود و همچنان توسط logging.redactSensitive ویرایش می‌شود. راهنمای کامل: پرچم‌های تشخیصی.

غیرفعال‌سازی

json5

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

یا diagnostics-otel را از plugins.allow حذف کنید، یا فرمان openclaw plugins disable diagnostics-otel را اجرا کنید.

مرتبط

گزارش‌گیری - گزارش‌های فایل، خروجی کنسول، دنبال‌کردن با CLI و زبانه گزارش‌های رابط کنترل
جزئیات داخلی گزارش‌گیری Gateway - سبک‌های گزارش WS، پیشوندهای زیرسامانه و ثبت کنسول
پرچم‌های تشخیصی - پرچم‌های هدفمند گزارش اشکال‌زدایی
صدور داده‌های تشخیصی - ابزار بسته پشتیبانی اپراتور (جدا از صدور OTEL)
مرجع پیکربندی - مرجع کامل فیلدهای diagnostics.*

Was this useful?

خروجی‌گیری OpenTelemetry

شروع سریع

سیگنال‌های صادرشده

مرجع پیکربندی

متغیرهای محیطی

حریم خصوصی و ضبط محتوا

نمونه‌برداری و تخلیه

متریک‌های صادرشده

مصرف مدل

جریان پیام

گفت‌وگو

صف‌ها و نشست‌ها

تله‌متری زنده‌بودن نشست

چرخه عمر چارچوب اجرایی

اجرای ابزار و تشخیص حلقه

اجرا

جزئیات داخلی تشخیص (حافظه، بارها، سلامت صادرکننده)

spanهای صادرشده

فهرست رویدادهای تشخیصی

بدون صادرکننده

غیرفعال‌سازی

مرتبط

On this page

Molty