OpenTelemetry

pip install opentelemetry-sdk==1.45.1 opentelemetry-instrumentation-requests==0.66b1 requests==2.32.5

mkdir -p /tmp/hue-http-demo
printf '%s\n' '{"messages":[{"id":"synthetic-1","snippet":"Synthetic message"}]}' > /tmp/hue-http-demo/messages.json
python -m http.server 8765 --bind 127.0.0.1 --directory /tmp/hue-http-demo

import json
from urllib.parse import urlsplit

import requests
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

LIMIT = 1024 * 1024


def capture_loaded_json(span, request, response):
    if not span.is_recording() or not response._content_consumed:
        return
    url = urlsplit(request.url)
    if (
        request.method != "GET"
        or url.hostname != "127.0.0.1"
        or url.path != "/messages.json"
        or url.query
        or request.body is not None
    ):
        return
    if len(response.content) > LIMIT:
        return
    content_type = response.headers.get("content-type", "").split(";", 1)[0]
    if content_type != "application/json":
        return
    try:
        output = json.dumps(response.json())
    except ValueError:
        return
    if len(output.encode("utf-8")) <= LIMIT:
        span.set_attribute("input.value", "{}")
        span.set_attribute("output.value", output)
        span.set_attribute("output.mime_type", content_type)


provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
instrumentor = RequestsInstrumentor()
instrumentor.instrument(tracer_provider=provider, response_hook=capture_loaded_json)
try:
    response = requests.get("http://127.0.0.1:8765/messages.json", timeout=5)
    response.raise_for_status()
    assert response.json()["messages"][0]["id"] == "synthetic-1"
finally:
    instrumentor.uninstrument()
    provider.shutdown()

receivers:
  otlp: # Standard exporters keep the default paths.
    protocols:
      http:
        endpoint: 127.0.0.1:4318
  otlp/hue-sdk: # The Hue SDKs post to their own paths.
    protocols:
      http:
        endpoint: 127.0.0.1:4319
        traces_url_path: /api/v1/otlp/v1/traces
        logs_url_path: /api/v1/otlp/v1/logs

const hue = createHue({ apiKey, serviceName: "my-agent", captureContent: true, baseUrl: "http://127.0.0.1:4319", liveSpans: false });

hue = Hue(api_key=api_key, base_url="http://127.0.0.1:4319", service_name="my-agent", capture_content=True, live_spans=False)

bun add @opentelemetry/sdk-trace@2.11.0 @opentelemetry/sdk-logs@0.222.0 @opentelemetry/resources@2.11.0

import { createHue, createHueTransport } from "@hue-run/sdk";
import { TracerProvider } from "@opentelemetry/sdk-trace";
import { LoggerProvider } from "@opentelemetry/sdk-logs";
import { resourceFromAttributes } from "@opentelemetry/resources";

const apiKey = process.env.HUE_API_KEY;
if (!apiKey) throw new Error("Set HUE_API_KEY in your server environment.");

const transport = createHueTransport({
  apiKey,
  serviceName: "existing-otel-demo",
  captureContent: true, // Keep recorded prompts, responses and tool inputs/outputs.
});
const resource = resourceFromAttributes({ "service.name": "existing-otel-demo" });
// Add Hue processors when constructing your application's providers.
const tracerProvider = new TracerProvider({
  resource,
  spanProcessors: [transport.spanProcessor],
});
const loggerProvider = new LoggerProvider({
  resource,
  processors: [transport.logRecordProcessor],
});
// Reuse these providers for Hue helpers and your existing instrumentation.
const hue = createHue({ transport, tracerProvider, loggerProvider });

try {
  await hue.checkConnection();
  const span = tracerProvider.getTracer("example.instrumentation").startSpan("example.work");
  try {
    span.setAttribute("example.operation", "verification");
    console.log("Trace ID:", span.spanContext().traceId);
  } finally {
    span.end();
  }
  // Export after the span ends, then inspect the delivery counters.
  console.log("Delivery counters:", await hue.flush());
} finally {
  try {
    await hue.shutdown();
  } finally {
    await Promise.allSettled([tracerProvider.shutdown(), loggerProvider.shutdown()]);
    await transport.shutdown();
  }
}

+ import { createHueTransport } from "@hue-run/sdk";
+ import { redactEmails } from "./redaction.ts";

  const langfuseSpanProcessor = new LangfuseSpanProcessor();
+ let hueTransport: ReturnType<typeof createHueTransport> | undefined;
+ try {
+   hueTransport = createHueTransport({
+     apiKey: process.env.HUE_API_KEY ?? "",
+     enabled: process.env.HUE_TRACING_ENABLED !== "false",
+     serviceName: "my-agent",
+     captureContent: true,
+     redact: redactEmails,
+   });
+ } catch {
+   // Keep existing tracing available. Do not log the key or exception object.
+   try { console.warn("Hue tracing initialization failed"); } catch {}
+ }

  const sdk = new NodeSDK({
    spanProcessors: [
      langfuseSpanProcessor,
+     ...(hueTransport ? [hueTransport.spanProcessor] : []),
    ],
  });

consumeSseStream: ({ stream }) => {
  // Start reading immediately so generation can finish after the response returns.
  const consumed = consumeStream({ stream });
  after(async () => {
    try {
      // Wait for stream completion before exporting the final spans.
      await consumed;
    } finally {
      const delivery = await hue.flushSafe({ timeoutMillis: 1000 });
      if (!delivery.ok) {
        // Diagnostics must also be unable to break application cleanup.
        try {
          console.warn("Hue telemetry flush incomplete", {
            timedOut: delivery.timedOut,
            ...delivery.report,
          });
        } catch {}
      }
    }
  });
},

import { SpanStatusCode, trace } from "@opentelemetry/api";

// The globally registered provider, as NodeSDK or provider.register() sets it.
// With a standalone provider, call provider.getTracer("support-agent") instead.
const tracer = trace.getTracer("support-agent");

export function handleRequest(input: string) {
  return tracer.startActiveSpan("agent.support_reply", async (root) => {
    const requestId = crypto.randomUUID();
    const mark = (name: string) => root.addEvent(name, { "hue.request.id": requestId });
    root.setAttributes({
      "hue.request.id": requestId,
      "hue.request.owner": true,
      "hue.request.origin": "foreground",
      "hue.agent.release": process.env.APP_RELEASE ?? "development",
    });
    mark("hue.request.received");
    try {
      const reply = await runAgent(input, { onFirstToken: () => mark("hue.response.first") });
      mark("hue.response.useful");
      return reply;
    } catch (error) {
      // A failed request is an error span; its timing then has no useful answer.
      root.setStatus({ code: SpanStatusCode.ERROR });
      throw error;
    } finally {
      mark("hue.request.completed");
      root.end();
    }
  });
}

{
  "version": 1,
  "requestKind": "task",
  "request": { "spanId": "<root span id>", "field": "attributes", "path": ["app.user_request"], "start": 0, "end": 64 },
  "authorization": [],
  "boundaries": [
    { "kind": "action", "spanId": "<tool span id>", "content": { "spanId": "<tool span id>", "field": "attributes", "path": ["gen_ai.tool.call.arguments"], "start": 0, "end": 120 } },
    { "kind": "delegation", "spanId": "<handoff span id>", "parent": { "spanId": "<root span id>", "field": "attributes", "path": ["app.user_request"], "start": 0, "end": 64 }, "content": { "spanId": "<handoff span id>", "field": "attributes", "path": ["app.delegated_task"], "start": 0, "end": 88 } }
  ],
  "linkedTraces": [{ "traceId": "<sub-agent trace id>", "parentSpanId": "<handoff span id>" }],
  "complete": true
}

{
  "kind": "output_reduction",
  "spanId": "<reduction span id>",
  "task": { "spanId": "<reduction span id>", "field": "attributes", "path": ["app.reduction_task"], "start": 0, "end": 40 },
  "original": { "spanId": "<tool span id>", "field": "attributes", "path": ["gen_ai.tool.call.result"], "start": 0, "end": 5120 },
  "retained": { "spanId": "<reduction span id>", "field": "attributes", "path": ["app.retained_output"], "start": 0, "end": 900 },
  "code": { "spanId": "<reduction span id>", "field": "attributes", "path": ["app.reduction_code"], "start": 0, "end": 300 },
  "decision": { "spanId": "<next model span id>", "field": "attributes", "path": ["app.decision"], "start": 0, "end": 200 },
  "use": { "spanId": "<reply span id>", "field": "attributes", "path": ["app.final_reply"], "start": 0, "end": 480 }
}