Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Kueri PromQL
Saat Anda memasukkan OpenTelemetry metrik ke dalam CloudWatch via[Titik akhir metrik](CloudWatch-OTLPEndpoint.md#CloudWatch-MetricsEndpoint), model data OTLP hierarkis diratakan menjadi label. PromQL-compatible Bagian ini menjelaskan struktur label, sintaks promQL untuk menanyakan label ini, dan dukungan di PromQL. UTF-8
**catatan**
PromQL di Prometheus 3 mendukung karakter lengkap dalam nama metrik dan nama label. UTF-8 Ini sangat penting untuk metrik OTLP, karena konvensi OpenTelemetry semantik menggunakan titik dalam nama atribut seperti. `service.name` Sebelumnya, titik-titik ini diganti dengan garis bawah selama penerjemahan, menyebabkan perbedaan antara apa yang didefinisikan dalam konvensi OTel dan apa yang dapat ditanyakan di Prometheus.
Saat menggunakan PromQL in CloudWatch, konvensi `@` awalan membedakan label OTLP-scoped dari label Prometheus standar. Bidang dalam setiap lingkup menggunakan `@` awalan ganda (misalnya,`@resource.@schema_url`), sementara atribut menggunakan awalan `@` lingkup tunggal, misalnya,. `@resource.service.name` Atribut titik data juga mendukung akses kosong (tidak diawali) untuk kompatibilitas mundur dengan kueri promQL standar, misalnya, dan setara. `{"http.server.active_requests"}` `{"@datapoint.@name"="http.server.active_requests"}`
Ekspresi promQL terlampir dalam kurawal kurawal, menentukan nama metrik dan satu set opsional pencocokan label. Contoh berikut memilih semua deret waktu untuk `http.server.active_requests` metrik:
```
{"http.server.active_requests"}
```
Contoh berikut memilih semua deret waktu untuk metrik di `http.server.active_requests` mana atribut OpenTelemetry sumber daya `service.name` sama`myservice`:
```
{"http.server.active_requests", "@resource.service.name"="myservice"}
```
Anda dapat menggabungkan beberapa pencocokan label dalam satu kueri. Contoh berikut memilih semua deret waktu untuk `http.server.active_requests` metrik di mana atribut OpenTelemetry resource `service.name` sama `myservice` di semua wilayah AS:
```
{"http.server.active_requests",
"@resource.service.name"="myservice",
"@aws.region"=~"us-.*"}
```
Contoh berikut menunjukkan kueri rentang. Ini menghitung nilai rata-rata semua titik data dalam rentang waktu tertentu untuk setiap deret waktu:
```
avg_over_time(
{"http.server.active_requests",
"@resource.service.name"="myservice"}[5m]
)
```
Tabel berikut merangkum konvensi awalan untuk setiap lingkup OTLP:
| Ruang lingkup OTLP | Awalan bidang | Atribut awalan | Contoh |
| --- | --- | --- | --- |
| Sumber daya | `@resource.@` | `@resource.` | `@resource.service.name="myservice"` |
| Lingkup Instrumentasi | `@instrumentation.@` | `@instrumentation.` | `@instrumentation.@name="otel-go/metrics"` |
| Titik data | `@datapoint.@` | `@datapoint.`atau telanjang | `cpu="cpu0"` atau `@datapoint.cpu="cpu0"` |
| AWS-dipesan | N/A | `@aws.` | `@aws.account_id="123456789"` |
## Pertanyaan terjual AWS metrik dengan PromQL
Untuk dapat menanyakan AWS metrik yang dijual di PromQL, Anda harus terlebih dahulu mengaktifkan pengayaan OTel dari metrik yang dijual. Lihat:[AWS metrik yang dijual dalam format OpenTelemetry](CloudWatch-OTelEnrichment.md).
Setelah Anda mengaktifkan pengayaan OTel, AWS metrik vended menjadi dapat ditanyakan melalui PromQL dengan label tambahan. Nama metrik sama dengan nama CloudWatch metrik asli, dan CloudWatch dimensi asli tersedia sebagai atribut titik data. Label berikut tersedia (contoh di bawah ini adalah untuk instance EC2):
| Label PromQL | Deskripsi | Contoh |
| --- | --- | --- |
| `InstanceId` | CloudWatch Dimensi asli, sebagai atribut titik data | `i-0123456789abcdef0` |
| `"@resource.cloud.resource_id"` | ARN penuh sumber daya | `arn:aws:ec2:us-east-1:123456789012:instance/i-0123456789abcdef0` |
| `"@resource.cloud.provider"` | Penyedia cloud | `aws` |
| `"@resource.cloud.region"` | AWS Wilayah tempat metrik ini berasal | `us-east-1` |
| `"@resource.cloud.account.id"` | AWS ID akun tempat metrik ini berasal | `123456789012` |
| `"@instrumentation.@name"` | Nama lingkup instrumentasi mengidentifikasi layanan sumber | `cloudwatch.aws/ec2` |
| `"@instrumentation.cloudwatch.source"` | Pengidentifikasi layanan sumber | `aws.ec2` |
| `"@instrumentation.cloudwatch.solution"` | Pengidentifikasi solusi pengayaan | `CloudWatchOTelEnrichment` |
| `"@aws.tag.Environment"` | AWS tag sumber daya | `production` |
| `"@aws.account"` | AWS akun tempat metrik ini dicerna (label sistem) | `123456789012` |
| `"@aws.region"` | AWS Wilayah tempat metrik ini dicerna (label sistem) | `us-east-1` |
Contoh berikut memilih `Invocations` untuk fungsi Lambda tertentu:
```
{Invocations, FunctionName="my-api-handler"}
```
Contoh berikut memilih `Errors` Lambda untuk semua fungsi yang ditandai dengan tim tertentu:
```
{Errors, "@instrumentation.@name"="cloudwatch.aws/lambda", "@aws.tag.Team"="backend"}
```
Contoh berikut menghitung total `Invocations` Lambda yang dikelompokkan berdasarkan tim:
```
sum by ("@aws.tag.Team")(
{Invocations, "@instrumentation.@name"="cloudwatch.aws/lambda"}
)
```
Contoh berikut memilih semua deret waktu untuk metrik EC2`CPUUtilization`. Penggunaan `"@instrumentation.@name"="cloudwatch.aws/ec2"` is untuk secara eksklusif mencocokkan CPUUutilization dari EC2 dan bukan dari AWS layanan lain seperti Amazon Relational Database Service:
```
histogram_avg({CPUUtilization, "@instrumentation.@name"="cloudwatch.aws/ec2"})
```
## Meminta dari Grafana
Anda dapat melakukan kueri CloudWatch data PromQL dari Grafana dengan menambahkan plugin sumber data Amazon **Managed Service for Prometheus dan mengarahkannya ke titik akhir** pemantauan. CloudWatch Penandatanganan SiGv4 dibangun ke plugin dan selalu diaktifkan, jadi tidak ada sakelar untuk dihidupkan. Plugin ini diterbitkan di [grafana. com/grafana/plugins/grafana-amazonprometheus-datasource/](https://grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/); instal dari katalog plugin Grafana sebelum menambahkan sumber data. Plugin AMP v3.0.0 membutuhkan Grafana. `>=11.6.11 <12 || >=12.0.10 <12.1 || >=12.1.7 <12.2 || >=12.2.5`
**Prasyarat IAM** — prinsipal IAM yang kredensialnya digunakan Grafana harus memiliki `cloudwatch:GetMetricData` keduanya (diperlukan untuk kueri instan dan jangkauan) dan (diperlukan untuk penemuan seri dan label). `cloudwatch:ListMetrics` Lihat perinciannya di [Izin IAM untuk PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM).
Untuk mengkonfigurasi Grafana, selesaikan langkah-langkah berikut.
1. Instal plugin sumber **data Amazon Managed Service untuk Prometheus** dari katalog plugin Grafana.
1. Di Grafana, buka **Koneksi**, **Sumber data, pilih Tambahkan sumber** **data**, dan pilih **Amazon Managed Service for Prometheus**.
1. Atur **URL** sumber data ke`https://monitoring.{{AWS Region}}.amazonaws.com`.
1. Atur **Wilayah** ke AWS Wilayah Anda. Pilih **penyedia Otentikasi** yang sesuai dengan lingkungan Anda (rantai kredensi default, kunci akses, atau peran IAM ruang kerja).
1. Pilih **Simpan & uji**.
## Menanyakan dari Grafana yang Dikelola Amazon
Anda dapat melakukan kueri data CloudWatch PromQL dari ruang kerja Grafana Terkelola Amazon dengan menambahkan **Layanan Terkelola Amazon untuk sumber data Prometheus** yang mengarah ke titik akhir pemantauan. CloudWatch Plugin sumber data ini menandatangani permintaan dengan SigV4 menggunakan peran IAM ruang kerja secara otomatis; SigV4 selalu diaktifkan, tanpa sakelar untuk mengonfigurasi. Plugin ini tersedia di Amazon Managed Grafana versi 12 dan yang lebih baru. Untuk informasi selengkapnya, lihat [Menyambungkan ke Layanan Terkelola Amazon untuk sumber data Prometheus](https://docs.aws.amazon.com/grafana/latest/userguide/amazon-prometheus-data-source.html) di Panduan Pengguna Grafana Terkelola *Amazon*.
**Prasyarat IAM** — peran IAM ruang kerja Grafana yang Dikelola Amazon harus memiliki `cloudwatch:GetMetricData` keduanya (diperlukan untuk kueri instan dan rentang) dan (diperlukan untuk penemuan seri dan label)`cloudwatch:ListMetrics`. Lihat perinciannya di [Izin IAM untuk PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM).
Untuk mengkonfigurasi sumber data, selesaikan langkah-langkah berikut.
1. Di ruang kerja Grafana Terkelola Amazon Anda, tambahkan Layanan **Terkelola Amazon untuk sumber data Prometheus**.
1. Atur **URL** sumber data ke`https://monitoring.{{AWS Region}}.amazonaws.com`.
1. Atur **Wilayah** ke AWS Wilayah Anda. Grafana Terkelola Amazon menyuntikkan kredensil dari peran IAM ruang kerja secara otomatis; Anda tidak perlu mengonfigurasi kunci statis.
1. Pilih **Simpan & uji**.
## Query dengan alat MCP
[CloudWatch MCP Server](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server/) menyediakan alat Model Context Protocol (MCP) yang memungkinkan asisten AI dan alat pengembangan menanyakan data CloudWatch PromQL atas nama Anda. Alat MCP menangani otentikasi dan pemformatan permintaan secara otomatis, sehingga Anda dapat fokus pada penulisan kueri PromQL daripada mengelola permintaan HTTP dan penandatanganan SigV4.
Alat PromQL berikut tersedia di MCP Server: CloudWatch
| Alat | Deskripsi |
| --- | --- |
| `execute_promql_query` | Menjalankan kueri PromQL instan, mengembalikan nilai metrik pada satu titik waktu. |
| `execute_promql_range_query` | Menjalankan kueri rentang PromQL selama jendela waktu, mengembalikan data deret waktu untuk analisis tren dan grafik. |
| `get_promql_label_values` | Mengambil nilai untuk label PromQL tertentu, seperti `__name__` untuk nama metrik atau untuk layanan. `@resource.service.name` |
| `get_promql_series` | Menemukan deret waktu yang cocok dengan pemilih label PromQL dan mengembalikan set label lengkap dari setiap seri yang cocok. |
| `get_promql_labels` | Daftar semua nama label PromQL yang tersedia untuk membantu menemukan struktur label metrik Anda. |
Untuk detail selengkapnya tentang parameter, konfigurasi, dan petunjuk penyiapan, lihat [Alat untuk CloudWatch PromQL dalam dokumentasi](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server#tools-for-cloudwatch-promql) CloudWatch MCP Server.
## Query dengan HTTP API
Anda juga dapat menanyakan data CloudWatch PromQL secara terprogram dengan memanggil titik akhir HTTP secara langsung. Prometheus-compatible Permintaan harus ditandatangani dengan [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) menggunakan `monitoring` sebagai nama layanan.
Titik akhir PromQL mengikuti pola. `https://monitoring.{{AWS Region}}.amazonaws.com/api/v1/{{operation}}` Misalnya, untuk Wilayah AS Timur (Virginia N.) (us-east-1), titik akhir untuk kueri instan adalah. `https://monitoring.us-east-1.amazonaws.com/api/v1/query`
Untuk referensi API lengkap, termasuk operasi yang didukung, parameter permintaan, dan format respons, lihat[Prometheus-compatible API](CloudWatch-PromQL-APIs.md). Untuk daftar AWS Wilayah di mana kueri PromQL tersedia, lihat. [Didukung AWS Wilayah](CloudWatch-PromQL.md#CloudWatch-PromQL-Regions) Untuk tindakan IAM yang diperlukan untuk setiap operasi, lihat[Izin IAM untuk PromQL](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM).