Spezifikation: Eingebettetes Metrikformat

Das eingebettete CloudWatch-Metrikformat ist eine JSON-Spezifikation, die CloudWatch Logs anweist, Metrikwerte, die in strukturierte Protokollereignisse eingebettet sind, automatisch zu extrahieren. Sie können CloudWatch zum grafischen Darstellen und Erstellen von Alarmen für die extrahierten Metrikwerte verwenden. In diesem Abschnitt werden die Konventionen für die Spezifikation des eingebetteten Metrikformats und die Dokumentstruktur des eingebetteten Metrikformats beschrieben.

Konventionen der Spezifikationen für eingebettete Metrikformate

Die Schlüsselwörter „MUSS“, „DARF NICHT“, „NOTWENDIG“, „SOLL“, „SOLL NICHT“, „SOLLTE“, „SOLLTE NICHT“, „EMPFOHLEN“, „KANN“ und „OPTIONAL“ in dieser Formatspezifikation sind wie in den Key Words RFC2119 beschrieben zu interpretieren.

Die Begriffe „JSON“, „JSON text“, „JSON value“, „member“, „element“, „object“, „array“, „number“, „string“, „boolean“, „true“, „false“ und „null“ in dieser Formatspezifikation sind wie in der JavaScript Object Notation RFC8259 definiert zu interpretieren.

Eingebettetes Metrikformat-Dokumentstruktur

Dieser Abschnitt beschreibt die Struktur eines Dokuments im eingebetteten Metrikformat. Dokumente im eingebetteten Metrikformat werden in der JavaScript Object Notation RFC8259 definiert.

Sofern nicht anders angegeben, DÜRFEN in dieser Spezifikation definierte Objekte KEINE zusätzlichen Elemente enthalten. Elemente, die von dieser Spezifikation nicht erkannt werden, MÜSSEN ignoriert werden. In dieser Spezifikation definierte Elemente berücksichtigen Groß- und Kleinschreibung.

Das eingebettete Metrikformat unterliegt denselben Beschränkungen wie CloudWatch-Logs-Standardereignisse und ist auf eine maximale Größe von 1 MB beschränkt.

Mit dem eingebetteten Metrikformat können Sie die Verarbeitung Ihrer EMF-Protokolle nach Metriken verfolgen, die im AWS/Logs-Namespace Ihres Kontos veröffentlicht werden. Diese können verwendet werden, um die fehlgeschlagene Metrikgenerierung von EMF nachzuverfolgen und festzustellen, ob Fehler aufgrund der Analyse oder der Validierung auftreten. Weitere Informationen finden Sie unter Überwachen mit CloudWatch-Metriken.

Stammknoten

Die LogEvent-Nachricht MUSS ein gültiges JSON-Objekt ohne zusätzliche Daten am Anfang oder Ende der LogEvent-Nachrichtenzeichenfolge sein. Weitere Informationen zur LogEvent-Struktur finden Sie unter InputLogEvent.

Dokumente im eingebetteten Metrikformat MÜSSEN das folgende Element der obersten Ebene auf dem Stammknoten enthalten. Dies ist ein Metadatenobjekt-Objekt.

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

Der Stammknoten MUSS alle Zielmitglieder-Elemente enthalten, die durch die Verweise in MetricDirective-Objekt definiert sind.

Der Stammknoten KANN alle anderen Elemente enthalten, die nicht in den oben genannten Anforderungen enthalten sind. Die Werte dieser Elemente MÜSSEN gültige JSON-Typen sein.

Metadatenobjekt

Das _aws-Element kann verwendet werden, um Metadaten über die Nutzlast darzustellen, die nachgeschaltete Services darüber informiert, wie sie das LogEvent verarbeiten sollen. Der Wert MUSS ein Objekt sein und MUSS die folgenden Elemente enthalten:

MetricDirective-Objekt

Das MetricDirective-Objekt setzt nachgeschaltete Services darüber in Kenntnis, dass das LogEvent Metriken enthält, die extrahiert und in CloudWatch veröffentlicht werden. MetricDirectives MÜSSEN die folgenden Elemente enthalten:

DimensionSet-Array

Ein DimensionSet ist ein Array von Zeichenfolgen, die die Dimensionsschlüssel enthalten, die auf alle Metriken im Dokument angewendet werden. Die Werte innerhalb dieses Arrays MÜSSEN auch Elemente auf dem Stammknoten sein, die als das Zielmitglieder bezeichnet werden.

Ein DimensionSet DARF NICHT mehr als 30 Dimensionsschlüssel enthalten. Ein DimensionSet kann leer sein.

Das Zielelement MUSS einen Zeichenfolgenwert haben. Dieser Wert DARF NICHT mehr als 1024 Zeichen enthalten. Das Zielelement definiert eine Dimension, die als Teil der Metrikidentität veröffentlicht wird. Jedes verwendete DimensionSet erstellt eine neue Metrik in CloudWatch. Weitere Informationen zu Dimensionen finden Sie unter Dimension und Dimensionen.

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

MetricDefinition-Objekt

Eine MetricDefinition ist ein Objekt, das das folgende Element enthalten MUSS:

Ein MetricDefinition-Objekt KANN die folgenden Elemente enthalten:

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

Referenzwerte

Referenzwerte sind Zeichenfolgenwerte, die Zielmitglieder-Elemente auf dem Stammknoten referenzieren. Diese Referenzen sollten NICHT mit den in RFC6901 beschriebenen JSON Pointers verwechselt werden. Zielwerte können nicht verschachtelt werden.

Zielmitglieder

Gültige Ziele MÜSSEN Elemente auf dem Stammknoten sein und dürfen keine verschachtelten Objekte sein. Ein _reference_-Wert von "A.a" MUSS beispielsweise mit dem folgenden Element übereinstimmen:

{ "A.a" }

Er DARF NICHT mit dem verschachtelten Element übereinstimmen:

{ "A": { "a" } }

Gültige Werte von Zielelementen hängen davon ab, was sie referenziert. Ein Metrikziel MUSS ein numerischer Wert oder ein Array numerischer Werte sein. Numerische Array-Metrikziele DÜRFEN NICHT mehr als 100 Mitglieder haben. Ein Dimensionsziel MUSS einen Zeichenfolgenwert haben.

Beispiel für ein eingebettetes Metrikformat und JSON-Schema

Im Folgenden finden Sie ein gültiges Beispiel für ein eingebettetes Metrikformat.

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

Sie können das folgende Schema verwenden, um Dokumente im eingebetteten Metrikformat zu validieren.

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

Entity-Informationen im EMF-Format

Wenn Sie Protokolle mithilfe des Embedded Metric Formats (EMF) in Amazon CloudWatch veröffentlichen, können Sie Entitätsinformationen in das Protokollereignis aufnehmen. In diesem Abschnitt wird beschrieben, wie Entity-Informationen angegeben werden und wie CloudWatch diese Informationen verarbeitet.

Entity-Typen

Wenn in der PutLogEvents-Anfrage keine Entity angegeben ist, sucht CloudWatch im EMF-Protokollinhalt nach Entity-Informationen:

Plattformsattribute

CloudWatch bestimmt den Plattformtyp automatisch auf der Grundlage dieser Attribute:

Beispiel-EMF-Protokollformat

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

Generierte Entity

Das obige EMF-Protokoll generiert die folgende Entity:

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

Entity-Verarbeitung

CloudWatch verarbeitet die Entity-Informationen folgendermaßen:

CloudWatch nutzt diese Entity-Informationen, um Beziehungen zwischen verschiedenen Telemetriedaten herzustellen und so eine verbesserte Beobachtbarkeit und Kontextanalyse Ihrer Anwendungen und Infrastruktur zu ermöglichen. Weitere Informationen finden Sie unter Hinzufügen verwandter Informationen zu benutzerdefinierter, an CloudWatch gesendeter Telemetrie.