Skip to main content
Cada ruta de lectura acepta sus propias claves de consulta. Una ruta de la matriz de filtros rechaza una clave desconocida o un valor de tipo incorrecto con 422 y validation_failed, salvo que la matriz indique otra cosa. Los alias cómodos como project, trace y user no son claves de consulta. No pases un filtro de una ruta a otra.

​
Crea una solicitud filtrada

Pon la query string después de la ruta. Usa --data-urlencode para que los caracteres reservados no causen problemas. Esta solicitud lee los logs críticos de un proyecto de las últimas 24 horas:
Añade los filtros en este orden:
  1. Selecciona el proyecto con project_id o project_ids.
  2. Añade un intervalo de tiempo con since y, si quieres, until.
  3. Añade filtros de servicio, release, entorno, estado o específicos de la señal.
  4. Define limit para obtener una página más pequeña.
  5. Añade campos de cursor solo después de que una respuesta con cursor los devuelva.
Cada fila devuelta coincide con todos los filtros de la solicitud. Un filtro omitido usa el valor predeterminado de la ruta. Por ejemplo, GET /api/logs usa status=active cuando omites status.

​
Matriz de filtros

Las claves de la columna «Obligatorias» deben estar en la solicitud. Todas las demás claves son opcionales. En la investigación de incidencias, selection es first, latest o recommended. Envía selection o occurrence_id, no los dos. Ambos necesitan un response_version entre 2 y 13. Con la versión 2 o posterior y sin selector, LogBrew usa recommended. Obtén un occurrence_id de GET /api/telemetry/issues/{issue_id}/events. Las rutas POST de analíticas reciben un cuerpo JSON. Consulta Analíticas de producto.

​
Filtros compartidos y específicos de cada señal

service_name, release y environment acotan todas las listas de telemetría. Usa los valores exactos que envía tu SDK. Algunos filtros pertenecen a una sola señal:
  • Los logs aceptan search, trace_id, severity y attribute_filters.
  • Los logs aceptan status: active (predeterminado), ignored o all. ignored selecciona los logs que una regla de logs oculta de la vista activa.
  • Las incidencias aceptan el status de incidencia: unresolved, resolved o archived. ignored es un nombre antiguo de archived y selecciona las mismas incidencias.
  • Las incidencias aceptan severity: info, warning, error o critical.
  • Las incidencias aceptan priority: high, medium o low.
  • Las incidencias aceptan assignee: me para las incidencias asignadas a la cuenta con la que iniciaste sesión, none para las incidencias sin responsable, my_teams para las incidencias de tus equipos, un ID de usuario o team:<team_id>.
  • Las acciones y las métricas aceptan name.
  • Las acciones aceptan distinct_id.
  • Las trazas aceptan el status de traza y min_duration_ms.
  • Los despliegues aceptan status: succeeded o failed.
Los filtros severity de logs e incidencias comparan la severidad efectiva. Si una regla cambió la severidad, el filtro usa el valor de la regla. Consulta Valores de severidad.

​
Intervalo de tiempo

since acepta un número entero positivo de horas o días, como 24h o 7d, o una marca de tiempo RFC3339. Una duración compacta es relativa a la hora de cada solicitud. until solo acepta una marca de tiempo RFC3339. Es una hora de fin exclusiva: una fila con la hora exacta de until no está en el resultado. since es inclusivo. Por ejemplo, since=2026-10-01T00:00:00Z y until=2026-10-02T00:00:00Z seleccionan 1 día completo. LogBrew compara las horas con precisión de milisegundos. until debe ser posterior a since. Si no lo es, o si until no es una marca de tiempo RFC3339, la solicitud falla con 422 y validation_failed. Para una lectura de varias páginas, elige una hora de inicio RFC3339 y mantenla en todas las páginas. Mantén también el mismo until en todas las páginas. Esta solicitud lee los logs de error de 1 día:
La lista de despliegues usa otras reglas de tiempo. Sus since y until solo aceptan marcas de tiempo RFC3339, y los dos son inclusivos. Comparan la hora en que terminó el despliegue.

​
Versión de la respuesta de incidencias

La lista de incidencias y el detalle de una incidencia aceptan response_version=1, response_version=2, response_version=3 o response_version=4. La versión 1 es la predeterminada. Cualquier otro valor falla con 422 y validation_failed.
  • La versión 1 muestra el estado archivado como ignored. No muestra la prioridad.
  • La versión 2 muestra el estado archivado como archived. Añade priority y priority_source.
  • La versión 3 tiene todos los campos de la versión 2. Añade assignee.
  • La versión 4 tiene todos los campos de la versión 3. assignee tiene type: user o team.
Todas las versiones aceptan status=archived, priority y assignee. Consulta la respuesta de incidencia.

​
Filtro de severidad

Usa severity=info|warning|error|critical en GET /api/logs. La clave antigua level es un alias de compatibilidad. Las dos claves aceptan los valores canónicos y los alias trace, debug, warn y fatal. LogBrew convierte un alias en su valor canónico antes de comparar. Si una solicitud envía severity y level a la vez, LogBrew normaliza primero los dos. Los valores en conflicto se rechazan con:

​
Filtros de trazas

En la búsqueda de trazas, status es error u ok. Omítelo para incluir los dos. min_duration_ms debe ser cero o mayor. Solo se aplica a la búsqueda de trazas. Esta solicitud encuentra las trazas de error que tardaron al menos 500 milisegundos:
Para el detalle y el resumen de una traza, codifica trace_id con codificación porcentual como segmento de la ruta. No lo envíes como clave de consulta.

​
Alcance del proyecto

Usa project_id=<project-uuid> para leer un proyecto. En las rutas que incluyen project_ids en la matriz, usa project_ids=<uuid>,<uuid> para un conjunto exacto de 2 a 50 proyectos. En esas rutas, omite las dos claves para leer todos los proyectos que la cuenta puede leer. Una ruta que requiere project_id solo acepta 1 proyecto.
LogBrew rechaza estas selecciones con 422 y validation_failed:
  • Una solicitud que tiene a la vez project_id y project_ids.
  • Un valor de project_ids con menos de 2 o más de 50 ID.
  • Un ID duplicado o un ID que no es un UUID.
Si un ID de project_ids corresponde a un proyecto que la cuenta no puede leer, la solicitud falla con 404 y not_found. No quites ese ID para continuar. Pide al usuario que elija un conjunto nuevo. Mantén el mismo alcance de proyecto en todas las páginas del cursor. No quites el filtro de proyecto después de un resultado vacío, porque eso plantea una pregunta distinta.

​
Series por intervalos

GET /api/telemetry/metrics/series devuelve una métrica dividida en intervalos. GET /api/telemetry/summary/volume devuelve los recuentos de señales divididos en intervalos. Las dos rutas siguen estas reglas:
  • since es obligatorio. until es opcional y, de forma predeterminada, es la hora de la solicitud.
  • El rango entre since y until es como máximo de 31 días.
  • interval es auto, 1m, 5m, 15m, 1h, 6h o 1d. El valor predeterminado es auto. Un valor de interval que genera más de 500 intervalos falla.
  • service_name, release y environment son filtros exactos.
En las series de métricas, name es el nombre exacto de la métrica de GET /api/telemetry/metrics. group_by es none, service_name, release o environment. series_limit va de 1 a 20. En el volumen de señales, until no puede estar en el futuro, y response_version solo puede ser 1.

​
Filtra por atributos de log

Usa GET /api/logs/attributes para encontrar las rutas y los tipos de atributo en los que puedes buscar. Después, envía attribute_filters a GET /api/logs. Las dos solicitudes necesitan since.

​
Lee el catálogo de atributos

Esta solicitud encuentra las rutas numéricas que contienen status en un proyecto:
La respuesta es un objeto, no un array simple. Este ejemplo sintético tiene 2 atributos y otra página:
type es string, number o boolean. observed_count es el número de logs del rango que tienen esa ruta y ese tipo. last_seen_at es la hora del más reciente. Un log puede tener muchas rutas. No sumes los recuentos para obtener un número de logs. coverage te indica en qué logs puede buscar un filtro de atributos: Los 3 grupos suman total_logs. El type, el search y el cursor del catálogo no cambian la cobertura. Una lista attributes vacía no significa que total_logs sea cero. El catálogo no tiene clave status. Su filtro de severidad compara la severidad capturada, no la severidad efectiva. search es una subcadena de la ruta de 1 a 128 bytes sin caracteres de control. limit define el número de atributos por página. El catálogo no usa pagination=cursor. Repite todos los filtros y copia los 3 campos de next_cursor: Detente cuando next_cursor sea null.

​
Aplica un filtro tipado

Copia la ruta y el tipo del catálogo. Las rutas usan la sintaxis JSON Pointer, no claves separadas por puntos. Mantén sin cambios cualquier escape ~0 o ~1 de la ruta. Esta solicitud lee los logs cuyo estado de respuesta numérico es 500 o mayor:
attribute_filters es un array JSON de 1 a 4 filtros. Un log debe coincidir con todos los filtros. Cada filtro tiene path, type, operator y value. El tipo JSON de value debe coincidir con type: el número 500 no es la cadena "500". ne solo coincide con los logs que tienen la ruta. Un log sin la ruta no coincide con ne. Para string, case_sensitive es opcional y su valor predeterminado es false. LogBrew rechaza "case_sensitive": true para number y boolean. Se aplican estos límites:
  • El array JSON tiene como máximo 4.096 bytes.
  • Un valor de cadena tiene como máximo 1.024 bytes.
  • contains y starts_with necesitan una cadena no vacía.
  • Un número debe ser finito y estar entre -9.007.199.254.740.992 y 9.007.199.254.740.992.
Un log en el que el índice no puede buscar no coincide con ningún filtro. Puede seguir apareciendo en una solicitud sin attribute_filters. Para la respuesta de logs, consulta Respuesta de log.

​
Corrige los errores de atributos

Cada uno de estos errores devuelve 422 con validation_failed: Corrige la solicitud antes de reintentar. No quites ningún filtro, porque eso cambia el resultado.

​
Paginación por cursor

El modo cursor se activa de forma explícita. Sin él, las rutas de lista devuelven un array simple. Envía pagination=cursor sin campos de cursor para la primera página. Para cada página siguiente, repite todos los filtros y envía el conjunto completo de campos de cursor: Asigna los campos de next_cursor devueltos a la siguiente solicitud:
  • next_cursor.time va a cursor_time.
  • next_cursor.id va a cursor_id.
  • En las trazas, next_cursor.trace_id va a cursor_trace_id.
  • En los releases, añade cursor_ delante del nombre de cada campo devuelto; por ejemplo, next_cursor.release va a cursor_release.
Detente cuando next_cursor sea null. No calcules un cursor a partir de la última fila. El cursor de releases no cambia los proyectos seleccionados. Mantén el project_id o los project_ids originales.
limit define el tamaño de la página. Una página puede contener menos filas. Estas rutas no aceptan page ni page_number. En la mayoría de las rutas, LogBrew cambia un limit superior al máximo por el máximo. La lista de despliegues rechaza un limit fuera del rango de 1 a 100 con 422. La lista de despliegues siempre devuelve un objeto de página con next_cursor, también sin pagination=cursor. LogBrew rechaza estas solicitudes con 422 y validation_failed:
  • Un valor de pagination distinto de cursor.
  • Campos de cursor sin pagination=cursor.
  • Un conjunto incompleto de campos de cursor.
  • Un cursor_time que no es una marca de tiempo RFC3339.
Un cursor marca una posición; no congela los datos. Empieza por una nueva primera página cuando necesites una vista actualizada. La CLI usa los mismos campos:

​
Diagnostica un resultado vacío

Una lista vacía significa que ninguna fila coincidió con todos los filtros. No dice nada sobre otras señales. Comprueba la solicitud en este orden:
  1. Confirma el ID del proyecto.
  2. Quita los filtros opcionales de uno en uno.
  3. Amplía since si el evento esperado es más antiguo. Quita until o muévelo más tarde si el evento esperado es más reciente.
  4. Compara service_name, release y environment con los valores que envía tu SDK.
  5. En los logs, añade status=all si una regla de logs puede ocultar el log esperado.
  6. Confirma que la ruta acepta cada filtro.

​
Soluciona una consulta rechazada

Una consulta rechazada devuelve el sobre de error estándar. Una clave desconocida o un valor de tipo incorrecto devuelve 422:
Soluciones habituales:
  • Sustituye un alias cómodo por la clave de la matriz de filtros.
  • Envía todos los campos de cursor para continuar que necesita la ruta.
  • Quita los campos de cursor de la solicitud de la primera página.
  • Usa un solo selector de proyecto.
  • Sustituye una severidad o un estado de traza no admitidos por un valor canónico.
Para los códigos de error y la recuperación, consulta Errores de la API. Para los cuerpos de respuesta, consulta Formatos de respuesta.