# 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.