> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Distributed Tracing

> How to trace application execution across multiple services.

When your AI application spans multiple services (an API gateway calling an agent service, an orchestrator invoking a Lambda function), you need traces from all services to appear in a single session. Distributed tracing links events across process boundaries so you can debug end-to-end.

```mermaid theme={null}
sequenceDiagram
    participant Client as Client Request
    participant Gateway as API Gateway
    participant UserSvc as User Service
    participant LLMSvc as LLM Service
    
    Client->>Gateway: HTTP Request<br/>trace-id: abc123
    
    Gateway->>UserSvc: Internal Call<br/>trace-id: abc123
    
    UserSvc->>LLMSvc: LLM Request<br/>trace-id: abc123
    LLMSvc->>LLMSvc: OpenAI Call
    LLMSvc-->>UserSvc: LLM Response
    
    UserSvc-->>Gateway: Result
    Gateway-->>Client: Final Response
    
    Note over Client,LLMSvc: All operations linked by trace-id
```

## Choose Your Approach

HoneyHive supports two approaches. Pick the one that fits your needs.

<Tabs>
  <Tab title="Session ID (Simple)">
    Pass the session ID between services so all events land in the same session. Events are grouped together but appear as siblings, not as parent-child.

    **Best for:** Simple architectures, serverless (Lambda), cases where you only need events in the same session.

    <Steps>
      <Step title="Get the session ID from Service A">
        ```python theme={null}
        from honeyhive import HoneyHiveTracer
        import os

        tracer = HoneyHiveTracer.init(
            api_key=os.getenv("HH_API_KEY"),
            project=os.getenv("HH_PROJECT"),
        )

        session_id = tracer.session_id
        ```
      </Step>

      <Step title="Pass the session ID to Service B">
        Include it in your HTTP request headers or body:

        ```python theme={null}
        import requests

        response = requests.post(
            "https://service-b.example.com/api/endpoint",
            json={"query": "hello", "session_id": session_id},
        )
        ```
      </Step>

      <Step title="Initialize the tracer with the session ID in Service B">
        ```python theme={null}
        from honeyhive import HoneyHiveTracer
        import os

        # Extract session_id from request (Flask example)
        session_id = request.json.get("session_id")

        tracer = HoneyHiveTracer.init(
            api_key=os.getenv("HH_API_KEY"),
            project=os.getenv("HH_PROJECT"),
            session_id=session_id,  # Links to Service A's trace
        )
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Context Propagation (Full)">
    Propagate the full W3C trace context via HTTP headers. Remote spans appear as **children** of the calling span, giving you a true nested trace tree across services.

    **Best for:** Production multi-service architectures where you need parent-child relationships and full trace hierarchy.

    HoneyHive provides two helpers:

    | Helper                                            | Side   | What it does                                                                        |
    | ------------------------------------------------- | ------ | ----------------------------------------------------------------------------------- |
    | `inject_context_into_carrier(headers, tracer)`    | Client | Injects trace ID, session ID, and project into outgoing HTTP headers                |
    | `with_distributed_trace_context(headers, tracer)` | Server | Extracts context from incoming headers and attaches all spans to the caller's trace |

    **Client side** - inject context before the HTTP call:

    ```python highlight={1,5} theme={null}
    from honeyhive.tracer.processing.context import enrich_span_context, inject_context_into_carrier

    async def call_remote_agent(query: str):
        with enrich_span_context(event_name="call_remote_agent", inputs={"query": query}):
            headers = {"Content-Type": "application/json"}
            inject_context_into_carrier(headers, tracer)

            response = requests.post(url, json=payload, headers=headers)
    ```

    **Server side** - extract context and attach to all spans:

    ```python highlight={1,5} theme={null}
    from honeyhive.tracer.processing.context import with_distributed_trace_context

    @app.route("/agent/invoke", methods=["POST"])
    async def invoke_agent():
        with with_distributed_trace_context(dict(request.headers), tracer):
            # All spans here are children of the client's calling span
            result = await run_agent(...)
    ```

    <Card title="Full Tutorial" icon="graduation-cap" href="/v2/tutorials/distributed-tracing">
      Build a complete distributed agent system with Google ADK using context propagation.
    </Card>
  </Tab>
</Tabs>

## Helper Reference

### `enrich_span_context()`

A context manager that creates a span enriched with HoneyHive-specific fields. Use it on the **client side** to wrap outgoing calls so the span carries inputs, outputs, and metadata.

| Parameter         | Type   | Description                                    |
| ----------------- | ------ | ---------------------------------------------- |
| `event_name`      | `str`  | **(required)** Name for the span.              |
| `inputs`          | `dict` | Input data recorded on the span.               |
| `outputs`         | `dict` | Output data recorded on the span.              |
| `metadata`        | `dict` | Arbitrary metadata attached to the span.       |
| `metrics`         | `dict` | Numeric metrics (latency, token counts, etc.). |
| `config`          | `dict` | Configuration snapshot for this span.          |
| `user_properties` | `dict` | End-user properties for the request.           |
| `error`           | `str`  | Error message if the operation failed.         |
| `feedback`        | `dict` | Feedback signals (e.g., ratings).              |

### `inject_context_into_carrier()`

Injects W3C `traceparent`, session ID, and project into an outgoing headers dict so the remote service can continue the trace.

| Parameter | Type              | Description                               |
| --------- | ----------------- | ----------------------------------------- |
| `headers` | `dict`            | HTTP headers dict to inject context into. |
| `tracer`  | `HoneyHiveTracer` | The active tracer instance.               |

### `with_distributed_trace_context()`

A context manager used on the **server side** to extract incoming trace context and attach all child spans to the caller's trace.

| Parameter | Type              | Description                               |
| --------- | ----------------- | ----------------------------------------- |
| `headers` | `dict`            | Incoming HTTP request headers.            |
| `tracer`  | `HoneyHiveTracer` | The active tracer instance on the server. |

## Serverless Environments (AWS Lambda)

For Lambda functions, call `tracer.flush()` before the handler returns to ensure all spans are exported before the runtime freezes. Use the session ID approach to link Lambda invocations to the calling service.

```python highlight={14} theme={null}
from honeyhive import HoneyHiveTracer
import os

def handler(event, context):
    session_id = event.get("session_id")

    tracer = HoneyHiveTracer.init(
        api_key=os.getenv("HH_API_KEY"),
        project=os.getenv("HH_PROJECT"),
        session_id=session_id,
    )

    result = process_event(event)
    tracer.flush()  # Drain pending spans before Lambda freezes
    return {"statusCode": 200, "body": result}
```

<Accordion title="Lambda install instructions" icon="aws">
  Use the x86\_64 runtime architecture and install the matching binary:

  ```bash theme={null}
  pip install \
      --platform manylinux2014_x86_64 \
      --target ./site-packages \
      --implementation cp \
      --python-version 3.11 \
      --only-binary=:all: \
      --upgrade honeyhive
  ```
</Accordion>

## Learn More

<CardGroup cols={2}>
  <Card title="Tracing Introduction" icon="route" href="/v2/tracing/introduction">
    Sessions, events, and context propagation concepts
  </Card>

  <Card title="Distributed Tracing Tutorial" icon="graduation-cap" href="/v2/tutorials/distributed-tracing">
    End-to-end walkthrough with Google ADK
  </Card>
</CardGroup>