Enriquecer solo lo que vas a consultar: filtros del enriquecimiento OTel en Amazon CloudWatch
El enriquecimiento OTel de Amazon CloudWatch se activa para toda la cuenta y, por defecto, decora todas las métricas vendidas de todos los namespaces que soporta. Suena cómodo hasta que miras la factura y te das cuenta de que estás enriqueciendo métricas de servicios que nadie consulta por PromQL. La pregunta no es si quieres el enriquecimiento, sino sobre qué métricas lo quieres.
Amazon CloudWatch agregó el 5 de octubre de 2026 la posibilidad de filtrar el enriquecimiento OTel por namespace y por nombre de métrica. Este artículo explica qué enriquece CloudWatch por defecto, cómo acotarlo con filtros de inclusión y exclusión, la diferencia entre fijar los filtros al iniciar y cambiarlos sobre una cuenta en marcha, y una semántica de reemplazo que conviene entender antes de automatizar. Cierra con ejemplos de la AWS Command Line Interface (AWS CLI) y las limitaciones.
Qué es el enriquecimiento OTel
El enriquecimiento OTel decora las métricas vendidas de tu cuenta con etiquetas de ARN del recurso y de etiquetas del recurso. Una vez enriquecidas, las métricas que tienen una dimensión de identificador de recurso, por ejemplo CPUUtilization de Amazon Elastic Compute Cloud (Amazon EC2) con una dimensión InstanceId, se pueden consultar con PromQL y agrupar o filtrar por atributos del recurso en PromQL y en Query Studio.
Antes de filtrar hay un requisito: el enriquecimiento tiene que estar iniciado para la cuenta. Y antes de iniciarlo, hay que habilitar las etiquetas de recurso en la telemetría. El orden importa, porque los filtros no sirven de nada si el enriquecimiento no está corriendo.
El alcance por defecto y por qué acotarlo
Por defecto, el enriquecimiento aplica a todos los namespaces que CloudWatch soporta para enriquecer. Eso es lo más simple de operar, pero no siempre es lo que quieres pagar. Si solo consultas por PromQL las métricas de un puñado de servicios, enriquecer el resto es costo que no se traduce en consultas.
Para eso están los dos parámetros opcionales: IncludeFilters y ExcludeFilters. Con ellos acotas el enriquecimiento a un subconjunto de namespaces y nombres de métrica. La documentación lo plantea justo como una herramienta para optimizar el costo del enriquecimiento cuando solo necesitas algunas métricas en OTel.
Cada filtro selecciona métricas de un namespace:
- Namespace es obligatorio. Se compara de forma exacta y distingue mayúsculas de minúsculas.
- MetricNames es opcional. Los nombres se comparan de forma exacta y distinguen mayúsculas. Si lo omites, se seleccionan todas las métricas del namespace.
Los límites: un máximo de 100 filtros entre IncludeFilters y ExcludeFilters combinados, y un máximo de 100 nombres de métrica por selector.
Iniciar frente a actualizar
Hay dos operaciones y la diferencia entre ellas es fácil de pasar por alto.
StartOTelEnrichment inicia el enriquecimiento para la cuenta y guarda los filtros que le pases. Pero esos filtros se guardan solo cuando esta operación inicia el enriquecimiento. Si llamas a StartOTelEnrichment en una cuenta donde el enriquecimiento ya está corriendo, no pasa nada: no modifica los filtros aplicados.
Para cambiar los filtros en una cuenta donde el enriquecimiento ya corre, se usa UpdateOTelEnrichment. Si llamas a UpdateOTelEnrichment y el enriquecimiento no está corriendo, devuelve ResourceNotFoundException.
Esa división tiene una consecuencia práctica: no puedes ajustar el alcance del enriquecimiento con la operación de inicio una vez que ya arrancó. El ajuste en caliente es siempre con la operación de actualización.
La semántica de reemplazo
Este es el punto que conviene entender antes de automatizar nada. Los filtros de la petición reemplazan por completo los filtros guardados. No se fusionan.
Y hay un detalle más fino: IncludeFilters y ExcludeFilters se reemplazan como un par. Una petición que especifica solo IncludeFilters también borra los ExcludeFilters guardados. Una petición que no especifica ninguno de los dos borra ambos.
En la práctica, esto significa que cada llamada a UpdateOTelEnrichment tiene que llevar el estado completo que quieres que quede, no solo el cambio. Si guardas un ExcludeFilter hoy y mañana llamas a la operación solo con un IncludeFilter nuevo, el ExcludeFilter de ayer desaparece. Para una automatización que ajusta filtros, esto obliga a construir el conjunto completo en cada petición en lugar de aplicar diferencias.
Cómo decidir qué enriquecer
Antes de escribir un filtro conviene saber qué métricas son candidatas. El enriquecimiento aplica solo a las métricas que tienen una dimensión de identificador de recurso, como InstanceId en una métrica de Amazon EC2. Una métrica sin esa dimensión no se enriquece, con filtro o sin él, así que no tiene sentido incluirla.
Dentro de ese universo, un criterio simple es partir de lo que ya consultas. Si tu equipo escribe consultas PromQL o paneles en Query Studio sobre las métricas de un grupo de servicios, esos namespaces son los que vale la pena enriquecer. El resto se puede dejar fuera con un filtro de inclusión acotado, o excluir con un filtro de exclusión si prefieres partir del alcance por defecto y recortar.
Dos preguntas ayudan a decidir entre inclusión y exclusión. Si la lista de lo que quieres enriquecer es corta y estable, un IncludeFilter la describe mejor. Si quieres casi todo salvo un namespace ruidoso o de alto volumen, un ExcludeFilter es más fácil de mantener. En ambos casos, el conteo cuenta contra el mismo límite de 100 filtros combinados.
Señal, objetivo y runbook
El hilo de esta serie se aplica casi literalmente, porque el tema es elegir la señal.
La señal son las métricas que de verdad consultas por PromQL o en Query Studio. Esas son las que vale la pena enriquecer.
El objetivo lo pone el equipo. Una meta razonable es que el conjunto enriquecido coincida con el conjunto consultado: ni métricas enriquecidas que nadie consulta, ni métricas que consultas sin las etiquetas de recurso que necesitas para agrupar. Es una meta de costo y cobertura, no un umbral del servicio.
El runbook es la configuración de los filtros: iniciar el enriquecimiento acotado y ajustarlo con la operación de actualización cuando cambie lo que consultas, siempre con el conjunto completo en cada petición.
Desde la AWS CLI
Las operaciones existen en la referencia de la AWS CLI como start-otel-enrichment y update-otel-enrichment.
Para acotar el enriquecimiento, al iniciarlo, a dos namespaces, uno completo y otro con métricas específicas:
1
aws cloudwatch start-otel-enrichment --include-filters '[{"Namespace":"AWS/EC2"},{"Namespace":"AWS/RDS","MetricNames":["CPUUtilization","FreeableMemory"]}]'Para cambiar los filtros en una cuenta donde el enriquecimiento ya corre, recordando que la petición reemplaza por completo lo guardado:
1
aws cloudwatch update-otel-enrichment --include-filters '[{"Namespace":"AWS/EC2"},{"Namespace":"AWS/RDS"}]'Para enriquecer todo salvo un namespace ruidoso, con un filtro de exclusión:
1
aws cloudwatch update-otel-enrichment --exclude-filters '[{"Namespace":"AWS/Usage"}]'Como el filtro de inclusión y el de exclusión se reemplazan como par, esta última llamada, al no incluir IncludeFilters, deja el enriquecimiento con el alcance por defecto menos el namespace excluido. Si antes tenías un IncludeFilter, esta llamada lo borra. Conviene tener presente el estado completo que quieres antes de ejecutar.
Limitaciones
- El enriquecimiento tiene que estar iniciado antes de poder filtrar. Antes de iniciarlo, hay que habilitar las etiquetas de recurso en la telemetría.
- StartOTelEnrichment guarda los filtros solo cuando inicia el enriquecimiento. En una cuenta que ya lo tiene corriendo, no modifica los filtros.
- UpdateOTelEnrichment devuelve ResourceNotFoundException si el enriquecimiento no está corriendo.
- Los filtros reemplazan por completo los guardados, no se fusionan. IncludeFilters y ExcludeFilters se reemplazan como par: enviar solo uno borra el otro, no enviar ninguno borra ambos.
- Namespace y nombres de métrica se comparan de forma exacta y distinguen mayúsculas de minúsculas.
- El máximo es de 100 filtros entre inclusión y exclusión combinados, y de 100 nombres de métrica por selector.
- El enriquecimiento, con filtros o sin ellos, aplica solo a métricas con una dimensión de identificador de recurso. Las que no la tienen no se enriquecen.
Recursos
- Filtering enrichment by namespace and metric - Qué hacen IncludeFilters y ExcludeFilters y cómo acotar el enriquecimiento por costo
- AWS vended metrics in OpenTelemetry format - Qué es el enriquecimiento OTel y cómo deja las métricas consultables por PromQL
- start-otel-enrichment - Opciones del comando que inicia el enriquecimiento y guarda los filtros iniciales
- update-otel-enrichment - Opciones del comando que reemplaza los filtros en una cuenta en marcha
- Introducing OpenTelemetry and PromQL support in Amazon CloudWatch - Contexto del enriquecimiento de métricas vendidas y su consulta con PromQL
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article