Integração do SDK para telemetria de aplicações

Instale o pacote do kit de desenvolvimento de software (SDK) do LogBrew para o seu runtime. O SDK formata os eventos e faz a entrega. O guia do pacote lista os tipos de evento, os limites e o comportamento de novas tentativas. Siga estas etapas em cada integração:

Instale o pacote do SDK para o seu runtime.
Mantenha a chave de ingestão do projeto fora do controle de versão.
Defina valores estáveis de serviço, ambiente e versão.
Envie um evento de teste seguro a partir da aplicação.
Leia o resultado da entrega. Depois, encontre o evento no LogBrew.

Um lote aceito chegou à API do LogBrew. Mesmo assim, os filtros podem esconder os eventos dele. Escolha o projeto e o período certos. Depois, confira se o serviço, o ambiente, a versão e o tipo de sinal correspondem. Antes de ativar a captura, escolha e teste os campos aprovados. Para preencher as Análises, siga Captura de eventos de produto.

Sinais e contexto compartilhado

Os cinco primeiros cartões são sinais. A versão e o ambiente são o contexto desses sinais. Eles não são um tipo de evento separado.

log

Uma mensagem estruturada com gravidade, origem, horário e contexto seguro.

trace_span

Uma operação cronometrada, ligada ao trace dela pelos IDs de trace e de span.

issue

Uma falha capturada, a gravidade dela e os detalhes do erro que a aplicação enviou.

action

Uma ação na sua aplicação, com identidade, sessão e propriedades seguras opcionais.

metric

Uma medição numérica com nome, tipo, valor, unidade e temporalidade.

versão e ambiente

A versão do código e o ambiente associados aos eventos seguintes no mesmo escopo do SDK.

Valores de gravidade

Use info, warning, error ou critical para logs e problemas. SDKs e runtimes podem enviar aliases como trace, debug, warn ou fatal. O LogBrew converte os aliases aceitos para os valores canônicos.

Instalação por gerenciador de pacotes

Instale o pacote do SDK para o runtime que envia a telemetria. Use a configuração de SDK ou de ingestão do projeto fornecida pelo LogBrew. Não use dados de login da conta como configuração do SDK.

Runtime	Instalação
JavaScript	`npm install @logbrew/sdk`
Navegador	`npm install @logbrew/sdk @logbrew/browser`
Node.js	`npm install @logbrew/sdk @logbrew/node`
Express	`npm install @logbrew/sdk @logbrew/node @logbrew/express`
Fastify	`npm install @logbrew/sdk @logbrew/node @logbrew/fastify`
NestJS	`npm install @logbrew/sdk @logbrew/node @logbrew/nestjs`
React	`npm install @logbrew/sdk @logbrew/browser @logbrew/react`
Next.js	`npm install @logbrew/sdk @logbrew/node @logbrew/next`
Angular	`npm install @logbrew/sdk @logbrew/angular`
Vue	`npm install @logbrew/sdk @logbrew/vue`
Svelte	`npm install @logbrew/sdk @logbrew/browser @logbrew/svelte`
React Native	`npm install @logbrew/sdk @logbrew/react-native`
Python	`python3 -m pip install logbrew-sdk`
FastAPI	`python3 -m pip install logbrew-fastapi`
Flask	`python3 -m pip install "logbrew-flask>=0.1.5,<0.2"`
Django	`python3 -m pip install logbrew-django`
Swift / Apple	Adicione `https://github.com/LogBrewCo/sdk.git` pelo SwiftPM.
PHP	`composer require logbrew/sdk:^0.1.1`
Ruby	`gem install logbrew-sdk`
Go	`go get github.com/LogBrewCo/sdk/go/logbrew@latest`
Rust	`cargo add logbrew`
Java / Spring	Adicione `co.logbrew:logbrew-sdk:0.1.9` do Maven Central.
.NET	`dotnet add package LogBrew --version 0.1.7`
ASP.NET Core	`dotnet add package LogBrew.AspNetCore --version 0.1.2`
C++ / CMake	Fixe `cpp/logbrew-cpp/v0.2.3` com o `FetchContent` do CMake.

Trace de requisições no Node.js

Para a correlação de traces com raiz na requisição, use @logbrew/sdk 0.1.16 ou mais recente e @logbrew/node 0.1.11 ou mais recente. O Express exige @logbrew/express 0.1.5 ou mais recente. O Fastify e o NestJS exigem o pacote do LogBrew correspondente na versão 0.1.6 ou mais recente. Essas integrações criam ou continuam um span por requisição. O nome do span usa o modelo de rota correspondente. Logs, problemas, ações e métricas dentro da requisição herdam o contexto de trace e de span dela. Um pacote mais novo não adiciona contexto a eventos enviados antes da atualização. A integração padrão de requisições não captura corpos de requisição ou de resposta, query strings, cabeçalhos arbitrários nem valores brutos de traceparent.

ASP.NET Core

A CLI v0.1.55 ou mais recente detecta projetos .NET 10 que usam Microsoft.NET.Sdk.Web. Veja uma prévia do plano de configuração na raiz do projeto. Este comando não altera seus arquivos:

logbrew setup --json

O plano do pacote publicado instala a integração com o host:

dotnet add package LogBrew.AspNetCore --version 0.1.2

Defina LOGBREW_SERVER_API_KEY, LOGBREW_SERVICE_NAME, LOGBREW_ENVIRONMENT e LOGBREW_RELEASE fora do controle de versão. Registre o LogBrew no host e coloque o middleware dele depois do roteamento:

using LogBrew;

var builder = WebApplication.CreateBuilder(args);
builder.AddLogBrew();

var app = builder.Build();
app.UseRouting();
app.UseLogBrew();
app.MapGet("/", () => "ok");
app.Run();

Sem LOGBREW_SERVER_API_KEY, as duas chamadas de registro não fazem nada e são seguras. O pacote NuGet do ASP.NET Core identifica a integração com o host já publicada. O guia público do pacote cobre o ciclo de vida do host, a captura de requisições, a captura de problemas, os limites de privacidade e a recuperação.

Java com Maven ou Gradle

A CLI v0.1.54 ou mais recente detecta pom.xml, build.gradle e build.gradle.kts. Veja uma prévia do plano de configuração na raiz do projeto. Este comando não altera seus arquivos:

logbrew setup --json

No Maven, adicione o pacote publicado:

<dependency>
  <groupId>co.logbrew</groupId>
  <artifactId>logbrew-sdk</artifactId>
  <version>0.1.9</version>
</dependency>

No Gradle Kotlin DSL, adicione o mesmo artefato do Maven Central:

implementation("co.logbrew:logbrew-sdk:0.1.9")

Use o Java 11 ou mais recente. Aplicações Spring Boot 3 e 4 podem expor um bean LogBrewClient da própria aplicação. Ele ativa integrações opcionais de requisições, exceções, cliente HTTP, JDBC e cache. A captura do Spring Kafka só é ativada de forma explícita, com logbrew.kafka.enabled=true. Ela usa a dependência do Spring Kafka e o bean de cliente que a aplicação já tem. O artefato do SDK Java no Maven Central identifica o pacote publicado. O guia público dele cobre a entrega HTTP com limites, o encerramento, o logging, a configuração do Spring, a correlação com o Kafka e os limites de privacidade.

C++ com CMake

O SDK de C++ exige C++17 e CMake 3.16 ou mais recente. A CLI v0.1.39 ou mais recente detecta um CMakeLists.txt na raiz. Execute logbrew setup --json para ver uma prévia deste plano de configuração sem alterar seus arquivos:

include(FetchContent)
FetchContent_Declare(
  logbrew
  GIT_REPOSITORY https://github.com/LogBrewCo/sdk.git
  GIT_TAG cpp/logbrew-cpp/v0.2.3
  GIT_SHALLOW TRUE
  SOURCE_SUBDIR cpp/logbrew-cpp
)
FetchContent_MakeAvailable(logbrew)

target_link_libraries(your_app PRIVATE LogBrew::LogBrew)

O target principal não tem dependências. Para enviar lotes pelo transporte opcional com libcurl, troque a chamada final FetchContent_MakeAvailable e o link do target acima por:

set(LOGBREW_BUILD_HTTP_TRANSPORT ON CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(logbrew)
target_link_libraries(your_app PRIVATE LogBrew::HttpTransport)

Configure a aplicação. Depois, faça o build para testar a versão do SDK escolhida:

cmake -S . -B build &&
cmake --build build

Em builds que não conseguem baixar o monorepo do SDK, use o arquivo logbrew-cpp-0.2.3.tar.gz, específico do C++, da versão 0.2.3 do C++. O pacote extraído aceita cmake --install e find_package(LogBrew 0.2.3 CONFIG REQUIRED). O guia do pacote cobre contexto tipado, evidências de problemas, eventos de span, métricas, ações e entrega HTTP.

Source maps de JavaScript

Em builds com Vite, siga Source maps de JavaScript. O guia cobre o plugin, a chave de artefato, as verificações de upload e um problema novo com os locais originais no código-fonte.

Apple, Flask e React Native

Use o produto Swift LogBrew para telemetria. Adicione LogBrewCrash só para capturar crashes ou travamentos da Apple. Siga Crashes e travamentos da Apple para fazer upload de dSYM e usar a simbolização hospedada. Para Flask, siga Configure o Flask. Para React Native e Expo, siga React Native. O guia cobre a chave do projeto, um log de teste seguro, erros de entrega e a configuração do Metro no Expo para source maps de produção.

Trace de filas no JavaScript

As integrações de filas do Node são pacotes npm separados. Instale os pacotes JavaScript base do LogBrew, o pacote de integração e o cliente de fila ou de broker que a sua aplicação já usa.

Fila ou broker	Instalação
BullMQ	`npm install @logbrew/sdk @logbrew/node @logbrew/bullmq bullmq`
KafkaJS	`npm install @logbrew/sdk @logbrew/node @logbrew/kafkajs kafkajs`
RabbitMQ / amqplib	`npm install @logbrew/sdk @logbrew/node @logbrew/amqplib amqplib`
Amazon SQS	`npm install @logbrew/sdk @logbrew/node @logbrew/aws-sqs @aws-sdk/client-sqs`

Use esses pacotes para correlacionar traces de forma explícita, sob controle da aplicação, nas chamadas de fila que você escolher. O LogBrew não controla a conexão com o broker, não cria filas e, por padrão, não modifica globalmente todos os clientes.

Mantenha payloads de filas, cabeçalhos arbitrários de mensagens, URLs de brokers e valores bearer de sessão ou de conta fora da configuração do SDK. Use a configuração de ingestão de servidor do projeto fornecida pelo LogBrew.

Envelope nativo direto

Use POST /api/telemetry/ingest só para um cliente próprio que nenhum SDK público do LogBrew atende. Os SDKs públicos usam um formato de lote próprio. Este endpoint não aceita esse formato. Envie de 1 a 512 itens em um envelope nativo. Todos os itens de um envelope compartilham o projeto, o serviço, a versão, o ambiente e o contexto de trace opcional.

Campo	Obrigatório	Observações
`project_id`	Sim	UUID do projeto do LogBrew. Precisa ser o mesmo projeto da chave de ingestão.
`environment`	Sim	Ambiente de implantação. Até 64 caracteres, sem espaços em branco, `/` ou `\`. O valor `None` é rejeitado.
`release`	Sim	Versão do código. Até 200 caracteres, sem `/`, `\`, tabulações ou quebras de linha. Não pode ser `.` nem `..`.
`service_name`	Sim	Nome lógico do serviço, como `checkout-api`. Não pode ficar em branco.
`sdk_name`	Sim	Identificador do SDK ou do cliente próprio.
`sdk_version`	Sim	Versão do SDK ou do cliente próprio.
`items`	Sim	De 1 a 512 itens `log`, `trace_span`, `issue` ou `action`.
`trace_id`	Não	ID de trace compartilhado pelos itens correlacionados do envelope. Obrigatório quando um item tem `span_id`.

Campos dos itens

Cada item tem um type e um objeto data. Um item de log usa level. Um item de problema usa severity. Os dois aceitam os valores de Valores de gravidade.

Campo do item	Vale para	Observações
`id`	Todos os itens	ID opcional do evento no cliente. De 1 a 200 caracteres, único no envelope.
`span_id`	`log`, `issue`, `action`	Opcional. 16 caracteres hexadecimais, nem todos zero. O envelope precisa ter `trace_id`.
`name`	`action`	Obrigatório. Até 64 bytes em UTF-8. Não pode começar com `$`, começar ou terminar com espaço em branco nem conter caracteres de controle ou de formatação invisíveis.

Envie um id em cada item quando o seu cliente puder fazer novas tentativas. Quando uma nova tentativa reenvia um item aceito com o mesmo id e o mesmo conteúdo, o LogBrew não o armazena de novo. A resposta conta esse item em already_accepted.

Exemplo de requisição

Salve o JSON abaixo como telemetry-envelope.json. Troque o ID de projeto do exemplo pelo ID exato do projeto da sua chave de ingestão. Preencha os horários com o horário UTC atual do evento de teste. Use os seus próprios valores de serviço e de versão.

telemetry-envelope.json

{
  "project_id": "11111111-1111-4111-8111-111111111111",
  "environment": "production",
  "release": "api@1.2.3",
  "service_name": "checkout-api",
  "sdk_name": "custom-native-client",
  "sdk_version": "1.0.0",
  "items": [
    {
      "type": "log",
      "data": {
        "id": "evt_example_log_0001",
        "level": "warning",
        "message": "checkout retry scheduled",
        "source": "runtime",
        "attributes": { "route": "/checkout" },
        "occurred_at": "2026-06-01T12:00:00Z"
      }
    },
    {
      "type": "action",
      "data": {
        "id": "evt_example_action_0001",
        "name": "checkout_failed",
        "distinct_id": "user_123",
        "session_id": "session_456",
        "occurred_at": "2026-06-01T12:00:00Z",
        "properties": { "cart_total": 4200 }
      }
    }
  ]
}

Carregue o valor de ingestão do projeto em LOGBREW_INGEST_BEARER pela sua configuração protegida. Não imprima esse valor nem use uma credencial da conta. O comando a seguir envia o arquivo uma vez. Ele exige o curl 7.76.0 ou mais recente:

: "${LOGBREW_INGEST_BEARER:?load the project-scoped ingest key}" &&
curl --fail-with-body --silent --show-error \
  "https://api.logbrew.co/api/telemetry/ingest" \
  -H "Authorization: Bearer $LOGBREW_INGEST_BEARER" \
  -H "Content-Type: application/json" \
  --data-binary @telemetry-envelope.json \
  --write-out '\nHTTP %{http_code}\n'

Leia o status HTTP e o corpo. --fail-with-body mantém o corpo do erro e retorna um código de saída diferente de zero em erros HTTP. Uma falha de rede ou um timeout não informa se o LogBrew aceitou a requisição. Envie o mesmo arquivo de novo só quando os itens dele tiverem valores de id. Sem valores de id, um segundo envio pode armazenar os itens duas vezes.

Resposta

Uma requisição bem-sucedida retorna 200 com a contagem de itens novos por fluxo. already_accepted conta os itens que uma requisição anterior já entregou.

{
  "issues": 0,
  "logs": 1,
  "trace_spans": 0,
  "actions": 1,
  "already_accepted": 0,
  "next": "review accepted telemetry in logs, issues, traces, actions, or live feed",
  "next_action": {
    "code": "review_ingested_telemetry",
    "target": "telemetry_reads"
  }
}

Erros

Uma chave de ingestão inválida ou revogada retorna 401. Uma chave de outro projeto também retorna 401:

{
  "error": "Invalid ingest key",
  "code": "ingest_key_invalid",
  "next": "create a project-scoped ingest key, then retry ingestion with that key",
  "next_action": {
    "code": "configure_ingest_key",
    "target": "project_ingest_key"
  }
}

Use uma chave de ingestão do projeto. Não a troque por uma credencial da conta. Uma chave de artefato não pode enviar telemetria. Um envelope que viola uma regra de campo retorna 422 com o código validation_failed. O campo error indica a regra. O campo next diz como corrigir a requisição. Por exemplo, "items": [] retorna:

{
  "error": "native telemetry envelope cannot be empty",
  "code": "validation_failed",
  "next": "send at least one native telemetry item",
  "next_action": {
    "code": "fix_request",
    "target": "request"
  }
}

Não envie um envelope quando não houver eventos. Um envelope com mais de 512 itens retorna 422 com o erro native telemetry envelope exceeds the item limit. Divida o envelope em lotes de até 512 itens. Mantenha o projeto e o contexto compartilhado em cada lote. Para limites de uso, limites de requisições e falhas do serviço, siga o code retornado em Erros da API.

Defina a versão e o ambiente na configuração do SDK. Crie ou continue o contexto de trace em cada operação. Não reutilize um ID de trace em trabalhos sem relação.

Primeiros passos

Conceitos

Instalar e enviar

Investigar

CLI e agentes

Suporte

Integração do SDK para telemetria de aplicações

Sinais e contexto compartilhado

log

trace_span

issue

action

metric

versão e ambiente

Valores de gravidade

Instalação por gerenciador de pacotes

Trace de requisições no Node.js

ASP.NET Core

Java com Maven ou Gradle

C++ com CMake

Source maps de JavaScript

Apple, Flask e React Native

Trace de filas no JavaScript

Envelope nativo direto

Campos dos itens

Exemplo de requisição

Resposta

Erros

​Sinais e contexto compartilhado

log

trace_span

issue

action

metric

versão e ambiente

​Valores de gravidade

​Instalação por gerenciador de pacotes

​Trace de requisições no Node.js

​ASP.NET Core

​Java com Maven ou Gradle

​C++ com CMake

​Source maps de JavaScript

​Apple, Flask e React Native

​Trace de filas no JavaScript

​Envelope nativo direto

​Campos dos itens

​Exemplo de requisição

​Resposta

​Erros

Sinais e contexto compartilhado

Valores de gravidade

Instalação por gerenciador de pacotes

Trace de requisições no Node.js

ASP.NET Core

Java com Maven ou Gradle

C++ com CMake

Source maps de JavaScript

Apple, Flask e React Native

Trace de filas no JavaScript

Envelope nativo direto

Campos dos itens

Exemplo de requisição

Resposta

Erros