Kueri metrik Prometheus menggunakan API dan PromQL

Layanan terkelola Azure Monitor untuk Prometheus, mengumpulkan metrik dari kluster Azure Kubernetes dan menyimpannya di ruang kerja Azure Monitor. PromQL (bahasa kueri Prometheus), adalah bahasa kueri fungsional yang memungkinkan Anda mengkueri dan menggabungkan data rangkaian waktu. Gunakan PromQL untuk mengkueri dan mengagregasi metrik yang disimpan di ruang kerja Azure Monitor.

Artikel ini menjelaskan cara mengkueri ruang kerja Azure Monitor menggunakan PromQL melalui REST API. Untuk informasi selengkapnya tentang PromQL, lihat Mengkueri prometheus.

Prasyarat

Untuk mengkueri ruang kerja monitor Azure menggunakan PromQL, Anda memerlukan prasyarat berikut:

• Kluster Azure Kubernetes atau kluster Kubernetes jarak jauh.
• Layanan terkelola Azure Monitor untuk metrik scraping Prometheus dari kluster Kubernetes.
• Ruang kerja Azure Monitor tempat metrik Prometheus disimpan.

Autentikasi

Untuk mengkueri ruang kerja Azure Monitor Anda, autentikasi menggunakan ID Microsoft Entra. API mendukung autentikasi Microsoft Entra menggunakan kredensial klien. Daftarkan aplikasi klien dengan ID Microsoft Entra dan minta token.

Untuk menyiapkan autentikasi Microsoft Entra, ikuti langkah-langkah di bawah ini:

1. Daftarkan aplikasi dengan ID Microsoft Entra.
2. Berikan akses untuk aplikasi ke ruang kerja Azure Monitor Anda.
3. Meminta token.

Mendaftarkan aplikasi dengan ID Microsoft Entra

1. Untuk mendaftarkan aplikasi, ikuti langkah-langkah di Mendaftarkan Aplikasi untuk meminta token otorisasi dan bekerja dengan API

Mengizinkan akses aplikasi ke ruang kerja Anda

Tetapkan peran Pembaca Data Pemantauan aplikasi Anda sehingga dapat mengkueri data dari ruang kerja Azure Monitor Anda.

1. Buka ruang kerja Azure Monitor Anda di portal Azure.

2. Pada halaman Gambaran Umum, perhatikan titik akhir Kueri Anda untuk digunakan dalam permintaan REST Anda.

3. Pilih Kontrol Akses (IAM).

4. Pilih Tambahkan, lalu Tambahkan penetapan peran dari halaman Kontrol Akses (IAM).

   

5. Pada halaman Tambahkan penetapan peran, cari Pemantauan.

6. Pilih Pembaca Data Pemantauan, lalu pilih tab Anggota.

   

7. Pilih Pilih anggota.

8. Cari aplikasi yang Anda daftarkan dan pilih.

9. Memilih Pilih.

10. Pilih Tinjau + tetapkan.

    

Anda telah membuat pendaftaran aplikasi dan telah menetapkannya akses ke data kueri dari ruang kerja Azure Monitor Anda. Sekarang Anda dapat membuat token dan menggunakannya dalam kueri.

Meminta token

Kirim permintaan berikut di prompt perintah atau dengan menggunakan klien seperti Insomnia atau Invoke-RestMethod PowerShell

curl -X POST 'https://login.microsoftonline.com/<tenant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret>' \
--data-urlencode 'resource=https://prometheus.monitor.azure.com'

Isi respons sampel:

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https:/prometheus.monitor.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

Simpan token akses dari respons untuk digunakan dalam permintaan HTTP berikut.

Titik akhir kueri

Temukan titik akhir kueri ruang kerja Azure Monitor Anda di halaman gambaran umum ruang kerja Azure Monitor.

API yang didukung

Kueri berikut ini didukung:

Kueri instan

Untuk informasi selengkapnya, lihat Kueri instan

Jalur: /api/v1/query
Contoh:

POST https://k8s-02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query  
--header 'Authorization:  Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=sum( \
    container_memory_working_set_bytes \
    * on(namespace,pod) \
    group_left(workload, workload_type) \
    namespace_workload_pod:kube_pod_owner:relabel{ workload_type="deployment"}) by (pod)'

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query?query=container_memory_working_set_bytes' 
--header 'Authorization:  Bearer <access token>'

Kueri rentang

Untuk informasi selengkapnya, lihat Kueri rentang
Jalur: /api/v1/query_range
Contoh:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range?query=container_memory_working_set_bytes&start=2023-03-01T00:00:00.000Z&end=2023-03-20T00:00:00.000Z&step=6h'
--header 'Authorization: Bearer <access token>

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range' 
--header 'Authorization:  Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=up' 
--data-urlencode 'start=2023-03-01T20:10:30.781Z' 
--data-urlencode 'end=2023-03-20T20:10:30.781Z' 
--data-urlencode 'step=6h'

Seri

Untuk informasi selengkapnya, lihat Seri

Jalur: /api/v1/series
Contoh:

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series' 
--header 'Authorization: Bearer <access token>
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'match[]=kube_pod_info{pod="bestapp-123abc456d-4nmfm"}'

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series?match[]=container_network_receive_bytes_total{namespace="default-1669648428598"}'

Label

Untuk informasi selengkapnya, lihat Jalur Label : /api/v1/labels
Contoh:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

Nilai label

Untuk informasi selengkapnya, lihat Nilai label
Jalur: /api/v1/label/__name__/values.

Contoh:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/label/__name__/values'

Untuk spesifikasi lengkap API prom OSS, lihat API HTTP Prometheus.

Batasan API

Batasan berikut adalah selain yang dirinci dalam spesifikasi Prometheus.

• Kueri harus dilingkup ke metrik
  Setiap rangkaian waktu mengambil kueri (/series atau /query atau /query_range) harus berisi pencocokan label __name__. Artinya, setiap kueri harus dilingkup ke metrik. Hanya ada satu pencocok label __name__ dalam kueri.
• Kueri /seri tidak mendukung filter ekspresi reguler
• Rentang waktu yang didukung
  • /query_range API mendukung rentang waktu 32 hari. Ini adalah rentang waktu maksimum yang diizinkan, termasuk pemilih rentang yang ditentukan dalam kueri itu sendiri. Misalnya, kueri rate(http_requests_total[1h] selama 24 jam terakhir sebenarnya akan berarti data sedang dikueri selama 25 jam. Ini berasal dari rentang 24 jam ditambah 1 jam yang ditentukan dalam kueri itu sendiri.
  • API /series mengambil data untuk rentang waktu maksimum 12 jam. Jika endTime tidak disediakan, endTime = time.now(). Jika kemarahan waktu lebih besar dari 12 jam, startTime diatur ke endTime – 12h
• Rentang waktu yang diabaikan
  Waktu mulai dan waktu akhir yang disediakan dengan /labels dan /label/__name__/values diabaikan, dan semua data yang disimpan di ruang kerja Azure Monitor dikueri.
• Fitur eksperimental
  Fitur eksperimental seperti pengecualian tidak didukung.

Untuk informasi selengkapnya tentang batas metrik Prometheus, lihat Metrik Prometheus

Sensitivitas huruf besar/besar

Layanan terkelola Azure Monitor untuk Prometheus adalah sistem yang tidak peka huruf besar/kecil. Ini memperlakukan string (seperti nama metrik, nama label, atau nilai label) sebagai rangkaian waktu yang sama jika berbeda dari rangkaian waktu lain hanya dengan kasus string.

Dalam layanan terkelola untuk Prometheus, rangkaian waktu berikut dianggap sama:

diskSize(cluster="eastus", node="node1", filesystem="usr_mnt")
diskSize(cluster="eastus", node="node1", filesystem="usr_MNT")

Contoh sebelumnya adalah rangkaian waktu tunggal dalam database rangkaian waktu. Pertimbangan berikut berlaku:

• Sampel apa pun yang diserap terhadapnya disimpan seolah-olah mereka diekstraksi atau diserap terhadap satu rangkaian waktu.
• Jika contoh sebelumnya diserap dengan stempel waktu yang sama, salah satunya dihilangkan secara acak.
• Casing yang disimpan dalam database deret waktu dan dikembalikan oleh kueri tidak dapat diprediksi. Rangkaian waktu yang sama mungkin mengembalikan casing yang berbeda pada waktu yang berbeda.
• Setiap nama metrik atau pencocok nama/nilai label yang ada dalam kueri diambil dari database rangkaian waktu melalui perbandingan yang tidak peka huruf besar/kecil. Jika ada pencocokan peka huruf besar/kecil dalam kueri, pencocokan ini secara otomatis diperlakukan sebagai pencocokan yang tidak peka huruf besar/kecil dalam perbandingan string.

Ini adalah praktik terbaik untuk menggunakan satu kasus yang konsisten untuk menghasilkan atau mengikis rangkaian waktu.

Prometheus sumber terbuka memperlakukan contoh sebelumnya sebagai dua rangkaian waktu yang berbeda. Sampel apa pun yang diekstraksi atau diserap terhadapnya disimpan secara terpisah.

Tanya jawab umum

Bagian ini menyediakan jawaban atas pertanyaan umum.

Saya kehilangan semua atau beberapa metrik saya. Bagaimana cara memecahkan masalah?

Anda dapat menggunakan panduan pemecahan masalah untuk menyerap metrik Prometheus dari agen terkelola di sini.

Mengapa saya kehilangan metrik yang memiliki dua label dengan nama yang sama tetapi casing yang berbeda?

Azure Managed Prometheus adalah sistem yang tidak peka huruf besar/kecil. Ini memperlakukan string, seperti nama metrik, nama label, atau nilai label, sebagai rangkaian waktu yang sama jika berbeda dari rangkaian waktu lain hanya dengan kasus string. Untuk informasi selengkapnya, lihat Gambaran umum metrik Prometheus.

Saya melihat beberapa celah dalam data metrik, mengapa ini terjadi?

Selama pembaruan node, Anda mungkin melihat celah 1 menit hingga 2 menit dalam data metrik untuk metrik yang dikumpulkan dari pengumpul tingkat kluster kami. Kesenjangan ini terjadi karena simpul tempat data berjalan sedang diperbarui sebagai bagian dari proses pembaruan normal. Proses pembaruan ini memengaruhi target di seluruh kluster seperti kube-state-metrics dan target aplikasi kustom yang ditentukan. Ini terjadi ketika kluster Anda diperbarui secara manual atau melalui pembaruan otomatis. Perilaku ini diharapkan dan terjadi karena simpul yang dijalankannya saat diperbarui. Perilaku ini tidak memengaruhi salah satu aturan pemberitahuan yang direkomendasikan.

Langkah berikutnya

Gambaran umum ruang kerja Azure Monitor
Mengelola ruang kerja Azure Monitor
Ringkasan Layanan Terkelola Azure Monitor untuk Prometheus
Kueri metrik Prometheus menggunakan buku kerja Azure