> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Hugging Face (tracing)

> Trace Hugging Face Transformers text-generation pipelines with Respan auto-instrumentation.

[Hugging Face](https://huggingface.co/) provides open models, datasets, and the Transformers library. Respan's Hugging Face instrumentation wraps the upstream Transformers OpenTelemetry instrumentor and normalizes `TextGenerationPipeline.__call__` spans into Respan text-generation traces with model metadata, generation parameters, prompt and completion content, token counts, latency, and workflow context.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Use Respan Gateway

See [Hugging Face gateway setup](/docs/gateway/huggingface) for the separate OpenAI-compatible gateway route.

#### Example projects

* [Python examples](https://github.com/respanai/respan-example-projects/tree/main/python/tracing/huggingface)

## Setup

#### Install packages

```bash
pip install respan-ai respan-instrumentation-huggingface transformers
```

#### Set environment variables

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
# Optional, only needed for private or gated Hugging Face models
export HF_TOKEN="YOUR_HF_TOKEN"
```

`RESPAN_API_KEY` exports traces to Respan. Hugging Face credentials are only needed when the Transformers model you load requires them.

#### Initialize and run

```python
from respan import Respan, workflow
from respan_instrumentation_huggingface import HuggingFaceInstrumentor
from transformers import pipeline

respan = Respan(
    app_name="huggingface-text-generation",
    instrumentations=[HuggingFaceInstrumentor()],
)

generator = pipeline(
    "text-generation",
    model="sshleifer/tiny-gpt2",
)


@workflow(name="huggingface_text_generation")
def run_generation():
    return generator(
        "Tracing Hugging Face pipelines helps",
        max_length=42,
        temperature=0.35,
        top_p=0.9,
        repetition_penalty=1.1,
    )


try:
    result = run_generation()
    print(result[0]["generated_text"])
finally:
    respan.shutdown()
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see the workflow span and its Hugging Face text-generation child span. The child span is stored as `log_type=text` and includes the model name, prompt, completion, generation parameters, estimated token usage, and latency.

## Supported coverage

| Feature                  | Coverage                                                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Single prompt generation | Captures one `TextGenerationPipeline.__call__` span with prompt and generated text.                                       |
| Batch prompts            | Captures indexed prompt inputs and the generated response for batched calls.                                              |
| Workflow context         | Preserves `@workflow` names so Hugging Face spans are grouped under the calling workflow.                                 |
| Content privacy          | Supports `TRACELOOP_TRACE_CONTENT=false` to suppress prompt and completion text while keeping model and request metadata. |

## Configuration

| Parameter             | Type           | Default | Description                                                               |
| --------------------- | -------------- | ------- | ------------------------------------------------------------------------- |
| `api_key`             | `str \| None`  | `None`  | Falls back to `RESPAN_API_KEY` env var.                                   |
| `base_url`            | `str \| None`  | `None`  | Falls back to `RESPAN_BASE_URL` env var.                                  |
| `instrumentations`    | `list`         | `[]`    | Plugin instrumentations to activate, such as `HuggingFaceInstrumentor()`. |
| `customer_identifier` | `str \| None`  | `None`  | Default customer identifier for all spans.                                |
| `metadata`            | `dict \| None` | `None`  | Default metadata attached to all spans.                                   |
| `environment`         | `str \| None`  | `None`  | Environment tag, such as `"production"`.                                  |

## Attributes

### In Respan()

Set defaults at initialization. These apply to all generated spans.

```python
from respan import Respan
from respan_instrumentation_huggingface import HuggingFaceInstrumentor

respan = Respan(
    instrumentations=[HuggingFaceInstrumentor()],
    customer_identifier="user_123",
    metadata={"service": "huggingface-pipeline", "version": "1.0.0"},
)
```

### With propagate_attributes

Override per-request using a context scope.

```python
from respan import Respan, propagate_attributes
from respan_instrumentation_huggingface import HuggingFaceInstrumentor

respan = Respan(instrumentations=[HuggingFaceInstrumentor()])

def handle_request(user_id: str, prompt: str):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_abc_123",
        metadata={"plan": "pro"},
    ):
        output = generator(prompt, max_length=42)
        print(output[0]["generated_text"])
```

| Attribute             | Type   | Description                                           |
| --------------------- | ------ | ----------------------------------------------------- |
| `customer_identifier` | `str`  | Identifies the end user in Respan analytics.          |
| `thread_identifier`   | `str`  | Groups related messages into a conversation.          |
| `metadata`            | `dict` | Custom key-value pairs. Merged with default metadata. |

## Disable captured content

Set `TRACELOOP_TRACE_CONTENT=false` before initializing Respan to keep prompt and completion text out of span content while still exporting model, generation parameter, workflow, and timing metadata.

```bash
export TRACELOOP_TRACE_CONTENT=false
```