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.

Choose a path

Flue runs on several hosts, and the shortest route to a run in the dashboard depends on where your agent runs and what you need from it.

For the full picture of which Runtype features apply to an agent that runs elsewhere, read Bring your own agent.

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.

Before you begin

You need the following:

• Node 22 or later.
• A Flue runtime from 1.0.0-beta.9 onward, or Flue 2.x. The package supports both through one entry point.
• A Runtype agent that receives the runs, and its agent ID.
• A telemetry API key with the Telemetry Ingest permission group (TELEMETRY:WRITE). Keys with AGENTS:WRITE also work.

The quickest way to get the agent and the key is the Connect an existing agent page in the dashboard. Open it from the command palette and choose Flue. Select or create the Receiving agent, then click Create telemetry key. In an empty workspace, the page creates both for you. The page shows a ready-to-run Flue instrumentation file. When the first run arrives, the page shows Trace received.

To set them up yourself, create an agent, then follow Create a telemetry API key.

Install and start

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:

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

instrument() returns a disposer, here stopInstrumenting. Call it when you stop instrumentation. It ends open spans as interrupted and does not flush them, because your application owns the exporter.

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. 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.

createRuntypeFlueInstrumentation() accepts the following options:

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:

import { NodeTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { resourceFromAttributes } from '@opentelemetry/resources'
import { instrument } from '@flue/runtime'
import {
  createRuntypeFlueInstrumentation,
  runtypeFlueResourceAttributes,
} from '@runtypelabs/flue-otel'
const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    'service.name': 'my-agent',
    ...runtypeFlueResourceAttributes({ agentId: process.env.RUNTYPE_AGENT_ID }),
  }),
  spanProcessors: [
    new BatchSpanProcessor(
      new OTLPTraceExporter({
        url: 'https://api.runtype.com/v1/otel/v1/traces',
        headers: { Authorization: `Bearer ${process.env.RUNTYPE_API_KEY}` },
      }),
      { maxExportBatchSize: 32 }
    ),
  ],
})
provider.register()
const stopInstrumenting = instrument(createRuntypeFlueInstrumentation())
process.once('beforeExit', () => void provider.shutdown().catch(console.error))

Set RUNTYPE_AGENT_ID to the ID of the Runtype agent that receives the run. Set RUNTYPE_API_KEY to the telemetry API key. maxExportBatchSize keeps each export request small while content is on. For the reason, see Size limits.

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

Verify the run

To confirm that runs reach Runtype, follow these steps:

1. Run your agent once and let the process exit or flush.
2. In the dashboard, open the agent and select the Runs tab.
3. Open the new run and check the iteration count, the stop reason, and the transcript.

If the run stays in progress, the closing span did not arrive. Check that your application calls forceFlush() or shutdown() on the provider. If no run appears, see Troubleshooting.

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:

createRuntypeFlueInstrumentation({
  agents: {
    triage: 'YOUR_TRIAGE_AGENT_ID',
    billing: 'YOUR_BILLING_AGENT_ID',
  },
})

Replace YOUR_TRIAGE_AGENT_ID and YOUR_BILLING_AGENT_ID with the corresponding Runtype agent IDs.

The package reports a delegated sub-agent as a tool call on the parent run. The sub-agent’s work stays in the delegating agent’s trace, and one trace represents one execution, so delegation does not create a second run.

What it emits

The instrumentation emits the following span types and attributes:

The package sets runtype.stop_reason to one of these values: end_turn, length, content_filter, error, or unknown.

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.

If your application already exports to another backend, pass a tracer from a separate provider that exports only to Runtype. Runtype’s spans then leave through that provider, and the rest of the process keeps its own exporter.

Control what content is sent

By default, the package sends the conversation, the final output, the system prompt, and each tool’s arguments and result. Each kind has its own switch, and every switch defaults to on. Runs need the conversation to show a transcript and to be captured as eval cases.

To send shape and cost only, with no content of any kind, pass content: false:

instrument(createRuntypeFlueInstrumentation({ content: false }))

Message content

Three switches control the content on the run’s invoke_agent span:

instrument(
  createRuntypeFlueInstrumentation({
    content: {
      inputMessages: true,
      outputMessages: true,
      systemInstructions: false,
    },
  })
)

• inputMessages is the conversation as the run’s last model turn saw it, including user messages sent while the run was in progress. Runtype shows it as the run’s transcript and uses it when you capture the run as an eval case.
• outputMessages is the final assistant text of the run. Runtype shows it as the run’s final output.
• systemInstructions is the system prompt. It is usually the largest value a run carries and rarely differs between runs, so it is the switch most deployments turn off.

Messages carry text only. Tool calls, tool results, thinking and image parts, and system rows in the history are left out. Message content behaves the same on Flue 1.x and 2.x.

Tool content

Each execute_tool span carries the tool’s arguments and result, shown on the tool’s card in the trace view. To drop either, switch it off:

instrument(
  createRuntypeFlueInstrumentation({
    content: {
      toolArguments: true,
      toolResults: false,
    },
  })
)

Runtype shows arguments as a JSON object. The package wraps a non-object value as { "value": ... }. A string result is sent as-is, and any other result is sent as JSON.

A delegation to a sub-agent is a tool call whose arguments carry the prompt handed to that sub-agent. To keep that prompt out of the export, return undefined from redact for the delegation tool, as shown in Redact content.

Size limits

maxChars sets the longest value the package sends, including the truncation marker. It defaults to 64 KiB and is capped at 256 KiB, because Runtype drops a single content attribute larger than that whole instead of cutting it.

Runtype accepts at most 384 KiB of content on one span. To stay under that limit, the package applies lower caps whatever maxChars says:

• Tool arguments and tool results are each capped at 192 KiB.
• Each message value and the system prompt on the run span are capped at 128 KiB.

When a value is too long, the package shortens it so that it still reads as incomplete:

• A result is cut and ends with …[truncated N chars].
• Arguments are replaced by { "truncated": "..." }, which holds the start of the JSON and the same marker, so they stay a valid object.
• A message list drops its oldest messages first, so the newest survive.

Runtype also limits the total content of one trace, and drops content past that limit. For the limit, see Capture conversation content.

Content makes spans large. One export request can carry at most 8 MiB, and a larger request is rejected whole. A batch of 512 spans, the BatchSpanProcessor default, can exceed that. Set maxExportBatchSize to 16 to 32 for agents with many tool calls, or 64 for short runs.

Redact content

redact runs on every content value before encoding and truncation. It receives the value and a context whose kind names the content:

Return undefined to drop that one attribute. If redact throws, the package drops that attribute and sends the rest of the span.

The following example masks email addresses in the conversation and drops the prompt that a delegate tool hands to a sub-agent:

import { instrument } from '@flue/runtime'
import {
  createRuntypeFlueInstrumentation,
  type FlueContentMessage,
} from '@runtypelabs/flue-otel'
const EMAIL = /[^\s@]+@[^\s@]+\.[^\s@]+/g
instrument(
  createRuntypeFlueInstrumentation({
    content: {
      redact: (value, context) => {
        if (context.kind === 'arguments' && context.toolName === 'delegate') return undefined
        if (context.kind !== 'input_messages') return value
        return (value as FlueContentMessage[]).map((message) => ({
          ...message,
          parts: message.parts.map((part) => ({
            ...part,
            content: part.content.replace(EMAIL, '[email]'),
          })),
        }))
      },
    },
  })
)

What it does not send

Whatever you set, the package never sends error messages or stack traces, a failed tool’s result, content from the host’s own session.shell() call, thinking or image parts, or Flue’s internal signal messages.

With content: false, the package sends only identifiers, structure, metrics, model IDs, token counts, durations, tool names, correlation IDs, error types, and exception class names for failed spans. This has two consequences:

• 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 the transcript.

Deploy on Cloudflare Workers

Workers Observability traces a Flue 2 agent deployed with @flue/vite and @cloudflare/vite-plugin automatically. It emits an invoke_agent span per run, a chat span per model turn, and an execute_tool span per tool call, in the same GenAI semantic conventions that this package emits, with conversation content included by default. You do not install this package or an OpenTelemetry SDK. Export the Workers traces to Runtype instead.

To export Workers traces to Runtype, follow these steps:

1. In the Cloudflare dashboard, open Workers Observability and add a destination of type Traces with the endpoint https://api.runtype.com/v1/otel/v1/traces and two custom headers: Authorization: Bearer rt_YOUR_TELEMETRY_KEY and x-runtype-agent-id: agent_YOUR_AGENT_ID. Replace rt_YOUR_TELEMETRY_KEY with your telemetry API key and agent_YOUR_AGENT_ID with the ID of the Runtype agent that receives the runs. Exporting Workers traces to an OTLP destination requires a Workers Paid plan.

2. Reference the destination in wrangler.jsonc:

   wrangler.jsonc

   {
     "observability": {
       "traces": {
         "enabled": true,
         "destinations": ["runtype"],
         "head_sampling_rate": 1,
       },
     },
   }

3. Run npx vite build && npx wrangler deploy and start a conversation. Each successful response appears under the agent’s Runs with a transcript, so you can capture it as an eval case.

Each response produces its own trace, and Runtype records each trace as a separate run, even when two messages share a conversation. A canceled response might not produce a completed run.

To remove the content, register instrument(createCloudflareTracing({ content: false })) from @flue/runtime/cloudflare at module scope in app.ts. The runs then lose eval capture as well.

Let Runtype call your Flue agent

Telemetry sends data from your agent to Runtype. To let Runtype call your agent, register it as an external agent whose endpoint streams Runtype execution events. You can then test it from the dashboard, put a Persona chat widget or a surface in front of it, or run it on a schedule. Create the agent with this request:

{
  "name": "Support agent (Flue)",
  "agentType": "external",
  "externalConfig": {
    "endpoint": "https://my-worker.example.workers.dev/dispatch",
    "protocol": "runtype-stream",
    "framework": "flue",
    "auth": { "type": "bearer", "credentials": "{{secret:MY_AGENT_TOKEN}}" }
  }
}

The endpoint receives POST {endpoint} with { "messages": [...], "context": { "conversationId": "..." } }. It answers with a text/event-stream of execution events: execution_start first, then one terminal execution_complete or execution_error last. The ExecutionStreamEvent union in the API reference lists every event. In a Flue 2 app, the route runs the turn with init(agent, { id: conversationId }) and handle.dispatch(message), then maps each chunk from handle.read(receipt, { onEvent }) onto the matching event.

Eval suites do not run against a runtype-stream endpoint. They run against an A2A endpoint. For the feature matrix, see Bring your own agent.

Troubleshooting

The following table lists common export problems:

To check what Runtype received for a trace, use Inspect ingest health.

Next steps

Continue with these guides:

• Bring your own agent: which Runtype features apply to an agent that runs elsewhere, and how to wire each.
• Improving your agents from production traces: turn ingested runs into evals and regression cases.
• Authentication: review API key scopes and authentication options.