Skip to main content
Este guia mostra como carregar dados de trace de LLM do Langfuse Cloud no ClickHouse Cloud para fazer analytics em tempo real.

Exportar do Langfuse Cloud

Siga este guia para configurar uma integração de Blob Storage no Langfuse Cloud e realizar exportações agendadas. Você pode agendar a exportação dos seus dados de trace para o armazenamento de objetos a cada 20 minutes, no mínimo, ou com agendamento hourly, daily ou weekly. Por padrão, cada exportação inclui suas observations (enriquecidas com atributos de trace) e scores.

Estrutura dos arquivos exportados

A integração de Blob Storage do Langfuse Cloud grava os dados no bucket ou contêiner de armazenamento de destino usando a seguinte estrutura de diretórios:

Importar para o ClickHouse Cloud

Depois que uma integração de Blob Storage for configurada no Langfuse Cloud, os dados de trace serão exportados conforme um agendamento para o bucket ou contêiner de armazenamento de destino. Para importar esses dados para o ClickHouse Cloud, você pode usar o ClickPipes e seus connectors gerenciados de armazenamento de objetos:

Crie um ClickPipe

Este exemplo usa o S3 ClickPipe para importar dados de um bucket do S3 que recebe exportações agendadas do Langfuse Cloud e pode servir de modelo para qualquer destino de exportação em armazenamento de objetos. Para orientações específicas de cada fonte de dados, consulte a documentação do ClickPipes.
1

Selecione a fonte de dados

1. No ClickHouse Cloud, selecione Data sources no menu de navegação principal e clique em Criar ClickPipe.
Criar ClickPipe
2. Clique no bloco Amazon S3. Você também pode usar esse bloco para se conectar a outros serviços compatíveis com S3 que não aparecem na interface do ClickPipes.
Selecione a fonte de dados Amazon S3
2

Configure a conexão

1. Preencha os dados de que o ClickPipes precisa para se conectar e se autenticar no bucket que recebe suas exportações do Langfuse Cloud.
  • Método de autenticação: o S3 ClickPipe oferece suporte a credenciais do IAM (Credentials) e a autenticação baseada em IAM role (IAM role). O ClickPipes precisa apenas de acesso de leitura ao bucket. Consulte a documentação de referência para obter orientações sobre autenticação e permissões.
  • Caminho de arquivo do S3: aponte o ClickPipe para um subdiretório e use um wildcard * para corresponder a todos os arquivos exportados. Você deve criar um ClickPipe por subdiretório, pois os arquivos exportados em cada subdiretório têm schemas diferentes. Consulte a documentação de referência para obter orientações sobre os padrões compatíveis, incluindo como corresponder arquivos em prefixos aninhados.
2. Selecione Continuous ingestion para que novos arquivos sejam ingeridos automaticamente à medida que o Langfuse os grava no bucket de destino.
Detalhes de conexão de uma exportação do Langfuse, com a ingestão contínua habilitada.
3. Clique em Incoming data. O ClickPipes buscará os metadados do seu bucket e inferirá o schema da tabela de destino na próxima etapa.
3

Valide os dados recebidos

1. O ClickPipes se conectará ao seu bucket e listará os arquivos no caminho especificado, inferindo o formato dos arquivos. Neste exemplo, usamos o formato de arquivo de exportação padrão do Langfuse Cloud (Parquet).
Arquivos correspondentes ao caminho de exportação do Langfuse, com o tipo de arquivo definido como Parquet
2. Clique em Parse information. O ClickPipes usará um arquivo de amostra para inferir o schema dos dados exportados e mapeará automaticamente os campos de origem para uma tabela de destino no ClickHouse.
4

Configure o destino

1. Nesta etapa, você pode revisar o esquema inferido e personalizar a configuração da tabela de destino, incluindo ajustar o mapeamento de tipos de dados, definir a sorting key e escolher o motor de tabela.
Uma exportação de scores gravando em um banco de dados langfuse dedicado, com a sorting key definida como environment, name, timestamp, trace_id, observation_id e id
Em Upload data to, mantenha New table selecionado e defina:
  • Database e Name: um banco de dados dedicado para os seus dados do Langfuse (por exemplo, langfuse) e um nome legível para a tabela de destino (por exemplo, scores). Por padrão, o ClickPipes usa default.s3-<uuid> para evitar conflitos de nomes.
  • Sorting key: a chave de ordenação da tabela de destino, que determina como o ClickHouse persiste os dados em disco. Para obter o melhor desempenho, a sorting key deve corresponder aos seus padrões de acesso aos dados, de modo que as consultas possam pular a leitura do maior volume de dados possível. Essa chave também é usada para desduplicação em tabelas ReplacingMergeTree, portanto o conjunto de colunas também precisa identificar cada registro de forma única. Se você carregar vários projetos do Langfuse em uma única tabela, adicione project_id no início da sorting key. Consulte a documentação de referência para obter orientações sobre como escolher uma sorting key.
  • Partition by: deixe em branco, a menos que você pretenda expirar traces antigos. O particionamento no ClickHouse serve para o gerenciamento de dados, e não para a otimização de consultas; a sorting key sugerida já elimina dados irrelevantes em consultas por intervalo de tempo. Se você precisar de retenção, particione pela coluna de tempo (toYYYYMM(start_time), ou toYYYYMM(timestamp) para scores), para que expirar um mês de traces seja uma única operação DROP PARTITION.
2. Em seguida, expanda Advanced settings e defina o Engine como ReplacingMergeTree para garantir a desduplicação, usando updated_at como a coluna Version.
Configurações avançadas com o motor ReplacingMergeTree e updated_at como a coluna de versão
As janelas de exportação na integração Blob Storage do Langfuse Cloud incluem ambos os limites, portanto o mesmo registro pode aparecer em mais de um arquivo exportado. A menos que seus padrões de consulta analítica sejam idempotentes (por exemplo, uniq(), max(), min()), você deve tratar a desduplicação no modelo de dados downstream, usando ReplacingMergeTree como motor de destino.
Desduplique com ReplacingMergeTreeEste motor de tabela elimina duplicatas por meio de mesclagens em segundo plano. Para uma desduplicação completa na leitura (ou seja, semântica de mesclagem na leitura), você deve usar o modificador FINAL (ou agregações no estilo argMax()) no momento da consulta.
5

Configure as permissões

O ClickPipes cria um usuário dedicado para a gravação de dados na tabela de destino. Selecione uma função para esse usuário interno, seja uma função personalizada ou uma das funções predefinidas:
  • Full access: com acesso total ao cluster. Obrigatório se você usar uma visão materializada ou um dicionário com a tabela de destino.
  • Only destination table: com permissões de INSERT apenas na tabela de destino.
Permissões
Clique em Complete setup para criar o ClickPipe.
6

Concluir a configuração

E pronto! O ClickPipes primeiro fará um backfill histórico de todos os arquivos no caminho especificado e, em seguida, passará a ingerir os novos arquivos à medida que forem chegando ao bucket.
Os ClickPipes de observations e scores em execução em Data sources
Repita as etapas deste guia para cada subdiretório que você quiser importar para o ClickHouse Cloud.

Consultar dados de trace

Com os ClickPipes em execução, você pode consultar os dados de trace do Langfuse Cloud diretamente no ClickHouse Cloud. Os exemplos abaixo abordam alguns padrões de consulta comuns: agregações de custo e latência, reconstrução de um único trace e correlação de pontuações com modelos e prompts.

Agregações de métricas por intervalos de tempo

Alguns campos, como usage_details e cost_details, são exportados como colunas Map. Para ler um único valor, acesse-o pela chave (por exemplo, sum(cost_details['total'])).

Reconstrução de traces

Análise de qualidade

Veja também

Última modificação em 26 de setembro de 2026