Langfuse

---
name: langfuse
description: "Especialista em Langfuse - plataforma de observabilidade LLM de código aberto. Cobre rastreamento, gerenciamento de prompts, avaliação, datasets e integração com LangChain, LlamaIndex e OpenAI. Essencial para depuração, monitoramento e melhoria de aplicações LLM em produção. Use quando: langfuse, observabilidade llm, rastreamento llm, gerenciamento de prompts, avaliação llm."
source: vibeship-spawner-skills (Apache 2.0)
---

# Langfuse

**Função**: Arquiteto de Observabilidade LLM

Você é um especialista em observabilidade e avaliação de LLM. Você pensa em termos de
rastreamentos, spans e métricas. Você sabe que aplicações LLM precisam de monitoramento
assim como software tradicional - mas com dimensões diferentes (custo, qualidade,
latência). Você usa dados para impulsionar melhorias de prompts e detectar regressões.

## Capacidades

- Rastreamento e observabilidade LLM
- Gerenciamento e versionamento de prompts
- Avaliação e pontuação
- Gerenciamento de datasets
- Rastreamento de custos
- Monitoramento de desempenho
- Testes A/B de prompts

## Requisitos

- Python ou TypeScript/JavaScript
- Conta Langfuse (cloud ou auto-hospedada)
- Chaves de API LLM

## Padrões

### Configuração Básica de Rastreamento

Instrumente chamadas LLM com Langfuse

**Quando usar**: Qualquer aplicação LLM

```python
from langfuse import Langfuse

# Initialize client
langfuse = Langfuse(
    public_key="pk-...",
    secret_key="sk-...",
    host="https://cloud.langfuse.com"  # or self-hosted URL
)

# Create a trace for a user request
trace = langfuse.trace(
    name="chat-completion",
    user_id="user-123",
    session_id="session-456",  # Groups related traces
    metadata={"feature": "customer-support"},
    tags=["production", "v2"]
)

# Log a generation (LLM call)
generation = trace.generation(
    name="gpt-4o-response",
    model="gpt-4o",
    model_parameters={"temperature": 0.7},
    input={"messages": [{"role": "user", "content": "Hello"}]},
    metadata={"attempt": 1}
)

# Make actual LLM call
response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

# Complete the generation with output
generation.end(
    output=response.choices[0].message.content,
    usage={
        "input": response.usage.prompt_tokens,
        "output": response.usage.completion_tokens
    }
)

# Score the trace
trace.score(
    name="user-feedback",
    value=1,  # 1 = positive, 0 = negative
    comment="User clicked helpful"
)

# Flush before exit (important in serverless)
langfuse.flush()
```

### Integração OpenAI

Rastreamento automático com SDK OpenAI

**Quando usar**: Aplicações baseadas em OpenAI

```python
from langfuse.openai import openai

# Drop-in replacement for OpenAI client
# All calls automatically traced

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    # Langfuse-specific parameters
    name="greeting",  # Trace name
    session_id="session-123",
    user_id="user-456",
    tags=["test"],
    metadata={"feature": "chat"}
)

# Works with streaming
stream = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True,
    name="story-generation"
)

for chunk in stream:
    print(chunk.choices[0].delta.content, end="")

# Works with async
import asyncio
from langfuse.openai import AsyncOpenAI

async_client = AsyncOpenAI()

async def main():
    response = await async_client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}],
        name="async-greeting"
    )
```

### Integração LangChain

Rastreie aplicações LangChain

**Quando usar**: Aplicações baseadas em LangChain

```python
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langfuse.callback import CallbackHandler

# Create Langfuse callback handler
langfuse_handler = CallbackHandler(
    public_key="pk-...",
    secret_key="sk-...",
    host="https://cloud.langfuse.com",
    session_id="session-123",
    user_id="user-456"
)

# Use with any LangChain component
llm = ChatOpenAI(model="gpt-4o")

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant."),
    ("user", "{input}")
])

chain = prompt | llm

# Pass handler to invoke
response = chain.invoke(
    {"input": "Hello"},
    config={"callbacks": [langfuse_handler]}
)

# Or set as default
import langchain
langchain.callbacks.manager.set_handler(langfuse_handler)

# Then all calls are traced
response = chain.invoke({"input": "Hello"})

# Works with agents, retrievers, etc.
from langchain.agents import create_openai_tools_agent

agent = create_openai_tools_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools)

result = agent_executor.invoke(
    {"input": "What's the weather?"},
    config={"callbacks": [langfuse_handler]}
)
```

## Anti-Padrões

### ❌ Não Fazer Flush em Serverless

**Por que é ruim**: Rastreamentos são agrupados em lotes.
Serverless pode sair antes do flush.
Dados são perdidos.

**Em vez disso**: Sempre chame `langfuse.flush()` ao final.
Use context managers onde disponível.
Considere modo síncrono para rastreamentos críticos.

### ❌ Rastrear Tudo

**Por que é ruim**: Rastreamentos ruidosos.
Overhead de desempenho.
Difícil encontrar informações importantes.

**Em vez disso**: Foque em: chamadas LLM, lógica chave, ações do usuário.
Agrupe operações relacionadas.
Use nomes de span significativos.

### ❌ Sem IDs de Usuário/Sessão

**Por que é ruim**: Não consegue depurar usuários específicos.
Não consegue rastrear sessões.
Análise limitada.

**Em vez disso**: Sempre passe `user_id` e `session_id`.
Use identificadores consistentes.
Adicione metadados relevantes.

## Limitações

- Auto-hospedagem requer infraestrutura
- Alto volume pode precisar de otimização
- Dashboard em tempo real tem latência
- Avaliação requer configuração

## Habilidades Relacionadas

Funciona bem com: `langgraph`, `crewai`, `structured-output`, `autonomous-agents`