OpenTelemetry Instrumentation for Hugging Face Transformers

0.58.0 · active · verified Fri Apr 10

The `opentelemetry-instrumentation-transformers` library provides OpenTelemetry instrumentation for the Hugging Face Transformers library. It automatically captures traces for operations performed using Transformers models, helping to monitor and observe AI/ML application performance and behavior. The current version is 0.58.0, and it follows a rapid release cadence, often aligning with updates to OpenTelemetry's Generative AI semantic conventions.

Warnings

breaking Frequent updates to OpenTelemetry Generative AI semantic conventions (semconv) may introduce breaking changes in the names and structure of span attributes. Applications consuming these traces should be prepared for attribute schema changes.
Fix: Consult the OpenTelemetry GenAI Semantic Conventions documentation and the `opentelemetry-instrumentation-transformers` changelog to adapt to updated attribute names and structures.
gotcha The `transformers` library must be installed and importable *before* `TransformersInstrumentor().instrument()` is called. If `transformers` is not present, instrumentation will fail silently or not apply.
Fix: Ensure `pip install transformers` is executed and `import transformers` can successfully run in your environment before initializing the instrumentor.
gotcha To observe traces, a complete OpenTelemetry SDK setup (including a `TracerProvider`, `Resource`, and `SpanProcessor` with an `Exporter`) is required. Without a configured exporter, traces will be generated but not sent anywhere.
Fix: Refer to the OpenTelemetry Python SDK documentation for proper setup of `TracerProvider`, `Resource`, and a suitable `SpanExporter` (e.g., `OTLPSpanExporter` for sending to an OTel collector).

Install

pip install opentelemetry-instrumentation-transformers transformers Install with transformers

Imports

TransformersInstrumentor

from opentelemetry.instrumentation.transformers import TransformersInstrumentor

Quickstart

This example sets up a basic OpenTelemetry SDK with a console exporter, then instruments the Hugging Face Transformers library. It then runs a sentiment analysis pipeline, generating traces that will be printed to the console.

import os
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import (
    ConsoleSpanExporter,
    SimpleSpanProcessor,
)
from opentelemetry.instrumentation.transformers import TransformersInstrumentor
from transformers import pipeline

# Configure OpenTelemetry SDK
# In production, use OTLPExporter to send traces to a collector.
resource = Resource.create({"service.name": "transformers-app"})
provider = TracerProvider(resource=resource)
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# Instrument the transformers library
TransformersInstrumentor().instrument()

# Use a transformers pipeline
print("Running transformers pipeline...")
pipe = pipeline("sentiment-analysis")
result = pipe("I love OpenTelemetry!")
print("Pipeline result:", result)

# Ensure traces are flushed before exit
provider.shutdown()

view raw JSON →