BeamWeaver integration

Export BeamWeaver agent, model, and tool traces to WeaveScope.

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 .

Configure trace export

Store the project API key in your environment:

export WEAVESCOPE_API_KEY=ws_...

Configure BeamWeaver in config/runtime.exs:

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:

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

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:

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:

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:

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