Exporter les traces Langfuse vers Databricks MLflow

Configurez Langfuse pour envoyer les spans de trace basés sur OpenTelemetry à l'endpoint OTLP de MLflow Databricks, afin que les traces soient stockées dans les tables Unity Catalog avec vos autres traces MLflow.

La consolidation des traces sur Databricks présente les avantages suivants :

• Query et comparez les appels instrumentés par Langfuse avec les traces d’autres frameworks en un seul endroit.
• Utilisez Databricks SQL pour analyser les données de trace à l'échelle.
• Appliquez la gouvernance Unity Catalog, tels que les contrôles d'accès et la traçabilité, à toutes vos traces.

Exigences

• Une nouvelle expérience MLflow avec un emplacement de trace UC.

Étape 1 : Installer les packages

Installez les packages requis dans votre Notebook Databricks :

Python

%pip install "langfuse>=3.14.5" "mlflow[databricks]>=3.14.0" opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
%restart_python

Étape 2 : Désactiver la collecte de traces Langfuse

Langfuse nécessite les variables d'environnement LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY et LANGFUSE_SECRET_KEY pour initialiser son SDK. Définissez ces variables sur des valeurs factices pour empêcher l'envoi de traces à un serveur Langfuse. Seul l’exportateur OTEL, configuré dans Ajouter l’exportateur OTLP, recevra les spans.

Python

import os

os.environ["LANGFUSE_HOST"] = "localhost"
os.environ["LANGFUSE_PUBLIC_KEY"] = ""
os.environ["LANGFUSE_SECRET_KEY"] = ""

remarque

C'est l'approche la plus simple pour empêcher Langfuse de collecter des traces sur ses propres serveurs. Vous pouvez également définir LANGFUSE_TRACING_ENABLED=False pour désactiver la collecte de traces intégrée de Langfuse.

Étape 3 : Configurer la connexion Databricks

Récupérez l’URL d’hôte du workspace et un jeton d’API. Dans un Notebook Databricks, vous pouvez les obtenir à partir du contexte du Notebook :

Python

# If running outside a Databricks notebook, set DATABRICKS_HOST and DATABRICKS_TOKEN environment variables manually.
context = dbutils.notebook.entry_point.getDbutils().notebook().getContext()
DATABRICKS_HOST = context.apiUrl().get().rstrip("/")
DATABRICKS_TOKEN = context.apiToken().get()

Étape 4 : Link un Experimentation à Unity Catalog

Définissez votre Unity Catalog catalogue, schéma et préfixe de table, puis liez-les à une Experimentation MLflow à l'aide de set_experiment. Ceci indique à Databricks où stocker les traces entrantes. Pour plus de détails sur la configuration complète, consultez Configuration : Créer une expérimentation avec un emplacement de trace Unity Catalog.

Python

import mlflow
from mlflow.entities.trace_location import UnityCatalog

CATALOG_NAME = "<UC_CATALOG_NAME>"
SCHEMA_NAME = "<UC_SCHEMA_NAME>"
TABLE_PREFIX = "<UC_TABLE_PREFIX>"

experiment = mlflow.set_experiment(
    experiment_name="<MLFLOW_EXPERIMENT_NAME>",
    trace_location=UnityCatalog(
        catalog_name=CATALOG_NAME,
        schema_name=SCHEMA_NAME,
        table_prefix=TABLE_PREFIX,
    ),
)

Étape 5 : Ajoutez l'exportateur OTLP Databricks

Obtenez le TracerProvider que Langfuse utilise, puis attachez un BatchSpanProcessor avec un OTLPSpanExporter qui pointe vers le Endpoint Databricks.

Python

from langfuse import get_client
from opentelemetry import trace as otel_trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# Initialize the Langfuse client. Langfuse registers its own TracerProvider as the global OpenTelemetry TracerProvider.
langfuse = get_client()

# Retrieve the global TracerProvider.
# Use this to attach an additional span processor that forwards Langfuse spans to Databricks.
provider = otel_trace.get_tracer_provider()

# Configure the OTLP exporter to send spans to the Databricks MLflow endpoint.
# The X-Databricks-UC-Table-Name header routes incoming spans to the Unity Catalog table defined by the trace location.
databricks_exporter = OTLPSpanExporter(
    endpoint=f"{DATABRICKS_HOST}/api/2.0/otel/v1/traces",
    headers={
        "content-type": "application/x-protobuf",
        "Authorization": f"Bearer {DATABRICKS_TOKEN}",
        "X-Databricks-UC-Table-Name": experiment.trace_location.full_otel_spans_table_name,
    },
)

# Attach the Databricks exporter to Langfuse's provider. Because the Langfuse
# env vars are set to dummy values, this processor is the only active exporter,
# so all spans are sent exclusively to Databricks.
provider.add_span_processor(BatchSpanProcessor(databricks_exporter))

Étape 6 : Exécuter une fonction tracée

Utilisez le décorateur @observe() de Langfuse pour instrumenter vos fonctions. Le décorateur crée des spans OTEL que l'exportateur envoie à Databricks.

Python

from langfuse import observe

@observe()
def my_llm_call(prompt: str) -> str:
    # Replace with your LLM logic (OpenAI, Anthropic, etc.)
    return f"Response to: {prompt}"

@observe()
def my_pipeline(user_input: str) -> str:
    result = my_llm_call(user_input)
    return result

my_pipeline("Hello, world!")

Étape 7 : Afficher les traces

Ouvrez l'expérimentation MLflow dans votre workspace Databricks et cliquez sur le tab Traces. La trace de l'appel my_pipeline devrait apparaître.

Ressources supplémentaires

• Stocker les traces OpenTelemetry dans Unity Catalog - En savoir plus sur le stockage et la gestion des traces dans les tables Unity Catalog.
• Affichez les traces dans l'interface utilisateur Databricks MLflow – Recherchez et filtrez les traces dans l'interface utilisateur MLflow.
• Interroger les traces OpenTelemetry stockées dans Unity Catalog - Requêtez directement les données de trace à l'aide de SQL via un SQL warehouse Databricks.
• Rechercher des traces par attributs de span OTel – Rechercher des traces Langfuse ingérées par attributs de span OpenTelemetry.