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 de métrique CloudWatch intégré est une spécification JSON utilisée pour demander à CloudWatch Logs d'extraire automatiquement les valeurs métriques intégrées dans les événements de journaux 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 métrique intégré et la structure du document du format métrique intégré.
Conventions de spécification de format de métrique intégrée
Les mots clés « DOIT », « NE DOIT PAS », « OBLIGATOIRE », « DOIT », « NE DOIT PAS », « DEVRAIT », « NE PAS », « RECOMMANDÉ », « PEUT » et « FACULTATIF » dans cette spécification de format doivent être interprétés comme décrit dans Mots clés 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 tels que définis dans JavaScript Object
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.
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 JavaScript Object Notation 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 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, voir Surveillance à l'aide de CloudWatch métriques.
Nœud racine
Le LogEvent message DOIT être un objet JSON valide sans données supplémentaires au début ou à la fin de la chaîne de LogEvent message. Pour plus d'informations sur la LogEvent structure, consultez InputLogEvent.
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.
{ "_aws": { "CloudWatchMetrics": [ ... ] } }
Le nœud racine DOIT contenir tous les membres Membres cibles définis par les références dans le MetricDirective objet.
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 les 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— Un tableau de données MetricDirective objet utilisé pour indiquer CloudWatch d'extraire les métriques 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 réseau.
Metrics (Métriques) — Tableau d'objets MetricDefinition. Ce tableau NE DOIT PAS contenir plus de 100 MetricDefinition objets.
DimensionSet réseau
A DimensionSet est un tableau de chaînes contenant les clés de dimension qui seront appliquées à toutes les métriques du document. Les valeurs de ce tableau DOIVENT également être des membres sur le nœud racine (appelé ) Membres cibles
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 utilisateur crée une nouvelle métrique dans CloudWatch. Pour obtenir de plus amples informations sur les dimensions, veuillez consulter Dimension et Dimensions.
{ "_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.
MetricDefinition objet
A MetricDefinition est un objet qui DOIT contenir le membre suivant :
Name (Nom) —Chaîne Valeurs de référence vers une métrique Membres cibles . 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. Si aucune valeur n'est fournie, la valeur par défaut NONE est supposée.
StorageResolution— Une 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 une métrique haute résolution, de sorte que la métrique est CloudWatch stockée avec une résolution inférieure à la minute inférieure à une seconde. Si vous définissez cette valeur sur 60, cette métrique est une résolution standard, qui est CloudWatch stockée à une résolution d'une minute. Les valeurs DEVRAIENT être des résolutions valides CloudWatch prises en charge, 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 Métriques haute résolution.
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.
{ "_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 sur le nœud racine. Ces références ne doivent PAS être confondues avec les pointeurs JSON décrits dans RFC6901
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 l'entité 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 du journal. Cette section décrit comment spécifier les informations d'entité et comment CloudWatch traiter ces informations.
Types d'entités
Lorsqu'aucune entité n'est spécifiée dans la PutLogEvents demande, les informations relatives à l'entité CloudWatch seront recherchées dans le contenu du journal EMF :
-
Entités de type service
Champs obligatoires :
ServiceetEnvironment -
Entités de type ressource
Champs obligatoires :
ResourceTypeetIdentifier
Attributs de plateforme
CloudWatch détermine automatiquement le type de plateforme en fonction de ces attributs :
-
Kubernetes (K8s) :
Nécessaire :
K8s.ClusterFacultatif :
K8s.NamespaceK8s.Workload,K8s.Node,K8s.Pod,EC2.InstanceId,EC2.AutoScalingGroup -
Amazon EKS
Nécessaire :
EKS.ClusterFacultatif :
K8s.NamespaceK8s.Workload,K8s.Node,K8s.Pod,EC2.InstanceId -
Amazon ECS :
Nécessaire :
ECS.ClusterFacultatif :
ECS.Service,ECS.Task -
Amazon EC2
Nécessaire :
EC2.InstanceIdFacultatif :
EC2.AutoScalingGroup -
Lambda :
Nécessaire :
Lambda.Function -
Hôtes génériques :
Nécessaire :
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 de l'entité comme suit :
-
KeyAttributes:
Détermine le type d'entité en fonction des champs obligatoires
Pour le type de service, extrait le nom du service et l'environnement
Ils deviennent les principaux identifiants de l'entité
-
Attributs :
Ensembles PlatformType basés sur les attributs de plate-forme inclus
Inclut toutes les informations pertinentes spécifiques à la plateforme
Maintient 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, permettant ainsi une meilleure observabilité et une 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
Note
Les informations sur les entités permettent de CloudWatch créer une image complète des données de télémétrie de votre application et de leurs relations au sein de votre infrastructure.
