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 .

Paste this into your coding agent:


Help me set up Respan tracing with the Hugging Face integration.
Follow https://www.respan.ai/docs/integrations/huggingface.md

Setup

Install packages

Terminal


pip install respan-ai respan-instrumentation-huggingface transformers

Set environment variables

Terminal


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

Terminal


export TRACELOOP_TRACE_CONTENT=false