Instrumenting a Flue agent

@runtypelabs/flue-otel is OpenTelemetry instrumentation from Runtype for Flue agents. Install it with Flue’s instrument() function, configure an OTLP exporter for Runtype, and view each instrumented run in the dashboard. Runtype displays the model, token usage, cost, loop iterations, tool calls, and stop reason.

Your agent continues to run with your model credentials. Runtype provides the dashboard where you inspect the run.

When to use this instead of a generic exporter

Reporting telemetry from an external agent covers the general path. A generic exporter sends the GenAI semantic-convention attributes that your spans contain.

This package adds two values that a generic export cannot derive after the spans leave the process:

• An exact loop iteration count. Flue events do not include an absolute ordinal. If you rank turn IDs after export, you count only the turns in the export batch. A five-turn run whose final batch has two turns appears to have two iterations. The instrumentation counts each agent turn before export.
• A run-level stop reason and summed token usage. The instrumentation sums token counts from model turns and adds the total to the run’s invoke_agent span. The run span retains that total when model spans flush in separate batches.

The package reports a delegated sub-agent as a tool call on the parent run. One trace represents one execution, so delegation does not create a second execution.

Install and start

Use Node 22 or later and a Flue runtime that exposes instrument(). Install the package and the OpenTelemetry API with this command:

$
npm install @runtypelabs/flue-otel @opentelemetry/api

Register the instrumentation with Flue using this code:

1
import { instrument } from '@flue/runtime'
2
import { createRuntypeFlueInstrumentation } from '@runtypelabs/flue-otel'
3
4
const stopInstrumenting = instrument(createRuntypeFlueInstrumentation())

The package supports Flue >=1.0.0-beta.9 and 2.x through one entry point.

For OpenTelemetry, the package depends on @opentelemetry/api and does not include an SDK, provider, exporter, sampler, or resource. Your application configures those components, and the instrumentation writes spans through the provider that you register. The instrumentation does not flush spans.

If your application already configures OpenTelemetry, register the instrumentation and add the resource attributes that identify the Runtype agent. Use runtypeFlueResourceAttributes({ agentId }) as described in Attribution.

Create a telemetry key with the Telemetry Ingest permission group. For the key creation steps, see Create a telemetry API key.

Set up an OpenTelemetry pipeline

If your application does not have an OpenTelemetry pipeline, install @opentelemetry/sdk-trace-node, @opentelemetry/exporter-trace-otlp-http, and @opentelemetry/resources. Configure the provider, exporter, and instrumentation with this example:

1
import { NodeTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-node'
2
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
3
import { resourceFromAttributes } from '@opentelemetry/resources'
4
import { instrument } from '@flue/runtime'
5
import {
6
  createRuntypeFlueInstrumentation,
7
  runtypeFlueResourceAttributes,
8
} from '@runtypelabs/flue-otel'
9
10
const provider = new NodeTracerProvider({
11
  resource: resourceFromAttributes({
12
    'service.name': 'my-agent',
13
    ...runtypeFlueResourceAttributes({ agentId: process.env.RUNTYPE_AGENT_ID }),
14
  }),
15
  spanProcessors: [
16
    new BatchSpanProcessor(
17
      new OTLPTraceExporter({
18
        url: 'https://api.runtype.com/v1/otel/v1/traces',
19
        headers: { Authorization: `Bearer ${process.env.RUNTYPE_API_KEY}` },
20
      })
21
    ),
22
  ],
23
})
24
provider.register()
25
26
instrument(createRuntypeFlueInstrumentation())
27
28
process.on('beforeExit', () => void provider.shutdown())

Set RUNTYPE_AGENT_ID to the ID of the Runtype agent that receives the run. Set RUNTYPE_API_KEY to the telemetry key.

The following settings keep spans in one trace and preserve the closing run span:

Flue’s instrument() returns a disposer. Call it when you stop instrumentation. It ends open spans as interrupted. It does not flush spans because your application owns the exporter.

Attribution: which Runtype agent owns the run

Runtype resolves the agent for each trace in this order:

1. The runtype.agent.id resource attribute. The runtypeFlueResourceAttributes({ agentId }) helper sets it.
2. The x-runtype-agent-id request header that your exporter sends.
3. The runtype.agent.id attribute on the run’s invoke_agent span. The agents option sets it.

Use the resource attribute or request header when one process runs one Runtype agent.

Run several agents in one process

When one process runs several agents, map each Flue agent name to a Runtype agent ID with the agents option:

1
createRuntypeFlueInstrumentation({
2
  agents: {
3
    triage: 'YOUR_TRIAGE_AGENT_ID',
4
    billing: 'YOUR_BILLING_AGENT_ID',
5
  },
6
})

Replace YOUR_TRIAGE_AGENT_ID and YOUR_BILLING_AGENT_ID with the corresponding Runtype agent IDs.

The package does not attribute a delegated sub-agent separately. The sub-agent’s work stays in the delegating agent’s trace, and one trace represents one execution.

What it emits

The instrumentation emits the following span types and attributes:

Every span also carries the flue.* correlation attributes that the standard @flue/opentelemetry instrumentation emits. These attributes support dashboards that group spans by Flue correlation keys.

The following details explain two intentional omissions:

Compose with other instrumentations

Flue’s instrument() supports multiple subscribers. This package uses a separate instrumentation key, so it does not replace @flue/opentelemetry.

If you already export Flue traces to Runtype with the standard @flue/opentelemetry instrumentation, replace it with this package for that endpoint.

What it does not send

The package sends no prompts, completions, tool arguments, tool results, error messages, or stack traces. It sends identifiers, structure, metrics, model IDs, token counts, durations, tool names, correlation IDs, error types, and exception class names for failed spans.

This integration does not export content. It does not configure content fields for the spans that it creates.

Before you choose this package, account for these effects:

• Runs have no transcript. You can inspect timing, cost, iteration counts, and the tool call sequence, but not the exchanged text.
• Eval capture is unavailable. Capturing an external run into an eval suite requires content.

The standard @flue/opentelemetry instrumentation exports content by default. If you need transcripts or eval capture, use that instrumentation instead. This package provides the exact loop count, stop reason, and summed run-level usage described in this guide.

Next steps

Continue with these guides:

• Improving your agents from production traces: turn ingested runs into evals and regression cases.
• Authentication: review API key scopes and authentication options.