> ## 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.

# Multi-Instance Tracing

> Run multiple tracer instances for multi-tenant, A/B testing, or environment-based routing.

## Overview

HoneyHive supports multiple tracer instances in a single application. Each instance maintains its own session context, configuration, and OTel `TracerProvider`. Instances do not share context.

```mermaid theme={null}
graph TB
    subgraph "Application"
        A[Request 1] --> B[Tracer 1]
        C[Request 2] --> D[Tracer 2]
        E[Request 3] --> F[Tracer 3]
    end
    
    subgraph "Isolated Sessions"
        B --> G["Session A (tenant: acme)"]
        D --> H["Session B (tenant: globex)"]
        F --> I["Session C (tenant: acme)"]
    end
    
    G --> J[HoneyHive API]
    H --> J
    I --> J
```

***

## Use Cases

### Environment-Based Routing

Route traces to different projects based on environment:

```python theme={null}
import os
from honeyhive import HoneyHiveTracer, trace

env = os.getenv("ENVIRONMENT", "development")

tracer = HoneyHiveTracer.init(
    project=f"myapp-{env}",
    source=env
)
```

### Multi-Tenant SaaS

Each tenant gets their own tracer with isolated context:

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

def handle_request(request):
    tracer = HoneyHiveTracer.init(
        api_key=os.environ["HH_API_KEY"],
        project=f"saas-{request.tenant_id}",
        source="production"
    )

    tracer.enrich_session({
        "tenant_id": request.tenant_id,
        "plan": request.tenant_plan
    })

    return process_with_tracer(request, tracer)
```

### A/B Testing

Run different configurations side-by-side with separate tracers:

```python theme={null}
from honeyhive import HoneyHiveTracer, trace
import os

def ab_test_handler(request):
    variant = get_ab_variant(request.user_id)

    tracer = HoneyHiveTracer.init(
        api_key=os.environ["HH_API_KEY"],
        project="ab-test",
        source="production"
    )

    tracer.enrich_session({
        "variant": variant,
        "user_id": request.user_id
    })

    if variant == "A":
        return process_with_gpt4(request, tracer)
    else:
        return process_with_claude(request, tracer)
```

### Feature Isolation

Route different features to different projects:

```python theme={null}
from honeyhive import HoneyHiveTracer, trace

customer_tracer = HoneyHiveTracer.init(
    project="customer-facing-api",
    source="production"
)

admin_tracer = HoneyHiveTracer.init(
    project="admin-tools",
    source="production"
)

@trace(tracer=customer_tracer)
def handle_customer_query(query: str) -> str:
    ...

@trace(tracer=admin_tracer)
def generate_internal_report(data: dict) -> str:
    ...
```

***

## Per-Request Initialization

For full isolation, initialize a tracer per request:

```python theme={null}
import os
from honeyhive import HoneyHiveTracer
from flask import Flask, request

app = Flask(__name__)

@app.route("/api/process", methods=["POST"])
def handle():
    tracer = HoneyHiveTracer.init(
        api_key=os.environ["HH_API_KEY"],
        project="my-app",
        source="api-server"
    )

    tracer.enrich_session({
        "endpoint": request.path,
        "method": request.method
    })

    result = process_request(request.json)
    tracer.force_flush()
    return result
```

***

## Thread Safety

HoneyHive uses Python's `contextvars` for thread safety. When using thread pools, propagate context explicitly:

```python theme={null}
from concurrent.futures import ThreadPoolExecutor
import contextvars

def process_in_threads(items, tracer):
    def process_item(item):
        return do_work(item)

    with ThreadPoolExecutor(max_workers=4) as executor:
        futures = [
            executor.submit(contextvars.copy_context().run, process_item, item)
            for item in items
        ]
        return [f.result() for f in futures]
```

<Warning>
  Copy the context for **each** `executor.submit()` call. Reusing a single context object across threads causes race conditions. See [Multi-Threading](/v2/tracing/multithreading) for details.
</Warning>

***

## Best Practices

* Keep tracer instances in a central registry - create once, reuse many times
* Use consistent naming conventions (`{app}-{environment}`)
* Use environment variables for API keys, never hard-code them
* Use metadata to differentiate when possible, rather than creating additional tracers
* 2-5 tracers per application is typical and performant

***

## Performance

| Metric          | Impact                            |
| --------------- | --------------------------------- |
| Memory          | \~100KB per tracer instance       |
| Network         | Batched, async export per tracer  |
| Span Processing | Each tracer has its own processor |

***

## Related

<CardGroup cols={2}>
  <Card title="Production Deployment" icon="rocket" href="/v2/tutorials/production-deployment">
    Initialization patterns for production environments
  </Card>

  <Card title="Multi-Threaded Tracing" icon="gears" href="/v2/tracing/multithreading">
    Context propagation across threads
  </Card>
</CardGroup>