openclaw-plugin-yuanbao 2.15.0 → 2.15.2-beta.bd3f19cc

package/README.md

@@ -349,6 +349,71 @@ Routing fields:
 
 ---
 
+## Observability (OpenTelemetry)
+
+The plugin emits runtime metrics through the **OpenTelemetry API**. It does
+**not** ship or configure an SDK/exporter itself — it reuses the global OTel
+provider registered by OpenClaw's `diagnostics-otel` plugin. When that plugin
+is not enabled, all telemetry calls are safe no-ops.
+
+### Emitted metrics (P0)
+
+| Metric                        | Type      | Attributes              | Meaning                                    |
+| ----------------------------- | --------- | ----------------------- | ------------------------------------------ |
+| `ws.connection.state`         | Gauge     | `account`               | WS state: 0 disconnected … 4 connected     |
+| `ws.reconnect.count`          | Counter   | `account`               | Reconnect attempts                         |
+| `inbound.message.count`       | Counter   | `account`, `chat`       | Inbound messages received                  |
+| `pipeline.execution.duration` | Histogram | `chat`                  | End-to-end pipeline duration (ms)          |
+| `pipeline.error.count`        | Counter   | `chat`, `middleware`, `error` | Pipeline failures by middleware/error |
+| `outbound.send.count`         | Counter   | `chat`, `result`        | Outbound sends (`ok` / `fail` / `error`)   |
+
+> **Privacy red line:** metric attributes never carry message text, phone
+> numbers, or PII. Only technical tags are emitted; `safeAttributes` drops any
+> non-scalar value as a backstop.
+
+### Enable export to Tencent Cloud APM
+
+Add the `diagnostics` + `plugins` blocks to `openclaw.json` (token is a
+placeholder — replace once your APM application is provisioned):
+
+```json5
+{
+  plugins: {
+    entries: {
+      "diagnostics-otel": { enabled: true },
+    },
+  },
+  diagnostics: {
+    enabled: true,
+    otel: {
+      enabled: true,
+      // Must include http:// prefix; see Tencent Cloud APM console
+      endpoint: "http://ap-guangzhou.apm.tencentcs.com:90/otlp",
+      protocol: "http/protobuf",
+      headers: { Authorization: "<PLACEHOLDER_TOKEN>" },
+      serviceName: "yuanbao-openclaw-plugin",
+      traces: true,
+      metrics: true,
+      logs: false,
+      // 10W-instance cost control: prioritize metrics, sample traces low
+      sampleRate: 0.1,
+      flushIntervalMs: 5000,
+    },
+  },
+}
+```
+
+Per-instance identity (to filter on the platform without logging into a single
+machine) is injected via the standard env var before starting the gateway:
+
+```bash
+export OTEL_RESOURCE_ATTRIBUTES="instance.id=<machine-id>"
+```
+
+Reference: [Tencent Cloud · 接入 OpenClaw 应用](https://cloud.tencent.com/document/product/248/129686).
+
+---
+
 ## Configuration reference
 
 Full configuration: [Gateway configuration](/gateway/configuration)

package/dist/src/access/ws/gateway.js

@@ -3,6 +3,7 @@ import { buildSyncCommandsPayload } from "../../business/commands/command-sync/i
 import { handleInboundMessage } from "../../business/inbound/index.js";
 import { resolveTraceContext } from "../../business/trace/context.js";
 import { createLog } from "../../logger.js";
+import { METRIC, WS_STATE_CODE, addCount, setGauge } from "../../infra/telemetry.js";
 import { getSignToken, forceRefreshSignToken } from "../api.js";
 import { decodeInboundMessage } from "./biz-codec.js";
 import { YuanbaoWsClient } from "./client.js";
@@ -57,6 +58,12 @@ export async function startYuanbaoWsGateway(params) {
             },
             onStateChange: (state) => {
                 gwlog.info(`[${account.accountId}] WS state: ${state}`);
+                setGauge(METRIC.wsConnectionState, WS_STATE_CODE[state] ?? -1, {
+                    account: account.accountId,
+                });
+                if (state === "reconnecting") {
+                    addCount(METRIC.wsReconnectCount, 1, { account: account.accountId });
+                }
                 statusSink?.({
                     wsState: state,
                     connected: state === "connected",
@@ -288,6 +295,7 @@ function handleWsDispatchEvent(params) {
         return;
     }
     const { msg, chatType } = converted;
+    addCount(METRIC.inboundMessageCount, 1, { account: account.accountId, chat: chatType });
     // Resolve / generate trace context
     const traceContext = resolveTraceContext({
         traceId: msg.trace_id,

package/dist/src/business/pipeline/engine.d.ts

@@ -16,4 +16,5 @@ export declare class MessagePipeline {
     remove(name: string): this;
     /** Execute the pipeline */
     execute(ctx: PipelineContext): Promise<void>;
+    private runMiddlewareChain;
 }

package/dist/src/business/pipeline/engine.js

@@ -3,6 +3,7 @@
  *
  * Onion-model middleware engine with conditional guards (when) and named insert/remove support.
  */
+import { METRIC, SPAN, addCount, recordDuration, withActiveSpan } from "../../infra/telemetry.js";
 export class MessagePipeline {
     middlewares = [];
     /** Register middleware at the end of the pipeline */
@@ -42,8 +43,17 @@ export class MessagePipeline {
     }
     /** Execute the pipeline */
     async execute(ctx) {
+        const chat = ctx.isGroup ? "group" : "c2c";
+        const incomingTraceId = ctx.raw.trace_id?.trim();
+        await withActiveSpan(SPAN.pipelineExecute, {
+            traceId: incomingTraceId,
+            attributes: { chat, account: ctx.account.accountId },
+        }, async () => this.runMiddlewareChain(ctx, chat));
+    }
+    async runMiddlewareChain(ctx, chat) {
         const chain = this.middlewares;
         let index = 0;
+        const startedAt = Date.now();
         const next = async () => {
             while (index < chain.length) {
                 const mw = chain[index++];
@@ -56,11 +66,21 @@ export class MessagePipeline {
                 }
                 catch (err) {
                     ctx.log.error(`middleware [${mw.name}] execution error`, { error: String(err) });
+                    addCount(METRIC.pipelineErrorCount, 1, {
+                        chat,
+                        middleware: mw.name,
+                        error: err instanceof Error ? err.name : "unknown",
+                    });
                     throw err;
                 }
                 return;
             }
         };
-        await next();
+        try {
+            await next();
+        }
+        finally {
+            recordDuration(METRIC.pipelineExecutionDuration, Date.now() - startedAt, { chat });
+        }
     }
 }

package/dist/src/business/pipeline/middlewares/resolve-trace.js

@@ -2,7 +2,7 @@
  * Middleware: parse or generate trace context from inbound message trace_id / seq_id.
  * Injected into ctx.traceContext for downstream middlewares and transport layer.
  */
-import { resolveTraceContext } from "../../trace/context.js";
+import { getActiveTraceparent, resolveTraceContext } from "../../trace/context.js";
 export const resolveTrace = {
     name: "resolve-trace",
     handler: async (ctx, next) => {
@@ -11,9 +11,14 @@ export const resolveTrace = {
             traceId: ctx.raw.trace_id,
             seqId: ctx.raw.seq_id ?? ctx.raw.msg_seq,
         });
+        const activeTraceparent = getActiveTraceparent();
+        if (activeTraceparent) {
+            ctx.traceContext = { ...ctx.traceContext, traceparent: activeTraceparent };
+        }
         ctx.log.debug("[resolve-trace] trace context resolved", {
             traceId: ctx.traceContext.traceId,
             seqId: ctx.traceContext.seqId ?? "(none)",
+            traceparent: ctx.traceContext.traceparent,
         });
         await next();
     },

package/dist/src/business/trace/context.d.ts

@@ -1,3 +1,4 @@
+import type { Context } from "@opentelemetry/api";
 export type YuanbaoTraceContext = {
     traceId: string;
     traceparent: string;
@@ -9,6 +10,13 @@ export type YuanbaoTraceContext = {
  * Generate a random trace ID (32-char hex string).
  * Used as fallback when inbound message has no trace_id.
  */ export declare function generateTraceId(): string;
+/**
+ * Build an OTel parent context that links a new span to an inbound trace id.
+ * Used when the upstream only provides trace_id (no parent span id).
+ */
+export declare function buildRemoteParentOtelContext(traceId: string): Context;
+/** Read the W3C traceparent for the currently active OTel span, if any. */
+export declare function getActiveTraceparent(): string | undefined;
 /**
  * Resolve or generate a complete trace context.
  * Prefers inbound traceId; generates one if missing.

package/dist/src/business/trace/context.js

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash, randomBytes } from "node:crypto";
+import { context, ROOT_CONTEXT, trace, TraceFlags, } from "@opentelemetry/api";
 import { createLog } from "../../logger.js";
 const traceStorage = new AsyncLocalStorage();
 const EMPTY_TRACE_ID = "0".repeat(32);
@@ -34,6 +35,28 @@ function normalizeTraceIdForTraceparent(traceId) {
 function buildTraceparent(traceId) {
     return `00-${normalizeTraceIdForTraceparent(traceId)}-${generateHex(8)}-01`;
 }
+/**
+ * Build an OTel parent context that links a new span to an inbound trace id.
+ * Used when the upstream only provides trace_id (no parent span id).
+ */
+export function buildRemoteParentOtelContext(traceId) {
+    const normalizedTraceId = normalizeTraceIdForTraceparent(traceId);
+    return trace.setSpanContext(ROOT_CONTEXT, {
+        traceId: normalizedTraceId,
+        spanId: generateHex(8),
+        traceFlags: TraceFlags.SAMPLED,
+        isRemote: true,
+    });
+}
+/** Read the W3C traceparent for the currently active OTel span, if any. */
+export function getActiveTraceparent() {
+    const spanContext = trace.getSpan(context.active())?.spanContext();
+    if (!spanContext || !trace.isSpanContextValid(spanContext)) {
+        return undefined;
+    }
+    const flags = spanContext.traceFlags.toString(16).padStart(2, "0");
+    return `00-${spanContext.traceId}-${spanContext.spanId}-${flags}`;
+}
 function normalizeSeqId(seqId) {
     if (seqId === undefined || seqId === null) {
         return undefined;

package/dist/src/infra/env.js

@@ -1,6 +1,7 @@
 import { createRequire } from "module";
 import os from "os";
 import semver from "semver";
+import { setTelemetryVersion } from "./telemetry.js";
 /**
  * Plugin version number.
  */
@@ -55,6 +56,7 @@ export const initEnv = (api) => {
     if (!_pluginVersion || !_openclawVersion) {
         legacyInitEnv();
     }
+    setTelemetryVersion(_pluginVersion);
     // Runtime compatibility guard (Layer 4 defense)
     if (_openclawVersion) {
         assertHostVersionCompatible(_openclawVersion);

package/dist/src/infra/telemetry.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Telemetry helpers — thin wrapper over `@opentelemetry/api`.
+ *
+ * The plugin only uses the OTel **API** package; the global SDK / exporter is
+ * registered by OpenClaw's `diagnostics-otel` plugin. When no global provider
+ * is present (local dev, tests, diagnostics disabled) every call degrades to a
+ * no-op automatically — the API ships no-op meters by default.
+ *
+ * Compliance red line: metric attributes must NEVER carry message text, phone
+ * numbers, or any PII. `safeAttributes` strips non-scalar values and truncates
+ * strings as a backstop, but callers are still responsible for only passing
+ * technical tags (state, result, chat type, middleware name, error class, …).
+ */
+import type { Attributes } from "@opentelemetry/api";
+/** Stable metric instrument names (dotted, OTel-style). */
+export declare const METRIC: {
+    readonly wsConnectionState: "ws.connection.state";
+    readonly wsReconnectCount: "ws.reconnect.count";
+    readonly inboundMessageCount: "inbound.message.count";
+    readonly pipelineExecutionDuration: "pipeline.execution.duration";
+    readonly pipelineErrorCount: "pipeline.error.count";
+    readonly outboundSendCount: "outbound.send.count";
+};
+/** Stable span names (dotted, OTel-style). */
+export declare const SPAN: {
+    readonly pipelineExecute: "pipeline.execute";
+};
+/** Numeric encoding for the WS connection-state gauge. */
+export declare const WS_STATE_CODE: Record<string, number>;
+/** Set the meter version (plugin version); optional, called once at init. */
+export declare function setTelemetryVersion(version: string): void;
+/**
+ * Drop anything that isn't a scalar (objects/arrays could smuggle PII) and
+ * truncate long strings. Returns undefined when there is nothing to keep.
+ */
+export declare function safeAttributes(attrs?: Attributes): Attributes | undefined;
+/** Increment a counter (default +1). */
+export declare function addCount(name: string, value?: number, attrs?: Attributes): void;
+/** Record a histogram value (e.g. a duration in ms). */
+export declare function recordDuration(name: string, value: number, attrs?: Attributes): void;
+/** Set the current value of a gauge. */
+export declare function setGauge(name: string, value: number, attrs?: Attributes): void;
+/**
+ * Run `fn` inside an active OTel span. Prefers inbound `traceId` (server logExt)
+ * over W3C `traceparent`: locally generated traceparent uses a random span id
+ * that was never exported, so linking via trace_id keeps APM correlation aligned
+ * with the backend. Falls back to traceparent when traceId is absent.
+ */
+export declare function withActiveSpan<T>(name: string, params: {
+    attributes?: Attributes;
+    traceId?: string;
+    traceparent?: string;
+}, fn: () => Promise<T>): Promise<T>;
+/** Reset cached instruments — test-only helper. */
+export declare function __resetTelemetryForTest(): void;

package/dist/src/infra/telemetry.js

@@ -0,0 +1,162 @@
+/**
+ * Telemetry helpers — thin wrapper over `@opentelemetry/api`.
+ *
+ * The plugin only uses the OTel **API** package; the global SDK / exporter is
+ * registered by OpenClaw's `diagnostics-otel` plugin. When no global provider
+ * is present (local dev, tests, diagnostics disabled) every call degrades to a
+ * no-op automatically — the API ships no-op meters by default.
+ *
+ * Compliance red line: metric attributes must NEVER carry message text, phone
+ * numbers, or any PII. `safeAttributes` strips non-scalar values and truncates
+ * strings as a backstop, but callers are still responsible for only passing
+ * technical tags (state, result, chat type, middleware name, error class, …).
+ */
+import { context, metrics, propagation, ROOT_CONTEXT, SpanKind, SpanStatusCode, trace, TraceFlags, } from "@opentelemetry/api";
+import { buildRemoteParentOtelContext } from "../business/trace/context.js";
+const METER_NAME = "openclaw-plugin-yuanbao";
+/** Stable metric instrument names (dotted, OTel-style). */
+export const METRIC = {
+    wsConnectionState: "ws.connection.state",
+    wsReconnectCount: "ws.reconnect.count",
+    inboundMessageCount: "inbound.message.count",
+    pipelineExecutionDuration: "pipeline.execution.duration",
+    pipelineErrorCount: "pipeline.error.count",
+    outboundSendCount: "outbound.send.count",
+};
+/** Stable span names (dotted, OTel-style). */
+export const SPAN = {
+    pipelineExecute: "pipeline.execute",
+};
+/** Numeric encoding for the WS connection-state gauge. */
+export const WS_STATE_CODE = {
+    disconnected: 0,
+    connecting: 1,
+    authenticating: 2,
+    reconnecting: 3,
+    connected: 4,
+};
+let meterVersion = "0.0.0";
+/** Set the meter version (plugin version); optional, called once at init. */
+export function setTelemetryVersion(version) {
+    if (version) {
+        meterVersion = version;
+    }
+}
+function getMeter() {
+    return metrics.getMeter(METER_NAME, meterVersion);
+}
+function getTracer() {
+    return trace.getTracer(METER_NAME, meterVersion);
+}
+const counters = new Map();
+const histograms = new Map();
+const gauges = new Map();
+function getCounter(name) {
+    let c = counters.get(name);
+    if (!c) {
+        c = getMeter().createCounter(name);
+        counters.set(name, c);
+    }
+    return c;
+}
+function getHistogram(name) {
+    let h = histograms.get(name);
+    if (!h) {
+        h = getMeter().createHistogram(name);
+        histograms.set(name, h);
+    }
+    return h;
+}
+function getGauge(name) {
+    let g = gauges.get(name);
+    if (!g) {
+        g = getMeter().createGauge(name);
+        gauges.set(name, g);
+    }
+    return g;
+}
+const MAX_ATTR_STR_LEN = 128;
+/**
+ * Drop anything that isn't a scalar (objects/arrays could smuggle PII) and
+ * truncate long strings. Returns undefined when there is nothing to keep.
+ */
+export function safeAttributes(attrs) {
+    if (!attrs) {
+        return undefined;
+    }
+    const out = {};
+    let kept = false;
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value == null) {
+            continue;
+        }
+        if (typeof value === "string") {
+            out[key] = value.length > MAX_ATTR_STR_LEN ? value.slice(0, MAX_ATTR_STR_LEN) : value;
+            kept = true;
+        }
+        else if (typeof value === "number" || typeof value === "boolean") {
+            out[key] = value;
+            kept = true;
+        }
+        // objects / arrays are intentionally dropped to avoid leaking content
+    }
+    return kept ? out : undefined;
+}
+/** Increment a counter (default +1). */
+export function addCount(name, value = 1, attrs) {
+    getCounter(name).add(value, safeAttributes(attrs));
+}
+/** Record a histogram value (e.g. a duration in ms). */
+export function recordDuration(name, value, attrs) {
+    getHistogram(name).record(value, safeAttributes(attrs));
+}
+/** Set the current value of a gauge. */
+export function setGauge(name, value, attrs) {
+    getGauge(name).record(value, safeAttributes(attrs));
+}
+/**
+ * Run `fn` inside an active OTel span. Prefers inbound `traceId` (server logExt)
+ * over W3C `traceparent`: locally generated traceparent uses a random span id
+ * that was never exported, so linking via trace_id keeps APM correlation aligned
+ * with the backend. Falls back to traceparent when traceId is absent.
+ */
+export async function withActiveSpan(name, params, fn) {
+    let parentCtx = ROOT_CONTEXT;
+    const traceparent = params.traceparent?.trim();
+    const traceId = params.traceId?.trim();
+    if (traceId) {
+        parentCtx = buildRemoteParentOtelContext(traceId);
+    }
+    else if (traceparent) {
+        parentCtx = propagation.extract(ROOT_CONTEXT, { traceparent });
+    }
+    const span = getTracer().startSpan(name, {
+        kind: SpanKind.SERVER,
+        attributes: safeAttributes(params.attributes),
+    }, parentCtx);
+    return context.with(trace.setSpan(parentCtx, span), async () => {
+        try {
+            const result = await fn();
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            span.setStatus({ code: SpanStatusCode.ERROR, message });
+            if (err instanceof Error) {
+                span.recordException(err);
+            }
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/** Reset cached instruments — test-only helper. */
+export function __resetTelemetryForTest() {
+    counters.clear();
+    histograms.clear();
+    gauges.clear();
+    meterVersion = "0.0.0";
+}

package/dist/src/infra/transport.js

@@ -5,6 +5,7 @@
  */
 import { createLog } from "../logger.js";
 import { getMember } from "./cache/member.js";
+import { METRIC, addCount } from "./telemetry.js";
 import { InMemoryTtlDb } from "./cache/ttl-db.js";
 import { classifyReplyMode } from "./reply-classify.js";
 const firstReplyRefDb = new InMemoryTtlDb({
@@ -59,6 +60,7 @@ export async function sendC2CMsgBody(params) {
             messageId: result.msgId,
             error: result.code !== 0 ? result.message || `code: ${result.code}` : undefined,
         };
+        addCount(METRIC.outboundSendCount, 1, { chat: "c2c", result: sendResult.ok ? "ok" : "fail" });
         if (!sendResult.ok) {
             log.error("[C2C] send failed", { error: sendResult.error });
         }
@@ -69,6 +71,7 @@ export async function sendC2CMsgBody(params) {
     }
     catch (err) {
         const error = err instanceof Error ? err.message : String(err);
+        addCount(METRIC.outboundSendCount, 1, { chat: "c2c", result: "error" });
         log.error("[C2C] send error", { error });
         return { ok: false, error };
     }
@@ -95,6 +98,7 @@ export async function sendGroupMsgBody(params) {
             messageId: result.msgId,
             error: result.code !== 0 ? result.message || `code: ${result.code}` : undefined,
         };
+        addCount(METRIC.outboundSendCount, 1, { chat: "group", result: sendResult.ok ? "ok" : "fail" });
         if (!sendResult.ok) {
             log.error("[group] send failed", { error: sendResult.error });
         }
@@ -105,6 +109,7 @@ export async function sendGroupMsgBody(params) {
     }
     catch (err) {
         const error = err instanceof Error ? err.message : String(err);
+        addCount(METRIC.outboundSendCount, 1, { chat: "group", result: "error" });
         log.error("[group] send error", { error });
         return { ok: false, error };
     }

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "openclaw-plugin-yuanbao",
-  "version": "2.15.0",
+  "version": "2.15.2-beta.bd3f19cc",
   "name": "YuanBao",
   "description": "YuanBao channel plugin",
   "channels": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-plugin-yuanbao",
-  "version": "2.15.0",
+  "version": "2.15.2-beta.bd3f19cc",
   "type": "module",
   "private": false,
   "description": "Tencent YuanBao intelligent bot channel plugin",
@@ -20,6 +20,7 @@
   ],
   "author": "Tencent YuanBao Team",
   "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
     "protobufjs": "^7.5.4",
     "semver": "^7.7.4",
     "ws": "^8.20.0"