Configure the destination
Use the project service key from Settings → Integrations & API keys. The key determines the destination project; a project ID inside an attribute does not grant access.
Set the complete signal-specific endpoints in your exporter’s configuration. Do not accidentally append another
/v1/traces or /v1/logs to them. Store the authorization value in your server environment or secret manager.
These routes accept the OpenTelemetry wire format, not arbitrary application JSON. Metrics ingestion and OTLP gRPC are not currently supported. Logs support trace-correlated evidence; this is not a general log-search service.
Attach Hue transport to JavaScript providers
If you want Hue’s content controls and export diagnostics while keeping provider ownership, attach its processors when you construct your providers. Install the TypeScript package, then install these explicit provider dependencies:otel.ts. This standalone example owns the providers it creates. In an existing application, add the processors to your existing provider construction and retain your normal global registration and propagation setup.
node otel.ts after setting your environment. An export rejection makes the command fail rather than reporting successful delivery. Hue does not register or replace a global tracer, logger, or context manager. An instrumentor that only uses global providers still needs your application’s normal OpenTelemetry initialization.
Flush streamed responses in Next.js
For an existing AI SDK 7 app, add Hue’s processors to your existing OpenTelemetry provider at startup and includetransport.flush() in your existing flushTelemetry() function. Keep the same transport instance for the server’s lifetime.
In the route, import consumeStream from ai and after from next/server. Replace a standalone after(flushTelemetry) with this option inside your existing createAgentUIStreamResponse call:
request.signal on generation, but do not pass it to this reader. Your agent and message-handling callbacks stay as they are.
Report flush failures in server logs. Do not shut down a shared transport after each request. Hosting timeouts and process termination can still interrupt delivery. See the AI SDK stream-abort guide.
Map agent data without inventing it
Hue preserves original resource, scope, status, events, links, dropped counts, typed attributes, and external trace/span IDs. It derives AI fields alongside those records using versioned normalization profiles. Supported profile families include generic OpenTelemetry, GenAI conventions, OpenInference, OpenLLMetry, and Vercel AI SDK 6/7. A profile family is not a guarantee that every package version or API surface has been tested. The TypeScript adapter is verified with AI SDK / OTel pairs7.0.99 / 1.0.99 and 7.0.100 / 1.0.100.
Prefer current GenAI attributes when your instrumentation supports them, including gen_ai.provider.name, gen_ai.request.model, gen_ai.usage.input_tokens, and gen_ai.usage.output_tokens. Preserve unavailable fields as absent. Do not submit 0 for unknown usage or null for an output that was never captured.
A child can arrive before its parent, and a correlated log can arrive before its span. Preserve the same trace ID and the correct parent/span IDs across services. Root-span completion does not prove that the whole distributed trace has arrived. Evaluations use a pinned evidence revision.
Control content at its source
When using an external exporter directly, configure capture and redaction in your instrumentation or collector. Hue stores the content it receives; it does not reconstruct missing prompts or apply an automatic retention timer. The TypeScript Hue transport filters recognized content whencaptureContent is false. Python’s capture_content controls Hue helpers and does not filter arbitrary third-party instrumentors. Avoid sensitive values in custom metadata regardless of your chosen SDK.