OpenInference : les conventions OpenTelemetry pour tracer les applications d'IA

1. Qu'est-ce qu'OpenInference ? #

Un vocabulaire commun pour les traces d'IA.

Définition #

OpenInference est un projet open source (initié par Arize) qui définit deux choses :

• des conventions sémantiques : quels attributs mettre sur un span pour décrire un appel de modèle, une recherche de documents, un appel d'outil ou une étape d'agent ;
• des instrumentations prêtes à l'emploi qui produisent automatiquement ces spans pour les principaux SDK et frameworks d'IA, en Python, JavaScript et Java.

Tout repose sur OpenTelemetry : les spans OpenInference sont des spans OpenTelemetry ordinaires, exportés en OTLP. Phoenix et Arize AX savent les afficher de façon riche (messages, documents, jetons), et n'importe quel backend OTLP peut les stocker.

Pourquoi des conventions ? #

Sans convention, chaque équipe nomme ses attributs à sa façon (prompt, llm_input, messages...) et aucun outil ne peut calculer un coût en jetons ou afficher une conversation. Avec OpenInference, llm.token_count.prompt signifie la même chose quel que soit le framework, ce qui permet des tableaux de bord, des évaluations et des comparaisons génériques.

2. Les types de spans #

openinference.span.kind.

Les valeurs #

À savoir : La liste des types évolue avec la spécification (par exemple DECISION pour les choix de routage) : consultez spec/semantic_conventions.md du dépôt OpenInference.

3. Les attributs essentiels #

Ce que contient un span.

Par famille #

4. Instrumenter #

Automatique d'abord, manuel ensuite.

Instrumentation automatique #

pip install arize-phoenix-otel openinference-instrumentation-openai openai

from phoenix.otel import register

# configure OpenTelemetry et active toutes les instrumentations OpenInference installées
tracer_provider = register(
    project_name="support-bot",
    endpoint="http://localhost:6006/v1/traces",   # Phoenix, en OTLP/HTTP
    auto_instrument=True,
)

from openai import OpenAI
client = OpenAI()
client.chat.completions.create(model="gpt-4o-mini",
                               messages=[{"role": "user", "content": "Bonjour"}])

Sans Phoenix, la même instrumentation fonctionne avec le SDK OpenTelemetry standard :

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from openinference.instrumentation.openai import OpenAIInstrumentor

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint="http://collector:4318/v1/traces")))
OpenAIInstrumentor().instrument(tracer_provider=provider)

Instrumentation manuelle #

Pour une étape maison (une recherche dans votre propre index, un outil métier), créez le span vous-même avec les conventions :

from opentelemetry import trace
from openinference.semconv.trace import SpanAttributes, OpenInferenceSpanKindValues

tracer = trace.get_tracer("rag")

def retrieve(question: str):
    with tracer.start_as_current_span("retrieve") as span:
        span.set_attribute(SpanAttributes.OPENINFERENCE_SPAN_KIND, OpenInferenceSpanKindValues.RETRIEVER.value)
        span.set_attribute(SpanAttributes.INPUT_VALUE, question)
        docs = index.search(question, k=3)
        for i, d in enumerate(docs):
            span.set_attribute(f"retrieval.documents.{i}.document.id", d.id)
            span.set_attribute(f"retrieval.documents.{i}.document.content", d.text)
            span.set_attribute(f"retrieval.documents.{i}.document.score", d.score)
        return docs

Contexte : sessions, utilisateurs, métadonnées #

from openinference.instrumentation import using_attributes

with using_attributes(session_id=conversation_id, user_id=user.id,
                      metadata={"app_version": "2.3.0", "feature": "faq"}, tags=["beta"]):
    answer = agent.run(question)   # tous les spans créés ici portent ces attributs

Bonne Pratique : Renseignez toujours session.id pour les conversations et une métadonnée de version : c'est ce qui permet d'afficher une conversation complète et de comparer deux versions de l'application.

5. Confidentialité et volume #

Les prompts contiennent des données sensibles.

Masquer #

Les prompts et les réponses peuvent contenir des données personnelles. Les instrumentations OpenInference acceptent une configuration de masquage, en code (TraceConfig) ou par variables d'environnement :

Erreur Courante : Masquer toutes les entrées empêche ensuite d'évaluer les réponses. Préférez masquer les champs sensibles (dans le code ou dans un OpenTelemetry Collector) et limiter l'accès aux traces.

6. OpenInference et les conventions GenAI d'OpenTelemetry #

Deux standards proches.

Comparaison #

OpenTelemetry définit aussi des conventions pour l'IA générative (attributs gen_ai.* : gen_ai.request.model, gen_ai.usage.input_tokens...), encore en cours de stabilisation. OpenInference est antérieur, plus riche sur les RAG et les agents (documents, reranking, outils, types de spans), et largement outillé.

Bonne Pratique : Choisissez l'instrumentation selon votre backend principal ; si vous devez alimenter plusieurs outils, un OpenTelemetry Collector peut renommer des attributs (processeur transform) pour passer d'une convention à l'autre.