Metrik yang ditentukan pengguna dari agen

Panduan ini menjelaskan cara mengonfigurasi agen Monitoring untuk mengenali dan mengekspor metrik aplikasi ke Cloud Monitoring.

Agen Monitoring adalah daemon collectd. Selain mengekspor banyak metrik sistem dan pihak ketiga yang telah ditentukan sebelumnya ke Cloud Monitoring, agen tersebut dapat mengekspor metrik aplikasi yang Anda kumpulkan ke Monitoring sebagai metrik yang ditentukan pengguna. Plugin yang dikumpulkan juga dapat diekspor ke Monitoring.

Cara alternatif untuk mengekspor metrik aplikasi ke Monitoring adalah dengan menggunakan StatsD. Cloud Monitoring menyediakan konfigurasi default yang memetakan metrik Statistik ke metrik yang ditentukan pengguna. Jika puas dengan pemetaan tersebut, Anda tidak memerlukan langkah-langkah penyesuaian yang dijelaskan di bawah. Untuk informasi selengkapnya, lihat plugin StatsD.

Untuk mengetahui informasi selengkapnya tentang metrik, lihat dokumen berikut:

Fungsi ini hanya tersedia untuk agen yang berjalan di Linux. Fitur ini tidak tersedia di Windows.

Sebelum memulai

Instal agen Monitoring terbaru pada instance VM dan pastikan agen tersebut berfungsi. Untuk mengupdate agen, lihat Mengupdate agen.
Konfigurasi collectd untuk mendapatkan data pemantauan dari aplikasi Anda. Collectd mendukung banyak framework aplikasi dan endpoint pemantauan standar melalui plugin bacanya. Temukan plugin baca yang sesuai untuk Anda.
(Opsional) Untuk memudahkan, tambahkan dokumentasi referensi yang dikumpulkan agen ke halaman man sistem Anda dengan memperbarui variabel MANPATH, lalu menjalankan mandb:
```
export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
sudo mandb
```
Halaman manual adalah untuk stackdriver-collectd.

File dan direktori penting

File dan direktori berikut, yang dibuat dengan menginstal agen, relevan dengan penggunaan agen Monitoring (dikumpulkan):

/etc/stackdriver/collectd.conf: File konfigurasi yang dikumpulkan yang digunakan oleh agen. Edit file ini untuk mengubah konfigurasi umum.

Catatan: Konfigurasi pengumpulan default sistem, /etc/collectd.conf, tidak digunakan oleh agen Monitoring.
/etc/stackdriver/collectd.d/: Direktori untuk file konfigurasi yang ditambahkan pengguna. Untuk mengirim metrik yang ditentukan pengguna dari agen, Anda harus menempatkan file konfigurasi yang diperlukan, yang dibahas di bawah, dalam direktori ini. Untuk kompatibilitas mundur, agen juga mencari file dalam /opt/stackdriver/collectd/etc/collectd.d/.
/opt/stackdriver/collectd/share/man/*: Dokumentasi untuk koleksi versi agen. Anda dapat menambahkan halaman ini ke kumpulan halaman man sistem Anda; lihat Sebelum memulai untuk detailnya.
/etc/init.d/stackdriver-agent: Skrip init untuk agen.

Cara Monitoring menangani metrik yang dikumpulkan

Sebagai latar belakang, agen Monitoring memproses metrik yang dikumpulkan dan mengirimkannya ke Monitoring, yang memperlakukan setiap metrik sebagai anggota dari salah satu kategori berikut:

Metrik buatan pengguna. Metrik yang dikumpulkan yang memiliki kunci metadata stackdriver_metric_type dan satu sumber data ditangani sebagai metrik yang ditentukan pengguna dan dikirim ke Monitoring menggunakan metode projects.timeSeries.create di Monitoring API.
Metrik yang diseleksi. Semua metrik yang dikumpulkan lainnya dikirim ke Monitoring menggunakan API internal. Hanya metrik dalam daftar metrik pilihan yang diterima dan diproses.
Metrik yang dihapus. Metrik yang dikumpulkan yang tidak ada dalam daftar metrik pilihan dan bukan metrik yang ditentukan pengguna akan dihapus secara diam-diam oleh Monitoring. Agen itu sendiri tidak mengetahui metrik mana yang diterima atau dibuang.

Menulis metrik yang ditentukan pengguna dengan agen

Anda mengonfigurasi agen untuk mengirim titik data metrik ke Monitoring. Setiap titik harus dikaitkan dengan metrik yang ditentukan pengguna, yang Anda tentukan dengan deskripsi metrik. Konsep ini diperkenalkan dalam Metrik, deret waktu, dan resource serta dijelaskan secara mendetail dalam Struktur deret waktu dan Ringkasan metrik yang ditentukan pengguna.

Anda dapat membuat metrik yang dikumpulkan diperlakukan sebagai metrik yang ditentukan pengguna dengan menambahkan metadata yang tepat ke metrik:

stackdriver_metric_type : (wajib) nama metrik yang diekspor. Contoh: custom.googleapis.com/my_custom_metric.
label:[LABEL] : (opsional) label tambahan untuk metrik yang diekspor. Misalnya, jika Anda ingin label Monitoring STRING bernama color, kunci metadata Anda adalah label:color dan nilai kuncinya bisa berupa "blue". Anda dapat memiliki hingga 10 label per jenis metrik.

Anda dapat menggunakan rantai filter yang dikumpulkan untuk mengubah metadata untuk metrik Anda. Karena rantai filter tidak dapat mengubah daftar sumber data, dan metrik yang ditentukan pengguna hanya mendukung satu sumber data, setiap metrik yang dikumpulkan yang ingin Anda gunakan dengan fasilitas ini harus memiliki satu sumber data.

Contoh

Dalam contoh ini, kita akan memantau koneksi Nginx aktif dari dua layanan Nginx, my_service_a dan my_service_b. Kita akan mengirimkannya ke Monitoring menggunakan metrik yang ditentukan pengguna. Kami akan melakukan langkah-langkah berikut:

Mengidentifikasi metrik yang dikumpulkan untuk setiap layanan Nginx.
Menentukan deskriptor metrik Monitoring.
Konfigurasi rantai filter yang dikumpulkan untuk menambahkan metadata ke metrik yang dikumpulkan, agar dapat memenuhi harapan agen Monitoring.

Metrik yang dikumpulkan yang masuk

Koleksi mengharapkan metrik terdiri dari komponen berikut. Lima komponen pertama membentuk ID yang dikumpulkan untuk metrik:

    Host, Plugin, Plugin-instance, Type, Type-instance, [value]

Dalam contoh ini, metrik yang ingin Anda kirim sebagai metrik yang ditentukan pengguna memiliki nilai berikut:

Komponen	Nilai yang diharapkan
Host	apa pun
Plugin	`curl_json`
Instance plugin	`nginx_my_service_a` atau `nginx_my_service_b`¹
Type	`gauge`
Instance jenis	`active-connections`
`[value]`	nilai apa pun²

Catatan:
¹ Dalam contoh, nilai ini mengenkode aplikasi (Nginx) dan nama layanan yang terhubung.
² Nilai ini biasanya berupa stempel waktu dan angka presisi ganda. Monitoring menangani detail penafsiran berbagai jenis nilai. Nilai gabungan tidak didukung oleh agen Monitoring.

Deskriptor metrik dan deret waktu pemantauan

Pada sisi Monitoring, desain deskripsi metrik untuk metrik yang ditentukan pengguna. Deskripsi berikut adalah pilihan yang wajar untuk data dalam contoh ini:

Nama: custom.googleapis.com/nginx/active_connections
Label:
- service_name (STRING): Nama layanan yang terhubung ke Nginx.
Jenis: GAUGE
Jenis: Double

Setelah mendesain deskripsi metrik, Anda dapat membuatnya menggunakan projects.metricDescriptors.create, atau membiarkannya dibuat untuk Anda dari metadata deret waktu, yang dibahas di bawah ini. Untuk informasi selengkapnya, lihat Membuat deskripsi metrik di halaman ini.

Data deret waktu untuk deskripsi metrik ini harus berisi informasi berikut, karena cara deskripsi metrik ditentukan:

Jenis metrik: custom.googleapis.com/nginx/active_connections
Nilai label metrik:
- service_name: "my_service_a" atau "my_service_b"

Informasi deret waktu lainnya, termasuk resource yang dimonitor terkait—instance VM yang mengirimkan data—dan titik data metrik, secara otomatis diperoleh oleh agen untuk semua metrik. Anda tidak perlu melakukan hal khusus.

Rantai filter Anda

Buat file, /opt/stackdriver/collectd/etc/collectd.d/nginx_curl_json.conf, yang berisi kode berikut:

LoadPlugin match_regex
LoadPlugin target_set
LoadPlugin target_replace

# Insert a new rule in the default "PreCache" chain, to divert your metrics.
PreCacheChain "PreCache"
<Chain "PreCache">
  <Rule "jump_to_custom_metrics_from_curl_json">
    # If the plugin name and instance match, this is PROBABLY a metric we're looking for:
    <Match regex>
      Plugin "^curl_json$"
      PluginInstance "^nginx_"
    </Match>
    <Target "jump">
      # Go execute the following chain; then come back.
      Chain "PreCache_curl_json"
    </Target>
  </Rule>
  # Continue processing metrics in the default "PreCache" chain.
</Chain>

# Following is a NEW filter chain, just for your metric.
# It is only executed if the default chain "jumps" here.
<Chain "PreCache_curl_json">

  # The following rule does all the work for your metric:
  <Rule "rewrite_curl_json_my_special_metric">
    # Do a careful match for just your metrics; if it fails, drop down
    # to the next rule:
    <Match regex>
      Plugin "^curl_json$"                   # Match on plugin.
      PluginInstance "^nginx_my_service_.*$" # Match on plugin instance.
      Type "^gauge$"                         # Match on type.
      TypeInstance "^active-connections$"    # Match on type instance.
    </Match>

    <Target "set">
      # Specify the metric descriptor type:
      MetaData "stackdriver_metric_type" "custom.googleapis.com/nginx/active_connections"
      # Specify a value for the "service_name" label; clean it up in the next Target:
      MetaData "label:service_name" "%{plugin_instance}"
    </Target>

    <Target "replace">
      # Remove the "nginx_" prefix in the service_name to get the real service name:
      MetaData "label:service_name" "nginx_" ""
    </Target>
  </Rule>

  # The following rule is run after rewriting your metric, or
  # if the metric wasn't one of your user-defined metrics. The rule returns
  # to the default "PreCache" chain. The default processing
  # will write all metrics to Cloud Monitoring,
  # which will drop any unrecognized metrics: ones that aren't
  # in the list of curated metrics and don't have
  # the user-defined metric metadata.
  <Rule "go_back">
    Target "return"
  </Rule>
</Chain>

Muat konfigurasi baru

Mulai ulang agen Anda untuk mengambil konfigurasi baru dengan menjalankan perintah berikut pada instance VM Anda:

sudo service stackdriver-agent restart

Informasi metrik yang ditentukan pengguna mulai mengalir ke Monitoring.

Referensi dan praktik terbaik

Deskripsi metrik dan deret waktu

Untuk pengantar metrik Cloud Monitoring, lihat Metrik, deret waktu, dan resource. Detail selengkapnya tersedia di Ringkasan metrik yang ditentukan pengguna dan Struktur deret waktu.

Deskripsi metrik. Deskripsi metrik memiliki bagian penting berikut:

Jenis formulir custom.googleapis.com/[NAME1]/.../[NAME0]. Contoh:
```
custom.googleapis.com/my_measurement
custom.googleapis.com/instance/network/received_packets_count
custom.googleapis.com/instance/network/sent_packets_count
```
Penamaan yang direkomendasikan bersifat hierarkis agar metrik lebih mudah dilacak oleh pengguna. Jenis metrik tidak boleh berisi tanda hubung; untuk aturan penamaan yang tepat, lihat Jenis dan label metrik penamaan.
Maksimal 10 label untuk menganotasi data metrik, seperti device_name, fault_type, atau response_code. Nilai label tidak ditentukan dalam deskriptor metrik.
Jenis dan jenis nilai titik data, seperti "nilai pengukuran jenis double". Untuk informasi selengkapnya, lihat MetricKind dan ValueType.

Deret waktu. Titik data metrik memiliki bagian penting berikut:

Jenis deskriptor metrik yang terkait.
Nilai untuk semua label deskriptor metrik.
Nilai dengan stempel waktu yang konsisten dengan jenis dan jenis nilai deskriptor metrik.
Resource yang dimonitor tempat data berasal, biasanya instance VM. Ruang untuk resource sudah bawaan, sehingga deskriptor tidak memerlukan label terpisah.

Membuat deskriptor metrik

Anda tidak perlu membuat deskriptor metrik terlebih dahulu. Saat titik data tiba di Monitoring, jenis metrik, label, dan nilai titik tersebut dapat digunakan untuk membuat deskripsi metrik kumulatif atau pengukur secara otomatis. Untuk informasi selengkapnya, lihat Pembuatan otomatis deskripsi metrik.

Namun, ada keuntungan untuk membuat deskriptor metrik Anda sendiri:

Anda dapat menyertakan beberapa dokumentasi yang cermat untuk metrik dan labelnya.
Anda dapat menentukan jenis dan jenis metrik tambahan. Satu-satunya kombinasi (jenis, jenis) yang didukung oleh agen adalah (GAUGE, Double) dan (CUMULATIVE, INT64). Untuk mengetahui informasi selengkapnya, lihat Jenis metrik dan jenis nilai.
Anda dapat menentukan jenis label selain STRING.

Jika Anda menulis titik data ke Monitoring yang menggunakan jenis metrik yang tidak ditentukan, deskriptor metrik baru akan dibuat untuk titik data tersebut. Perilaku ini dapat menjadi masalah saat Anda men-debug kode yang menulis data metrik. Jika salah mengeja jenis metrik akan menyebabkan deskriptor metrik palsu.

Setelah Anda membuat deskripsi metrik, atau setelah dibuat, deskriptor metrik tidak dapat diubah. Misalnya, Anda tidak dapat menambahkan atau menghapus label. Anda hanya dapat menghapus deskripsi metrik—yang akan menghapus semua datanya—lalu membuat ulang deskripsi sesuai keinginan Anda.

Untuk detail selengkapnya tentang cara membuat deskripsi metrik, lihat Membuat metrik.

Harga

Secara umum, metrik sistem Cloud Monitoring gratis, sedangkan metrik dari sistem, agen, atau aplikasi eksternal tidak. Metrik yang dapat ditagih ditagih berdasarkan jumlah byte atau jumlah sampel yang diserap.

Untuk mengetahui informasi selengkapnya tentang harga Cloud Monitoring, lihat dokumen berikut:

Batas

Cloud Monitoring memiliki batasan jumlah deret waktu metrik dan jumlah deskriptor metrik yang ditentukan pengguna di setiap project. Untuk mengetahui detailnya, lihat Kuota dan batas.

Jika mengetahui bahwa Anda telah membuat deskripsi metrik yang tidak lagi diinginkan, Anda dapat menemukan dan menghapus deskripsi tersebut menggunakan Monitoring API. Untuk mengetahui informasi selengkapnya, lihat projects.metricDescriptors.

Pemecahan masalah

Bagian ini menjelaskan cara mengonfigurasi plugin write_log agen Monitoring untuk menghapus kumpulan lengkap titik metrik, termasuk metadata. Ini dapat digunakan untuk menentukan titik yang perlu diubah, serta untuk memastikan transformasi Anda berperilaku seperti yang diharapkan.

Mengaktifkan write_log

Plugin write_log disertakan dalam paket stackdriver-agent. Untuk mengaktifkan plugin:

Sebagai root, edit file konfigurasi berikut:
```
/etc/stackdriver/collectd.conf
```
Tepat setelah LoadPlugin write_gcm, tambahkan:
```
LoadPlugin write_log
```
Tepat setelah <Plugin "write_gcm">…</Plugin>, tambahkan:
```
<Plugin "write_log">
  Format JSON
</Plugin>
```
Telusuri <Target "write">…</Target> dan setelah setiap Plugin "write_gcm", tambahkan:
```
Plugin "write_log"
```
Simpan perubahan Anda dan mulai ulang agen:
```
sudo service stackdriver-agent restart
```

Perubahan ini akan mencetak satu baris log per nilai metrik yang dilaporkan, termasuk ID yang dikumpulkan lengkap, entri metadata, dan nilai.

Output dari write_log

Jika berhasil pada langkah sebelumnya, Anda akan melihat output write_log di log sistem:

Linux berbasis Debian: /var/log/syslog
Linux berbasis Red Hat: /var/log/messages

Baris contoh di bawah ini telah diformat agar lebih mudah dibaca dalam dokumen ini.

Dec  8 15:13:45 test-write-log collectd[1061]: write_log values:#012[{
    "values":[1933524992], "dstypes":["gauge"], "dsnames":["value"],
    "time":1481210025.252, "interval":60.000,
    "host":"test-write-log.c.test-write-log.internal",
    "plugin":"df", "plugin_instance":"udev", "type":"df_complex", "type_instance":"free"}]

Dec  8 15:13:45 test-write-log collectd[1061]: write_log values:#012[{
    "values":[0], "dstypes":["gauge"], "dsnames":["value"],
    "time":1481210025.252, "interval":60.000,
    "host":"test-write-log.c.test-write-log.internal",
    "plugin":"df", "plugin_instance":"udev", "type":"df_complex", "type_instance":"reserved"}]