Exportação OpenTelemetry

info

Beta

Esse recurso está em Beta.

A integração OpenTelemetry envia métricas e logs Lakebase Postgres para qualquer destino que aceite o uso de dados do protocolo OpenTelemetry (OTLP). Você pode usar o Grafana Cloud, o New Relic, a ingestão de OTLP do Datadog, o Honeycomb ou outro backend compatível com OTLP.

Esta página descreve como a integração funciona em projetos Lakebase, como ela se relaciona com o seu workspace do Databricks e com o Lakebase App, e como configurar e verificar a exportação.

Como funciona

Lakebase execução e gerenciamento do OpenTelemetry Collector para seu projeto. O coletor extrai métricas compute , recebe logs do seu sistema de computação e os encaminha para o endpoint OTLP que você configurou. Os dados refletem as ramificações e os processos computacionais do seu projeto: métricas e logs estão associados aos processos computacionais ativos que atendem ao seu endpoint.

nota

Se a escala para zero suspender um compute, esse compute não emitirá métricas ou logs até que seja executado novamente. Você poderá observar lacunas durante os períodos de paradoxo. Para enviar dados após a configuração, certifique-se de que os recursos de computação estejam ativos — por exemplo, executando uma consulta no editorSQL ou no seu aplicativo.

métricas

As métricas exportadas incluem:

• Métricas de host/ compute — Uso de CPU e memória para compute.
• SQL e métricas de banco de dados — Contagem de conexões, tamanho do banco de dados, atraso de replicação, atividade de linhas e estatísticas relacionadas ao banco de dados. Esses nomes de métricas são exportados com um prefixo lakebase_ (por exemplo, lakebase_connection_counts).

Em conjunto, estes dados correspondem ao que você vê no painel de métricas do produto, exportados no formato OTLP.

Nomes de métricas exportadas

O coletor de métricas encaminha apenas as métricas que correspondem às suas regras de coleta e filtragem. As métricas do host mantêm seus nomes originais no estilo Prometheus. As métricas do PostgreSQL têm um prefixo lakebase_ na exportação. Seu backend de observabilidade ainda pode adicionar ou alterar sufixos (por exemplo _total) ao converter OTLP para outro formato.

Categoria	Nomes incluídos (conforme enviados para o OTLP)
Host / compute	Séries cujos nomes correspondem a host_load*, host_cpu_seconds* e host_memory* (expressão regular ^host_(load|cpu_seconds|memory).+). Exemplos incluem host_cpu_seconds_total (tempo de CPU por mode, por exemplo idle vs não-parado), host_memory_total_bytes, host_memory_available_bytes e host_memory_cached_bytes. Outras séries correspondentes podem aparecer se o compute as disponibilizar.
Conexões	lakebase_connection_counts (rótulo inclui datname e sessão state, por exemplo active).
Tamanho e limites do banco de dados	lakebase_db_total_size, lakebase_max_cluster_size e lakebase_pg_stats_userdb. A série lakebase_pg_stats_userdb usa um rótulo kind para a estatística (por exemplo, tamanho do banco de dados, contagens de linhas, impasses) — veja as mesmas dimensões do painel de métricas do produto.
Replicação	lakebase_replication_delay_bytes, lakebase_replication_delay_seconds e qualquer outra série cujo nome original corresponda a replication_delay_*.
Cache de arquivos local (LFC)	Todas as séries cujo nome original começa com lakebase_lfc_*. Exemplos incluem lakebase_lfc_hits, lakebase_lfc_misses, lakebase_lfc_cache_size_limit e lakebase_lfc_approximate_working_set_size_windows.

Categoria	Nomes incluídos (conforme enviados para o OTLP)
Host / compute	Séries cujos nomes correspondem a host_load*, host_cpu_seconds* e host_memory* (expressão regular ^host_(load|cpu_seconds|memory).+). Exemplos incluem host_cpu_seconds_total (tempo de CPU por mode, por exemplo idle vs não-parado), host_memory_total_bytes, host_memory_available_bytes e host_memory_cached_bytes. Outras séries correspondentes podem aparecer se o compute as disponibilizar.
Conexões	lakebase_connection_counts (rótulo inclui datname e sessão state, por exemplo active).
Tamanho e limites do banco de dados	lakebase_db_total_size, lakebase_max_cluster_size e lakebase_pg_stats_userdb. A série lakebase_pg_stats_userdb usa um rótulo kind para a estatística (por exemplo, tamanho do banco de dados, contagens de linhas, impasses) — veja as mesmas dimensões do painel de métricas do produto.
Replicação	lakebase_replication_delay_bytes, lakebase_replication_delay_seconds e qualquer outra série cujo nome original corresponda a replication_delay_*.
Cache de arquivos local (LFC)	Todas as séries cujo nome original começa com lakebase_lfc_*. Exemplos incluem lakebase_lfc_hits, lakebase_lfc_misses, lakebase_lfc_cache_size_limit e lakebase_lfc_approximate_working_set_size_windows.

logs

Quando ativado, logs (erros, avisos, eventos relacionados à conexão e mensagens semelhantes) são encaminhados para o seu pipeline logs OTLP. O atributo recurso service.name configurado identifica o serviço lógico para registro no backend.

Pré-requisitos

• Um projeto Lakebase e acesso ao aplicativo Lakebase a partir do seu workspace Databricks . Consulte Começar com Lakebase Postgres.
• Um backend de observabilidade compatível com OTLP e seu URL base , além das credenciais ( key API , tokens de portador ou autenticação básica).
• Caminho de rede da infraestrutura Databricks-gerenciar até o seu endpoint OTLP (por exemplo, um endpoint HTTPS público ou um coletor acessível a partir do seu ambiente cloud ).

Abra a configuração do OpenTelemetry.

1. Abra o aplicativoLakebase para seu workspace e selecione seu projeto.
2. Acesse as Configurações do projeto e, em seguida, vá para Integrações . A integração com o OpenTelemetry está disponível na seção Integrações .
3. Como alternativa, na página de monitoramento , selecione Exportar telemetria para abrir as configurações do projeto, onde você configura o OpenTelemetry.

Configure o protocolo de conexão, endpoint, a autenticação, as substituições de caminho opcionais e os atributos de recurso no formulário.

Selecione os dados a serem exportados

Escolha uma ou ambas:

• análises — Host e SQL/database análises conforme descrito acima.
• logsdo Postgres — transmissões de logs para observabilidade e resolução de problemas.

Configure a conexão

1. Protocolo — Para a maioria dos fornecedores, recomenda-se o HTTP (OTLP sobre HTTP, normalmente na porta 4318). Use gRPC (normalmente a porta 4317) se o seu servidor ou rede exigir.

2. URL do endpoint — Insira o URL base do seu coletor ou endpoint de ingestão OTLP do fornecedor sem adicionar /v1/metrics ou /v1/logs. O coletor anexa os caminhos OTLP padrão:

   • /v1/metrics para métricas
   • /v1/logs para logs

   Exemplos:

   • Grafana cloud : use o URL do gateway OTLP para sua pilha (geralmente https://otlp-gateway-<region>.grafana.net/otlp). Consulte a documentação do Grafana Cloud OpenTelemetry para a sua região.
   • Datadog : utilize o URL de ingestão OTLP para o seu site, conforme descrito na configuração do Datadog OpenTelemetry.

nota

Se a sua plataforma espera métricas ou logs em caminhos não padrão, use as substituições de endpoint opcionais no formulário (por exemplo, caminhos personalizados para métricas ou logs). Configure as alterações somente quando a documentação do fornecedor assim o exigir.

3. Autenticação

   • Token de portador — Tokens de portador (alguns fornecedores usam tokens de licença ou de ingestão).
   • Básico — Nome de usuário e senha.
   • ChaveAPI — Valor key API ; você pode definir um nome de cabeçalho personalizado se o seu backend esperar algo diferente do default (alguns provedores usam nomes de cabeçalho específicos do fornecedor).

Opções avançadas

• Delta métricas — Alguns backends esperam temporalidade delta em vez de contadores cumulativos. Caso sua plataforma exija, habilite a opção para converter métricas cumulativas em temporalidade delta.

Configurar atributos de recurso

Defina service.name para identificar seu projeto do Lakebase no seu backend de observabilidade. O nome do serviço configurado aplica-se tanto às métricas exportadas quanto aos logs do Postgres.

Adicionar atributos de recursos personalizados

Você pode adicionar até 10 atributos de recursos personalizados por projeto, além de service.name. O coletor anexa esses pares key-value às métricas e aos logs exportados para que você possa filtrar e agrupar a telemetria no seu backend de observabilidade.

1. No formulário de configuração do OpenTelemetry, vá para recurso attributes e clique em Add attribute .
2. Na linha Attribute 1 , insira uma key em Enter key e um valor opcional em Enter value (Optional) .
3. Clique em Adicionar atributo para adicionar mais linhas, até 10 atributos personalizados.
4. Clique em Salvar para aplicar as alterações.

For example, set team to payments, environment to production, or cost_center to 1234.

Para editar ou renomear um atributo, atualize seu valor ou key. Para remover um atributo, clique no ícone da lixeira em sua linha. Ao editar uma integração existente, reinsira suas credenciais de autenticação e clique em Salvar para aplicar suas alterações.

Requisitos de atributos

Custom recurso attributes must meet these requirements:

• Keys: Each key must be unique and contain 1 to 128 characters. Use only lowercase letters (a-z), digits (0-9), underscores (_), periods (.), and hyphens (-).
• Values: os valores podem conter texto Unicode, espaços e pontuação, e podem estar vazios. Caracteres de controle, como tab e novas linhas, não são permitidos.
• Comprimento do valor: cada valor pode conter até 1.024 unidades de código UTF-16. A maioria dos caracteres conta como uma unidade de código, mas alguns caracteres, como muitos emojis, contam como duas. Os mesmos requisitos de comprimento de valor e de caracteres se aplicam a service.name .

Set service.name in its separate field. You can't add it as a custom attribute key.

As seguintes chaves são reservadas para a telemetria do Lakebase e não podem ser usadas como chaves de atributos personalizados:

• project_id
• endpoint_id
• region_id
• host
• endpoint_type
• endpoint_ephemeral
• compute_binding_id
• compute_role
• net.peer.ip
• Qualquer key que comece com k8s.

Salvar e verificar

Salve a integração. Em poucos minutos, os dados aparecem no seu painel de controle.

Check the recurso attributes on newly exported métricas and Logs to verify that they include your configured service.name and custom attributes.

Configuração específica do fornecedor

Nuvem Grafana

Você pode usar a interface de usuário do Grafana Cloud para obter o URLendpoint OTLP e os valores de autenticação e, em seguida, inseri-los na integração Lakebase OpenTelemetry, conforme descrito em Configurar a conexão.

Conexões (configuração guiada com blocos de conexão)

1. Faça login no portal da nuvem Grafana.
2. No Grafana, acesse Conexões ou expanda o menu e escolha Adicionar nova conexão .
3. Pesquise por OpenTelemetry (OTLP) . Siga os passos na tela: escolha OpenTelemetry SDK , Other como linguagem e infraestrutura e OpenTelemetry Collector como método.
4. Na página de instruções de instrumentação , crie ou escolha tokens para usar na exportação Lakebase OpenTelemetry.
5. Copie os detalhes de conexão fornecidos pelo Grafana (OTEL_EXPORTER_OTLP_ENDPOINT e OTEL_EXPORTER_OTLP_HEADERS).

Mapear valores do Grafana para o Lakebase

1. Protocolo — Use HTTP, a menos que o Grafana ou sua rede exijam gRPC. O gateway OTLP em nuvem do Grafana geralmente usa OTLP sobre HTTP.
2. URL do endpoint — Use apenas a URL base do OTLP (o valor mostrado para OTEL_EXPORTER_OTLP_ENDPOINT ou a URL do gateway na página OpenTelemetry). Não adicione /v1/metrics ou /v1/logs; o Lakebase adiciona esses caminhos. O nome do host geralmente segue https://otlp-gateway-<region>.grafana.net/otlp; use o URL exato da sua pilha porque a região e hostname variam.
3. Autenticação — Use o método que o Grafana documenta para seus tokens: Básico se o Grafana fornecer um nome de usuário e senha (por exemplo, ID da instância e tokens), Bearer para tokens de portador ou chaveAPI com um nome de cabeçalho personalizado se o Grafana especificar um cabeçalho nãodefault . Para autenticação básica, o Grafana pode fornecer um valor codificado em base64 que você precisa decodificar antes de usar.

Para obter informações atualizadas sobre a interface do usuário, formatos de tokens e orientações de arquitetura, consulte Enviar dados para o endpointOTLP do Grafana Cloud na documentação do Grafana Cloud.

nota

A navegação na nuvem do Grafana e os nomes dos blocos podem mudar entre versões. Se um controle tiver um nome diferente no seu portal, use a pesquisa no produto ou a documentação do Grafana para encontrar o endpoint OTLP e a autenticação para sua pilha.

Após os dados chegarem à nuvem do Grafana, use o Explore e o Loki para verificar se você está recebendo métricas e logs.

Datadog

Você pode enviar métricas e logs do Lakebase para o Datadog usando seu endpoint de ingestão OTLP. O Datadog funciona melhor com temporalidade delta para contadores e histogramas. Ative a opção de métricas Delta na configuração do Lakebase OpenTelemetry.

Encontre seu endpoint OTLP do Datadog

A URL do endpoint OTLP depende do seu site Datadog. Valores comuns:

Site Datadog	endpoint OTLP (HTTP)
US1 (datadoghq.com)	https://otlp.datadoghq.com
US3 (us3.datadoghq.com)	https://otlp.us3.datadoghq.com
US5 (us5.datadoghq.com)	https://otlp.us5.datadoghq.com
EU1 (datadoghq.eu)	https://otlp.datadoghq.eu
AP1 (ap1.datadoghq.com)	https://otlp.ap1.datadoghq.com

Site Datadog	endpoint OTLP (HTTP)
US1 (datadoghq.com)	https://otlp.datadoghq.com
US3 (us3.datadoghq.com)	https://otlp.us3.datadoghq.com
US5 (us5.datadoghq.com)	https://otlp.us5.datadoghq.com
EU1 (datadoghq.eu)	https://otlp.datadoghq.eu
AP1 (ap1.datadoghq.com)	https://otlp.ap1.datadoghq.com

Para outros sites do Datadog, consulte a seção "Ingestão OTLP do Datadog" na documentação do Datadog.

Mapear valores do Datadog para o Lakebase

1. Protocolo — Usar HTTP (OTLP sobre HTTP na porta 4318). O Datadog também oferece suporte ao gRPC (porta 4317), caso seja necessário para a sua configuração de rede.
2. URL do endpoint — Insira a URL OTLP base para o seu site Datadog (consulte a tabela acima). Não adicione /v1/metrics ou /v1/logs; o Lakebase adiciona esses caminhos automaticamente.
3. Autenticação — Use a autenticação por chaveAPI . Insira sua key API Datadog como valor e defina o nome do cabeçalho como DD-API-KEY.
4. Delta métricas — Habilite Delta métricas em Opções avançadas. O Datadog espera temporalidade delta para contadores e histogramas. Sem essa configuração, os contadores cumulativos podem gerar cálculos de taxa incorretos ou contagens duplicadas no Datadog.

Após os dados chegarem ao Datadog, use o métricas Explorer para pesquisar métricas e logs lakebase_ para verificar se logs estão chegando com o seu service.name configurado.

nota

O Datadog aplica suas próprias convenções de nomenclatura ao ingerir dados OTLP. Por exemplo, pode adicionar .count ou .sum a métricas de histograma, ou converter pontos em sublinhado. Consulte o mapeamento de métricas OTLP do Datadog para obter detalhes sobre como os nomes das métricas são transformados.

Solução de problemas

• Sem dados — Confirme o URL, o protocolo e as credenciais do OTLP. Confirme se o compute não está sendo reduzido a zero. execução de uma consulta de teste para ativar a compute.
• HTTP 404 na exportação — Muitas vezes significa que o backend não aceita OTLP em {base}/v1/metrics ou {base}/v1/logs. Confirme a documentação do fornecedor ou use configurações alternativas de caminho se sua plataforma usar caminhos não padrão.
• Erros de validação ao salvar — O produto pode testar a acessibilidade do endpoint OTLP. Caso a validação falhe, verifique os requisitos de firewall e TLS, confirme os URLs da região e confirme se o backend suporta OTLP HTTP ou gRPC, conforme selecionado.

Para métricas in-produto sem exportação externa, consulte painel de métricas. Para ferramentas exclusivas para clientes que se conectam via Postgres, consulte Ferramentas de monitoramento externo.

Próximos passos

• Monitorar projetos Lakebase: Acompanhe o desempenho, o uso de recursos e a análise de query com ferramentas integradas e externas. Consulte Observabilidade.
• Visualizar métricas : Confira as estatísticas de CPU, memória, conexões e banco de dados no painel de métricas do produto. Consulte o painel de métricas.
• Conecte ferramentas de monitoramento externas : Monitore seu banco de dados com pgAdmin ou PgHero usando protocolos padrão do Postgres. Consulte Ferramentas de monitoramento externo.