Halaman ini diterjemahkan oleh Cloud Translation API.

Metrik yang ditentukan pengguna dari agen

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

Agen Monitoring adalah daemon collectd. Selain mengekspor banyak metrik sistem dan pihak ketiga standar ke Cloud Monitoring, agen dapat mengekspor metrik aplikasi collectd Anda sendiri ke Monitoring sebagai metrik yang ditentukan pengguna. Plugin collectd Anda juga dapat mengekspor ke Monitoring.

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

Untuk 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 di instance VM dan verifikasi bahwa agen tersebut berfungsi. Untuk mengupdate agen, lihat Mengupdate agen.
Konfigurasikan collectd untuk mendapatkan data pemantauan dari aplikasi Anda. Collectd mendukung banyak framework aplikasi dan endpoint pemantauan standar melalui plugin baca. Temukan plugin baca yang sesuai untuk Anda.
(Opsional) Untuk memudahkan, tambahkan dokumentasi referensi collectd agen ke halaman man sistem Anda dengan memperbarui variabel MANPATH, lalu menjalankan mandb:
```
export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
sudo mandb
```
Halaman man ditujukan untuk stackdriver-collectd.

File dan direktori penting

File dan direktori berikut, yang dibuat dengan menginstal agen, relevan untuk menggunakan Agen pemantauan (collectd):

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

Catatan: Konfigurasi collectd 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 menempatkan file konfigurasi yang diperlukan, yang dibahas di bawah, di direktori ini. Untuk kompatibilitas mundur, agen juga mencari file di /opt/stackdriver/collectd/etc/collectd.d/.
/opt/stackdriver/collectd/share/man/*: Dokumentasi untuk versi collectd agen. Anda dapat menambahkan halaman ini ke kumpulan halaman man sistem; lihat Sebelum memulai untuk mengetahui detailnya.
/etc/init.d/stackdriver-agent: Skrip init untuk agen.

Cara Monitoring menangani metrik collectd

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

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

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 deskriptor metrik. Konsep ini diperkenalkan di Metrik, deret waktu, dan resource dan dijelaskan secara mendetail di Struktur deret waktu dan Ringkasan metrik yang ditentukan pengguna.

Anda dapat membuat metrik collectd diperlakukan sebagai metrik yang ditentukan pengguna dengan menambahkan metadata yang sesuai 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 menginginkan label STRING Pemantauan bernama color, kunci metadata Anda akan menjadi label:color dan nilai kuncinya dapat berupa "blue". Anda dapat memiliki hingga 10 label per jenis metrik.

Anda dapat menggunakan rantai filter collectd 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 collectd 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. Kami akan mengirimkannya ke Pemantauan menggunakan metrik yang ditentukan pengguna. Kami akan melakukan langkah-langkah berikut:

Identifikasi metrik collectd untuk setiap layanan Nginx.
Tentukan deskriptor metrik Monitoring.
Konfigurasikan rantai filter collectd untuk menambahkan metadata ke metrik collectd, guna memenuhi ekspektasi agen Pemantauan.

Metrik collectd masuk

Collectd mengharapkan metrik terdiri dari komponen berikut. Lima komponen pertama membentuk ID collectd 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`¹
Jenis	`gauge`
Instance jenis	`active-connections`
`[value]`	nilai apa pun²

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

Memantau deskripsi metrik dan deret waktu

Di sisi Monitoring, desain deskriptor 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 Anda dapat membiarkannya dibuat untuk Anda dari metadata deret waktu, yang dibahas di bawah. 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 dipantau terkait—instance VM yang mengirim 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>

Memuat konfigurasi baru

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

sudo service stackdriver-agent restart

Informasi metrik yang ditentukan pengguna mulai mengalir ke Pemantauan.

Referensi dan praktik terbaik

Deskriptor 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 dalam bentuk 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 orang. Jenis metrik tidak boleh berisi tanda hubung; untuk mengetahui aturan penamaan yang tepat, lihat Penamaan jenis dan label metrik.
Maksimal 10 label untuk menganotasi data metrik, seperti device_name, fault_type, atau response_code. Nilai label tidak ditentukan dalam deskripsi metrik.
Jenis dan jenis nilai titik data, seperti "nilai pengukur jenis double". Untuk informasi selengkapnya, lihat MetricKind dan ValueType.

Deret waktu. Titik data metrik memiliki bagian penting berikut:

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

Membuat deskriptor metrik

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

Namun, ada keuntungan dalam membuat deskripsi 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, type) yang didukung oleh agen adalah (GAUGE, DOUBLE) dan (CUMULATIVE, INT64). Untuk 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, deskripsi metrik baru akan dibuat untuk titik data tersebut. Perilaku ini dapat menjadi masalah saat Anda men-debug kode yang menulis data metrik. Kesalahan ejaan pada jenis metrik akan menghasilkan deskripsi metrik yang tidak benar.

Setelah Anda membuat deskripsi metrik, atau setelah deskripsi metrik dibuat untuk Anda, deskripsi tersebut 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 mengetahui detail selengkapnya tentang cara membuat deskripsi metrik, lihat Membuat metrik.

Harga

Secara umum, metrik sistem Cloud Monitoring gratis, dan metrik dari sistem, agen, atau aplikasi eksternal tidak gratis. 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 batas pada jumlah deret waktu metrik dan jumlah deskripsi metrik yang ditentukan pengguna di setiap project. Untuk mengetahui detailnya, lihat Kuota dan batas.

Jika Anda mendapati 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 membuang kumpulan lengkap titik metrik, termasuk metadata. Hal ini dapat digunakan untuk menentukan titik yang perlu ditransformasi, 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 dan mulai ulang agen:
```
sudo service stackdriver-agent restart
```

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

Output write_log

Jika berhasil di 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 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"}]