Spécifications : format de métrique intégrée

Le format de métrique intégrée CloudWatch est une spécification JSON utilisée pour demander à CloudWatch Logs d'extraire automatiquement les valeurs de métrique intégrée dans des événements de journal structurés. Vous pouvez utiliser CloudWatch pour tracer et créer des alertes sur les valeurs de métrique 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é.

Conventions de spécification de format de métrique intégrée

Les mots-clés « DOIT », « NE DOIT PAS », « OBLIGATOIRE », « DEVRAIT », « NE DEVRAIT PAS », « RECOMMANDÉ », « PEUT » et « FACULTATIF » dans cette spécification de format doivent être interprétés tels que décrits dans Mots-clés RFC2119.

Les termes « JSON », « texte JSON », « valeur JSON », « membre », « élément », « objet », « tableau », « nombre », « chaîne », « booléen », « true », « false » et « null » dans cette spécification de format doivent être interprétés tels que définis dans Notation d'objet JavaScript RFC8259.

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 de format de métrique intégrée sont définis dans Notation d'objet JavaScript 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ée 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 Surveillance à l'aide des métriques CloudWatch.

Nœud racine

Le message LogEvent DOIT être un objet JSON valide sans données supplémentaires au début ou à la fin de la chaîne de message LogEvent. Pour de plus amples informations sur la structure LogEvent, veuillez consulter 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 Objet 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 membre _aws peut être utilisé pour représenter les métadonnées relatives à la charge utile qui informe les services en aval de la façon dont ils doivent traiter le LogEvent. La valeur DOIT être un objet et DOIT contenir les membres suivants :

Objet MetricDirective

L'objet MetricDirective indique aux services en aval que LogEvent contient des métriques qui seront extraites et publiées dans CloudWatch. MetricDirectives DOIT contenir les membres suivants :

Tableau DimensionSet

Un tableau 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

Un objet DimensionSet NE DOIT PAS contenir plus de 30 clés de dimension. Un tableau 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 utilisé 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"
}

Objet MetricDefinition

Un objet MetricDefinition DOIT contenir le membre suivant :

Un objet MetricDefinition PEUT contenir les membres suivants :

{
  "_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. 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 dans Amazon CloudWatch à l’aide du format de métriques intégré (EMF), 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 traite ces informations.

Types d’entités

Lorsqu’aucune entité n’est spécifiée avec la demande PutLogEvents, CloudWatch recherche les informations d’entité dans le contenu du journal EMF :

Attributs de plateforme

CloudWatch détermine automatiquement le type de plate-forme en fonction des attributs suivants :

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 d’entité comme suit :

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 une observabilité et une analyse contextuelle améliorées de vos applications et de votre infrastructure. Pour plus d’informations, consultez Comment ajouter des informations connexes à la télémétrie personnalisée envoyée à CloudWatch.