@openclaw/diagnostics-otel 2026.2.15 → 2026.2.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/diagnostics-otel",
-  "version": "2026.2.15",
+  "version": "2026.2.19",
   "description": "OpenClaw diagnostics OpenTelemetry exporter",
   "type": "module",
   "dependencies": {

package/src/service.test.ts

@@ -30,6 +30,7 @@ const sdkStart = vi.hoisted(() => vi.fn().mockResolvedValue(undefined));
 const sdkShutdown = vi.hoisted(() => vi.fn().mockResolvedValue(undefined));
 const logEmit = vi.hoisted(() => vi.fn());
 const logShutdown = vi.hoisted(() => vi.fn().mockResolvedValue(undefined));
+const traceExporterCtor = vi.hoisted(() => vi.fn());
 
 vi.mock("@opentelemetry/api", () => ({
   metrics: {
@@ -55,7 +56,11 @@ vi.mock("@opentelemetry/exporter-metrics-otlp-http", () => ({
 }));
 
 vi.mock("@opentelemetry/exporter-trace-otlp-http", () => ({
-  OTLPTraceExporter: class {},
+  OTLPTraceExporter: class {
+    constructor(options?: unknown) {
+      traceExporterCtor(options);
+    }
+  },
 }));
 
 vi.mock("@opentelemetry/exporter-logs-otlp-http", () => ({
@@ -65,7 +70,6 @@ vi.mock("@opentelemetry/exporter-logs-otlp-http", () => ({
 vi.mock("@opentelemetry/sdk-logs", () => ({
   BatchLogRecordProcessor: class {},
   LoggerProvider: class {
-    addLogRecordProcessor = vi.fn();
     getLogger = vi.fn(() => ({
       emit: logEmit,
     }));
@@ -91,9 +95,7 @@ vi.mock("@opentelemetry/resources", () => ({
 }));
 
 vi.mock("@opentelemetry/semantic-conventions", () => ({
-  SemanticResourceAttributes: {
-    SERVICE_NAME: "service.name",
-  },
+  ATTR_SERVICE_NAME: "service.name",
 }));
 
 vi.mock("openclaw/plugin-sdk", async () => {
@@ -104,9 +106,38 @@ vi.mock("openclaw/plugin-sdk", async () => {
   };
 });
 
+import type { OpenClawPluginServiceContext } from "openclaw/plugin-sdk";
 import { emitDiagnosticEvent } from "openclaw/plugin-sdk";
 import { createDiagnosticsOtelService } from "./service.js";
 
+function createLogger() {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  };
+}
+
+function createTraceOnlyContext(endpoint: string): OpenClawPluginServiceContext {
+  return {
+    config: {
+      diagnostics: {
+        enabled: true,
+        otel: {
+          enabled: true,
+          endpoint,
+          protocol: "http/protobuf",
+          traces: true,
+          metrics: false,
+          logs: false,
+        },
+      },
+    },
+    logger: createLogger(),
+    stateDir: "/tmp/openclaw-diagnostics-otel-test",
+  };
+}
 describe("diagnostics-otel service", () => {
   beforeEach(() => {
     telemetryState.counters.clear();
@@ -118,6 +149,7 @@ describe("diagnostics-otel service", () => {
     sdkShutdown.mockClear();
     logEmit.mockClear();
     logShutdown.mockClear();
+    traceExporterCtor.mockClear();
     registerLogTransportMock.mockReset();
   });
 
@@ -130,7 +162,7 @@ describe("diagnostics-otel service", () => {
     });
 
     const service = createDiagnosticsOtelService();
-    await service.start({
+    const ctx: OpenClawPluginServiceContext = {
       config: {
         diagnostics: {
           enabled: true,
@@ -144,13 +176,10 @@ describe("diagnostics-otel service", () => {
           },
         },
       },
-      logger: {
-        info: vi.fn(),
-        warn: vi.fn(),
-        error: vi.fn(),
-        debug: vi.fn(),
-      },
-    });
+      logger: createLogger(),
+      stateDir: "/tmp/openclaw-diagnostics-otel-test",
+    };
+    await service.start(ctx);
 
     emitDiagnosticEvent({
       type: "webhook.received",
@@ -222,6 +251,46 @@ describe("diagnostics-otel service", () => {
     });
     expect(logEmit).toHaveBeenCalled();
 
-    await service.stop?.();
+    await service.stop?.(ctx);
+  });
+
+  test("appends signal path when endpoint contains non-signal /v1 segment", async () => {
+    const service = createDiagnosticsOtelService();
+    const ctx = createTraceOnlyContext("https://www.comet.com/opik/api/v1/private/otel");
+    await service.start(ctx);
+
+    const options = traceExporterCtor.mock.calls[0]?.[0] as { url?: string } | undefined;
+    expect(options?.url).toBe("https://www.comet.com/opik/api/v1/private/otel/v1/traces");
+    await service.stop?.(ctx);
+  });
+
+  test("keeps already signal-qualified endpoint unchanged", async () => {
+    const service = createDiagnosticsOtelService();
+    const ctx = createTraceOnlyContext("https://collector.example.com/v1/traces");
+    await service.start(ctx);
+
+    const options = traceExporterCtor.mock.calls[0]?.[0] as { url?: string } | undefined;
+    expect(options?.url).toBe("https://collector.example.com/v1/traces");
+    await service.stop?.(ctx);
+  });
+
+  test("keeps signal-qualified endpoint unchanged when it has query params", async () => {
+    const service = createDiagnosticsOtelService();
+    const ctx = createTraceOnlyContext("https://collector.example.com/v1/traces?timeout=30s");
+    await service.start(ctx);
+
+    const options = traceExporterCtor.mock.calls[0]?.[0] as { url?: string } | undefined;
+    expect(options?.url).toBe("https://collector.example.com/v1/traces?timeout=30s");
+    await service.stop?.(ctx);
+  });
+
+  test("keeps signal-qualified endpoint unchanged when signal path casing differs", async () => {
+    const service = createDiagnosticsOtelService();
+    const ctx = createTraceOnlyContext("https://collector.example.com/v1/Traces");
+    await service.start(ctx);
+
+    const options = traceExporterCtor.mock.calls[0]?.[0] as { url?: string } | undefined;
+    expect(options?.url).toBe("https://collector.example.com/v1/Traces");
+    await service.stop?.(ctx);
   });
 });

package/src/service.ts

@@ -1,6 +1,5 @@
-import type { SeverityNumber } from "@opentelemetry/api-logs";
-import type { DiagnosticEventPayload, OpenClawPluginService } from "openclaw/plugin-sdk";
 import { metrics, trace, SpanStatusCode } from "@opentelemetry/api";
+import type { SeverityNumber } from "@opentelemetry/api-logs";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
@@ -9,7 +8,8 @@ import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs
 import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import { ParentBasedSampler, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";
-import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import type { DiagnosticEventPayload, OpenClawPluginService } from "openclaw/plugin-sdk";
 import { onDiagnosticEvent, registerLogTransport } from "openclaw/plugin-sdk";
 
 const DEFAULT_SERVICE_NAME = "openclaw";
@@ -23,7 +23,8 @@ function resolveOtelUrl(endpoint: string | undefined, path: string): string | un
   if (!endpoint) {
     return undefined;
   }
-  if (endpoint.includes("/v1/")) {
+  const endpointWithoutQueryOrFragment = endpoint.split(/[?#]/, 1)[0] ?? endpoint;
+  if (/\/v1\/(?:traces|metrics|logs)$/i.test(endpointWithoutQueryOrFragment)) {
     return endpoint;
   }
   return `${endpoint}/${path}`;
@@ -39,6 +40,20 @@ function resolveSampleRate(value: number | undefined): number | undefined {
   return value;
 }
 
+function formatError(err: unknown): string {
+  if (err instanceof Error) {
+    return err.stack ?? err.message;
+  }
+  if (typeof err === "string") {
+    return err;
+  }
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}
+
 export function createDiagnosticsOtelService(): OpenClawPluginService {
   let sdk: NodeSDK | null = null;
   let logProvider: LoggerProvider | null = null;
@@ -74,7 +89,7 @@ export function createDiagnosticsOtelService(): OpenClawPluginService {
       }
 
       const resource = resourceFromAttributes({
-        [SemanticResourceAttributes.SERVICE_NAME]: serviceName,
+        [ATTR_SERVICE_NAME]: serviceName,
       });
 
       const traceUrl = resolveOtelUrl(endpoint, "v1/traces");
@@ -117,7 +132,12 @@ export function createDiagnosticsOtelService(): OpenClawPluginService {
             : {}),
         });
 
-        sdk.start();
+        try {
+          await sdk.start();
+        } catch (err) {
+          ctx.logger.error(`diagnostics-otel: failed to start SDK: ${formatError(err)}`);
+          throw err;
+        }
       }
 
       const logSeverityMap: Record<string, SeverityNumber> = {
@@ -210,115 +230,122 @@ export function createDiagnosticsOtelService(): OpenClawPluginService {
           ...(logUrl ? { url: logUrl } : {}),
           ...(headers ? { headers } : {}),
         });
-        const processor = new BatchLogRecordProcessor(
+        const logProcessor = new BatchLogRecordProcessor(
           logExporter,
           typeof otel.flushIntervalMs === "number"
             ? { scheduledDelayMillis: Math.max(1000, otel.flushIntervalMs) }
             : {},
         );
-        logProvider = new LoggerProvider({ resource, processors: [processor] });
+        logProvider = new LoggerProvider({
+          resource,
+          processors: [logProcessor],
+        });
         const otelLogger = logProvider.getLogger("openclaw");
 
         stopLogTransport = registerLogTransport((logObj) => {
-          const safeStringify = (value: unknown) => {
-            try {
-              return JSON.stringify(value);
-            } catch {
-              return String(value);
-            }
-          };
-          const meta = (logObj as Record<string, unknown>)._meta as
-            | {
-                logLevelName?: string;
-                date?: Date;
-                name?: string;
-                parentNames?: string[];
-                path?: {
-                  filePath?: string;
-                  fileLine?: string;
-                  fileColumn?: string;
-                  filePathWithLine?: string;
-                  method?: string;
-                };
+          try {
+            const safeStringify = (value: unknown) => {
+              try {
+                return JSON.stringify(value);
+              } catch {
+                return String(value);
               }
-            | undefined;
-          const logLevelName = meta?.logLevelName ?? "INFO";
-          const severityNumber = logSeverityMap[logLevelName] ?? (9 as SeverityNumber);
-
-          const numericArgs = Object.entries(logObj)
-            .filter(([key]) => /^\d+$/.test(key))
-            .toSorted((a, b) => Number(a[0]) - Number(b[0]))
-            .map(([, value]) => value);
-
-          let bindings: Record<string, unknown> | undefined;
-          if (typeof numericArgs[0] === "string" && numericArgs[0].trim().startsWith("{")) {
-            try {
-              const parsed = JSON.parse(numericArgs[0]);
-              if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                bindings = parsed as Record<string, unknown>;
-                numericArgs.shift();
+            };
+            const meta = (logObj as Record<string, unknown>)._meta as
+              | {
+                  logLevelName?: string;
+                  date?: Date;
+                  name?: string;
+                  parentNames?: string[];
+                  path?: {
+                    filePath?: string;
+                    fileLine?: string;
+                    fileColumn?: string;
+                    filePathWithLine?: string;
+                    method?: string;
+                  };
+                }
+              | undefined;
+            const logLevelName = meta?.logLevelName ?? "INFO";
+            const severityNumber = logSeverityMap[logLevelName] ?? (9 as SeverityNumber);
+
+            const numericArgs = Object.entries(logObj)
+              .filter(([key]) => /^\d+$/.test(key))
+              .toSorted((a, b) => Number(a[0]) - Number(b[0]))
+              .map(([, value]) => value);
+
+            let bindings: Record<string, unknown> | undefined;
+            if (typeof numericArgs[0] === "string" && numericArgs[0].trim().startsWith("{")) {
+              try {
+                const parsed = JSON.parse(numericArgs[0]);
+                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                  bindings = parsed as Record<string, unknown>;
+                  numericArgs.shift();
+                }
+              } catch {
+                // ignore malformed json bindings
               }
-            } catch {
-              // ignore malformed json bindings
             }
-          }
 
-          let message = "";
-          if (numericArgs.length > 0 && typeof numericArgs[numericArgs.length - 1] === "string") {
-            message = String(numericArgs.pop());
-          } else if (numericArgs.length === 1) {
-            message = safeStringify(numericArgs[0]);
-            numericArgs.length = 0;
-          }
-          if (!message) {
-            message = "log";
-          }
+            let message = "";
+            if (numericArgs.length > 0 && typeof numericArgs[numericArgs.length - 1] === "string") {
+              message = String(numericArgs.pop());
+            } else if (numericArgs.length === 1) {
+              message = safeStringify(numericArgs[0]);
+              numericArgs.length = 0;
+            }
+            if (!message) {
+              message = "log";
+            }
 
-          const attributes: Record<string, string | number | boolean> = {
-            "openclaw.log.level": logLevelName,
-          };
-          if (meta?.name) {
-            attributes["openclaw.logger"] = meta.name;
-          }
-          if (meta?.parentNames?.length) {
-            attributes["openclaw.logger.parents"] = meta.parentNames.join(".");
-          }
-          if (bindings) {
-            for (const [key, value] of Object.entries(bindings)) {
-              if (
-                typeof value === "string" ||
-                typeof value === "number" ||
-                typeof value === "boolean"
-              ) {
-                attributes[`openclaw.${key}`] = value;
-              } else if (value != null) {
-                attributes[`openclaw.${key}`] = safeStringify(value);
+            const attributes: Record<string, string | number | boolean> = {
+              "openclaw.log.level": logLevelName,
+            };
+            if (meta?.name) {
+              attributes["openclaw.logger"] = meta.name;
+            }
+            if (meta?.parentNames?.length) {
+              attributes["openclaw.logger.parents"] = meta.parentNames.join(".");
+            }
+            if (bindings) {
+              for (const [key, value] of Object.entries(bindings)) {
+                if (
+                  typeof value === "string" ||
+                  typeof value === "number" ||
+                  typeof value === "boolean"
+                ) {
+                  attributes[`openclaw.${key}`] = value;
+                } else if (value != null) {
+                  attributes[`openclaw.${key}`] = safeStringify(value);
+                }
               }
             }
-          }
-          if (numericArgs.length > 0) {
-            attributes["openclaw.log.args"] = safeStringify(numericArgs);
-          }
-          if (meta?.path?.filePath) {
-            attributes["code.filepath"] = meta.path.filePath;
-          }
-          if (meta?.path?.fileLine) {
-            attributes["code.lineno"] = Number(meta.path.fileLine);
-          }
-          if (meta?.path?.method) {
-            attributes["code.function"] = meta.path.method;
-          }
-          if (meta?.path?.filePathWithLine) {
-            attributes["openclaw.code.location"] = meta.path.filePathWithLine;
-          }
+            if (numericArgs.length > 0) {
+              attributes["openclaw.log.args"] = safeStringify(numericArgs);
+            }
+            if (meta?.path?.filePath) {
+              attributes["code.filepath"] = meta.path.filePath;
+            }
+            if (meta?.path?.fileLine) {
+              attributes["code.lineno"] = Number(meta.path.fileLine);
+            }
+            if (meta?.path?.method) {
+              attributes["code.function"] = meta.path.method;
+            }
+            if (meta?.path?.filePathWithLine) {
+              attributes["openclaw.code.location"] = meta.path.filePathWithLine;
+            }
 
-          otelLogger.emit({
-            body: message,
-            severityText: logLevelName,
-            severityNumber,
-            attributes,
-            timestamp: meta?.date ?? new Date(),
-          });
+            otelLogger.emit({
+              body: message,
+              severityText: logLevelName,
+              severityNumber,
+              attributes,
+              timestamp: meta?.date ?? new Date(),
+            });
+          } catch (err) {
+            ctx.logger.error(`diagnostics-otel: log transport failed: ${formatError(err)}`);
+          }
         });
       }
 
@@ -571,43 +598,49 @@ export function createDiagnosticsOtelService(): OpenClawPluginService {
       };
 
       unsubscribe = onDiagnosticEvent((evt: DiagnosticEventPayload) => {
-        switch (evt.type) {
-          case "model.usage":
-            recordModelUsage(evt);
-            return;
-          case "webhook.received":
-            recordWebhookReceived(evt);
-            return;
-          case "webhook.processed":
-            recordWebhookProcessed(evt);
-            return;
-          case "webhook.error":
-            recordWebhookError(evt);
-            return;
-          case "message.queued":
-            recordMessageQueued(evt);
-            return;
-          case "message.processed":
-            recordMessageProcessed(evt);
-            return;
-          case "queue.lane.enqueue":
-            recordLaneEnqueue(evt);
-            return;
-          case "queue.lane.dequeue":
-            recordLaneDequeue(evt);
-            return;
-          case "session.state":
-            recordSessionState(evt);
-            return;
-          case "session.stuck":
-            recordSessionStuck(evt);
-            return;
-          case "run.attempt":
-            recordRunAttempt(evt);
-            return;
-          case "diagnostic.heartbeat":
-            recordHeartbeat(evt);
-            return;
+        try {
+          switch (evt.type) {
+            case "model.usage":
+              recordModelUsage(evt);
+              return;
+            case "webhook.received":
+              recordWebhookReceived(evt);
+              return;
+            case "webhook.processed":
+              recordWebhookProcessed(evt);
+              return;
+            case "webhook.error":
+              recordWebhookError(evt);
+              return;
+            case "message.queued":
+              recordMessageQueued(evt);
+              return;
+            case "message.processed":
+              recordMessageProcessed(evt);
+              return;
+            case "queue.lane.enqueue":
+              recordLaneEnqueue(evt);
+              return;
+            case "queue.lane.dequeue":
+              recordLaneDequeue(evt);
+              return;
+            case "session.state":
+              recordSessionState(evt);
+              return;
+            case "session.stuck":
+              recordSessionStuck(evt);
+              return;
+            case "run.attempt":
+              recordRunAttempt(evt);
+              return;
+            case "diagnostic.heartbeat":
+              recordHeartbeat(evt);
+              return;
+          }
+        } catch (err) {
+          ctx.logger.error(
+            `diagnostics-otel: event handler failed (${evt.type}): ${formatError(err)}`,
+          );
         }
       });