---
description: Send your first BeamWeaver trace to WeaveScope.
---

# Quickstart with BeamWeaver

Connect an Elixir application, run one traced operation, and inspect the result
in WeaveScope.

## Before you begin

You need:

- An Elixir application
- Credentials for the model provider your application calls
- Permission to create a project API key in WeaveScope

{% stepper %}
{% step %}
### Create a project and API key

[Sign in to WeaveScope](https://app.weavescope.com/auth/login) and complete
onboarding. WeaveScope creates your first project and shows its API key during
the connection step.

The key is shown in full only once. Store the complete `ws_...` value in your
application's secrets manager.

{% hint style="warning" %}
You cannot retrieve the full key later. If you lose it, revoke it and create a
replacement from **Settings → API keys**.
{% endhint %}

Export the key in your development environment:

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

{% endstep %}
{% step %}
### Install BeamWeaver

Add BeamWeaver to your dependencies:

```elixir
# mix.exs
defp deps do
  [
    {:beam_weaver, "~> 0.1.16"}
  ]
end
```

Then fetch the dependency:

```bash
mix deps.get
```

{% endstep %}
{% step %}
### Configure trace export

Configure your model provider and WeaveScope in `config/runtime.exs`:

```elixir
import Config

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

Keep only the provider configuration your application needs. See the
[BeamWeaver provider guides](https://docs.weavescope.com/beamweaver/partners)
for other providers.

When both `endpoint` and `api_key` are configured, BeamWeaver exports traces
through its background queue.

{% endstep %}
{% step %}
### Trace an operation

Pass `trace:` at the boundary of the operation you want to observe. Child model
and tool calls then share the same trace:

```elixir
def run_report(report, user) do
  MyApp.Agents.ReportAgent.invoke(%{topic: report.topic},
    trace: [
      name: "report.workflow",
      user_id: user.id,
      thread_id: report.id,
      session_id: report.session_id,
      execution_mode: "scheduled_report",
      environment: "production",
      fields: %{
        account_id: user.account_id,
        report_id: report.id
      },
      metadata: %{trigger: "scheduler"}
    ]
  )
end
```

Use `fields` for flat values you want to filter by. Use `metadata` for context
that only needs to appear in trace details.

{% endstep %}
{% step %}
### Flush short-lived processes

Phoenix applications and other long-running OTP services can rely on the
supervised export queue. A short-lived script should flush the queue before it
exits:

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

{% endstep %}
{% step %}
### Inspect the trace

Open **Tracing** in WeaveScope and select the project that owns the API key.
Your trace should appear after the ingestion queue processes it.

If it does not appear, check that:

- You selected the correct project.
- The time range includes the trace start time.
- The API key has not been revoked.
- A short-lived process flushed its export queue.
- The ingestion request was accepted.

{% hint style="info" %}
A `202 Accepted` response means WeaveScope queued the data for processing. The
trace list and monitoring charts may take a moment to update.
{% endhint %}

See [Troubleshooting](troubleshooting.md) if the trace is still missing.

{% endstep %}
{% endstepper %}

## Next steps

- [Debug a trace](debug-traces.md) to inspect messages, tool calls, payloads,
  errors, and timings.
- Read [How tracing works](tracing-model.md) before building a custom exporter.
- Open [Monitoring](monitoring.md) after production traffic starts flowing.
- Review [Model pricing](model-pricing.md) if a model shows zero cost.