Hugging Face (tracing)

Hugging Face 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 and grab an API key.

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

Use Respan Gateway

See Hugging Face gateway setup for the separate OpenAI-compatible gateway route.

Example projects

Python examples

Setup

Install packages

pip install respan-ai respan-instrumentation-huggingface transformers

Set environment variables

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

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

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.

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.

export TRACELOOP_TRACE_CONTENT=false