Observability — OpenTelemetry (self-host)

FluxyChat ships lightweight telemetry hooks in the SDK and Worker. Export to console for local dev, or OTLP HTTP for self-hosted backends — no SaaS required.

SDK

import {
  createTelemetryManager,
  registerTelemetry,
  createConsoleTelemetryIntegration,
  createOtlpTelemetryIntegration,
} from "@fluxy-chat/sdk";

const telemetry = createTelemetryManager({ functionId: "support-agent" });

registerTelemetry(telemetry, createConsoleTelemetryIntegration());

registerTelemetry(
  telemetry,
  createOtlpTelemetryIntegration({
    endpoint: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ?? "http://localhost:4318/v1/traces",
    serviceName: "my-app",
  }),
);

Wire telemetry.record(...) from your agent middleware or use OpenTelemetryIntegration when you already have an OTel tracer.

Worker

The Worker exposes a diagnostics-style channel via tracing.publish / tracing.subscribe:

import { tracing } from "./lib/tracing.js";
import { attachOtlpTracingExport } from "./lib/tracing-otlp.js";

attachOtlpTracingExport({
  tracing,
  endpoint: env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ?? "http://localhost:4318/v1/traces",
  serviceName: "fluxy-chat-worker",
});

Self-host backends (zero SaaS)

GenAI spans follow semantic-conventions-genai split from OpenTelemetry semconv 1.42.0 (Development): invoke_agent {name}, execute_tool {tool}, gen_ai.conversation.id = room id. HITL wait is a child span fluxy.approval.wait with fluxy.approval.wait_ms. Outbound webhooks and ticket HTTP carry W3C traceparent.

Set OTEL_EXPORTER_OTLP_TRACES_ENDPOINT in Worker secrets or your app env. Telemetry export is best-effort and never blocks chat delivery.

DevTools inspector

For interactive debugging (token usage, tool calls, timeline), use the dashboard DevTools page (/devtools) and SDK createDevToolsInspector. See DevTools inspector guide.