Send OpenTelemetry Traces to Weave ↗

    import json
    import os
    from opentelemetry import trace
    from opentelemetry.sdk import trace as trace_sdk
    from opentelemetry.sdk.resources import Resource
    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
    from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor

    # Configuration
    ENTITY = "<your-team-name>"
    PROJECT = "<your-project-name>"
    WANDB_API_KEY = os.environ["WANDB_API_KEY"]

    OTEL_EXPORTER_OTLP_ENDPOINT = "https://trace.wandb.ai/otel/v1/traces"

    exporter = OTLPSpanExporter(
        endpoint=OTEL_EXPORTER_OTLP_ENDPOINT,
        headers={"wandb-api-key": WANDB_API_KEY},
    )

    tracer_provider = trace_sdk.TracerProvider(resource=Resource({
        "wandb.entity": ENTITY,
        "wandb.project": PROJECT,
    }))
    tracer_provider.add_span_processor(BatchSpanProcessor(exporter))

    # Optionally, print the spans to the console
    tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

    trace.set_tracer_provider(tracer_provider)

    # Creates a tracer from the global tracer provider
    tracer = trace.get_tracer(__name__)
    ```
<span class="tab-end"></span>

<span class="tab-start" data-tab-title="TypeScript"></span>
```typescript
    import { trace, context } from "@opentelemetry/api";
    import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
    import {
      BatchSpanProcessor,
      ConsoleSpanExporter,
    } from "@opentelemetry/sdk-trace-base";
    import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
    import { Resource } from "@opentelemetry/resources";

    // Configuration
    const ENTITY = "<your-team-name>";
    const PROJECT = "<your-project-name>";
    const WANDB_API_KEY = process.env.WANDB_API_KEY;

    if (!WANDB_API_KEY) {
      console.error("Error: WANDB_API_KEY environment variable is not set");
      console.error("Run: export WANDB_API_KEY=your_api_key_here");
      process.exit(1);
    }

    // OTel Setup
    const OTEL_EXPORTER_OTLP_ENDPOINT = "https://trace.wandb.ai/otel/v1/traces";

    const exporter = new OTLPTraceExporter({
      url: OTEL_EXPORTER_OTLP_ENDPOINT,
      headers: { "wandb-api-key": WANDB_API_KEY },
    });

    // Initialize tracer provider with span processors
    const provider = new NodeTracerProvider({
      resource: new Resource({
        "wandb.entity": ENTITY,
        "wandb.project": PROJECT,
      }),
      spanProcessors: [
        new BatchSpanProcessor(exporter),
        new BatchSpanProcessor(new ConsoleSpanExporter()),
      ],
    });

    // Register the tracer provider
    provider.register();

    // Create a tracer from the global tracer provider
    const tracer = trace.getTracer("threads-examples");
    ```
<span class="tab-end"></span>
<span class="tab-group-end"></span>
</Accordion>

<Accordion title="Trace a basic single-turn thread">
<span class="tab-group-start"></span>
<span class="tab-start" data-tab-title="Python"></span>
```python
    def example_1_basic_thread_and_turn():
        """Example 1: Basic thread with a single turn"""
        print("\n=== Example 1: Basic Thread and Turn ===")

        # Create a thread context
        thread_id = "thread_example_1"

        # This span represents a turn (direct child of thread)
        with tracer.start_as_current_span("process_user_message") as turn_span:
            # Set thread attributes
            turn_span.set_attribute("wandb.thread_id", thread_id)
            turn_span.set_attribute("wandb.is_turn", True)

            # Add some example attributes
            turn_span.set_attribute("input.value", "Hello, help me with setup")

            # Simulate some work with nested spans
            with tracer.start_as_current_span("generate_response") as nested_span:
                # This is a nested call within the turn, so is_turn should be false or unset
                nested_span.set_attribute("wandb.thread_id", thread_id)
                # wandb.is_turn is not set or set to False for nested calls

                response = "I'll help you get started with the setup process."
                nested_span.set_attribute("output.value", response)

            turn_span.set_attribute("output.value", response)
            print(f"Turn completed in thread: {thread_id}")

    def main():
        example_1_basic_thread_and_turn()

    if __name__ == "__main__":
        main()
    ```
<span class="tab-end"></span>

<span class="tab-start" data-tab-title="TypeScript"></span>
```typescript
    function example_1_basic_thread_and_turn() {
      console.log("\n=== Example 1: Basic Thread and Turn ===");

      // Create a thread context
      const threadId = "thread_example_1";

      // This span represents a turn (direct child of thread)
      tracer.startActiveSpan("process_user_message", (turnSpan) => {
        // Set thread attributes
        turnSpan.setAttribute("wandb.thread_id", threadId);
        turnSpan.setAttribute("wandb.is_turn", true);

        // Add some example attributes
        turnSpan.setAttribute("input.value", "Hello, help me with setup");

        let response: string;
        
        // Simulate some work with nested spans
        tracer.startActiveSpan("generate_response", (nestedSpan) => {
          // This is a nested call within the turn, so is_turn should be false or unset
          nestedSpan.setAttribute("wandb.thread_id", threadId);
          // wandb.is_turn is not set or set to false for nested calls

          response = "I'll help you get started with the setup process.";
          nestedSpan.setAttribute("output.value", response);
          nestedSpan.end();
        });
        
        turnSpan.setAttribute("output.value", response!);
        console.log(`Turn completed in thread: ${threadId}`);
        turnSpan.end();
      });
    }

    function main() {
      example_1_basic_thread_and_turn();
    }

    main();
    ```
<span class="tab-end"></span>
<span class="tab-group-end"></span>
</Accordion>

<Accordion title="Trace a multi-turn conversation sharing one thread ID">
<span class="tab-group-start"></span>
<span class="tab-start" data-tab-title="Python"></span>
```python
    def example_2_multiple_turns():
        """Example 2: Multiple turns in a single thread"""
        print("\n=== Example 2: Multiple Turns in Thread ===")

        thread_id = "thread_conversation_123"

        # Turn 1
        with tracer.start_as_current_span("process_message_turn1") as turn1_span:
            turn1_span.set_attribute("wandb.thread_id", thread_id)
            turn1_span.set_attribute("wandb.is_turn", True)
            turn1_span.set_attribute("input.value", "What programming languages do you recommend?")

            # Nested operations
            with tracer.start_as_current_span("analyze_query") as analyze_span:
                analyze_span.set_attribute("wandb.thread_id", thread_id)
                # No is_turn attribute or set to False for nested spans

            response1 = "I recommend Python for beginners and JavaScript for web development."
            turn1_span.set_attribute("output.value", response1)
            print(f"Turn 1 completed in thread: {thread_id}")

        # Turn 2
        with tracer.start_as_current_span("process_message_turn2") as turn2_span:
            turn2_span.set_attribute("wandb.thread_id", thread_id)
            turn2_span.set_attribute("wandb.is_turn", True)
            turn2_span.set_attribute("input.value", "Can you explain Python vs JavaScript?")

            # Nested operations
            with tracer.start_as_current_span("comparison_analysis") as compare_span:
                compare_span.set_attribute("wandb.thread_id", thread_id)
                compare_span.set_attribute("wandb.is_turn", False)  # Explicitly false for nested

            response2 = "Python excels at data science while JavaScript dominates web development."
            turn2_span.set_attribute("output.value", response2)
            print(f"Turn 2 completed in thread: {thread_id}")

    def main():
        example_2_multiple_turns()

    if __name__ == "__main__":
        main()
    ```
<span class="tab-end"></span>

<span class="tab-start" data-tab-title="TypeScript"></span>
```typescript
    function example_2_multiple_turns() {
      console.log("\n=== Example 2: Multiple Turns in Thread ===");

      const threadId = "thread_conversation_123";

      // Turn 1
      tracer.startActiveSpan("process_message_turn1", (turn1Span) => {
        turn1Span.setAttribute("wandb.thread_id", threadId);
        turn1Span.setAttribute("wandb.is_turn", true);
        turn1Span.setAttribute(
          "input.value",
          "What programming languages do you recommend?"
        );

        // Nested operations
        tracer.startActiveSpan("analyze_query", (analyzeSpan) => {
          analyzeSpan.setAttribute("wandb.thread_id", threadId);
          // No is_turn attribute or set to false for nested spans
          analyzeSpan.end();
        });

        const response1 =
          "I recommend Python for beginners and JavaScript for web development.";
        turn1Span.setAttribute("output.value", response1);
        console.log(`Turn 1 completed in thread: ${threadId}`);
        turn1Span.end();
      });

      // Turn 2
      tracer.startActiveSpan("process_message_turn2", (turn2Span) => {
        turn2Span.setAttribute("wandb.thread_id", threadId);
        turn2Span.setAttribute("wandb.is_turn", true);
        turn2Span.setAttribute("input.value", "Can you explain Python vs JavaScript?");

        // Nested operations
        tracer.startActiveSpan("comparison_analysis", (compareSpan) => {
          compareSpan.setAttribute("wandb.thread_id", threadId);
          compareSpan.setAttribute("wandb.is_turn", false); // Explicitly false for nested
          compareSpan.end();
        });

        const response2 =
          "Python excels at data science while JavaScript dominates web development.";
        turn2Span.setAttribute("output.value", response2);
        console.log(`Turn 2 completed in thread: ${threadId}`);
        turn2Span.end();
      });
    }

    function main() {
      example_2_multiple_turns();
    }

    main();
    ```
<span class="tab-end"></span>
<span class="tab-group-end"></span>
</Accordion>

<Accordion title="Trace deeply nested operations and mark only the outermost span as a turn">
<span class="tab-group-start"></span>
<span class="tab-start" data-tab-title="Python"></span>
```python
    def example_3_complex_nested_structure():
        """Example 3: Complex nested structure with multiple levels"""
        print("\n=== Example 3: Complex Nested Structure ===")

        thread_id = "thread_complex_456"

        # Turn with multiple levels of nesting
        with tracer.start_as_current_span("handle_complex_request") as turn_span:
            turn_span.set_attribute("wandb.thread_id", thread_id)
            turn_span.set_attribute("wandb.is_turn", True)
            turn_span.set_attribute("input.value", "Analyze this code and suggest improvements")

            # Level 1 nested operation
            with tracer.start_as_current_span("code_analysis") as analysis_span:
                analysis_span.set_attribute("wandb.thread_id", thread_id)
                # No is_turn for nested operations

                # Level 2 nested operation
                with tracer.start_as_current_span("syntax_check") as syntax_span:
                    syntax_span.set_attribute("wandb.thread_id", thread_id)
                    syntax_span.set_attribute("result", "No syntax errors found")

                # Another Level 2 nested operation
                with tracer.start_as_current_span("performance_check") as perf_span:
                    perf_span.set_attribute("wandb.thread_id", thread_id)
                    perf_span.set_attribute("result", "Found 2 optimization opportunities")

            # Another Level 1 nested operation
            with tracer.start_as_current_span("generate_suggestions") as suggest_span:
                suggest_span.set_attribute("wandb.thread_id", thread_id)
                suggestions = ["Use list comprehension", "Consider caching results"]
                suggest_span.set_attribute("suggestions", json.dumps(suggestions))

            turn_span.set_attribute("output.value", "Analysis complete with 2 improvement suggestions")
            print(f"Complex turn completed in thread: {thread_id}")

    def main():
        example_3_complex_nested_structure()

    if __name__ == "__main__":
        main()
    ```
<span class="tab-end"></span>

<span class="tab-start" data-tab-title="TypeScript"></span>
```typescript
    function example_3_complex_nested_structure() {
      console.log("\n=== Example 3: Complex Nested Structure ===");

      const threadId = "thread_complex_456";

      // Turn with multiple levels of nesting
      tracer.startActiveSpan("handle_complex_request", (turnSpan) => {
        turnSpan.setAttribute("wandb.thread_id", threadId);
        turnSpan.setAttribute("wandb.is_turn", true);
        turnSpan.setAttribute(
          "input.value",
          "Analyze this code and suggest improvements"
        );

        // Level 1 nested operation
        tracer.startActiveSpan("code_analysis", (analysisSpan) => {
          analysisSpan.setAttribute("wandb.thread_id", threadId);
          // No is_turn for nested operations

          // Level 2 nested operation
          tracer.startActiveSpan("syntax_check", (syntaxSpan) => {
            syntaxSpan.setAttribute("wandb.thread_id", threadId);
            syntaxSpan.setAttribute("result", "No syntax errors found");
            syntaxSpan.end();
          });

          // Another Level 2 nested operation
          tracer.startActiveSpan("performance_check", (perfSpan) => {
            perfSpan.setAttribute("wandb.thread_id", threadId);
            perfSpan.setAttribute("result", "Found 2 optimization opportunities");
            perfSpan.end();
          });

          analysisSpan.end();
        });

        // Another Level 1 nested operation
        tracer.startActiveSpan("generate_suggestions", (suggestSpan) => {
          suggestSpan.setAttribute("wandb.thread_id", threadId);
          const suggestions = ["Use list comprehension", "Consider caching results"];
          suggestSpan.setAttribute("suggestions", JSON.stringify(suggestions));
          suggestSpan.end();
        });

        turnSpan.setAttribute(
          "output.value",
          "Analysis complete with 2 improvement suggestions"
        );
        console.log(`Complex turn completed in thread: ${threadId}`);
        turnSpan.end();
      });
    }

    function main() {
      example_3_complex_nested_structure();
    }

    main();
    ```
<span class="tab-end"></span>
<span class="tab-group-end"></span>
</Accordion>

<Accordion title="Trace background operations that belong to a thread but aren't turns">
<span class="tab-group-start"></span>
<span class="tab-start" data-tab-title="Python"></span>
```python
    def example_4_non_turn_operations():
        """Example 4: Operations that are part of a thread but not turns"""
        print("\n=== Example 4: Non-Turn Thread Operations ===")

        thread_id = "thread_background_789"

        # Background operation that's part of thread but not a turn
        with tracer.start_as_current_span("background_indexing") as bg_span:
            bg_span.set_attribute("wandb.thread_id", thread_id)
            # wandb.is_turn is unset or false - this is not a turn
            bg_span.set_attribute("wandb.is_turn", False)
            bg_span.set_attribute("operation", "Indexing conversation history")
            print(f"Background operation in thread: {thread_id}")

        # Actual turn in the same thread
        with tracer.start_as_current_span("user_query") as turn_span:
            turn_span.set_attribute("wandb.thread_id", thread_id)
            turn_span.set_attribute("wandb.is_turn", True)
            turn_span.set_attribute("input.value", "Search my previous conversations")
            turn_span.set_attribute("output.value", "Found 5 relevant conversations")
            print(f"Turn completed in thread: {thread_id}")

    def main():
        example_4_non_turn_operations()

    if __name__ == "__main__":
        main()
    ```
<span class="tab-end"></span>

<span class="tab-start" data-tab-title="TypeScript"></span>
```typescript
    function example_4_non_turn_operations() {
      console.log("\n=== Example 4: Non-Turn Thread Operations ===");

      const threadId = "thread_background_789";

      // Background operation that's part of thread but not a turn
      tracer.startActiveSpan("background_indexing", (bgSpan) => {
        bgSpan.setAttribute("wandb.thread_id", threadId);
        // wandb.is_turn is unset or false - this is not a turn
        bgSpan.setAttribute("wandb.is_turn", false);
        bgSpan.setAttribute("operation", "Indexing conversation history");
        console.log(`Background operation in thread: ${threadId}`);
        bgSpan.end();
      });

      // Actual turn in the same thread
      tracer.startActiveSpan("user_query", (turnSpan) => {
        turnSpan.setAttribute("wandb.thread_id", threadId);
        turnSpan.setAttribute("wandb.is_turn", true);
        turnSpan.setAttribute("input.value", "Search my previous conversations");
        turnSpan.setAttribute("output.value", "Found 5 relevant conversations");
        console.log(`Turn completed in thread: ${threadId}`);
        turnSpan.end();
      });
    }

    function main() {
      example_4_non_turn_operations();
    }

    main();
    ```
<span class="tab-end"></span>
<span class="tab-group-end"></span>
</Accordion>

After sending these traces, you can view them in the Weave UI under the **Threads** tab, where they'll be grouped by `thread_id` and each turn will appear as a separate row.

## Attribute Mappings

Weave automatically maps OpenTelemetry span attributes from various instrumentation frameworks to its internal data model. When multiple attribute names map to the same field, Weave applies them in priority order, allowing frameworks to coexist in the same traces.

### Supported Frameworks

Weave supports attribute conventions from the following observability frameworks and SDKs:

* **OpenTelemetry GenAI**: Standard semantic conventions for generative AI (`gen_ai.*`)
* **OpenInference**: Arize AI's instrumentation library (`input.value`, `output.value`, `llm.*`, `openinference.*`)
* **Vercel AI SDK**: Vercel's AI SDK attributes (`ai.prompt`, `ai.response`, `ai.model.*`, `ai.usage.*`)
* **MLflow**: MLflow tracking attributes (`mlflow.spanInputs`, `mlflow.spanOutputs`)
* **Traceloop**: OpenLLMetry instrumentation (`traceloop.entity.*`, `traceloop.span.kind`)
* **Google Vertex AI**: Vertex AI agent attributes (`gcp.vertex.agent.*`)
* **OpenLit**: OpenLit observability attributes (`gen_ai.content.completion`)
* **Langfuse**: Langfuse tracing attributes (`langfuse.startTime`, `langfuse.endTime`)

### Attribute Reference

| Attribute Field Name              | W\&B Mapping                  | Description                            | Type                        | Example                                        |
| :-------------------------------- | :---------------------------- | :------------------------------------- | :-------------------------- | :--------------------------------------------- |
| `ai.prompt`                       | `inputs`                      | User prompt text or messages.          | String, list, dict          | `"Write a short haiku about summer."`          |
| `gen_ai.prompt`                   | `inputs`                      | AI model prompt or message array.      | List, dict, string          | `[{"role":"user","content":"abc"}]`            |
| `input.value`                     | `inputs`                      | Input value for model invocation.      | String, list, dict          | `{"text":"Tell a joke"}`                       |
| `mlflow.spanInputs`               | `inputs`                      | Span input data.                       | String, list, dict          | `["prompt text"]`                              |
| `traceloop.entity.input`          | `inputs`                      | Entity input data.                     | String, list, dict          | `"Translate this to French"`                   |
| `gcp.vertex.agent.tool_call_args` | `inputs`                      | Tool call arguments.                   | Dict                        | `{"args":{"query":"weather in SF"}}`           |
| `gcp.vertex.agent.llm_request`    | `inputs`                      | LLM request payload.                   | Dict                        | `{"contents":[{"role":"user","parts":[...]}]}` |
| `input`                           | `inputs`                      | Generic input value.                   | String, list, dict          | `"Summarize this text"`                        |
| `inputs`                          | `inputs`                      | Generic input array.                   | List, dict, string          | `["Summarize this text"]`                      |
| `ai.response`                     | `outputs`                     | Model response text or data.           | String, list, dict          | `"Here is a haiku..."`                         |
| `gen_ai.completion`               | `outputs`                     | AI completion result.                  | String, list, dict          | `"Completion text"`                            |
| `output.value`                    | `outputs`                     | Output value from model.               | String, list, dict          | `{"text":"Answer text"}`                       |
| `mlflow.spanOutputs`              | `outputs`                     | Span output data.                      | String, list, dict          | `["answer"]`                                   |
| `gen_ai.content.completion`       | `outputs`                     | Content completion result.             | String                      | `"Answer text"`                                |
| `traceloop.entity.output`         | `outputs`                     | Entity output data.                    | String, list, dict          | `"Answer text"`                                |
| `gcp.vertex.agent.tool_response`  | `outputs`                     | Tool execution response.               | Dict, string                | `{"toolResponse":"ok"}`                        |
| `gcp.vertex.agent.llm_response`   | `outputs`                     | LLM response payload.                  | Dict, string                | `{"candidates":[...]}`                         |
| `output`                          | `outputs`                     | Generic output value.                  | String, list, dict          | `"Answer text"`                                |
| `outputs`                         | `outputs`                     | Generic output array.                  | List, dict, string          | `["Answer text"]`                              |
| `gen_ai.usage.input_tokens`       | `usage.input_tokens`          | Number of input tokens consumed.       | Int                         | `42`                                           |
| `gen_ai.usage.prompt_tokens`      | `usage.prompt_tokens`         | Number of prompt tokens consumed.      | Int                         | `30`                                           |
| `llm.token_count.prompt`          | `usage.prompt_tokens`         | Prompt token count.                    | Int                         | `30`                                           |
| `ai.usage.promptTokens`           | `usage.prompt_tokens`         | Prompt tokens consumed.                | Int                         | `30`                                           |
| `gen_ai.usage.completion_tokens`  | `usage.completion_tokens`     | Number of completion tokens generated. | Int                         | `40`                                           |
| `llm.token_count.completion`      | `usage.completion_tokens`     | Completion token count.                | Int                         | `40`                                           |
| `ai.usage.completionTokens`       | `usage.completion_tokens`     | Completion tokens generated.           | Int                         | `40`                                           |
| `llm.usage.total_tokens`          | `usage.total_tokens`          | Total tokens used in request.          | Int                         | `70`                                           |
| `llm.token_count.total`           | `usage.total_tokens`          | Total token count.                     | Int                         | `70`                                           |
| `gen_ai.system`                   | `attributes.system`           | System prompt or instructions.         | String                      | `"You are a helpful assistant."`               |
| `llm.system`                      | `attributes.system`           | System prompt or instructions.         | String                      | `"You are a helpful assistant."`               |
| `weave.span.kind`                 | `attributes.kind`             | Span type or category.                 | String                      | `"llm"`                                        |
| `traceloop.span.kind`             | `attributes.kind`             | Span type or category.                 | String                      | `"llm"`                                        |
| `openinference.span.kind`         | `attributes.kind`             | Span type or category.                 | String                      | `"llm"`                                        |
| `gen_ai.response.model`           | `attributes.model`            | Model identifier.                      | String                      | `"gpt-4o"`                                     |
| `llm.model_name`                  | `attributes.model`            | Model identifier.                      | String                      | `"gpt-4o-mini"`                                |
| `ai.model.id`                     | `attributes.model`            | Model identifier.                      | String                      | `"gpt-4o"`                                     |
| `llm.provider`                    | `attributes.provider`         | Model provider name.                   | String                      | `"openai"`                                     |
| `ai.model.provider`               | `attributes.provider`         | Model provider name.                   | String                      | `"openai"`                                     |
| `gen_ai.request`                  | `attributes.model_parameters` | Model generation parameters.           | Dict                        | `{"temperature":0.7,"max_tokens":256}`         |
| `llm.invocation_parameters`       | `attributes.model_parameters` | Model invocation parameters.           | Dict                        | `{"temperature":0.2}`                          |
| `wandb.display_name`              | `display_name`                | Custom display name for UI.            | String                      | `"User Message"`                               |
| `gcp.vertex.agent.session_id`     | `thread_id`                   | Session or thread identifier.          | String                      | `"thread_123"`                                 |
| `wandb.thread_id`                 | `thread_id`                   | Thread identifier for conversations.   | String                      | `"thread_123"`                                 |
| `wb_run_id`                       | `wb_run_id`                   | Associated W\&B run identifier.        | String                      | `"abc123"`                                     |
| `wandb.wb_run_id`                 | `wb_run_id`                   | Associated W\&B run identifier.        | String                      | `"abc123"`                                     |
| `gcp.vertex.agent.session_id`     | `is_turn`                     | Marks span as conversation turn.       | Boolean                     | `true`                                         |
| `wandb.is_turn`                   | `is_turn`                     | Marks span as conversation turn.       | Boolean                     | `true`                                         |
| `langfuse.startTime`              | `start_time` (override)       | Override span start timestamp.         | Timestamp (ISO8601/unix ns) | `"2024-01-01T12:00:00Z"`                       |
| `langfuse.endTime`                | `end_time` (override)         | Override span end timestamp.           | Timestamp (ISO8601/unix ns) | `"2024-01-01T12:00:01Z"`                       |

## Limitations

* The Weave UI does not support rendering OTel trace tool calls the Chat view. They appear as raw JSON instead.