Workflow:Wandb Weave Tracing Setup
| Knowledge Sources | |
|---|---|
| Domains | LLM_Ops, Observability, Tracing |
| Last Updated | 2026-02-14 11:00 GMT |
Overview
End-to-end process for instrumenting Python functions with Weave tracing to capture inputs, outputs, and execution metadata for LLM application debugging and monitoring.
Description
This workflow covers the fundamental usage pattern of the Weave SDK: initializing a Weave project, decorating functions with the @weave.op decorator, and executing traced functions to generate call trees. The tracing system automatically captures function arguments, return values, execution timing, and parent-child call relationships. Traces are sent to the Weave backend where they can be viewed, searched, and analyzed through the Weights & Biases UI. The decorator supports synchronous functions, asynchronous functions, generators, and methods on Weave Objects.
Usage
Execute this workflow when you are building or debugging a Generative AI application and need to capture a structured record of function calls, LLM interactions, and data transformations. This is the starting point for any Weave instrumentation and is required before using Evaluations, Monitoring, or Integration tracing.
Execution Steps
Step 1: Install the SDK
Install the Weave Python package from PyPI. The package requires Python 3.10 or higher and includes core dependencies such as Pydantic, W&B client, and HTTP transport libraries.
Key considerations:
- Ensure Python 3.10+ is available in your environment
- A Weights & Biases account is required (free tier available)
- Optional extras can be installed for specific integrations
Step 2: Initialize the Weave Client
Call the initialization function with a project name to establish a connection to the Weave backend. This authenticates with Weights & Biases, resolves the entity and project identifiers, creates a global client context, and optionally enables automatic integration patching for LLM providers.
Key considerations:
- The project name follows the format entity/project or just project (defaults to current W&B entity)
- Authentication uses existing W&B credentials or triggers an interactive login
- The client is stored in a global context and shared across all traced operations
- Integration auto-patching can be disabled via settings if explicit control is needed
Step 3: Decorate Functions with the Op Decorator
Apply the @weave.op decorator to any function you want traced. The decorator wraps the function to intercept calls, create trace records, and forward results to the Weave backend. It preserves the original function signature and supports sync, async, generator, and async generator functions.
Key considerations:
- The decorator auto-detects function type (sync, async, generator) and applies the appropriate wrapper
- Nested decorated functions create parent-child call relationships automatically
- Methods on classes inheriting from weave.Object or weave.Model are also supported
- Custom display names can be set for better readability in the trace UI
Step 4: Execute Traced Functions
Call the decorated functions as normal. Each invocation creates a Call object that records inputs, outputs, timing, exceptions, and trace metadata. Call trees are built automatically when traced functions invoke other traced functions.
Key considerations:
- No changes needed to the calling code; the decorator handles all instrumentation
- Exceptions are captured and recorded before being re-raised
- Streaming and generator outputs are accumulated and logged upon completion
- Sampling can be configured to trace only a fraction of calls in high-throughput scenarios
Step 5: Publish and Retrieve Objects
Optionally publish traced operations, datasets, or other Weave objects to the backend for versioning and reuse. Published objects receive a unique reference URI that can be used to retrieve them later.
Key considerations:
- Each publish creates a new version of the object
- Objects are retrieved using weave.ref() or weave.get()
- The attributes context manager allows attaching custom metadata to calls
Step 6: Finalize the Session
Call the finish function to flush any pending traces and close the connection to the Weave backend. This ensures all captured data is persisted before the process exits.
Key considerations:
- Always call finish at the end of scripts to prevent data loss
- In long-running services, the client manages its own connection lifecycle