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

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

> Elige un SDK de LogBrew para tu runtime. Configura su clave de ingesta. Envía telemetría de la aplicación y encuentra el evento de prueba en tu proyecto.

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:

1. Instala el paquete del SDK para tu runtime.
2. Guarda la clave de ingesta del proyecto fuera del control de versiones.
3. Define valores estables de servicio, entorno y release.
4. Envía un evento de prueba seguro desde la aplicación.
5. 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](/es/guides/safe-capture).
Para llenar Analíticas, sigue [Captura de eventos de producto](/es/guides/product-events).

## <span id="item-types">Señales y contexto compartido</span>

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.

<CardGroup cols={2}>
  <Card title="log" icon="file-text">
    Un mensaje estructurado con severidad, origen, hora y contexto seguro.
  </Card>

  <Card title="trace_span" icon="route">
    Una operación medida en el tiempo, vinculada a su traza mediante los ID de
    traza y de span.
  </Card>

  <Card title="issue" icon="bug">
    Un fallo capturado, su severidad y los detalles del error que envió la app.
  </Card>

  <Card title="action" icon="mouse-pointer-click">
    Una acción en tu app, con sujeto, sesión y propiedades seguras opcionales.
  </Card>

  <Card title="metric" icon="chart-line">
    Una medida numérica con nombre, tipo, valor, unidad y temporalidad.
  </Card>

  <Card title="release y entorno" icon="tags">
    La versión del código y el entorno que se adjuntan a los eventos
    posteriores del mismo ámbito del SDK.
  </Card>
</CardGroup>

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

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

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

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

```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();
```

Sin `LOGBREW_SERVER_API_KEY`, las dos llamadas de registro no hacen nada y son
seguras. El
[paquete NuGet de ASP.NET Core](https://www.nuget.org/packages/LogBrew.AspNetCore/0.1.2)
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:

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

Con Maven, añade el paquete publicado:

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

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

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

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

```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)
```

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:

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

```bash theme={null}
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](https://github.com/LogBrewCo/sdk/releases/tag/cpp/logbrew-cpp/v0.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](/es/guides/source-maps). 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](/es/guides/apple-crashes-and-hangs) para
subir los dSYM y usar la simbolización alojada.

Para Flask, sigue la guía [Flask](/es/guides/flask).

Para React Native y Expo, sigue [React Native](/es/guides/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.

## <span id="javascript-queue-tracing">Trazado de colas en JavaScript</span>

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.

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

## <span id="required-envelope-fields">Sobre nativo directo</span>

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

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

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

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:

```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'
```

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.

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

### Errores

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

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:

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

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](/es/reference/api-errors).

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


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