Kesepakatan Struktur dokumen format metrik tersemat Informasi entitas dalam format EMF

Spesifikasi: Format metrik tersemat

Format metrik CloudWatch tertanam adalah spesifikasi JSON yang digunakan untuk menginstruksikan CloudWatch Log untuk secara otomatis mengekstrak nilai metrik yang disematkan dalam peristiwa log terstruktur. Anda dapat menggunakan CloudWatch untuk membuat grafik dan membuat alarm pada nilai metrik yang diekstraksi. Bagian ini menjelaskan konvensi spesifikasi format metrik tertanam dan struktur dokumen format metrik tertanam.

catatan

Format metrik tertanam memastikan setidaknya satu kali pengiriman metrik yang diekstrak dari peristiwa log, sementara nilai metrik duplikat kadang-kadang dapat terjadi.

Kesepakatan spesifikasi format metrik tersemat

Kata kunci “HARUS”, “TIDAK HARUS”, “DIPERLUKAN”, “HARUS”, “TIDAK AKAN”, “HARUS”, “SEHARUSNYA TIDAK”, “DIREKOMENDASI”, “MUNGKIN”, dan “OPSIONAL” dalam spesifikasi format ini harus ditafsirkan seperti yang dijelaskan dalam Kata K unci RFC 2119.

Istilah “JSON”, “teks JSON”, “nilai JSON”, “anggota”, “elemen”, “objek”, “susunan”, “nomor”, “rangkaian”, “boolean”, “benar”, “palsu”, dan “noll” dalam spesifikasi format ini akan ditafsirkan sebagaimana ditentukan dalam JavaScript Notasi Objek RFC8259.

catatan

Jika Anda berencana untuk membuat alarm-alarm pada metrik yang telah dibuat dengan menggunakan format metrik tersemat, silakan lihat Menyetel alarm pada metrik-metrik yang dibuat dengan format metrik tersemat untuk rekomendasinya.

Struktur dokumen format metrik tersemat

Bagian ini akan menjelaskan struktur dokumen format metrik tersemat. Dokumen format metrik tertanam didefinisikan dalam JavaScript Object Notation RFC8259.

Kecuali jika dinyatakan lain, objek-objek yang ditentukan oleh spesifikasi ini TIDAK BOLEH memuat anggota-anggota tambahan. Anggota yang tidak dikenali oleh spesifikasi ini HARUS diabaikan. Anggota yang ditentukan dalam spesifikasi ini bersifat peka terhadap huruf besar dan kecil.

Format metrik yang disematkan tunduk pada batas yang sama dengan peristiwa CloudWatch Logs standar dan dibatasi hingga ukuran maksimum 1 MB.

Dengan format metrik tersemat, Anda dapat melacak pemrosesan log EMF berdasarkan metrik yang diterbitkan di ruang nama AWS/Logs akun Anda. Hal ini dapat digunakan untuk melacak pembuatan metrik yang gagal dari EMF, serta apakah kegagalan terjadi diakibatkan oleh penguraian atau validasi. Untuk detail selengkapnya, lihat Pemantauan dengan CloudWatch metrik.

Simpul akar

LogEvent Pesan HARUS berupa objek JSON yang valid tanpa data tambahan di awal atau akhir string LogEvent pesan. Untuk informasi lebih lanjut tentang LogEvent struktur, lihat InputLogEvent.

Dokumen format metrik tersemat HARUS memuat anggota tingkat atas berikut pada simpul akar. Ini adalah sebuah objek Objek metadata.


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

Simpul akar HARUS memuat semua anggota Anggota target yang ditentukan oleh referensi yang ada di MetricDirective objek.

Simpul akar tersebut MUNGKIN memuat anggota-anggota lain yang tidak termasuk dalam persyaratan di atas. Nilai-nilai dari anggota-anggota ini HARUS merupakan jenis JSON yang benar.

Objek metadata

Ang _aws gota dapat digunakan untuk mewakili metadata tentang muatan yang menginformasikan layanan hilir bagaimana mereka harus memproses LogEvent. Nilai tersebut HARUS menjadi objek dan HARUS berisi anggota-anggota berikut:

CloudWatchMetrics— Array yang MetricDirective objek digunakan untuk menginstruksikan CloudWatch untuk mengekstrak metrik dari node root. LogEvent
```
{
  "_aws": {
    "CloudWatchMetrics": [ ... ]
  }
}
```
Timestamp— Angka yang mewakili stempel waktu yang digunakan untuk metrik yang diekstrak dari peristiwa. Nilai HARUS dinyatakan sebagai angka milidetik setelah 1 Jan 1970 00:00:00 UTC.
```
{
  "_aws": {
    "Timestamp": 1559748430481
  }
}
```

MetricDirective objek

Ob MetricDirective jek menginstruksikan layanan hilir yang LogEvent berisi metrik yang akan diekstraksi dan dipublikasikan. CloudWatch MetricDirectives HARUS berisi anggota berikut:

Namespace — Sebuah string yang mewakili CloudWatch namespace untuk metrik.
Dimensi— Sebuah DimensionSet susunan.
Metrik— Susunan objek MetricDefinition. Array ini TIDAK BOLEH berisi lebih dari 100 MetricDefinition objek.

DimensionSet susunan

A DimensionSet adalah array string yang berisi kunci dimensi yang akan diterapkan ke semua metrik dalam dokumen. Nilai-nilai dalam susunan ini HARUS juga menjadi anggota di simpul-akar—disebut sebagai Anggota target

A TIDAK DimensionSet HARUS berisi lebih dari 30 kunci dimensi. A DimensionSet mungkin kosong.

Anggota target HARUS memiliki sebuah nilai string. Nilai-nilai ini TIDAK BOLEH memuat lebih dari 1024 karakter. Anggota target menentukan sebuah dimensi yang akan diterbitkan sebagai bagian dari identitas metrik. Setiap yang DimensionSet digunakan membuat metrik baru di CloudWatch. Untuk informasi selengkapnya tentang dimensi, silakan lihat Dimensi dan Dimensi-dimensi.


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

catatan

Anda perlu berhati-hati ketika mengonfigurasi ekstraksi metrik Anda karena hal ini akan berdampak pada penggunaan metrik kustom dan penagihannya. Jika Anda secara tidak sengaja membuat metrik-metrik yang didasarkan pada dimensi yang memiliki kardinalitas tinggi (seperti requestId), maka format metrik tersemat akan berdasarkan desain membuat sebuah metrik kustom yang sesuai dengan masing-masing kombinasi dimensi yang unik. Untuk informasi selengkapnya, silakan lihat Dimensi.

MetricDefinition objek

A MetricDefinition adalah objek yang HARUS berisi anggota berikut:

Nama— Sebuah string Nilai referensi ke sebuah metrik Anggota target. Target metrik HARUS berupa sebuah nilai numerik atau susunan nilai-nilai numerik.

Sebuah MetricDefinition objek DAPAT berisi anggota berikut:

Unit— Sebuah nilai string OPSIONAL yang mewakili satuan pengukuran untuk metrik yang sesuai. Nilai HARUS berupa satuan CloudWatch metrik yang valid. Untuk informasi tentang unit yang valid, lihat MetricDatum. Jika sebuah nilai tidak disediakan, maka nilai bawaan diasumsikan sebagai TIDAK ADA.
StorageResolution— Nilai integer OPTIONAL yang mewakili resolusi penyimpanan untuk metrik yang sesuai. Menyetel ini ke 1 menentukan metrik ini sebagai metrik resolusi tinggi, sehingga CloudWatch menyimpan metrik dengan resolusi sub-menit hingga satu detik. Menyetel ini ke 60 menentukan metrik ini sebagai resolusi standar, yang disimpan pada CloudWatch resolusi 1 menit. Nilai HARUS menjadi resolusi yang CloudWatch didukung yang valid, 1 atau 60. Jika sebuah nilai tidak disediakan, maka nilai bawaan diasumsikan 60.

Untuk informasi selengkapnya tentang metrik resolusi tinggi, silakan lihat High-resolution metrik.

catatan


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

Nilai referensi

Nilai-nilai referensi adalah nilai string yang mereferensikan anggota-anggota Anggota target pada simpul akar. Referensi-referensi ini TIDAK boleh disalahartikan dengan JSON Pointers yang dijelaskan dalam RFC6901. Nilai target tidak dapat disarangkan.

Anggota target

Target yang benar HARUS merupakan anggota pada simpul akar dan tidak dapat menjadi objek yang disarangkan. Sebagai contoh, suatu _reference_value "A.a" HARUS yang cocok dengan anggota-anggota berikut ini:


{ "A.a" }

TIDAK BOLEH cocok dengan anggota yang disarangkan:


{ "A": { "a" } }

Nilai yang benar dari anggota-anggota target bergantung pada hal yang mereferensikan mereka. Sebuah target metrik HARUS berupa sebuah nilai numerik atau susunan nilai-nilai numerik. Target metrik susunan numerik TIDAK BOLEH memiliki lebih dari 100 anggota. Sebuah target dimensi HARUS memiliki sebuah nilai string.

Contoh format metrik tersemat dan skema JSON

Berikut ini adalah sebuah contoh format metrik tersemat yang benar.


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

Anda dapat menggunakan skema berikut untuk melakukan validasi terhadap dokumen format metrik tersemat.


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

Informasi entitas dalam format EMF

Saat Anda menerbitkan log ke Amazon CloudWatch menggunakan Embedded Metric Format (EMF), Anda dapat menyertakan informasi entitas dalam peristiwa log. Bagian ini menjelaskan cara menentukan informasi entitas dan bagaimana mem CloudWatch proses informasi ini.

Jenis entitas

Ketika tidak ada Entitas yang ditentukan dengan PutLogEvents permintaan, CloudWatch akan mencari informasi entitas dalam konten log EMF:

Service-type entitas

Bidang yang wajib diisi: Service dan Environment
Resource-type entitas

Bidang yang wajib diisi: ResourceType dan Identifier

Atribut platform

CloudWatch secara otomatis menentukan jenis platform berdasarkan atribut ini:

Kubernetes (K8s):

Wajib: K8s.Cluster

Opsional: K8s.NamespaceK8s.Workload,K8s.Node,K8s.Pod,EC2.InstanceId, EC2.AutoScalingGroup
Amazon EX

Wajib: EKS.Cluster

Opsional:K8s.Namespace,K8s.Workload,K8s.Node,K8s.Pod, EC2.InstanceId
Amazon ECS:

Wajib: ECS.Cluster

Opsional:ECS.Service, ECS.Task
Amazon EC2

Wajib: EC2.InstanceId

Opsional: EC2.AutoScalingGroup
Lambda:

Wajib: Lambda.Function
Host generik:

Wajib: Host

Contoh format log 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
}

Entitas yang Dibuat

Log EMF di atas akan menghasilkan Entitas berikut:


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

Pemrosesan entitas

CloudWatch memproses informasi entitas sebagai berikut:

KeyAttributes:
- Menentukan jenis entitas berdasarkan bidang yang diperlukan
- Untuk Service-type, ekstrak nama Layanan dan Lingkungan
- Ini menjadi pengidentifikasi utama untuk entitas
Atribut:
- Set PlatformType berdasarkan atribut platform yang disertakan
- Termasuk semua informasi spesifik platform yang relevan
- Mempertahankan konteks hubungan untuk data telemetri

CloudWatch menggunakan informasi entitas ini untuk membangun hubungan antara berbagai bagian data telemetri, memungkinkan peningkatan pengamatan dan analisis kontekstual aplikasi dan infrastruktur Anda. Untuk informasi selengkapnya, lihat Cara menambahkan informasi terkait ke telemetri khusus yang dikirim ke CloudWatch.

catatan

Informasi entitas membantu CloudWatch membuat gambaran lengkap data telemetri aplikasi Anda dan hubungannya dalam infrastruktur Anda.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Menggunakan pustaka klien

Menggunakan PutLogEvents API untuk mengirim log format metrik tertanam yang dibuat secara manual