HoneyHive Docs

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.

Choose Your Approach

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

Session ID (Simple)
Context Propagation (Full)

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.

Get the session ID from Service A

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

Pass the session ID to Service B

Include it in your HTTP request headers or body:

import requests

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

Initialize the tracer with the session ID in Service B

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
)

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:

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:

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(...)

Full Tutorial

Build a complete distributed agent system with Google ADK using context propagation.

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.

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}

Lambda install instructions

Use the x86_64 runtime architecture and install the matching binary:

pip install \
    --platform manylinux2014_x86_64 \
    --target ./site-packages \
    --implementation cp \
    --python-version 3.11 \
    --only-binary=:all: \
    --upgrade honeyhive

Getting Started

Observability

Evaluation

Prompt Management

Administration

Learn More

Distributed Tracing

Choose Your Approach

Full Tutorial

Helper Reference

`enrich_span_context()`

`inject_context_into_carrier()`

`with_distributed_trace_context()`

Serverless Environments (AWS Lambda)

Learn More

Tracing Introduction

Distributed Tracing Tutorial

Getting Started

Observability

Evaluation

Prompt Management

Administration

Learn More

Documentation Index

​Choose Your Approach

Full Tutorial

​Helper Reference

​enrich_span_context()

​inject_context_into_carrier()

​with_distributed_trace_context()

​Serverless Environments (AWS Lambda)

​Learn More

Tracing Introduction

Distributed Tracing Tutorial

Choose Your Approach

Helper Reference

`enrich_span_context()`

`inject_context_into_carrier()`

`with_distributed_trace_context()`

Serverless Environments (AWS Lambda)

Learn More