Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Spécifications : format de métrique intégrée Le format métrique CloudWatch intégré est une spécification JSON utilisée pour demander aux CloudWatch journaux d'extraire automatiquement les valeurs métriques intégrées dans les événements de journal structurés. Vous pouvez l'utiliser CloudWatch pour représenter graphiquement et créer des alarmes sur les valeurs métriques extraites. Cette section décrit les conventions de spécification du format de métriques intégré et la structure du document au format de métriques intégré. **Note** Le format de métrique intégré garantit la livraison au moins une fois des métriques extraites des événements du journal, tandis que des valeurs de métriques dupliquées peuvent parfois apparaître. ## Conventions de spécification de format de métrique intégrée Les mots clés « DOIT », « NE DOIT PAS », « OBLIGATOIRE », « NE DOIT PAS », « DEVRAIT », « NE DEVRAIT PAS », « RECOMMANDÉ », « PEUT » et « FACULTATIF » dans cette spécification de format doivent être interprétés comme décrit dans les mots [ clés ](http://tools.ietf.org/html/rfc2119) RFC2119. Les termes « JSON », « texte JSON », « valeur JSON », « membre », « élément », « objet », « tableau », « nombre », « chaîne », « booléen », « vrai », « faux » et « nul » dans cette spécification de format doivent être interprétés comme défini dans la notation d'[JavaScript objet RFC8259. ](https://tools.ietf.org/html/rfc8259) **Note** Si vous prévoyez de créer des alertes sur des métriques créées à l'aide du format de métrique intégrée, consultez les recommandations de la rubrique [Configuration d'alertes sur les métriques créées avec le format de métrique intégrée](CloudWatch_Embedded_Metric_Format_Alarms.md). ## Structure du document au format de métrique intégrée Cette section décrit la structure d'un document au format de métrique intégrée. Les documents au format métrique intégré sont définis dans la notation [ JavaScript d'objet RFC8259](https://tools.ietf.org/html/rfc8259). Sauf indication contraire, les objets définis par la présente spécification NE DOIVENT PAS contenir de membres supplémentaires. Les membres non reconnus par cette spécification DOIVENT être ignorés. Les membres définis dans cette spécification sont sensibles à la casse. Le format de métrique intégré est soumis aux mêmes limites que les événements CloudWatch Logs standard et est limité à une taille maximale de 1 Mo. Avec le format de métrique intégré, vous pouvez suivre le traitement de vos journaux EMF par des métriques qui sont publiées dans l'espace de nom `AWS/Logs` de votre compte. Celles-ci peuvent être utilisées pour suivre les échecs de génération de métriques à partir d'EMF, ainsi que pour savoir si les échecs sont dus à l'analyse ou à la validation. Pour plus de détails, consultez la section [ Surveillance à l'aide de CloudWatch métriques](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html). ### Nœud racine Le LogEvent message DOIT être un objet JSON valide sans aucune donnée supplémentaire au début ou à la fin de la chaîne de LogEvent message. Pour plus d'informations sur la LogEvent structure, consultez [ InputLogEvent](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_InputLogEvent.html). Les documents au format de métrique intégrée DOIVENT contenir le membre de niveau supérieur suivant sur le nœud racine. Il s'agit d'un objet [Objet Métadonnées](#CloudWatch_Embedded_Metric_Format_Specification_structure_metadata). ``` { "_aws": { "CloudWatchMetrics": [ ... ] } } ``` Le nœud racine DOIT contenir tous les membres [Membres cibles](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) définis par les références dans le [MetricDirective objet](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdirective). Le nœud racine peut contenir tous les autres membres qui ne sont pas inclus dans les exigences ci-dessus. Les valeurs de ces membres DOIVENT être des types JSON valides. ### Objet Métadonnées Le `_aws` membre peut être utilisé pour représenter des métadonnées relatives à la charge utile qui indiquent aux services en aval comment ils doivent traiter le LogEvent. La valeur DOIT être un objet et DOIT contenir les membres suivants : + **CloudWatchMetrics**— Tableau [MetricDirective objet](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdirective) utilisé pour demander d'extraire CloudWatch des métriques à partir du nœud racine du LogEvent. ``` { "_aws": { "CloudWatchMetrics": [ ... ] } } ``` + **Timestamp (Horodatage)** — Nombre représentant l'horodatage utilisé pour les métriques extraites de l'événement. Les valeurs DOIVENT être exprimées en tant que nombre de millisecondes après le 1er janv. 1970 00:00:00 UTC. ``` { "_aws": { "Timestamp": 1559748430481 } } ``` ### MetricDirective objet L' MetricDirective objet indique aux services en aval qu'ils LogEvent contiennent des métriques qui seront extraites et publiées. CloudWatch MetricDirectives DOIT contenir les membres suivants : + **Namespace ** — Chaîne représentant l'espace de CloudWatch noms de la métrique. + **Dimensions** — [DimensionSet tableau](#CloudWatch_Embedded_Metric_Format_Specification_structure_dimensionset). + **Metrics (Métriques)** — Tableau d'objets [MetricDefinition objet](#CloudWatch_Embedded_Metric_Format_Specification_structure_metricdefinition). Ce tableau NE DOIT PAS contenir plus de 100 MetricDefinition objets. ### DimensionSet tableau A DimensionSet est un tableau de chaînes contenant les clés de dimension qui seront appliquées à toutes les mesures du document. Les valeurs de ce tableau DOIVENT également être des membres sur le nœud racine (appelé ) [Membres cibles](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) A NE DimensionSet DOIT PAS contenir plus de 30 clés de dimension. A DimensionSet PEUT être vide. Le membre cible DOIT avoir une valeur de chaîne. Cette valeur NE DOIT PAS contenir plus de 1024 caractères. Le membre cible définit une dimension qui sera publiée dans le cadre de l'identité de métrique. Chaque DimensionSet utilisation crée une nouvelle métrique dans CloudWatch. Pour obtenir de plus amples informations sur les dimensions, veuillez consulter [Dimension](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_Dimension.html) et [Dimensions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension). ``` { "_aws": { "CloudWatchMetrics": [ { "Dimensions": [ [ "functionVersion" ] ], ... } ] }, "functionVersion": "$LATEST" } ``` **Note** Soyez prudent lorsque vous configurez votre extraction de métriques car cela affecte votre utilisation de métriques personnalisées et la facture correspondante. Si vous créez involontairement des métriques basées sur des dimensions à cardinalité élevée (telles que `requestId`), le format de métrique intégrée créera par définition une métrique personnalisée correspondant à chaque combinaison de dimensions unique. Pour de plus amples informations, veuillez consulter [Dimensions](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Dimension). ### MetricDefinition objet A MetricDefinition est un objet qui DOIT contenir le membre suivant : + **Name (Nom)** —Chaîne [Valeurs de référence](#CloudWatch_Embedded_Metric_Format_Specification_structure_referencevalues) vers une métrique [Membres cibles](#CloudWatch_Embedded_Metric_Format_Specification_structure_target). Les cibles des métriques DOIVENT être une valeur numérique ou un tableau de valeurs numériques. Un MetricDefinition objet PEUT contenir les membres suivants : + **Unit (Unitéà** — Valeur de chaîne FACULTATIVE représentant l'unité de mesure pour la métrique correspondante. Les valeurs DEVRAIENT être des unités CloudWatch métriques valides. Pour plus d'informations sur les unités valides, consultez [ MetricDatum](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html). Si aucune valeur n'est fournie, la valeur par défaut NONE est supposée. + **StorageResolution**— Valeur entière FACULTATIVE représentant la résolution de stockage pour la métrique correspondante. Si cette valeur est définie sur 1, cette métrique est définie comme une métrique haute résolution, de sorte que la métrique CloudWatch est stockée avec une résolution inférieure à une minute inférieure à une seconde. Si cette valeur est définie sur 60, cette métrique est définie comme une résolution standard, qui est stockée à une résolution CloudWatch d'une minute. Les valeurs DEVRAIENT être des résolutions CloudWatch prises en charge valides, 1 ou 60. Si aucune valeur n'est fournie, la valeur par défaut 60 est choisie. Pour plus d'informations sur les métriques haute résolution, consultez [High-resolution métriques](publishingMetrics.md#high-resolution-metrics). **Note** Si vous prévoyez de créer des alertes sur des métriques créées à l'aide du format de métrique intégrée, consultez les recommandations de la rubrique [Configuration d'alertes sur les métriques créées avec le format de métrique intégrée](CloudWatch_Embedded_Metric_Format_Alarms.md). ``` { "_aws": { "CloudWatchMetrics": [ { "Metrics": [ { "Name": "Time", "Unit": "Milliseconds", "StorageResolution": 60 } ], ... } ] }, "Time": 1 } ``` ### Valeurs de référence Les valeurs de référence sont des valeurs de chaîne qui font référence aux membres [Membres cibles](#CloudWatch_Embedded_Metric_Format_Specification_structure_target) sur le nœud racine. Ces références ne doivent PAS être confondues avec les pointeurs JSON décrits dans [RFC6901](https://tools.ietf.org/html/rfc6901). Les valeurs cibles ne peuvent pas être imbriquées. ### Membres cibles Les cibles valides DOIVENT être des membres sur le nœud racine et ne peuvent pas être des objets imbriqués. Par exemple, une valeur \_reference\_ de `"A.a"` DOIT correspondre au membre suivant : ``` { "A.a" } ``` Elle NE DOIT PAS correspondre au membre imbriqué : ``` { "A": { "a" } } ``` Les valeurs valides des membres cibles dépendent de ce qui les référence. Une cible de métrique DOIT être une valeur numérique ou un tableau de valeurs numériques. Les cibles de métriques de tableau numérique NE DOIVENT PAS avoir plus de 100 membres. Une cible de dimension DOIT avoir une valeur de chaîne. ### Exemple de format de métrique intégrée et schéma JSON Voici un exemple valide de format de métrique intégré. ``` { "_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" } ``` Vous pouvez utiliser le schéma suivant pour valider les documents au format de métrique intégré. ``` { "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 ] } } } } } } } } } } } ``` ## Informations sur les entités au format EMF Lorsque vous publiez des journaux sur Amazon à CloudWatch l'aide du format EMF (Embedded Metric Format), vous pouvez inclure des informations sur les entités dans l'événement de journal. Cette section explique comment spécifier les informations sur les entités et comment CloudWatch traiter ces informations. ### Types d’entités Lorsqu'aucune entité n'est spécifiée avec la `PutLogEvents` demande, CloudWatch recherche des informations sur l'entité dans le contenu du journal EMF : + **Service-type entités ** Champs obligatoires : `Service` et `Environment` + **Resource-type entités ** Champs obligatoires : `ResourceType` et `Identifier` ### Attributs de plateforme CloudWatch détermine automatiquement le type de plateforme en fonction de ces attributs : + **Kubernetes (K8s) :** Obligatoire : `K8s.Cluster` Facultatif : `K8s.Namespace`, `K8s.Workload`, `K8s.Node`, `K8s.Pod`, `EC2.InstanceId`, `EC2.AutoScalingGroup` + **Amazon EKS** Obligatoire : `EKS.Cluster` Facultatif : `K8s.Namespace``K8s.Workload`,`K8s.Node`,`K8s.Pod`, `EC2.InstanceId` + **Amazon ECS :** Obligatoire : `ECS.Cluster` Facultatif :`ECS.Service`, `ECS.Task` + **Amazon EC2** Obligatoire : `EC2.InstanceId` Facultatif : `EC2.AutoScalingGroup` + **Lambda :** Obligatoire : `Lambda.Function` + **Hôtes génériques :** Obligatoire : `Host` ### Exemple de format de journal 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 } ``` ### Entité générée Le journal EMF ci-dessus générera l’entité suivante : ``` { "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" } } ``` ### Traitement des entités CloudWatch traite les informations relatives à l'entité comme suit : + **KeyAttributes:** + Détermine le type d’entité en fonction des champs obligatoires + Pour Service-type, extrait le nom du service et l'environnement + Ceux-ci deviennent les identifiants principaux de l’entité + **Attributs** : + Ensembles PlatformType basés sur les attributs de plate-forme inclus + Inclut toutes les informations pertinentes spécifiques à la plateforme + Conserve le contexte relationnel pour les données de télémétrie CloudWatch utilise ces informations d'entité pour établir des relations entre différents éléments de données de télémétrie, ce qui permet d'améliorer l'observabilité et l'analyse contextuelle de vos applications et de votre infrastructure. Pour plus d'informations, consultez [ Comment ajouter des informations associées à la télémétrie personnalisée envoyée à. CloudWatch ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/adding-your-own-related-telemetry.html) **Note** Les informations sur les entités permettent de CloudWatch créer une image complète des données télémétriques de votre application et de leurs relations au sein de votre infrastructure.