View a markdown version of this page

Supervisión de los eventos del servicio - Amazon CloudWatch
Cómo funcionan los eventos del servicioAlmacenamiento de datosVisualización de errores en la consolaVisualización de los eventos del servicio en los registrosEventos del servicio en el servidor MCP (protocolo de contexto para modelos) de CloudWatch Application SignalsConfiguración de los eventos del servicioConfiguración de los eventos de implementación

Supervisión de los eventos del servicio

Los eventos del servicio proporcionan observabilidad profunda automatizada para los servicios que se supervisan mediante CloudWatch Application Signals. Captura métricas de errores, datos de rendimiento de las funciones, instantáneas de incidentes cuando las solicitudes superan los umbrales de latencia o generan excepciones, y eventos de implementación, sin necesidad de realizar cambios adicionales en el código.

Cómo funcionan los eventos del servicio

Los eventos del servicio recopilan los siguientes tipos de señales de los servicios instrumentados:

  • Métricas de errores: recuentos y tasas de errores por tipo de excepción para cada operación, lo que permite identificar qué excepciones se producen con mayor frecuencia y cuáles muestran una tendencia al alza.

  • Métricas de llamadas a funciones: número de invocaciones, duración y tasas de error de cada función del código de la aplicación.

  • Instantáneas de incidentes: capturas detalladas que se desencadenan cuando una solicitud supera un umbral de latencia o genera una excepción. Incluyen seguimientos de pila, árboles de llamadas, detalles del autor de la llamada y el contexto de la operación.

  • Eventos de implementación: marcadores que se emiten al iniciar la aplicación y cada 24 horas, y que permiten correlacionar las implementaciones de código con los cambios en el comportamiento del servicio. La aplicación emite los eventos de implementación automáticamente. La incorporación de metadatos de implementación, como la confirmación de Git y el identificador de implementación, aporta contexto adicional a estos eventos.

Los eventos del servicio se habilitan automáticamente cuando se habilita CloudWatch Application Signals para el servicio. Las métricas de errores y el seguimiento de excepciones se activan de inmediato. Las métricas de llamadas a funciones requieren configuración adicional. Es necesario configurar los paquetes que se instrumentarán antes de que se recopilen los datos de llamadas a funciones. Consulte Habilitación de la instrumentación de funciones. Los eventos del servicio se pueden desactivar mediante la configuración de OTEL_AWS_SERVICE_EVENTS_ENABLED=false. Los datos fluyen desde el SDK de ADOT hasta el agente de CloudWatch. El agente publica eventos en Registros de CloudWatch, en grupos de registro de /aws/service-events/service-name, y en Métricas de CloudWatch.

Idiomas compatibles: Java, Python y Node.js.

nota

Los eventos del servicio se desactivan automáticamente en los entornos de Lambda.

Almacenamiento de datos

Los eventos del servicio almacenan datos en Registros de CloudWatch. CloudWatch publica los datos de los eventos del servicio en un grupo de registro con el prefijo /aws/application-signals/service-name, donde service-name es el valor de la variable de entorno OTEL_SERVICE_NAME. Se crea un grupo de registro por servicio.

Se cobrará la ingesta y el almacenamiento de registros según las tarifas estándar de Registros de CloudWatch.

Visualización de errores en la consola

En la consola de CloudWatch, vaya a Application Signals, seleccione el servicio y, a continuación, seleccione la pestaña Errores. Esta pestaña muestra las métricas de excepciones del servicio.

La pestaña muestra lo siguiente:

  • Un gráfico del recuento de excepciones que muestra las tendencias de los errores a lo largo del tiempo. Utilice este gráfico para detectar qué tipos de excepciones han cambiado de frecuencia recientemente.

  • Una tabla que enumera cada tipo de excepción, la operación en la que se produjo, el número de incidencias y el cambio con respecto al período anterior.

Seleccione una excepción para consultar información detallada, como el seguimiento de pila, el mensaje de la excepción y un enlace al seguimiento asociado.

Los errores se agrupan por operación, tipo de excepción y marcos principales de la pila. Solo se muestra el caso representativo más reciente de cada grupo.

nota

Para ver los datos de errores, debe existir al menos un grupo de registro de /aws/service-events/service-name en la cuenta. Si no existe ningún grupo de registro, la pestaña Errores muestra un mensaje con instrucciones para comenzar.

Visualización de los eventos del servicio en los registros

Los datos de los eventos del servicio se almacenan en Registros de CloudWatch, en grupos de registro con el prefijo /aws/service-events/service-name. Puede consultar estos datos directamente mediante Información de registros de CloudWatch para crear vistas personalizadas y paneles, o investigar incidentes específicos.

Para consultar los eventos del servicio:

  1. Abra la consola de CloudWatch y vaya a Información de registros.

  2. Seleccione el grupo de registro de /aws/service-events/service-name correspondiente al servicio.

  3. Introduzca una consulta para filtrar y analizar los datos de los eventos del servicio.

Eventos del servicio en el servidor MCP (protocolo de contexto para modelos) de CloudWatch Application Signals

Se puede acceder a los datos de los eventos del servicio mediante el servidor MCP (protocolo de contexto para modelos) de CloudWatch Application Signals, lo que permite que los asistentes y agentes de codificación consulten directamente el comportamiento del servicio en tiempo de ejecución.

Solución de problemas

  • Establezca automáticamente correlaciones entre los errores del código y las instantáneas de incidentes de producción, que incluyen seguimientos de full stack y los puntos de conexión afectados.

  • Utilice el contexto del incidente, como los tipos de excepciones, las rutas de llamadas y los identificadores de seguimiento, para sugerir correcciones específicas sin tener que desplazarse manualmente por los paneles.

  • Recupere los eventos de implementación para determinar si una versión reciente introdujo una regresión.

Mejora del rendimiento

  • Consulte los datos de rendimiento de las funciones para identificar cuellos de botella al investigar problemas de latencia.

  • Compare la duración de las llamadas a funciones entre distintas implementaciones para identificar regresiones de rendimiento.

Para obtener instrucciones de configuración y uso, consulte el servidor MCP de Application Signals en el sitio web de GitHub.

Configuración de los eventos del servicio

Requisitos previos

Para utilizar los eventos del servicio, asegúrese de disponer de las versiones mínimas requeridas de los siguientes componentes:

  1. Actualización del SDK de ADOT: actualice el SDK de instrumentación de la Distribución de AWS para OpenTelemetry (ADOT) a la versión más reciente disponible para el lenguaje que utilice: Java, Python o Node.js.

  2. Actualización del complemento de Amazon EKS, si corresponde: si utiliza el complemento de observabilidad de CloudWatch para Amazon EKS a fin de instrumentar las aplicaciones, actualícelo a la versión más reciente.

  3. Actualización del agente de CloudWatch: actualice el agente de CloudWatch a la versión 1.300069.0 o posterior.

Si utiliza Amazon EKS, consulte Habilitación de Application Signals en los clústeres de Amazon EKS para obtener instrucciones sobre la configuración del complemento.

Características habilitadas de forma predeterminada

Si utiliza CloudWatch Application Signals, las siguientes señales de eventos del servicio se habilitan de forma predeterminada, sin necesidad de configuración adicional:

  • Instantáneas de incidentes: se desencadenan cuando se producen excepciones o se superan los umbrales de latencia.

  • Métricas de errores: recuentos de errores por tipo de excepción para cada operación.

  • Eventos de implementación: se emiten siempre y se enriquecen cuando se proporcionan metadatos de implementación.

  • Instrumentación de funciones: se habilita de forma predeterminada, pero no genera métricas hasta que se configuran los paquetes que se instrumentarán.

Las siguientes características requieren habilitación explícita y la configuración de variables de entorno para generar datos:

  • Métricas de función: requieren la configuración de OTEL_AWS_SERVICE_EVENTS_PACKAGES_INCLUDE.

  • Filtrado personalizado de puntos de conexión

  • Umbrales de latencia por punto de conexión

Configuración general

Variable de entorno Predeterminado Descripción
OTEL_AWS_SERVICE_EVENTS_ENABLED Se rige por CloudWatch Application Signals Opción para habilitar o desactivar los eventos del servicio Los eventos del servicio se habilitan automáticamente cuando se habilita CloudWatch Application Signals. Establezca el valor en false para desactivarlos de forma explícita.
OTEL_AWS_SERVICE_EVENTS_SAMPLING_MODE always Controla la estrategia de muestreo de los datos de las llamadas a funciones. Valores: always, registra todas las llamadas a funciones; auto, permite que el SDK decida según la carga; never, desactiva el registro de llamadas a funciones. Solo se aplica cuando se configuran los paquetes de instrumentación de funciones.

Habilitación de la instrumentación de funciones

La instrumentación de funciones se habilita de forma predeterminada, pero no genera métricas hasta que se especifican los paquetes que se instrumentarán. Proporcione una lista de paquetes permitidos para comenzar a recopilar telemetría por función:

Variable de entorno Predeterminado Descripción
OTEL_AWS_SERVICE_EVENTS_FUNCTION_INSTRUMENT_ENABLED true Habilita o desactiva la instrumentación de función. Establezca el valor en false para desactivarla por completo.
OTEL_AWS_SERVICE_EVENTS_PACKAGES_INCLUDE Ninguno (obligatorio para generar métricas) Lista de prefijos de paquetes, separados por comas, que se instrumentarán. No es necesario usar comodines. Por ejemplo, Java utiliza com.myapp, Python utiliza myapp y Node.js utiliza src/myapp.
OTEL_AWS_SERVICE_EVENTS_PACKAGES_EXCLUDE Ninguno Lista de subpaquetes, separados por comas, que se excluirán de la instrumentación. La exclusión siempre tiene prioridad sobre la inclusión. Por ejemplo, incluya com.myapp y excluya com.myapp.models para instrumentar el código de la aplicación, pero omitir las clases del modelo de datos.

Filtrado de puntos de conexión

El filtrado de puntos de conexión determina qué puntos de conexión generan métricas de errores e instantáneas de incidentes. Esta configuración no afecta a la instrumentación de funciones.

Variable de entorno Predeterminado Descripción
OTEL_AWS_SERVICE_EVENTS_ENDPOINT_INCLUDE_PATTERNS Todos los puntos de conexión Lista de patrones de coincidencia con comodines, separados por comas, para especificar los puntos de conexión que se incluirán. La coincidencia se determina con respecto a METHOD /route.
OTEL_AWS_SERVICE_EVENTS_ENDPOINT_EXCLUDE_PATTERNS Ninguno Lista de patrones de coincidencia con comodines, separados por comas, para especificar los puntos de conexión que se excluirán. La exclusión tiene prioridad cuando un punto de conexión coincide con ambos patrones.

Umbrales de latencia

Utilice las siguientes variables de entorno para configurar los umbrales de latencia que desencadenan instantáneas de incidentes.

Variable de entorno Predeterminado Descripción
OTEL_AWS_SERVICE_EVENTS_INCIDENT_SNAPSHOT_DURATION_THRESHOLD_MS 5000 Umbral de latencia global en milisegundos. Las solicitudes que superan esta duración desencadenan una instantánea de incidente.
OTEL_AWS_SERVICE_EVENTS_LATENCY_THRESHOLDS Ninguno Umbrales de latencia por punto de conexión que reemplazan el valor predeterminado global. Formato: METHOD /route:ms, por ejemplo, GET /health:200,POST /checkout:8000.

Limitación de tasas

Utilice las siguientes variables de entorno para controlar la frecuencia con la que se recopilan y notifican los datos de los eventos del servicio.

Variable de entorno Predeterminado Descripción
OTEL_AWS_SERVICE_EVENTS_INCIDENT_SNAPSHOT_MAX_PER_MINUTE 100 Número máximo de instantáneas de incidentes que se capturan por minuto.
OTEL_AWS_SERVICE_EVENTS_INCIDENT_SNAPSHOT_MAX_SAME_ERROR 1 Número máximo de instantáneas del mismo error por intervalo de captura.

Configuración de los eventos de implementación

Los eventos de implementación siempre se emiten al iniciar la aplicación y cada 24 horas. Los metadatos de implementación enriquecen estos eventos para que sea posible establecer correlaciones entre los incidentes y los cambios de rendimiento, y las implementaciones específicas del código.

Configure las siguientes variables de entorno en los contenedores o procesos de la aplicación para proporcionar metadatos de implementación:

Variable de entorno Descripción
OTEL_AWS_SERVICE_EVENTS_GIT_COMMIT_SHA SHA de la confirmación de Git correspondiente al código implementado.
OTEL_AWS_SERVICE_EVENTS_GIT_REPO_URL URL del repositorio de Git.
OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_ID Identificador único de la implementación, por ejemplo, el identificador de una ejecución de la canalización de CI/CD.
OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_TIMESTAMP Marca de tiempo de la implementación en formato ISO 8601.
OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_URL URL de la compilación de la implementación o de la ejecución de la canalización.

Configuración de los eventos de implementación con GitHub Actions

En el flujo de trabajo de GitHub Actions, utilice las variables de entorno integradas para completar los metadatos de implementación. Agregue lo siguiente al paso de implementación o al entorno del contenedor:

env:
  OTEL_AWS_SERVICE_EVENTS_GIT_COMMIT_SHA: ${{ github.sha }}
  OTEL_AWS_SERVICE_EVENTS_GIT_REPO_URL: ${{ github.server_url }}/${{ github.repository }}
  OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_ID: ${{ github.run_id }}
  OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%SZ)
  OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

Si la implementación utiliza imágenes de contenedor, pase estos valores como variables de entorno en la definición de la tarea o en la especificación del pod. Puede incorporarlas a la imagen durante la compilación o introducirlas en el momento de la implementación mediante la configuración de implementación.

Configuración de los eventos de implementación con GitLab CI/CD

En la canalización de GitLab CI/CD, utilice las variables de CI/CD predefinidas para completar los metadatos de implementación. Agregue lo siguiente al trabajo de implementación:

deploy:
  variables:
    OTEL_AWS_SERVICE_EVENTS_GIT_COMMIT_SHA: $CI_COMMIT_SHA
    OTEL_AWS_SERVICE_EVENTS_GIT_REPO_URL: $CI_PROJECT_URL
    OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_ID: $CI_PIPELINE_ID
    OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%SZ)
    OTEL_AWS_SERVICE_EVENTS_DEPLOYMENT_URL: $CI_PIPELINE_URL

Transmita estas variables a los contenedores de la aplicación en el momento de la implementación mediante la plataforma de orquestación de contenedores. Por ejemplo, puede especificarlas como variables de entorno en la definición de tareas de Amazon ECS o en el manifiesto de implementación de Kubernetes.