tracelet-instrument

Goal: make an agent's execution visible — every LLM call, tool call, prompt, token count and latency — without sending anything to a cloud service. tracelet is a local OTLP collector + UI; any OpenTelemetry exporter pointed at http://127.0.0.1:4318 shows up live.

Procedure

1. Start the collector (keep it running in a terminal):

bash npx @jnmetacode/tracelet # ingests OTLP on :4318, UI on :4321

1. Point the app's exporter at it. For most OpenTelemetry SDKs the zero-code

route is environment variables:

bash export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 export OTEL_SERVICE_NAME=my-agent

1. Framework-specific wiring (pick the one that matches the codebase):

Vercel AI SDK — pass telemetry on each call and register a Node tracer:

js const result = await generateText({ model, prompt, experimental_telemetry: { isEnabled: true }, });

OpenTelemetry JS (manual spans):

js import { NodeSDK } from '@opentelemetry/sdk-node'; import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'; new NodeSDK({ traceExporter: new OTLPTraceExporter({ url: 'http://127.0.0.1:4318/v1/traces' }) }).start();

Python: pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http, then the same OTEL_EXPORTER_OTLP_ENDPOINT env var works.

1. Name spans so the waterfall reads like the agent's plan: one root span per

run (agent.run), one child per tool call (tool.<name>) and per model call. Attach gen_ai.request.model, input.value, output.value attributes — tracelet recognizes the GenAI/OpenInference conventions and renders prompts, tokens and tool I/O.

1. Verify: trigger one agent run, open http://127.0.0.1:4321, and confirm

the trace shows the expected span tree with prompts/tokens. If nothing arrives, the exporter is usually pointed at the wrong port (4318) or batching hasn't flushed — force a flush/shutdown on process exit.

Both OTLP/HTTP protobuf (SDK default) and JSON are accepted — no exporter config gymnastics needed.