Specifica: Embedded Metric Format - Amazon CloudWatch
ConvenzioniStruttura del documento in Embedded Metric FormatInformazioni sulle entità in formato EMF

Specifica: Embedded Metric Format

CloudWatch Embedded Metric Format è una specifica JSON utilizzata per indicare a CloudWatch Logs di estrarre automaticamente i valori dei parametri incorporati in eventi di log strutturati. Puoi utilizzare CloudWatch per disegnare grafici e creare allarmi sui valori dei parametri estratti. Questa sezione descrive le convenzioni relative alle specifiche di Embedded Metric Format e la struttura del documento in Embedded Metric Format.

Convenzioni specifiche di Embedded Metric Format

Le parole chiave “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY” e “OPTIONAL” in questa specifica di formato devono essere interpretate come descritto in Key Words RFC2119.

I termini "JSON", "JSON text", "JSON value", "member", "element", "object", "array", "number", "string", "boolean", "true", "false" e "null" in questa specifica di formato devono essere interpretati come definito in JavaScript Object Notation RFC8259.

Nota

Se prevedi di creare allarmi su parametri creati utilizzando il formato dei parametri incorporati, consulta Impostazione degli allarmi sui parametri creati con il formato dei parametri incorporati per ottenere dei suggerimenti.

Struttura del documento in Embedded Metric Format

In questa sezione viene descritta la struttura di un documento in formato del parametro integrato. I documenti in Embedded Metric Format sono definiti in JavaScript Object Notation RFC8259.

Salvo ove diversamente specificato, gli oggetti definiti da questa specifica NON DEVONO contenere alcun membro aggiuntivo. I membri non riconosciuti da questa specifica DEVONO essere ignorati. I membri definiti in questa specifica rispettano la distinzione tra maiuscole e minuscole.

Embedded Metric Format è soggetto agli stessi limiti degli eventi CloudWatch Logs standard ed è limitato a una dimensione massima di 1 MB.

Con la specifica Embedded Metric Format, puoi tenere traccia dell'elaborazione dei registri EMF in base ai parametri pubblicati nello spazio dei nomi AWS/Logs del tuo account. Questi possono essere utilizzati per tenere traccia della generazione di parametri con esito negativo per EMF e per verificare se gli errori sono dovuti all'analisi o alla convalida. Per ulteriori informazioni, consulta la pagina Monitoraggio dell'utilizzo con i parametri di CloudWatch.

Nodo radice

Il messaggio LogEvent DEVE essere un oggetto JSON valido senza dati aggiuntivi all'inizio o alla fine della stringa di messaggio LogEvent. Per ulteriori informazioni sulla struttura LogEvent, consulta InputLogEvent.

I documenti in Embedded Metric Format DEVONO contenere il seguente membro di primo livello sul nodo principale. Questo è un oggetto Oggetto metadati. 

{
 "_aws": {
    "CloudWatchMetrics": [ ... ]
  }
}

Il nodo principale DEVE contenere tutti i membri Membri di destinazione definiti dai riferimenti nel Oggetto MetricDirective.

Il nodo principale PUÒ contenere tutti gli altri membri che non sono inclusi nei requisiti precedenti. I valori di questi membri DEVONO essere tipi JSON validi.

Oggetto metadati

Il membro _aws può essere utilizzato per rappresentare i metadati relativi al payload che indica ai servizi downstream come devono elaborare il LogEvent. Il valore DEVE essere un oggetto e DEVE contenere i seguenti membri:

  • CloudWatchMetrics: una matrice di Oggetto MetricDirective usata per indicare a CloudWatchMetrics di estrarre i parametri dal nodo principale del LogEvent.

    {
  "_aws": {
    "CloudWatchMetrics": [ ... ]
  }
}

  • Time stamp Un numero che rappresenta la marca temporale usata per i parametri estratti dall'evento. I valori DEVONO essere espressi come il numero di millisecondi dopo il 1 gennaio 1970 00:00:00 UTC.

    {
  "_aws": {
    "Timestamp": 1559748430481
  }
}

Oggetto MetricDirective

L'oggetto MetricDirective indica ai servizi downstream che il LogEvent contiene parametri che verranno estratti e pubblicati in CloudWatch. I MetricDirective DEVONO contenere i seguenti membri:

  • Spazio dei nomi Una stringa che rappresenta lo spazio dei nomi CloudWatch per il parametro.

  • Dimensioni Un Matrice DimensionSet.

  • Parametri Una matrice di oggetti MetricDefinition. Questa matrice NON DEVE contenere più di 100 oggetti MetricDefinition.

Matrice DimensionSet

DimensionSet è una matrice di stringhe contenenti le chiavi di dimensione che verranno applicate a tutti i parametri nel documento. I valori all'interno di questa matrice DEVONO anche essere membri del nodo principale, definiti come Membri di destinazione

Una DimensionSet NON DEVE contenere più di 30 chiavi di dimensione. Un DimensionSet PUÒ essere vuoto.

Il membro di destinazione DEVE avere un valore stringa. Questo valore NON DEVE contenere più di 1024 caratteri. Il membro di destinazione definisce una dimensione che verrà pubblicata nell'identità del parametro. Ogni DimensionSet utilizzatO crea un nuovo parametro in CloudWatch. Per ulteriori informazioni sulle dimensioni, consulta Dimensione e Dimensioni.

{
 "_aws": {
   "CloudWatchMetrics": [
     {
       "Dimensions": [ [ "functionVersion" ] ],
       ...
     }
   ]
 },
 "functionVersion": "$LATEST"
}
Nota

Fai attenzione durante la configurazione dell'estrazione dei parametri poiché influenza l'utilizzo di parametri personalizzati e l'addebito corrispondente. Se crei involontariamente delle metriche basate su dimensioni ad alta cardinalità (ad esempio requestId), Embedded Metric Format creerà per impostazione predefinita una metrica personalizzata corrispondente a ogni combinazione di dimensione univoca. Per ulteriori informazioni, consulta Dimensioni.

Oggetto MetricDefinition

Un MetricDefinition è un oggetto che DEVE contenere il seguente membro:

Un oggetto MetricDefinition PUÒ contenere i seguenti membri:

  • Unità Un valore stringa OPZIONALE che rappresenta l'unità di misura per il parametro corrispondente. I valori DEVONO essere unità dei parametri CloudWatch. Per informazioni sulle unità valide, consulta MetricDatum. Se non viene fornito un valore, viene assunto il valore predefinito NONE.

  • StorageResolution: un valore intero OPZIONALE che rappresenta la risoluzione di archiviazione per il parametro corrispondente. L'impostazione su 1 specifica questo parametro come parametro ad alta risoluzione pertanto CloudWatch memorizza il parametro con una risoluzione inferiore al minuto a un secondo. L'impostazione su 60 specifica questo parametro come risoluzione standard, che CloudWatch memorizza con una risoluzione di 1 minuto. I valori DEVONO essere risoluzioni valide supportate da CloudWatch, 1 o 60. Se non viene fornito un valore, viene assunto il valore predefinito 60.

    Per ulteriori informazioni sui parametri ad alta risoluzione, consulta Parametri ad alta risoluzione.

Nota

Se prevedi di creare allarmi su parametri creati utilizzando il formato dei parametri incorporati, consulta Impostazione degli allarmi sui parametri creati con il formato dei parametri incorporati per ottenere dei suggerimenti.

{
  "_aws": {
    "CloudWatchMetrics": [
      {
        "Metrics": [
          {
            "Name": "Time",
            "Unit": "Milliseconds",
            "StorageResolution": 60
          }
        ],
        ...
      }
    ]
  },
  "Time": 1
}

Valori di riferimento

I valori di riferimento sono valori stringa che fanno riferimento ai membri Membri di destinazione del nodo principale. Questi riferimenti NON devono essere confusi con i puntatori JSON descritti in RFC6901. I valori di destinazione non possono essere nidificati.

Membri di destinazione

Destinazioni valide DEVONO essere membri del nodo principale e non possono essere oggetti nidificati. Ad esempio, a _reference_ value di "A.a" DEVE corrispondere al seguente membro:

{ "A.a" }

NON DEVE corrispondere al membro nidificato:

{ "A": { "a" } }

I valori validi dei membri di destinazione dipendono da ciò che vi fa riferimento. Una destinazione parametro DEVE essere un valore numerico o una matrice di valori numerici. Le destinazioni di parametro di matrice numerica NON DEVONO avere più di 100 membri. Una destinazione di dimensione DEVE avere un valore stringa.

Esempio di Embedded Metric Format e schema JSON

Di seguito è riportato un esempio valido di Embedded Metric Format.

{
  "_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"
}

Puoi utilizzare lo schema seguente per convalidare i documenti in Embedded Metric Format.

{
    "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
                                            ]
                                         }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Informazioni sulle entità in formato EMF

Quando pubblichi log su Amazon CloudWatch utilizzando Embedded Metric Format (EMF), puoi includere informazioni sull'entità nell'evento del log. Questa sezione descrive come specificare le informazioni sulle entità e come CloudWatch elabora queste informazioni.

Tipi di entità

Quando nella richiesta PutLogEvents non viene specificata alcuna entità, CloudWatch cerca le informazioni sull'entità nel contenuto del log EMF:

  • Entità di tipo servizio

    Campi obbligatori: Service e Environment

  • Entità di tipo risorsa

    Campi obbligatori: ResourceType e Identifier

Attributi della piattaforma

CloudWatch determina automaticamente il tipo di piattaforma in base a questi attributi:

  • Kubernetes (K8s):

    Obbligatorio: K8s.Cluster

    Facoltativo: K8s.Namespace, K8s.Workload, K8s.Node, K8s.Pod, EC2.InstanceId, EC2.AutoScalingGroup

  • Amazon EKS

    Obbligatorio: EKS.Cluster

    Facoltativo: K8s.Namespace, K8s.Workload, K8s.Node, K8s.Pod, EC2.InstanceId

  • Amazon ECS:

    Obbligatorio: ECS.Cluster

    Facoltativo: ECS.Service, ECS.Task

  • Amazon EC2

    Obbligatorio: EC2.InstanceId

    Facoltativo: EC2.AutoScalingGroup

  • Lambda:

    Obbligatorio: Lambda.Function

  • Host generici:

    Obbligatorio: Host

Formato di log EMF di esempio

{
    "_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à generata

Il log EMF sopra riportato genererà la seguente entità:

{
    "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"
    }
}

Elaborazione dell'entità

CloudWatch elabora le informazioni sull'entità come segue:

  • KeyAttributes:

    • Determina il tipo di entità in base ai campi obbligatori

    • Per Service-type, estrae il nome del servizio e l'ambiente

    • Questi diventano gli identificativi principali dell'entità

  • Attributi:

    • Imposta PlatformType in base agli attributi della piattaforma inclusi

    • Include tutte le informazioni pertinenti specifiche della piattaforma

    • Mantiene il contesto relazionale per i dati di telemetria

CloudWatch utilizza queste informazioni sull'entità per stabilire relazioni tra diversi dati di telemetria, migliorando l'osservabilità e l'analisi contestuale delle applicazioni e dell'infrastruttura. Per ulteriori informazioni, consulta How to add related information to custom telemetry sent to CloudWatch.

Nota

Le informazioni sulle entità aiutano CloudWatch a creare un quadro completo dei dati di telemetria dell'applicazione e delle relative relazioni all'interno dell'infrastruttura.