---
description: Export BeamWeaver agent, model, and tool traces to WeaveScope.
---

# BeamWeaver integration

BeamWeaver is the recommended WeaveScope integration for Elixir applications.
It captures agent runs, model calls, tool calls, errors, usage, and metadata,
then exports them without blocking the application request.

For BeamWeaver concepts and APIs beyond tracing, use the
[BeamWeaver documentation](https://docs.weavescope.com/beamweaver).

## Configure trace export

Store the project API key in your environment:

```bash
export WEAVESCOPE_API_KEY=ws_...
```

Configure BeamWeaver in `config/runtime.exs`:

```elixir
import Config

config :beam_weaver,
  weave_scope: [
    endpoint: "https://app.weavescope.com",
    api_key: System.fetch_env!("WEAVESCOPE_API_KEY")
  ]
```

Configure model-provider credentials separately. Keep only the providers your
application calls:

```elixir
config :beam_weaver,
  openai: [api_key: System.fetch_env!("OPENAI_API_KEY")],
  anthropic: [api_key: System.fetch_env!("ANTHROPIC_API_KEY")],
  google: [api_key: System.fetch_env!("GOOGLE_API_KEY")]
```

See the [BeamWeaver provider guides](https://docs.weavescope.com/beamweaver/partners)
for supported providers, models, and provider-specific options.

## Add trace identity

Pass `trace:` at the application boundary so the complete workflow shares one
trace ID:

```elixir
MyAgent.invoke(input,
  trace: [
    name: "customer_support_agent",
    thread_id: thread.id,
    user_id: thread.user_id,
    session_id: thread.session_id,
    execution_mode: "support_chat",
    environment: "production",
    fields: %{ticket_id: ticket.id, account_id: account.id},
    metadata: %{feature: "support_inbox"}
  ]
)
```

| Field | Use |
| --- | --- |
| `:name` | Name shown for the root trace. |
| `:thread_id` | Conversation or durable workflow thread. |
| `:user_id` | Authenticated end user. |
| `:session_id` | Browser, job, or application session. |
| `:execution_mode` | Workflow mode, such as `ai_chat` or `background_job`. |
| `:environment` | Deployment environment. |
| `:fields` / `:custom_fields` | Flat, indexed values available to filters. |
| `:metadata` | Additional context shown in trace details. |

Custom fields accept flat string dimensions. BeamWeaver drops blank or nested
values, private keys, and secret-like fields such as `api_key`, `token`,
`secret`, `password`, and `authorization`.

## What BeamWeaver sends

BeamWeaver sends native observation events to:

```text
POST /api/v1/observations/batch
```

Depending on the operation, an observation can include:

- Trace, observation, and parent observation IDs
- Run kind, name, status, and timestamps
- Tags, metadata, context metadata, and custom fields
- Inputs, outputs, and errors
- Provider, model, request ID, finish reason, and service tier
- Token usage and cost metadata
- Tool call IDs and structured-output metadata

When tracing is active, model and tool calls become child observations under
the current agent or workflow trace.

## Export behavior

BeamWeaver exports observations through a supervised background queue:

| Setting | Default |
| --- | ---: |
| Batch size | 50 observations |
| Flush interval | 250 ms |
| Maximum queued observations | 10,000 |
| When the queue is full | Drop the oldest observation |
| Initial retry delay | 100 ms with backoff |
| Maximum attempts | 5 |

Transient transport failures are retried. Invalid payloads are not retried.
Export failures are logged but do not change the result of the application path
being traced.

Flush the queue before a short-lived process exits:

```elixir
BeamWeaver.Tracing.flush_exporter(60_000)
```

## Preserve trace context in tasks

BeamWeaver propagates trace context through its graph nodes. If your own code
starts supervised tasks, use the BeamWeaver tracing helpers to keep child runs
under the current trace:

```elixir
task =
  BeamWeaver.Tracing.async(MyApp.TaskSupervisor, fn ->
    BeamWeaver.Tracing.with_run("model call", fn ->
      call_model()
    end)
  end)
```

A detached task without the active context starts a separate root trace. See
the [BeamWeaver tracing guide](https://docs.weavescope.com/beamweaver/tracing)
for additional context-propagation patterns.

## Redaction

Before export, BeamWeaver redacts common secrets from inputs, outputs,
metadata, usage, and errors. This includes authorization headers, API keys,
bearer tokens, URL credentials, query-string secrets, private-key blocks, and
common secret fields.

Review the data your application records before enabling tracing in production.
Redaction reduces accidental exposure, but it does not replace application-level
data classification and filtering.