Exportar rastreamentos do Langfuse para o Databricks

Configure o Langfuse para enviar spans OTel para o Endpoint OTLP do Databricks. Os rastreios são armazenados em tabelas do Unity Catalog junto com seus outros rastreios do MLflow, onde você pode consultá-los e compará-los com SQL ou exibi-los na interface do usuário do MLflow.

A consolidação de rastreamentos no Databricks permite:

• Consulte e compare chamadas instrumentadas pelo Langfuse junto com rastreamentos de outros frameworks em um único local.
• Use o Databricks SQL para analisar dados de rastreamento em escala.
• Aplique a governança do Unity Catalog, como controles de acesso e linhagem, a todos os seus rastreamentos.

Requisitos

• Um workspace habilitado para o Unity Catalog.
• Permissões para criar catálogos e esquemas no Unity Catalog.
• Um Databricks SQL warehouse com a permissão CAN USE para visualizar rastreamentos.
• Um workspace em uma região suportada. Consulte Recursos com disponibilidade regional limitada.
• Um experimento do MLflow com um local de rastreamento do UC. Para obter detalhes de configuração, consulte Requisitos.
• As seguintes permissões do Unity Catalog no catálogo e no esquema usados para armazenar rastreamentos:
  • USE_CATALOG e USE_SCHEMA no catálogo e no esquema.
  • MODIFY e SELECT nas tabelas <table_prefix>_otel_*. Consulte Conceder permissões.
  • CREATE TABLE no esquema, para que a etapa de configuração possa criar as tabelas de rastreamento para o novo experimento.

Passo 1: Instalar pacotes

Instale os pacotes necessários no seu notebook do Databricks:

Python

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

O passo 2: Desativar a coleta de rastreamentos do Langfuse

O Langfuse inicializa seu SDK a partir das variáveis de ambiente LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY e LANGFUSE_SECRET_KEY. Defina-os como valores fictícios para que os intervalos vão apenas para o exportador do Databricks adicionado no o passo 5.

Python

import os

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

nota

Como alternativa, defina LANGFUSE_TRACING_ENABLED=False para desativar a coleta de rastreamento integrada do Langfuse.

O passo 3: Configurar a conexão do Databricks

Recupere a URL do host do workspace e o token da API. Em um notebook do Databricks, obtenha-os a partir do contexto do 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()

O passo 4: Link um experimento ao Unity Catalog

Vincule um catálogo, um esquema e um prefixo de tabela do Unity Catalog a um experimento do MLflow. Isso indica ao Databricks onde armazenar os rastreamentos recebidos.

Python

import mlflow
from mlflow.entities.trace_location import UnityCatalog

experiment = mlflow.set_experiment(
    experiment_name="<MLFLOW_EXPERIMENT_NAME>",
    trace_location=UnityCatalog(
        catalog_name="<UC_CATALOG_NAME>",
        schema_name="<UC_SCHEMA_NAME>",
        table_prefix="<UC_TABLE_PREFIX>",
    ),
)

Para obter detalhes completos sobre a configuração, consulte Criar um experimento com um local de rastreamento do Unity Catalog.

O passo 5: Adicionar o exportador OTLP do Databricks

Recupere o TracerProvider que o Langfuse registra como o provedor global de OTel e, em seguida, anexe um BatchSpanProcessor que aponte para o endpoint OTLP do Databricks. O cabeçalho X-Databricks-UC-Table-Name roteia os vãos de entrada para a tabela do Unity Catalog definida pelo local de rastreamento.

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 OTel TracerProvider.
langfuse = get_client()

# Retrieve the global TracerProvider to attach an additional span processor.
provider = otel_trace.get_tracer_provider()

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,
    },
)

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

Passo 6: Executar uma função rastreada

Use o decorador @observe() do Langfuse para instrumentar seu agente. O decorador cria spans OTel que o exportador envia para o 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!")

Etapa 7: view traces

Abra o experimento do MLflow no seu Workspace do Databricks e clique na Traces tab. O rastreamento da chamada my_pipeline é exibido.

Para pesquisar rastreamentos do Langfuse ingeridos por valores de atributo de span do OTel, consulte Search for traces by OTel span attributes.