# Incrustar métricas en los registros El formato de métrica integrado de CloudWatch le permite generar métricas personalizadas de forma asíncrona en forma de registros escritos en registros de CloudWatch. Puede integrar métricas personalizadas junto con datos de eventos de registro detallados, y CloudWatch automáticamente extrae las métricas personalizadas para que pueda visualizarlas y crear alarmas en función de ellas con el fin de detectar los incidentes en tiempo real. Además, los eventos de registro detallados que se asocian a las métricas extraídas se pueden consultar con CloudWatch Logs Insights para ofrecer información detallada acerca de las causas raíz de los eventos operativos. El formato de métrica integrado le ayuda a generar métricas personalizadas accionables a partir de recursos efímeros como las funciones de Lambda y los contenedores. Ahora, mediante el uso del formato de métricas integradas para enviar registros desde estos recursos efímeros, puede crear métricas personalizadas con facilidad y sin tener que instrumentar o mantener un código independiente, a la vez que obtiene funciones analíticas potentes en sus datos de registro. No es necesario realizar ninguna configuración para utilizar el formato de métrica integrado. Puede estructurar sus registros siguiendo la [Especificación del formato de métrica integrado](CloudWatch_Embedded_Metric_Format_Specification.md) o generarlos mediante nuestras bibliotecas de cliente y enviarlos a registros de CloudWatch mediante la [API PutLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) o el [agente de CloudWatch.](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Generation_CloudWatch_Agent.html) Para generar métricas a partir de registros con formato de métrica integrado, necesita el permiso `logs:PutLogEvents`, aunque no es necesario que también tenga el permiso `cloudwatch:PutMetricData`. Se incurre en cargos por la incorporación y el archivado de registros, así como por las métricas personalizadas que se generan. Para obtener más información, consulte [Precios de Amazon CloudWatch](https://aws.amazon.com/cloudwatch/pricing). **nota** Tenga cuidado al configurar su extracción de métricas, ya que afecta a su uso de métricas personalizadas y a la factura correspondiente. Si crea métricas de forma involuntaria basadas en dimensiones de alta cardinalidad (como `requestId`), el formato de métricas integradas creará, por diseño, una métrica personalizada correspondiente a cada combinación de dimensiones única. Para obtener más información, consulte [Dimensiones](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension). En los siguientes temas se describe cómo publicar registros con el formato de métricas incrustadas, ver las métricas y los registros en la consola y configurar alarmas en las métricas creadas con el formato de métricas incrustadas. **Topics** + [Publicación de registros mediante el formato de métrica integrado](CloudWatch_Embedded_Metric_Format_Generation.md) + [Visualización de sus métricas y registros en la consola](CloudWatch_Embedded_Metric_Format_View.md) + [Configurar alarmas en las métricas creadas con el formato de métrica integrado](CloudWatch_Embedded_Metric_Format_Alarms.md) # Publicación de registros mediante el formato de métrica integrado Puede generar registros de formato de métricas incrustadas con los siguientes métodos: + Generar y enviar los registros mediante las [bibliotecas de cliente de código abierto](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Libraries.html). + Genere manualmente los registros utilizando la [especificación de formato de métrica integrado](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Specification.html) y, a continuación, utilice el [agente de CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Generation_CloudWatch_Agent.html) o la [API PutLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) para enviar los registros. Los siguientes temas proporcionan más información acerca de las métricas incrustadas. **Topics** + [Crear registros en formato de métrica integrado utilizando las bibliotecas de cliente](CloudWatch_Embedded_Metric_Format_Libraries.md) + [Especificación: Formato de métricas integradas](CloudWatch_Embedded_Metric_Format_Specification.md) + [Uso de la API PutLogEvents para enviar registros de formato de métricas integradas creados manualmente](CloudWatch_Embedded_Metric_Format_Generation_PutLogEvents.md) + [Uso del agente de CloudWatch para enviar registros de formato de métricas integradas](CloudWatch_Embedded_Metric_Format_Generation_CloudWatch_Agent.md) + [Uso del formato de métricas integradas con Distro para OpenTelemetry de AWS.](CloudWatch_Embedded_Metric_Format_OpenTelemetry.md) # Crear registros en formato de métrica integrado utilizando las bibliotecas de cliente Puede usar las bibliotecas de cliente de código abierto que proporciona Amazon para crear registros de formato de métricas incrustadas. Puede encontrar ejemplos completos de diferentes configuraciones en nuestras bibliotecas de cliente, en **/examples**. Las bibliotecas y las instrucciones sobre cómo usarlas se encuentran en GitHub. + [Node.Js](https://github.com/awslabs/aws-embedded-metrics-node) **nota** Para Node.js, se requieren las versiones 4.1.1\$1, 3.0.2\$1 y 2.0.7\$1 para su uso con el formato de registro JSON de Lambda. El uso de versiones anteriores en estos entornos Lambda provocará la pérdida de las métricas. Para obtener más información, consulte [Acceso a los registros de Amazon CloudWatch para AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs.html). + [Python](https://github.com/awslabs/aws-embedded-metrics-python) + [Java](https://github.com/awslabs/aws-embedded-metrics-java) + [C\$1](https://github.com/awslabs/aws-embedded-metrics-dotnet) Las bibliotecas cliente están diseñadas para funcionar de forma inmediata con el agente de CloudWatch. Los registros en formato de métrica integrado generados se envían al agente de CloudWatch, que, a continuación, los agrega y publica en registros de CloudWatch por usted. **nota** Cuando se utiliza Lambda, no se requiere ningún agente para enviar los registros a CloudWatch. Todo lo que se registre en STDOUT se envía a registros de CloudWatch a través del agente de registro de Lambda. # Especificación: Formato de métricas integradas El formato de métricas integradas de CloudWatch es una especificación JSON que se utiliza para indicar a CloudWatch Logs que extraiga automáticamente los valores de métricas integradas en eventos de registro estructurados. Puede utilizar CloudWatch para graficar y crear alarmas en los valores de métricas extraídos. En esta sección, se describen las convenciones de especificación del formato de métricas integradas y la estructura del documento del formato de métricas integradas. ## Convenciones de especificación de formato de métricas integradas Las palabras clave “DEBE”, “NO DEBE”, “OBLIGATORIO”, “DEBERÁ”, “NO DEBERÁ”, “DEBERÍA”, “NO DEBERÍA”, “RECOMENDADO”, “PUEDE QUE” y “OPCIONAL” de esta especificación de formato se interpretarán tal como se describe en [Palabras clave RFC2119](http://tools.ietf.org/html/rfc2119). Los términos "JSON", "texto JSON", "valor JSON", "miembro", "elemento", "objeto", "matriz", "número", "cadena", "valor booleano", "true", "false" y "null" de esta especificación de formato se interpretarán tal como se define en [Notación de objetos de JavaScript RFC8259](https://tools.ietf.org/html/rfc8259). **nota** Si planea crear alarmas a partir de métricas creadas con un formato de métrica integrado, consulte [Configurar alarmas en las métricas creadas con el formato de métrica integrado](CloudWatch_Embedded_Metric_Format_Alarms.md) para obtener recomendaciones. ## Estructura de los documentos con formato de métricas integradas En esta sección se describe la estructura de un documento con formato de métricas integradas. Los documentos con formato de métricas integradas se definen en [Notación de objetos de JavaScript RFC8259](https://tools.ietf.org/html/rfc8259). A menos que se indique lo contrario, los objetos definidos por esta especificación NO DEBEN contener miembros adicionales. Los miembros no reconocidos por esta especificación DEBEN pasarse por alto. Los miembros definidos en esta especificación distinguen entre mayúsculas y minúsculas. El formato de las métricas integradas está sujeto a los mismos límites que los eventos estándar de CloudWatch Logs y están limitados a un tamaño máximo de 1 MB. Con el formato de métrica incorporado, puede hacer un seguimiento del procesamiento de sus registros de EMF por métricas publicadas en el espacio de nombres de `AWS/Logs` de su cuenta. Se pueden utilizar para hacer un seguimiento de la generación con errores de métricas a partir de EMF, así como para determinar si se producen errores debido al análisis o la validación. Para obtener más información, consulte [Supervisión con métricas de CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html). ### Nodo Raíz El mensaje LogEvent DEBE ser un objeto JSON válido sin datos adicionales al principio o al final de la cadena de mensajes LogEvent. Para obtener más información acerca de la estructura LogEvent, consulte [InputLogEvent](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_InputLogEvent.html). Los documentos con formato de métricas integradas DEBEN contener el siguiente miembro de nivel superior en el nodo raíz. Este es un objeto [Objeto de metadatos](#CloudWatch_Embedded_Metric_Format_Specification_structure_metadata). ``` { "_aws": { "CloudWatchMetrics": [ ... ] } } ``` El nodo raíz DEBE contener todos los [Miembros de destino](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) miembros definidos por las referencias en el [Objeto MetricDirective](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdirective). PUEDE QUE el nodo raíz contenga cualquier otro miembro que no esté incluido en los requisitos anteriores. Los valores de estos miembros DEBEN ser tipos JSON válidos. ### Objeto de metadatos El miembro `_aws` se puede utilizar para representar metadatos sobre la carga que informa a los servicios posteriores de cómo deben procesar el LogEvent. El valor DEBE ser un objeto y DEBE contener los siguientes miembros: + **CloudWatchMetrics**: Matriz de [Objeto MetricDirective](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdirective) que se utiliza para indicar a CloudWatch que extraiga métricas del nodo raíz del LogEvent. ``` { "_aws": { "CloudWatchMetrics": [ ... ] } } ``` + **Marca temporal**: Número que representa la marca temporal que se utiliza para las métricas que se extraen del evento. Los valores DEBEN expresarse como el número de milisegundos después del 1 de enero de 1970 00:00:00 UTC. ``` { "_aws": { "Timestamp": 1559748430481 } } ``` ### Objeto MetricDirective El objeto MetricDirective indica a los servicios posteriores que LogEvent contiene métricas que se extraerán y publicarán en CloudWatch. MetricDirectives DEBE contener los siguientes miembros: + **Espacio de nombres**: cadena que representa el espacio de nombres de CloudWatch para la métrica. + **Dimensiones**: [Matriz DimensionSet](#CloudWatch_Embedded_Metric_Format_Specification_structure_dimensionset). + **Métricas**: matriz de objetos de [Objeto MetricDefinition](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdefinition). Esta matriz NO DEBE contener más de 100 objetos MetricDefinition. ### Matriz DimensionSet Un DimensionSet es una matriz de cadenas que contiene las claves de dimensión que se aplicarán a todas las métricas del documento. Los valores de esta matriz también DEBEN ser miembros en el nodo raíz, denominado [Miembros de destino](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) Un DimensionSet NO DEBE contener más de 30 claves de dimensión. Una DimensionSet PUEDE estar vacía. El miembro de destino DEBE tener un valor de cadena. Este valor NO DEBE contener más de 1024 caracteres. El miembro de destino define una dimensión que se publicará como parte de la identidad de métrica. Cada DimensionSet que se utiliza crea una métrica nueva en CloudWatch. Para obtener más información acerca de las dimensiones, consulte [Dimensión](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_Dimension.html) y [Dimensiones](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension). ``` { "_aws": { "CloudWatchMetrics": [ { "Dimensions": [ [ "functionVersion" ] ], ... } ] }, "functionVersion": "$LATEST" } ``` **nota** Tenga cuidado al configurar su extracción de métricas, ya que afecta a su uso de métricas personalizadas y a la factura correspondiente. Si crea métricas de forma involuntaria basadas en dimensiones de alta cardinalidad (como `requestId`), el formato de métricas integradas creará, por diseño, una métrica personalizada correspondiente a cada combinación de dimensiones única. Para obtener más información, consulte [Dimensiones](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension). ### Objeto MetricDefinition Una MetricDefinition es un objeto que DEBE contener el siguiente miembro: + **Nombre**: cadena [Valores de referencia](#CloudWatch_Embedded_Metric_Format_Specification_structure_referencevalues) a una métrica [Miembros de destino](#CloudWatch_Embedded_Metric_Format_Specification_structure_target). Los destinos de la métrica DEBEN ser un valor numérico o una matriz de valores numéricos. PUEDE QUE un objeto MetricDefinition contenga el siguiente elemento: + **Unidad**: valor de cadena OPCIONAL que representa la unidad de medida de la métrica correspondiente. Los valores DEBEN ser unidades métricas válidas de CloudWatch. Para obtener información acerca de las unidades válidas, consulte [MetricDatum](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html). Si no se proporciona un valor, el sistema presupone que se utiliza un valor predeterminado de NONE. + **StorageResolution**: valor entero OPCIONAL que representa la resolución de almacenamiento de la métrica correspondiente. Si se establece en 1, se especifica esta métrica como una métrica de alta resolución, de modo que CloudWatch almacena la métrica con una resolución inferior a un minuto hasta un segundo. Si se establece en 60, se especifica esta métrica como resolución estándar, que CloudWatch almacena con una resolución de 1 minuto. Los valores DEBEN ser válidos para las resoluciones compatibles con CloudWatch, 1 o 60. Si no se proporciona un valor, el sistema supone que se utiliza un valor predeterminado de 60. Para obtener más información acerca de las métricas de alta resolución, consulte [Métricas de alta resolución](publishingMetrics.md#high-resolution-metrics). **nota** Si planea crear alarmas a partir de métricas creadas con un formato de métrica integrado, consulte [Configurar alarmas en las métricas creadas con el formato de métrica integrado](CloudWatch_Embedded_Metric_Format_Alarms.md) para obtener recomendaciones. ``` { "_aws": { "CloudWatchMetrics": [ { "Metrics": [ { "Name": "Time", "Unit": "Milliseconds", "StorageResolution": 60 } ], ... } ] }, "Time": 1 } ``` ### Valores de referencia Los valores de referencia son valores de cadena que hacen referencia a los miembros [Miembros de destino](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) en el nodo raíz. Estas referencias NO deberían confundirse con los punteros JSON descritos en [RFC6901](https://tools.ietf.org/html/rfc6901). Los valores de destino no se pueden anidar. ### Miembros de destino Los destinos válidos DEBEN ser miembros en el nodo raíz y no pueden ser objetos anidados. Por ejemplo, un valor \$1reference\$1 de `"A.a"` DEBE coincidir con el siguiente miembro: ``` { "A.a" } ``` NO DEBE coincidir con el miembro anidado: ``` { "A": { "a" } } ``` Los valores válidos de los miembros de destino dependen de lo que los hace referencia. El destino de la métrica DEBE ser un valor numérico o una matriz de valores numéricos. Los destinos de la métrica de matriz numérica NO DEBEN tener más de 100 miembros. Un destino de dimensión DEBE tener un valor de cadena. ### Ejemplo de formato de métricas integradas y esquema JSON A continuación, se muestra un ejemplo válido de formato de métricas integradas. ``` { "_aws": { "Timestamp": 1574109732004, "CloudWatchMetrics": [ { "Namespace": "lambda-function-metrics", "Dimensions": [["functionVersion"]], "Metrics": [ { "Name": "time", "Unit": "Milliseconds", "StorageResolution": 60 } ] } ] }, "functionVersion": "$LATEST", "time": 100, "requestId": "989ffbf8-9ace-4817-a57c-e4dd734019ee" } ``` Puede utilizar el siguiente esquema para validar documentos con formato de métricas integradas. ``` { "type": "object", "title": "Root Node", "required": [ "_aws" ], "properties": { "_aws": { "$id": "#/properties/_aws", "type": "object", "title": "Metadata", "required": [ "Timestamp", "CloudWatchMetrics" ], "properties": { "Timestamp": { "$id": "#/properties/_aws/properties/Timestamp", "type": "integer", "title": "The Timestamp Schema", "examples": [ 1565375354953 ] }, "CloudWatchMetrics": { "$id": "#/properties/_aws/properties/CloudWatchMetrics", "type": "array", "title": "MetricDirectives", "items": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items", "type": "object", "title": "MetricDirective", "required": [ "Namespace", "Dimensions", "Metrics" ], "properties": { "Namespace": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Namespace", "type": "string", "title": "CloudWatch Metrics Namespace", "examples": [ "MyApp" ], "pattern": "^(.*)$", "minLength": 1, "maxLength": 1024 }, "Dimensions": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Dimensions", "type": "array", "title": "The Dimensions Schema", "minItems": 1, "items": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Dimensions/items", "type": "array", "title": "DimensionSet", "minItems": 0, "maxItems": 30, "items": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Dimensions/items/items", "type": "string", "title": "DimensionReference", "examples": [ "Operation" ], "pattern": "^(.*)$", "minLength": 1, "maxLength": 250 } } }, "Metrics": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics", "type": "array", "title": "MetricDefinitions", "items": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items", "type": "object", "title": "MetricDefinition", "required": [ "Name" ], "properties": { "Name": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items/properties/Name", "type": "string", "title": "MetricName", "examples": [ "ProcessingLatency" ], "pattern": "^(.*)$", "minLength": 1, "maxLength": 1024 }, "Unit": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items/properties/Unit", "type": "string", "title": "MetricUnit", "examples": [ "Milliseconds" ], "pattern": "^(Seconds|Microseconds|Milliseconds|Bytes|Kilobytes|Megabytes|Gigabytes|Terabytes|Bits|Kilobits|Megabits|Gigabits|Terabits|Percent|Count|Bytes\\/Second|Kilobytes\\/Second|Megabytes\\/Second|Gigabytes\\/Second|Terabytes\\/Second|Bits\\/Second|Kilobits\\/Second|Megabits\\/Second|Gigabits\\/Second|Terabits\\/Second|Count\\/Second|None)$" }, "StorageResolution": { "$id": "#/properties/_aws/properties/CloudWatchMetrics/items/properties/Metrics/items/properties/StorageResolution", "type": "integer", "title": "StorageResolution", "examples": [ 60 ] } } } } } } } } } } } ``` ## Información de la entidad en formato EMF Al publicar registros en Amazon CloudWatch con el formato de métricas integradas (EMF), puede incluir información de la entidad en el evento de registro. En esta sección se describe cómo especificar información de entidades y cómo CloudWatch procesa esta información. ### Tipos de entidad Cuando no se especifica una entidad con la solicitud `PutLogEvents`, CloudWatch buscará la información de la entidad en el contenido del registro de EMF: + **Entidades de tipo de servicio** Campos obligatorios: `Service` y `Environment` + **Entidades de tipo de recurso** Campos obligatorios: `ResourceType` y `Identifier` ### Atributos de la plataforma CloudWatch determina automáticamente el tipo de plataforma en función de estos atributos: + **Kubernetes (K8s):** Obligatorio: `K8s.Cluster` Opcional: `K8s.Namespace`, `K8s.Workload`, `K8s.Node`, `K8s.Pod`, `EC2.InstanceId`, `EC2.AutoScalingGroup` + **Amazon EKS** Obligatorio: `EKS.Cluster` Opcional: `K8s.Namespace`, `K8s.Workload`, `K8s.Node`, `K8s.Pod`, `EC2.InstanceId` + **Amazon ECS:** Obligatorio: `ECS.Cluster` Opcional: `ECS.Service`, `ECS.Task` + **Amazon EC2** Obligatorio: `EC2.InstanceId` Optional: `EC2.AutoScalingGroup` + **Lambda:** Obligatorio: `Lambda.Function` + **Hosts genéricos:** Obligatorio: `Host` ### Ejemplo de formato de registro EMF ``` { "_aws": { "CloudWatchMetrics": [ { "Metrics": [ {"Name": "RequestLatency", "Unit": "Milliseconds"} ], "Namespace": "MyApplication" } ] }, "Service": "PaymentService", "Environment": "Production", "K8s.Cluster": "main-cluster", "K8s.Namespace": "payment-ns", "K8s.Pod": "payment-pod-123", "K8s.Node": "worker-node-1", "K8s.Workload": "payment-deployment", "RequestLatency": 135.5, "timestamp": 1622163600000 } ``` ### Entidad generada El registro EMF anterior generará la siguiente entidad: ``` { "KeyAttributes": { "Type": "Service", "Name": "PaymentService", "Environment": "Production" }, "Attributes": { "PlatformType": "K8s", "K8s.Cluster": "main-cluster", "K8s.Namespace": "payment-ns", "K8s.Pod": "payment-pod-123", "K8s.Node": "worker-node-1", "K8s.Workload": "payment-deployment" } } ``` ### Procesamiento de entidad CloudWatch procesa la información de la entidad de la siguiente manera: + **Atributos clave:** + Determina el tipo de entidad en función de los campos obligatorios + Para el tipo de servicio, extrae el nombre del servicio y el entorno + Estos se convierten en los identificadores principales de la entidad + **Atributos:** + Establece PlatformType según los atributos de plataforma incluidos + Incluye toda la información relevante específica de la plataforma + Mantiene el contexto de relación para los datos de telemetría CloudWatch utiliza esta información de entidad para establecer relaciones entre distintos datos de telemetría, lo que permite mejorar la observabilidad y el análisis contextual de sus aplicaciones e infraestructura. Para obtener más información, consulte [Cómo agregar información relacionada a la telemetría personalizada que se envía a CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/adding-your-own-related-telemetry.html). **nota** La información de entidad ayuda a CloudWatch a crear una imagen completa de los datos de telemetría de su aplicación y sus relaciones dentro de la infraestructura. # Uso de la API PutLogEvents para enviar registros de formato de métricas integradas creados manualmente Puede enviar registros de formato de métricas integrados a Registros de CloudWatch mediante la API [PutLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html) de Registros de CloudWatch. Al llamar a PutLogEvents, tiene la opción de incluir el siguiente encabezado HTTP, que indica a Registros de CloudWatch las métricas que deberían extraerse, pero no es obligatorio. ``` x-amzn-logs-format: json/emf ``` A continuación, se muestra un ejemplo completo del uso de SDK para Java 2.x de AWS: ``` package org.example.basicapp; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.cloudwatchlogs.CloudWatchLogsClient; import software.amazon.awssdk.services.cloudwatchlogs.model.DescribeLogStreamsRequest; import software.amazon.awssdk.services.cloudwatchlogs.model.DescribeLogStreamsResponse; import software.amazon.awssdk.services.cloudwatchlogs.model.InputLogEvent; import software.amazon.awssdk.services.cloudwatchlogs.model.PutLogEventsRequest; import java.util.Collections; public class EmbeddedMetricsExample { public static void main(String[] args) { final String usage = "To run this example, supply a Region code (eg. us-east-1), log group, and stream name as command line arguments" + "Ex: PutLogEvents "; if (args.length != 3) { System.out.println(usage); System.exit(1); } String regionId = args[0]; String logGroupName = args[1]; String logStreamName = args[2]; CloudWatchLogsClient logsClient = CloudWatchLogsClient.builder().region(Region.of(regionId)).build(); // Build a JSON log using the EmbeddedMetricFormat. long timestamp = System.currentTimeMillis(); String message = "{" + " \"_aws\": {" + " \"Timestamp\": " + timestamp + "," + " \"CloudWatchMetrics\": [" + " {" + " \"Namespace\": \"MyApp\"," + " \"Dimensions\": [[\"Operation\"], [\"Operation\", \"Cell\"]]," + " \"Metrics\": [{ \"Name\": \"ProcessingLatency\", \"Unit\": \"Milliseconds\", \"StorageResolution\": 60 }]" + " }" + " ]" + " }," + " \"Operation\": \"Aggregator\"," + " \"Cell\": \"001\"," + " \"ProcessingLatency\": 100" + "}"; InputLogEvent inputLogEvent = InputLogEvent.builder() .message(message) .timestamp(timestamp) .build(); // Specify the request parameters. PutLogEventsRequest putLogEventsRequest = PutLogEventsRequest.builder() .logEvents(Collections.singletonList(inputLogEvent)) .logGroupName(logGroupName) .logStreamName(logStreamName) .build(); logsClient.putLogEvents(putLogEventsRequest); System.out.println("Successfully put CloudWatch log event"); } } ``` **nota** Con el formato de métrica incorporado, puede hacer un seguimiento del procesamiento de sus registros de EMF por métricas publicadas en el espacio de nombres de `AWS/Logs` de su cuenta. Se pueden utilizar para hacer un seguimiento de la generación con errores de métricas a partir de EMF, así como para determinar si se producen errores debido al análisis o la validación. Para obtener más información, consulte [Supervisión con métricas de CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html). # Uso del agente de CloudWatch para enviar registros de formato de métricas integradas En esta sección se describe cómo instalar y utilizar el agente de CloudWatch. En la primera parte de esta sección se describe cómo instalar el agente de CloudWatch. En la segunda parte de esta sección se describe cómo utilizar el agente de CloudWatch para enviar registros con formato de métricas incrustadas. Si desea utilizar este método, debe instalar el agente de CloudWatch para los Servicios de AWS desde los que desea enviar registros con formato de métricas incrustadas. A continuación, puede empezar a enviar los eventos. La versión del agente de CloudWatch debe ser 1.230621.0 o una posterior. **nota** No es necesario que se instale el agente de CloudWatch para enviar registros desde las funciones de Lambda. Los tiempos de espera de las funciones Lambda no se administran automáticamente. Esto significa que si el tiempo de espera de su función se agota antes de que las métricas se vacíen, las métricas de esa invocación no se capturarán. ## Instalación del agente de CloudWatch Instale el agente de CloudWatch para cada servicio que deba enviar registros con formato de métricas integradas. ### Instalación del agente de CloudWatch en EC2 Primero, instale el agente de CloudWatch en la instancia. Para obtener más información, consulte [Instalación del agente de CloudWatch](install-CloudWatch-Agent-on-EC2-Instance.md). Una vez que haya instalado el agente, configúrelo para que escuche un puerto UDP o TCP para los registros de formato de métricas integradas. A continuación, se muestra un ejemplo de esta configuración que escucha el socket predeterminado `tcp:25888`. Para obtener más información acerca de la configuración del agente, consulte [Cree o edite de forma manual el archivo de configuración del agente de CloudWatch](CloudWatch-Agent-Configuration-File-Details.md). ``` { "logs": { "metrics_collected": { "emf": { } } } } ``` ### Instalación del agente de CloudWatch en Amazon ECS La manera más fácil de implementar el agente de CloudWatch en Amazon ECS es ejecutarlo como sidecar al definirlo en la misma definición de tarea que su aplicación. **Creación de un archivo de configuración del agente** Cree el archivo de configuración del agente de CloudWatch localmente. En este ejemplo, la ruta relativa del archivo será `amazon-cloudwatch-agent.json`. Para obtener más información acerca de la configuración del agente, consulte [Cree o edite de forma manual el archivo de configuración del agente de CloudWatch](CloudWatch-Agent-Configuration-File-Details.md). ``` { "logs": { "metrics_collected": { "emf": { } } } } ``` **Envío de la configuración al almacén de parámetros SSM ** Escriba el siguiente comando para publicar el archivo de configuración del agente de CloudWatch al almacén de parámetros de AWS Systems Manager (SSM). ``` aws ssm put-parameter \ --name "cwagentconfig" \ --type "String" \ --value "`cat amazon-cloudwatch-agent.json`" \ --region "{{region}}" ``` **Configuración de la definición de la tarea** Configure la definición de tarea para utilizar el agente de CloudWatch y exponer el puerto TCP o UDP. La definición de tarea de ejemplo que debe utilizar depende del modo de red. Observe que `webapp` especifica la variable de entorno `AWS_EMF_AGENT_ENDPOINT`. La biblioteca la utiliza y debe apuntar al punto de enlace que escucha el agente. Además, el `cwagent` especifica el `CW_CONFIG_CONTENT` como parámetro “valueFrom” que apunta a la configuración de SSM que creó en el paso anterior. Esta sección contiene un ejemplo para el modo puente y un ejemplo para el modo host o awsvpc. Para obtener más ejemplos de cómo se puede configurar el agente de CloudWatch en Amazon ECS, consulte el [Github samples repository](https://github.com/aws-samples/amazon-cloudwatch-container-insights/tree/master/ecs-task-definition-templates/deployment-mode/sidecar) (Repositorio de muestras de Github) A continuación, se muestra un ejemplo del modo puente. Cuando se habilitan redes en modo puente, el agente debe enlazarse con la aplicación mediante el parámetro `links` y debe hacerse referencia al mismo con el nombre del contenedor. ``` { "containerDefinitions": [ { "name": "webapp", "links": [ "cwagent" ], "image": "my-org/web-app:latest", "memory": 256, "cpu": 256, "environment": [{ "name": "AWS_EMF_AGENT_ENDPOINT", "value": "tcp://cwagent:25888" }], }, { "name": "cwagent", "mountPoints": [], "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest", "memory": 256, "cpu": 256, "portMappings": [{ "protocol": "tcp", "containerPort": 25888 }], "environment": [{ "name": "CW_CONFIG_CONTENT", "valueFrom": "cwagentconfig" }], } ], } ``` A continuación, se muestra un ejemplo del modo de host o el modo awsvpc. Al ejecutarse en estos modos de red, se puede hacer referencia al agente a través de `localhost`. ``` { "containerDefinitions": [ { "name": "webapp", "image": "my-org/web-app:latest", "memory": 256, "cpu": 256, "environment": [{ "name": "AWS_EMF_AGENT_ENDPOINT", "value": "tcp://127.0.0.1:25888" }], }, { "name": "cwagent", "mountPoints": [], "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest", "memory": 256, "cpu": 256, "portMappings": [{ "protocol": "tcp", "containerPort": 25888 }], "environment": [{ "name": "CW_CONFIG_CONTENT", "valueFrom": "cwagentconfig" }], } ], } ``` **nota** En el modo awsvpc, debe proporcionar una dirección IP pública a la VPC (solo para Fargate), configurar una gateway NAT o configurar un punto de enlace de la VPC de CloudWatch Logs. Para obtener más información acerca de cómo configurar una NAT, consulte [Gateways NAT](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html). Para obtener más información acerca de cómo se configura un punto de enlace de la VPC de CloudWatch Logs, consulte [Using CloudWatch Logs with Interface VPC Endpoints](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/cloudwatch-logs-and-interface-VPC.html) (Uso de CloudWatch Logs con los puntos de enlace de la VPC de tipo interfaz). A continuación, se muestra un ejemplo de cómo asignar una dirección IP pública a una tarea que utiliza el tipo de lanzamiento de Fargate. ``` aws ecs run-task \ --cluster {{cluster-name}} \ --task-definition cwagent-fargate \ --region {{region}} \ --launch-type FARGATE \ --network-configuration "awsvpcConfiguration={subnets=[{{subnetId}}],securityGroups=[{{sgId}}],assignPublicIp=ENABLED}" ``` **Seguro de permisos** Asegúrese de que el rol de IAM que ejecuta las tareas tiene permiso para leer datos del almacén de parámetros SSM. Puede añadir este permiso asociando la política **AmazonSSMReadOnlyAccess**. Para ello, introduzca el siguiente comando. ``` aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess \ --role-name CWAgentECSExecutionRole ``` ### Instalación del agente de CloudWatch en Amazon EKS Algunas partes de este proceso se pueden omitir si ya ha instalado CloudWatch Container Insights en este clúster. Permisos Si aún no ha instalado Container Insights, asegúrese primero de que los nodos de Amazon EKS tienen los permisos de IAM adecuados. Deben tener la **CloudWatchAgentServerPolicy** asociada. Para obtener más información, consulte [Verificación de los requisitos previos de Información de contenedores en CloudWatch](Container-Insights-prerequisites.md). **Creación de ConfigMap** Cree un ConfigMap para el agente. El ConfigMap también indica al agente que escuche un puerto TCP o UDP. Utilice el siguiente ConfigMap. ``` # cwagent-emf-configmap.yaml apiVersion: v1 data: # Any changes here must not break the JSON format cwagentconfig.json: | { "agent": { "omit_hostname": true }, "logs": { "metrics_collected": { "emf": { } } } } kind: ConfigMap metadata: name: cwagentemfconfig namespace: default ``` Si ya ha instalado Container Insights, añada la siguiente línea `"emf": { }` a su ConfigMap existente. **Aplicación del ConfigMap** Escriba el siguiente comando para aplicar el ConfigMap. ``` kubectl apply -f cwagent-emf-configmap.yaml ``` **Implementación del agente** Para implementar el agente de CloudWatch como un sidecar, agregue el agente a la definición del pod, como en el ejemplo siguiente. ``` apiVersion: v1 kind: Pod metadata: name: myapp namespace: default spec: containers: # Your container definitions go here - name: web-app image: my-org/web-app:latest # CloudWatch Agent configuration - name: cloudwatch-agent image: public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest imagePullPolicy: Always resources: limits: cpu: 200m memory: 100Mi requests: cpu: 200m memory: 100Mi volumeMounts: - name: cwagentconfig mountPath: /etc/cwagentconfig ports: # this should match the port configured in the ConfigMap - protocol: TCP hostPort: 25888 containerPort: 25888 volumes: - name: cwagentconfig configMap: name: cwagentemfconfig ``` ## Uso del agente de CloudWatch para enviar registros de formato de métricas integradas Una vez que el agente de CloudWatch esté instalado y en ejecución, podrá enviar los registros con formato de métricas integradas a través de TCP o UDP. Hay dos requisitos al enviar los registros a través del agente: + Los registros deben contener una `LogGroupName` clave que indique al agente qué grupo de registros utilizar. + Cada evento de registro debe estar en una sola línea. En otras palabras, un evento de registro no puede contener el carácter de nueva línea (\$1n). Los eventos de registro también deben seguir la especificación de formato de métricas integradas. Para obtener más información, consulte [Especificación: Formato de métricas integradas](CloudWatch_Embedded_Metric_Format_Specification.md). Si planea crear alarmas a partir de métricas creadas con un formato de métrica integrado, consulte [Configurar alarmas en las métricas creadas con el formato de métrica integrado](CloudWatch_Embedded_Metric_Format_Alarms.md) para obtener recomendaciones. A continuación, se muestra un ejemplo de envío manual de eventos de registro desde un shell Bash de Linux. En su lugar, puede utilizar las interfaces de socket UDP proporcionadas por el lenguaje de programación que elija. ``` echo '{"_aws":{"Timestamp":1574109732004,"LogGroupName":"Foo","CloudWatchMetrics":[{"Namespace":"MyApp","Dimensions":[["Operation"]],"Metrics":[{"Name":"ProcessingLatency","Unit":"Milliseconds","StorageResolution":60}]}]},"Operation":"Aggregator","ProcessingLatency":100}' \ > /dev/udp/0.0.0.0/25888 ``` **nota** Con el formato de métrica incorporado, puede hacer un seguimiento del procesamiento de sus registros de EMF por métricas publicadas en el espacio de nombres de `AWS/Logs` de su cuenta. Se pueden utilizar para hacer un seguimiento de la generación con errores de métricas a partir de EMF, así como para determinar si se producen errores debido al análisis o la validación. Para obtener más información, consulte [Supervisión con métricas de CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html). # Uso del formato de métricas integradas con Distro para OpenTelemetry de AWS. OpenTelemetry es una iniciativa de código abierto que elimina los límites y restricciones entre los formatos específicos del proveedor para el seguimiento, los registros y las métricas al ofrecer un único conjunto de especificaciones y de las API. Para obtener más información, consulte [OpenTelemetry](https://opentelemetry.io/). Puede utilizar el formato de métricas integradas como parte del proyecto OpenTelemetry. El uso del formato de métricas incrustadas con OpenTelemetry requiere dos componentes: un origen de datos compatible con OpenTelemetry y el recopilador de Distro para OpenTelemetry de AWS habilitado para su uso con registros de formato de métricas incrustadas de CloudWatch. Tenemos redistribuciones preconfiguradas de los componentes de OpenTelemetry, que AWS mantiene, para que la incorporación sea lo más fácil posible. Para obtener más información sobre el uso de OpenTelemetry con formato de métricas incrustadas, además de otros servicios de AWS, consulte [AWS Distro para OpenTelemetry](https://aws-otel.github.io/). Para obtener información adicional sobre la compatibilidad y el uso de idiomas, consulte [Observabilidad de AWS en Github](https://github.com/aws-observability). # Visualización de sus métricas y registros en la consola Después de generar registros con formato de métricas integradas que extraen métricas, puede utilizar la consola de CloudWatch para ver las métricas. Las métricas integradas tienen las dimensiones que especificó al generar los registros. Además, las métricas integradas que generó con las bibliotecas del cliente tienen las siguientes dimensiones predeterminadas: + ServiceType + ServiceName + LogGroup En esta sección se describe cómo ver estas métricas en la consola de CloudWatch y cómo consultar las métricas extraídas mediante [Información de registros de CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html). **Para ver las métricas generadas a partir de los registros de formato de métricas integradas** 1. Abra la consola de CloudWatch en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. En el panel de navegación, seleccione **Métricas**. 1. Seleccione un espacio de nombres que especificó para las métricas integradas cuando las generó. Si utilizó las bibliotecas de cliente para generar las métricas y no especificó un espacio de nombres, seleccione **aws-embedded-metrics**. Este es el espacio de nombres predeterminado de las métricas integradas generadas mediante las bibliotecas de cliente. 1. Seleccione una dimensión de métrica (por ejemplo, **ServiceName**). 1. La pestaña **All metrics** muestra todas las métricas para dicha dimensión en el espacio de nombres. Se puede hacer lo siguiente: 1. Para ordenar la tabla, utilice el encabezado de columna. 1. Para representar gráficamente una métrica, active la casilla de verificación situada junto a ella. Para seleccionar todas las métricas, seleccione la casilla de verificación en la fila de encabezado de la tabla. 1. Para filtrar por recurso, seleccione el ID de recurso y, a continuación, elija **Add to search (Añadir a la búsqueda)**. 1. Para filtrar por métrica, elija el nombre de la métrica y, a continuación, seleccione **Add to search (Añadir a búsqueda)**. **Consulta de registros que utilizan CloudWatch Logs Insights** Puede consultar los eventos de registro detallados que están asociados a las métricas extraídas mediante CloudWatch Logs Insights para ofrecer información detallada acerca de las causas raíz de los eventos operativos. Una de las ventajas de extraer métricas de los registros es que puede filtrar estos más adelante por la métrica única (nombre de métrica más conjunto de dimensiones único) y los valores de métrica, para obtener el contexto de los eventos que contribuyeron al valor de métrica agregado Por ejemplo, para obtener un ID de rastro de X-Ray o un ID de solicitud integrada, podría ejecutar la siguiente consulta en CloudWatch Logs Insights. ``` filter Latency > 1000 and Operation = "Aggregator" | fields RequestId, TraceId ``` También puede realizar la agregación en tiempo de consulta en claves de alta cardinalidad, como la búsqueda de los clientes afectados por un evento. En el siguiente ejemplo, se ilustra este caso. ``` filter Latency > 1000 and Operation = "Aggregator" | stats count() by CustomerId ``` Para obtener más información, consulte [Analizar datos de registro con CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html) # Configurar alarmas en las métricas creadas con el formato de métrica integrado En general, la creación de alarmas en las métricas generadas mediante el formato de métricas incrustadas sigue el mismo patrón que la creación de alarmas en cualquier otra métrica. Para obtener más información, consulte [Uso de las alarmas de Amazon CloudWatch](CloudWatch_Alarms.md). La generación de métricas en formato de métricas incrustadas depende del flujo de publicación de registros, ya que Registros de CloudWatch debe procesar los registros para transformarlos en métricas. Es importante que publique los registros de manera oportuna para que los puntos de datos de las métricas se creen dentro del periodo de tiempo en el que se evalúan las alarmas. Si planea usar el formato de métrica incrustadas para enviar métricas de alta resolución y crear alarmas en estas métricas, le recomendamos que vacíe los registros en Registros de CloudWatch en un intervalo de 5 segundos o menos para evitar ingresar una demora adicional que pueda provocar alarmas en datos parciales o faltantes. Si utiliza el agente de CloudWatch, puede ajustar el intervalo de descarga configurando el parámetro `force_flush_interval` en el archivo de configuración del agente de CloudWatch. Este valor se establece de forma predeterminada en 5 segundos. Si utiliza Lambda en otras plataformas en las que no puede controlar el intervalo de vaciado de registros, considere la posibilidad de utilizar alarmas “M de N” para controlar la cantidad de puntos de datos que se utilizan para emitir la alarma. Para obtener más información, consulte [Evaluación de alarmas](alarm-evaluation.md).