> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Flue (tracing)

> Trace Flue TypeScript runtime workflows and agents with Respan including model turns, tools, tasks, shell operations, compaction, and structured logs.

[Flue](https://flueframework.com/) is a TypeScript agent harness framework for autonomous agents and AI workflows. Use `@respan/instrumentation-flue` to subscribe to Flue runtime events and emit canonical Respan spans.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Example projects

* [TypeScript examples](https://github.com/respanai/respan-example-projects/tree/main/typescript/tracing/flue)

## Setup

#### Install packages

```bash
npm install @flue/runtime @respan/respan @respan/tracing @respan/instrumentation-flue
```

#### Set environment variables

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

#### Initialize Respan before Flue handles activity

```typescript
import * as FlueRuntime from "@flue/runtime";
import { Respan } from "@respan/respan";
import { FlueInstrumentor } from "@respan/instrumentation-flue";

const respan = new Respan({
  apiKey: process.env.RESPAN_API_KEY,
  baseURL: process.env.RESPAN_BASE_URL,
  appName: "flue-tracing",
  instrumentations: [
    new FlueInstrumentor({
      runtimeModule: FlueRuntime,
      workflowName: "Flue App.workflow",
    }),
  ],
});

await respan.initialize();
```

Register the instrumentor once during application startup, before Flue handles workflow or agent activity.

#### Run Flue activity inside a Respan workflow

```typescript
await respan.propagateAttributes(
  {
    trace_group_identifier: "Flue App.workflow",
    metadata: {
      service: "agent-runtime",
      framework: "flue",
    },
  },
  async () => {
    await respan.withWorkflow({ name: "Flue App" }, async () => {
      // Run your Flue agent, workflow, or runtime activity here.
    });
  }
);

```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see Flue workflow runs, agent sessions, model turns, tool executions, tasks, shell operations, compaction events, and structured logs.

## Captured data

| Data             | Description                                                                 |
| ---------------- | --------------------------------------------------------------------------- |
| Workflow runs    | Flue run lifecycle events, inputs, outputs, duration, and errors.           |
| Direct agents    | Agent lifecycle events for direct Flue agent sessions.                      |
| Model turns      | Model request, response, usage, provider, API type, and reasoning metadata. |
| Tools            | Tool names, arguments, outputs, durations, and errors.                      |
| Tasks            | Delegated task prompts, agents, results, durations, and failures.           |
| Shell operations | Shell command operations and command failure details.                       |
| Compaction       | Context compaction metadata including before/after message counts.          |
| Structured logs  | Flue application logs emitted through the runtime context.                  |

## Attributes

Use Respan attributes to group Flue runs by user, trace group, or deployment.

```typescript
await respan.propagateAttributes(
  {
    customer_identifier: "user_123",
    thread_identifier: "flue-session-abc",
    trace_group_identifier: "Support Agent.workflow",
    metadata: {
      environment: "production",
      channel: "support",
    },
  },
  async () => {
    await respan.withWorkflow({ name: "Support Agent" }, runFlueAgent);
  }
);
```

| Attribute                | Type     | Description                                    |
| ------------------------ | -------- | ---------------------------------------------- |
| `customer_identifier`    | `string` | Identifies the end user in Respan analytics.   |
| `thread_identifier`      | `string` | Groups related Flue activity into a session.   |
| `trace_group_identifier` | `string` | Groups related spans into a named trace group. |
| `metadata`               | `object` | Custom key-value pairs attached to spans.      |

## Notes

* `@respan/instrumentation-flue` listens to Flue's runtime `observe()` event stream.
* Pass `runtimeModule` when your app imports `@flue/runtime` directly. This ensures the instrumentor observes the same runtime module instance your application uses.
* The TypeScript examples are deterministic and emit representative Flue workflow, agent, model-turn, tool, task, compaction, log, and recovery events without calling an external LLM provider.