> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logbrew.co/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Escolha um SDK do LogBrew para o seu runtime. Configure a chave de ingestão. Envie telemetria da aplicação e encontre o evento de teste no projeto.

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:

1. Instale o pacote do SDK para o seu runtime.
2. Mantenha a chave de ingestão do projeto fora do controle de versão.
3. Defina valores estáveis de serviço, ambiente e versão.
4. Envie um evento de teste seguro a partir da aplicação.
5. 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](/pt-BR/guides/safe-capture).
Para preencher as Análises, siga [Captura de eventos de produto](/pt-BR/guides/product-events).

## <span id="item-types">Sinais e contexto compartilhado</span>

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.

<CardGroup cols={2}>
  <Card title="log" icon="file-text">
    Uma mensagem estruturada com gravidade, origem, horário e contexto seguro.
  </Card>

  <Card title="trace_span" icon="route">
    Uma operação cronometrada, ligada ao trace dela pelos IDs de trace e de
    span.
  </Card>

  <Card title="issue" icon="bug">
    Uma falha capturada, a gravidade dela e os detalhes do erro que a aplicação
    enviou.
  </Card>

  <Card title="action" icon="mouse-pointer-click">
    Uma ação na sua aplicação, com identidade, sessão e propriedades seguras
    opcionais.
  </Card>

  <Card title="metric" icon="chart-line">
    Uma medição numérica com nome, tipo, valor, unidade e temporalidade.
  </Card>

  <Card title="versão e ambiente" icon="tags">
    A versão do código e o ambiente associados aos eventos seguintes no mesmo escopo do SDK.
  </Card>
</CardGroup>

## 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](/pt-BR/guides/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.10` 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:

```bash theme={null}
logbrew setup --json
```

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

```bash theme={null}
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:

```csharp theme={null}
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](https://www.nuget.org/packages/LogBrew.AspNetCore/0.1.2)
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:

```bash theme={null}
logbrew setup --json
```

No Maven, adicione o pacote publicado:

```xml theme={null}
<dependency>
  <groupId>co.logbrew</groupId>
  <artifactId>logbrew-sdk</artifactId>
  <version>0.1.10</version>
</dependency>
```

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

```kotlin theme={null}
implementation("co.logbrew:logbrew-sdk:0.1.10")
```

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](https://central.sonatype.com/artifact/co.logbrew/logbrew-sdk/0.1.10)
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:

```cmake theme={null}
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:

```cmake theme={null}
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:

```bash theme={null}
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++](https://github.com/LogBrewCo/sdk/releases/tag/cpp/logbrew-cpp/v0.2.3).
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](/pt-BR/guides/source-maps).
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](/pt-BR/guides/apple-crashes-and-hangs)
para fazer upload de dSYM e usar a simbolização hospedada.

Para Flask, siga [Configure o Flask](/pt-BR/guides/flask).

Para React Native e Expo, siga [React Native](/pt-BR/guides/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.

## <span id="javascript-queue-tracing">Trace de filas no JavaScript</span>

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.

<Warning>
  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.
</Warning>

## <span id="required-envelope-fields">Envelope nativo direto</span>

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](/pt-BR/concepts/telemetry#severity-values).

| 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.

```json telemetry-envelope.json theme={null}
{
  "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:

```bash theme={null}
: "${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.

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/pt-BR/reference/api-errors).

<Tip>
  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.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.