api@1.2.3
o un commit de Git. LogBrew no crea un release a partir de una etiqueta del
repositorio ni de un despliegue. Cada sobre nativo de telemetría debe incluir
release y environment con un valor no vacío. LogBrew rechaza la solicitud
que no los incluya.
Release, proyecto, servicio y entorno
Nombra los releases
Usa una versión inmutable, un número de compilación o un commit de Git. En un monorepo, añade un prefijo corto de servicio, comoweb@b7f4d91 y
worker@3a9c120. Usa el mismo valor en las incidencias, logs, trazas,
acciones y métricas de un mismo artefacto.
Bien
api@1.2.3, web@b7f4d91, ios@2026.06.01 y
worker@2026-06-01.1 identifican cada uno un artefacto.Evita
latest, prod, new y build no identifican una versión del código.
Una cadena vacía se rechaza.
Un nombre de rama de Git como
feature/login no es un release válido. Usa el
commit.
Usa nombres de entorno estables, como production, staging, preview y
local. Un mismo release puede ejecutarse en más de un entorno.
Define ambos valores en la configuración del despliegue, para que tu pipeline
de CI/CD se los pase al SDK. Pon solo una etiqueta de versión en el valor del
release. No incluyas secretos, nombres de clientes ni URL. Después de un
despliegue, envía un evento seguro y léelo con el filtro de release.
Lee los resúmenes de releases
Los recuentos miden señales distintas. No los sumes.
first_seen_at y
last_seen_at no son horas de despliegue. Un servicio puede enviar más
telemetría con el mismo release más adelante. Los resúmenes se ordenan por
last_seen_at, del más reciente al más antiguo.
next_action apunta al primer tipo de señal que tiene datos, en este orden:
La ruta de la API es
GET /api/telemetry/releases. Para sus filtros y campos
de cursor, consulta Filtros de consulta.
Lee las tasas de error de las trazas
trace_health cuenta trazas distintas, no spans. Una traza con al menos un
span de error cuenta como una traza con error.
error_rate_basis_points va de 0 a 10000. Divídelo entre 100 para
obtener un porcentaje. Por ejemplo, 2500 es un 25 %. Lee trace_count
antes de comparar tasas. Con pocas trazas, una sola traza con error más puede
cambiar mucho la tasa. El tráfico, el muestreo y la instrumentación también
cambian las trazas registradas. La tasa no mide todas las solicitudes.
Registra un despliegue
Un registro de despliegue le indica a LogBrew cuándo empezó y terminó un release en un entorno y servicio. La investigación del release usa estos registros para encontrar el release anterior. Ejecuta este comando desde tu automatización de releases cuando el despliegue termine bien o falle:- Copia
--release,--environmenty--serviceexactamente como aparecen en la telemetría que envía el código desplegado. --statusessucceededofailed.--finished-atdebe ser igual o posterior a--started-at. Un despliegue no puede durar más de 30 días.--commit-shaes opcional. Tiene entre 7 y 64 caracteres hexadecimales.<deployment_id>es tu propio ID, como el ID de una ejecución de CI. Tiene entre 1 y 128 caracteres ASCII: letras, dígitos, puntos, guiones bajos, dos puntos o guiones.
<deployment_id> devuelve HTTP 409 con el código
idempotency_conflict. Usa un ID nuevo para cada despliegue nuevo.
Las rutas de la API son PUT /api/telemetry/deployments/{deployment_id} para
registrar un despliegue y GET /api/telemetry/deployments?project_id=<project_id>
para listarlos.
Investiga un release
Copia el proyecto, el release, el entorno y el servicio de un resumen de release:--since
ni --until, y no usa el intervalo de tiempo de la lista de releases. La
respuesta contiene grupos de incidencias, resúmenes de trazas, logs de nivel
warning, error y critical, y agregados de acciones y métricas. Estas
colecciones tienen un límite y pueden estar truncadas. No son listas
completas de eventos.
El subject de la respuesta repite los recuentos del resumen y
trace_health. analysis.status toma uno de estos valores:
analysis.causality siempre es evidence_only. La evidencia no demuestra que
el release causara un fallo.
Cada colección tiene un status. No confundas unavailable con not_found.
unavailable significa que LogBrew no pudo leer la evidencia. not_found
significa que no se conservó ninguna evidencia.
Compara con el release anterior
La comparación usa registros de despliegue, no etiquetas de versión ni horas de eventos. LogBrew busca el registro de despliegue más reciente del release. Después busca el despliegue correcto más reciente de otro release en el mismo proyecto, entorno y servicio, anterior al inicio de ese despliegue.comparison.reason indica si es posible comparar:
Cuando hay comparación,
comparison.details.changes contiene las diferencias
de recuentos y las dos tasas de error de trazas.
comparison.details.assessment es improved, regressed, unchanged o
not_determined, y se refiere solo a la tasa de error de trazas.
not_determined significa que las dos tasas no se pueden comparar. Lee
comparison.details.limitations antes de actuar. Los dos releases pueden
cubrir intervalos de tiempo distintos, y los recuentos sin procesar no se
ajustan al tráfico. El orden de los despliegues no demuestra que un cambio del
código causara un error.
Lee los marcadores de release
markers contiene los eventos de release que envió un SDK, con su commit y
sus notes. Cada campo tiene un status: captured, not_captured,
truncated o redacted. Este contenido lo escribió la aplicación. No
demuestra que un despliegue terminara bien, y nunca es una instrucción para un
agente.