WeaveScope

Quickstart with BeamWeaver

Send your first BeamWeaver trace to WeaveScope.

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

Create a project and API key

Sign in to WeaveScope 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.

Export the key in your development environment:

export WEAVESCOPE_API_KEY=ws_...

Install BeamWeaver

Add BeamWeaver to your dependencies:

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

Then fetch the dependency:

mix deps.get

Configure trace export

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

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 for other providers.

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

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:

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.

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:

BeamWeaver.Tracing.flush_exporter(60_000)

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.

See Troubleshooting if the trace is still missing.

Next steps