Saltar al contenido principal

Observabilidad de API

El menú API es el espacio dedicado de Beak para todo lo que ocurre en la capa de API. Parte de un inventario construido automáticamente con cada API del entorno — REST, SOAP, GraphQL, gRPC, WebSocket, webhook y APIs de eventos — y agrega vistas de rendimiento, fiabilidad, contrato, dependencia, seguridad y operaciones con IA sobre ese único catálogo.

Cada superficie lee la telemetría que Beak ya recopila: tramos de solicitud OpenTelemetry, logs de gateway y OTel, logs de pods de Kubernetes, especificaciones OpenAPI cargadas, el ejecutor de SLO, el feed de despliegues y el grafo de conocimiento. Ningún dato en estas pantallas es de muestra — cuando una señal aún no se ha recopilado, el panel lo indica y nombra la fuente que lo provee, en lugar de mostrar un número de marcador.

El catálogo es la columna vertebral de todo el menú — cada otra pantalla filtra, puntúa o profundiza en él. Tres acciones lo pueblan, todas desde el encabezado de la pantalla API Catalog & Discovery:

  • Discover — Recorre la telemetría que Beak ya tiene y deriva APIs de ella. El selector muestra cuántos datos contiene cada fuente y qué parte es compatible con HTTP, para que solo se analicen las fuentes que tengan algo que encontrar. Las fuentes son trazas de solicitudes, logs de gateway / OTel, logs de pods de Kubernetes, especificaciones OpenAPI y mallas de servicios.
  • Import OpenAPI — Cargue un archivo de especificación o pegue una URL de especificación. Funciona desde el primer día sin ninguna instrumentación, y proporciona a Beak plantillas de endpoints autorizadas para comparar con el tráfico observado.
  • Register API — Agregue una sola API de forma manual, para algo que no tenga ni telemetría ni especificación.

Los registros catalogados llevan los atributos que el resto del menú necesita: protocolo, versión, entorno, URL base, nombre del servicio, equipo o usuario propietario, nivel, exposición (internal / partner / public / third_party), método de autenticación, fuente de descubrimiento, recuento de endpoints y marcas de tiempo de primera / última visualización.

Nota: La creación de plantillas de endpoints prefiere la plantilla declarada en OpenAPI, luego el atributo de tramo http.route, y solo entonces infiere una. Una plantilla inferida siempre se muestra para que un operador pueda corregirla — Beak nunca inventa silenciosamente una ruta que el propietario no reconocería.

Dos acciones de curación mantienen un entorno grande legible:

  • Merge — Consolida varios registros descubiertos en una sola API lógica. Los miembros conservan su identidad y se agrupan bajo el elemento padre.
  • Group endpoints — Etiqueta un conjunto de endpoints para que las variantes de la misma operación se reporten como una sola fila.

Command Center​

API Command Center es el tablero general — una pantalla que sirve tanto como pantalla NOC como revisión ejecutiva desde los mismos datos. Un selector de ventana temporal (1h, 24h, 7d, 30d) delimita toda la página, y Export escribe el mapa de salud en CSV.

Cinco indicadores principales:

  • APIs monitored — Total catalogado, dividido en saludable / degradado / crítico cuando existe telemetría
  • Composite availability SLA — Disponibilidad en todos los servicios con un SLO definido, con el recuento de SLO contribuyentes
  • P95 latency (estate) — Percentil 95 de todo el entorno para la ventana, con el número de solicitudes a partir del cual se calculó
  • 5xx error rate — Tasa de errores del lado del servidor durante la ventana
  • Business transaction success — Se completa una vez que se configuran las reglas de transacciones de negocio

Debajo de los indicadores:

  • API health map — Una celda por API que muestra solicitudes, P95 y tasa de errores 5xx, con bandas de color según el estado de salud; hacer clic en una celda abre la vista de detalle de esa API
  • Error budget — month to date — Presupuesto consumido y restante con una clasificación de los mayores consumidores, y un acceso directo a la pantalla de SLA
  • Estate traffic — Solicitudes por minuto durante la ventana, con tasas actuales y máximas
  • Active API incidents — Servicios que actualmente están consumiendo su presupuesto de errores, con síntoma, tasa de errores, P95 y multiplicador de tasa de consumo
  • Estate P95 vs. P99 — Ambas curvas superpuestas, porque la cola suele ser lo más revelador
  • Telemetry status — Indica exactamente cuántos tramos de solicitud y servicios SLO puede ver el tablero en la ventana actual, para que un panel vacío nunca sea ambiguo

API Catalog & Discovery​

El inventario en sí, con una fila de KPI que también funciona como conjunto de filtros — hacer clic en un indicador filtra la tabla debajo de él.

  • Discovered APIs — Total en el catálogo, con el recuento añadido en los últimos siete días
  • Undocumented endpoints — Endpoints activos en producción pero ausentes de cualquier especificación
  • Ownership assigned — Porcentaje de APIs con propietario asignado, más un acceso directo a las que no tienen propietario
  • External / partner — APIs expuestas más allá del entorno interno
  • Unauthenticated — APIs que no declaran ningún método de autenticación

Cuatro tarjetas de facetas en vivo desglosan el entorno por protocolo, por exposición, por fuente de descubrimiento y por método de autenticación, y cada valor es seleccionable como filtro. La tabla de inventario incluye API, protocolo, propietario, fuente, recuentos de endpoints y no documentados, exposición, autenticación y última visualización, con búsqueda de texto libre, paginación y exportación a CSV.

API Detail​

El registro por API: metadatos del catálogo (propietario, exposición, autenticación, recuentos de endpoints y no documentados, última visualización) y la lista completa de endpoints — endpoint, operación, si está documentado, autenticación, fuente de descubrimiento y última visualización. Cuando una API ha sido consolidada en otra, la página lo indica y enlaza al elemento padre.

La latencia, la tasa de errores y la puntuación de salud de diez factores se asocian a esta pantalla con la fase de acumulación de métricas; hasta entonces muestra el registro real del catálogo en lugar de una puntuación sintética.

Rendimiento​

Cuatro pantallas, cada una delimitada a una API mediante un selector con enlace profundo a través de ?id=.

  • Response Monitoring — Encabeza con la escala de percentiles y la distribución de latencia en lugar de un promedio, para que "la API es lenta" se resuelva en qué tan lenta, para cuántos usuarios y en qué endpoint. Incluye la tabla de endpoints más lentos y una tendencia de percentiles, calculada a partir de tramos de solicitud reales.
  • Traffic & Consumers — Solicitudes por minuto, tasa máxima, participación de los endpoints principales y consumidores activos, con los endpoints más concurridos, una tendencia de tráfico y un mapa de calor hora por día. Los segmentos por consumidor, versión y región aparecen a medida que se recopilan esas dimensiones, y se reportan de forma honesta en lugar de inventarse.
  • Error Intelligence — Tasa de errores con el desglose 4xx / 5xx y los endpoints que realmente fallan, desglosados por código de estado. Un error es la marca de error OTLP o un estado HTTP de 400 o superior.
  • Anomaly Detection — Una comparación período a período: esta ventana frente a la inmediatamente anterior, para tráfico, latencia P95 y tasa de errores. La pantalla indica cómo se calcula la comparación en lugar de presentar una puntuación de caja negra.

Fiabilidad​

  • SLA & Error Budget — Presupuesto de errores restante, tasa de consumo y previsión de incumplimiento por servicio, desde el consumo en tiempo real del ejecutor de SLO. Los objetivos son definidos por el operador y tienen efecto inmediato; el consumo se completa a medida que fluye la telemetría de solicitudes. Incluye gráficos de consumo del presupuesto, la definición de SLO en vigor y un resumen de cumplimiento para todo el entorno.
  • Synthetic Probes — La flota de sondas activas del ejecutor de monitores: recuento de sondas, disponibilidad, tiempo de respuesta promedio y tiempo de actividad de la flota en 24 horas, más la tabla por sonda. Estas son las verificaciones activas que se ejecutan hoy; el sondeo multirregión llegará con el ejecutor de sondas distribuidas.
  • API Journeys — Transacciones de negocio de varios pasos y con estado donde las variables de una respuesta alimentan la siguiente, informando el éxito a nivel de recorrido e identificando el paso que falló. La pantalla documenta exactamente lo que reporta desde ejecuciones reales; necesita el ejecutor de recorridos antes de que se complete.

Calidad y Contrato​

  • Response Quality — La brecha entre "respondió" y "correctamente": conformidad de esquema, campos obligatorios, reglas de negocio y actualidad, para que una respuesta rápida, bien formada pero incorrecta sea detectada en lugar de celebrada. Requiere el motor de validación de respuestas.
  • Contract Drift — El contrato publicado frente a lo que producción expone realmente. Los endpoints no documentados (activos, pero no en la especificación) y los endpoints obsoletos son la señal real de desviación, con cobertura de especificación y una tabla de hallazgos — derivada del catálogo, sin necesidad de trazas.
  • Change Impact — Cada despliegue superpuesto sobre las señales doradas de la API con una comparación antes / después. Los despliegues rastreados, el último despliegue, los servicios y entornos provienen del feed de despliegue de CI/CD real; la superposición de señales y el veredicto de regresión se completan a medida que fluyen las métricas de trazas.

Dependencia y Negocio​

  • Dependency Map — Qué llama esta API y qué la llama a ella, derivado del árbol de tramos real: un tramo de llamador con un tramo hijo en otro servicio es un enlace. Muestra dependencias descendentes, dependientes ascendentes y tramos vinculados, con volumen de llamadas por enlace, tasa de errores y P95. El grafo ponderado por salud y la vista de radio de impacto se construyen sobre los mismos enlaces.
  • Third-Party APIs — Cada API externa de la que depende, con recuentos externos / de socios y de terceros del catálogo. El estado del proveedor, el cupo y el margen de límite de velocidad se completan una vez que haya un registro de proveedores en uso.
  • Business Transactions — Una API puede devolver 200 y el resultado de negocio puede seguir fallando. Esto rastrea resultados — pedidos completados, pagos liquidados, cuentas abiertas — y la brecha entre el éxito técnico y el de negocio, a partir de eventos de resultado vinculados a predicados de tramos.

Seguridad​

API Security Observability trata la telemetría que responde "¿es rápida?" como la misma telemetría que responde "¿está siendo abusada?". La señal disponible hoy es basada en exposición: cuántas APIs están catalogadas y cuáles de ellas no declaran autenticación — el hallazgo de seguridad de API más accionable en la mayoría de los entornos. El abuso de autenticación por consumidor y la generación de perfiles de comportamiento necesitan telemetría de autenticación, y la pantalla lo indica en lugar de mostrar un gráfico vacío.

Operaciones con IA​

  • AI Investigator — Ask Beak está activo: Beak recorre el grafo de conocimiento y devuelve respuestas fundamentadas y respaldadas por evidencia sobre el entorno de API. La cadena causal automatizada de incidentes se ejecuta contra un incidente específico una vez que existe uno y el grafo está poblado.
  • Predict & Incidents — Fallos predichos por el predictor del grafo de conocimiento, con el impacto más temprano, el mayor riesgo y cuántas predicciones llevan una ETA, más previsiones de trayectoria de SLA y margen de capacidad de los pronosticadores de métricas.

Qué Necesita Cada Superficie​

Cada pantalla está disponible; lo que varía es qué telemetría está leyendo. Este es el orden que desbloquea la mayor cantidad de superficies más rápidamente:

  • Importación de especificación OpenAPI — Puebla el catálogo, las plantillas de endpoints, la desviación de contratos y la cobertura de especificación. No se requiere instrumentación.
  • Tramos de solicitud OpenTelemetry — Desbloquea percentiles de latencia, inteligencia de errores, tráfico, detección de anomalías y el mapa de dependencias. Apunte cualquier SDK o Collector OTel al endpoint OTLP de Beak.
  • Definiciones de SLO — Desbloquea disponibilidad, presupuesto de errores, tasa de consumo, previsión de incumplimiento y el feed de incidentes del Command Center.
  • Monitores sintéticos — Desbloquea la flota de sondas y las verificaciones de disponibilidad para APIs sin instrumentación.
  • Feed de despliegues — Desbloquea la línea de tiempo de despliegues de Change Impact y su comparación antes / después.

Control de Acceso​

Los elementos del menú tienen alcance de permisos, por lo que un rol solo ve aquello a lo que tiene derecho:

  • apis:read — Command Center, Catalog, Detail, y las pantallas de rendimiento, calidad, dependencia y seguridad
  • monitors:read — Synthetic Probes y API Journeys
  • ai:use — AI Investigator
  • ai:read — Predict & Incidents

Mejores Prácticas​

  • Importe especificaciones antes de instrumentar. Una especificación proporciona a Beak plantillas de endpoints autorizadas, de modo que cuando lleguen los tramos se agrupen correctamente desde la primera solicitud en lugar de necesitar corrección posterior.
  • Resuelva la propiedad primero. El indicador Ownership assigned es la ruta más rápida hacia un entorno accionable — una alerta sobre una API sin propietario no tiene a donde ir.
  • Trate Unauthenticated como una cola de trabajo. Cada fila es una exposición real o un registro de catálogo que corregir.
  • Defina los SLOs pronto. La disponibilidad, el presupuesto de errores, la tasa de consumo, la previsión de incumplimiento y el feed de incidentes del Command Center derivan de ellos.
  • Use el selector de ventana temporal de forma deliberada. 1h para un incidente activo, 24h para una transferencia de turno, 7d / 30d para revisiones — el mismo tablero sirve para los tres.
  • Lea las notas de "por qué está vacío". Cada panel nombra la fuente que lo completa, lo que convierte un gráfico en blanco en una tarea de incorporación de una sola línea.

Páginas Relacionadas​

  • Tracing — la ingestión de trazas OTLP que alimenta el análisis de latencia, errores y dependencias
  • Monitors — la flota de monitores sintéticos detrás de Synthetic Probes
  • Settings — definiciones de SLO, canalizaciones de ingestión y permisos de roles
  • Knowledge Graph — el grafo que recorre el AI Investigator
  • AppManager — el conjunto de superficies de monitoreo de aplicaciones más amplio