Integración del SDK para la telemetría de tu aplicación

Instala el paquete del SDK de LogBrew para tu runtime. El SDK da formato a los eventos y los entrega. La guía del paquete lista sus tipos de eventos, sus límites y su comportamiento de reintento. Sigue estos pasos en cada integración:

Instala el paquete del SDK para tu runtime.
Guarda la clave de ingesta del proyecto fuera del control de versiones.
Define valores estables de servicio, entorno y release.
Envía un evento de prueba seguro desde la aplicación.
Lee el resultado de la entrega. Después, busca el evento en LogBrew.

Un lote aceptado llegó a la API de LogBrew. Aun así, los filtros pueden ocultar sus eventos. Elige el proyecto y el intervalo de tiempo correctos. Después, haz coincidir el servicio, el entorno, el release y el tipo de señal. Antes de activar la captura, elige y prueba los campos aprobados. Para llenar Analíticas, sigue Captura de eventos de producto.

Señales y contexto compartido

Las cinco primeras tarjetas son señales. El release y el entorno son el contexto de esas señales. No son un tipo de evento aparte.

log

Un mensaje estructurado con severidad, origen, hora y contexto seguro.

trace_span

Una operación medida en el tiempo, vinculada a su traza mediante los ID de traza y de span.

issue

Un fallo capturado, su severidad y los detalles del error que envió la app.

action

Una acción en tu app, con sujeto, sesión y propiedades seguras opcionales.

metric

Una medida numérica con nombre, tipo, valor, unidad y temporalidad.

release y entorno

La versión del código y el entorno que se adjuntan a los eventos posteriores del mismo ámbito del SDK.

Valores de severidad

Usa info, warning, error o critical en logs e incidencias. Los SDK y los runtimes pueden enviar alias como trace, debug, warn o fatal. LogBrew normaliza los alias aceptados a los valores canónicos.

Instalación con gestores de paquetes

Instala el paquete del SDK para el runtime que envía la telemetría. Usa la configuración de SDK o de ingesta del proyecto que te da LogBrew. No uses los datos de inicio de sesión de la cuenta como configuración del SDK.

Runtime	Instalación
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	Añade `https://github.com/LogBrewCo/sdk.git` con 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	Añade `co.logbrew:logbrew-sdk:0.1.9` desde 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	Fija `cpp/logbrew-cpp/v0.2.3` con `FetchContent` de CMake.

Trazado de solicitudes en Node.js

Para correlacionar trazas desde la raíz de la solicitud, usa @logbrew/sdk 0.1.16 o posterior y @logbrew/node 0.1.11 o posterior. Express necesita @logbrew/express 0.1.5 o posterior. Fastify y NestJS necesitan su paquete de LogBrew en la versión 0.1.6 o posterior. Estas integraciones crean o continúan un span por solicitud. El nombre del span usa la plantilla de ruta que coincide. Los logs, incidencias, acciones y métricas dentro de la solicitud heredan su contexto de traza y de span. Un paquete más nuevo no añade contexto a los eventos enviados antes de actualizarlo. La integración de solicitudes predeterminada no captura los cuerpos de solicitud ni de respuesta, las cadenas de consulta, cabeceras arbitrarias ni los valores traceparent sin procesar.

ASP.NET Core

La CLI v0.1.55 o posterior detecta los proyectos de .NET 10 que usan Microsoft.NET.Sdk.Web. Previsualiza el plan de configuración desde la raíz del proyecto. Este comando no cambia tus archivos:

logbrew setup --json

El plan publicado instala la integración con el host:

dotnet add package LogBrew.AspNetCore --version 0.1.2

Define LOGBREW_SERVER_API_KEY, LOGBREW_SERVICE_NAME, LOGBREW_ENVIRONMENT y LOGBREW_RELEASE fuera del control de versiones. Registra LogBrew en el host y coloca su middleware después del enrutamiento:

using LogBrew;

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

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

Sin LOGBREW_SERVER_API_KEY, las dos llamadas de registro no hacen nada y son seguras. El paquete NuGet de ASP.NET Core identifica la integración con el host publicada. Su guía pública del paquete cubre el ciclo de vida del host, la captura de solicitudes, la captura de incidencias, los límites de privacidad y la recuperación.

Java con Maven o Gradle

La CLI v0.1.54 o posterior detecta pom.xml, build.gradle y build.gradle.kts. Previsualiza el plan de configuración desde la raíz del proyecto. Este comando no cambia tus archivos:

logbrew setup --json

Con Maven, añade el paquete publicado:

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

Con Gradle Kotlin DSL, añade el mismo artefacto de Maven Central:

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

Usa Java 11 o posterior. Las aplicaciones de Spring Boot 3 y 4 pueden exponer un bean LogBrewClient propio de la app. Este activa las integraciones opcionales de solicitudes, excepciones, cliente HTTP, JDBC y caché. La captura de Spring Kafka se activa solo de forma explícita con logbrew.kafka.enabled=true. Usa la dependencia de Spring Kafka y el bean de cliente que ya tiene la aplicación. El artefacto del SDK de Java en Maven Central identifica el paquete publicado. Su guía pública cubre la entrega HTTP con límites, el cierre, el registro de logs, la configuración de Spring, la correlación con Kafka y los límites de privacidad.

C++ con CMake

El SDK de C++ necesita C++17 y CMake 3.16 o posterior. La CLI v0.1.39 o posterior detecta un CMakeLists.txt en la raíz. Ejecuta logbrew setup --json para previsualizar este plan de configuración sin cambiar tus archivos:

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)

El target principal no tiene dependencias. Para enviar lotes con el transporte opcional de libcurl, sustituye la última llamada a FetchContent_MakeAvailable y el enlace del target anteriores por:

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

Configura la aplicación. Después, compílala para probar la versión del SDK elegida:

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

Para las compilaciones que no pueden descargar el monorepo del SDK, usa el recurso propio de C++ logbrew-cpp-0.2.3.tar.gz del release C++ 0.2.3. El paquete extraído admite cmake --install y find_package(LogBrew 0.2.3 CONFIG REQUIRED). Su guía del paquete cubre el contexto tipado, la evidencia de incidencias, los eventos de span, las métricas, las acciones y la entrega HTTP.

Mapas de origen de JavaScript

Para compilaciones con Vite, sigue Mapas de origen de JavaScript. Cubre el plugin, la clave de artefactos, las comprobaciones de la carga y una incidencia nueva con ubicaciones del código fuente original.

Apple, Flask y React Native

Usa el producto Swift LogBrew para la telemetría. Añade LogBrewCrash solo para capturar fallos o bloqueos en Apple. Sigue Fallos y bloqueos de Apple para subir los dSYM y usar la simbolización alojada. Para Flask, sigue la guía Flask. Para React Native y Expo, sigue React Native. Cubre la clave del proyecto, un log de prueba seguro, los errores de entrega y la configuración de Metro en Expo para los mapas de origen de producción.

Trazado de colas en JavaScript

Las integraciones de colas para Node son paquetes npm aparte. Instala los paquetes base de JavaScript de LogBrew, el paquete de la integración y el cliente de colas o de broker que ya usa tu app.

Cola o broker	Instalación
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`

Usa estos paquetes para correlacionar trazas de forma explícita, controlada por tu app, en torno a las llamadas a colas que elijas. LogBrew no gestiona la conexión con tu broker, no crea colas y, de forma predeterminada, no modifica globalmente todos los clientes.

Mantén fuera de la configuración del SDK los contenidos de los mensajes de la cola, las cabeceras arbitrarias de los mensajes, las URL del broker y los tokens bearer de sesión o de cuenta. Usa la configuración de ingesta de servidor del proyecto que te da LogBrew.

Sobre nativo directo

Usa POST /api/telemetry/ingest solo para un cliente propio que ningún SDK público de LogBrew admita. Los SDK públicos usan su propio formato de lotes. Este endpoint no acepta ese formato. Envía de 1 a 512 elementos en un sobre nativo. Todos los elementos de un sobre comparten el proyecto, el servicio, el release, el entorno y el contexto de la traza opcional.

Campo	Obligatorio	Notas
`project_id`	Sí	UUID del proyecto de LogBrew. Debe coincidir con el proyecto de la clave de ingesta.
`environment`	Sí	Entorno de despliegue. 64 caracteres o menos, sin espacios en blanco, `/` ni `\`. El valor `None` se rechaza.
`release`	Sí	Versión del código. 200 caracteres o menos, sin `/`, `\`, tabuladores ni saltos de línea. No puede ser `.` ni `..`.
`service_name`	Sí	Nombre lógico del servicio, como `checkout-api`. No puede estar vacío.
`sdk_name`	Sí	Identificador del SDK o del cliente propio.
`sdk_version`	Sí	Versión del SDK o del cliente propio.
`items`	Sí	De 1 a 512 elementos `log`, `trace_span`, `issue` o `action`.
`trace_id`	No	ID de traza que comparten los elementos correlacionados del sobre. Obligatorio cuando un elemento tiene `span_id`.

Campos de los elementos

Cada elemento tiene un type y un objeto data. Un elemento de log usa level. Un elemento de incidencia usa severity. Ambos aceptan los valores de Valores de severidad.

Campo del elemento	Se aplica a	Notas
`id`	Todos los elementos	ID de evento opcional del cliente. De 1 a 200 caracteres, único en el sobre.
`span_id`	`log`, `issue`, `action`	Opcional. 16 caracteres hexadecimales, no todos ceros. El sobre debe tener `trace_id`.
`name`	`action`	Obligatorio. 64 bytes UTF-8 o menos. No puede empezar por `$`, ni empezar o terminar con espacios en blanco, ni contener caracteres de control o de formato invisibles.

Envía un id con cada elemento cuando tu cliente pueda reintentar. Cuando un reintento vuelve a enviar un elemento aceptado con el mismo id y el mismo contenido, LogBrew no lo guarda otra vez. La respuesta cuenta ese elemento en already_accepted.

Ejemplo de solicitud

Guarda el JSON siguiente como telemetry-envelope.json. Sustituye el ID de proyecto de ejemplo por el ID exacto del proyecto de tu clave de ingesta. Pon en las marcas de tiempo la hora UTC actual del evento de prueba. Usa tus propios valores de servicio y release.

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 }
      }
    }
  ]
}

Carga el valor de ingesta del proyecto en LOGBREW_INGEST_BEARER desde tu configuración protegida. No lo imprimas ni uses una credencial de la cuenta. El siguiente comando envía el archivo una vez. Necesita curl 7.76.0 o posterior:

: "${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'

Lee el estado HTTP y el cuerpo. --fail-with-body conserva el cuerpo del error y devuelve un código de salida distinto de cero en los errores HTTP. Un fallo de red o un tiempo de espera agotado no te dice si LogBrew aceptó la solicitud. Vuelve a enviar el mismo archivo solo cuando sus elementos tengan valores id. Sin valores id, un segundo envío puede guardar los elementos dos veces.

Respuesta

Una solicitud correcta devuelve 200 con el número de elementos nuevos por flujo. already_accepted cuenta los elementos que ya entregó una solicitud anterior.

{
  "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"
  }
}

Errores

Una clave de ingesta no válida o revocada devuelve 401. Una clave de otro proyecto también devuelve 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"
  }
}

Usa una clave de ingesta del proyecto. No la sustituyas por una credencial de la cuenta. Una clave de artefactos no puede enviar telemetría. Un sobre que incumple una regla de campo devuelve 422 con el código validation_failed. El campo error nombra la regla. El campo next te indica cómo corregir la solicitud. Por ejemplo, "items": [] devuelve:

{
  "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"
  }
}

No envíes un sobre cuando no haya eventos. Un sobre con más de 512 elementos devuelve 422 con el error native telemetry envelope exceeds the item limit. Divídelo en lotes de 512 elementos o menos. Mantén el proyecto y el contexto compartido en cada lote. Para los límites de uso, los límites de solicitudes y los fallos del servicio, sigue el code devuelto en Errores de la API.

Define el release y el entorno al configurar el SDK. Crea o continúa el contexto de la traza en cada operación. No reutilices un mismo ID de traza para trabajos no relacionados.

Inicio

Conceptos

Instalar y enviar

Investigar

CLI y agentes

Ayuda

Integración del SDK para la telemetría de tu aplicación

Señales y contexto compartido

log

trace_span

issue

action

metric

release y entorno

Valores de severidad

Instalación con gestores de paquetes

Trazado de solicitudes en Node.js

ASP.NET Core

Java con Maven o Gradle

C++ con CMake

Mapas de origen de JavaScript

Apple, Flask y React Native

Trazado de colas en JavaScript

Sobre nativo directo

Campos de los elementos

Ejemplo de solicitud

Respuesta

Errores

​Señales y contexto compartido

log

trace_span

issue

action

metric

release y entorno

​Valores de severidad

​Instalación con gestores de paquetes

​Trazado de solicitudes en Node.js

​ASP.NET Core

​Java con Maven o Gradle

​C++ con CMake

​Mapas de origen de JavaScript

​Apple, Flask y React Native

​Trazado de colas en JavaScript

​Sobre nativo directo

​Campos de los elementos

​Ejemplo de solicitud

​Respuesta

​Errores

Señales y contexto compartido

Valores de severidad

Instalación con gestores de paquetes

Trazado de solicitudes en Node.js

ASP.NET Core

Java con Maven o Gradle

C++ con CMake

Mapas de origen de JavaScript

Apple, Flask y React Native

Trazado de colas en JavaScript

Sobre nativo directo

Campos de los elementos

Ejemplo de solicitud

Respuesta

Errores