Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

代理程式的使用者定義指標

本指南說明如何設定 Monitoring 代理程式，以辨識應用程式指標並匯出至 Cloud Monitoring。

Monitoring 代理程式是一個 collectd Daemon。除了將許多預先定義的系統和第三方指標匯出至 Cloud Monitoring，代理程式也可以將您自己的 collectd 應用程式指標匯出至 Monitoring，做為使用者定義指標。您的 collectd 外掛程式也可以匯出至 Monitoring。

如要將應用程式指標匯出至 Monitoring，也可以使用 StatsD。Cloud Monitoring 提供預設設定，可將 StatsD 指標對應至使用者定義的指標。如果對該對應感到滿意，就不需要執行下文所述的自訂步驟。詳情請參閱「StatsD 外掛程式」。

如要進一步瞭解指標，請參閱下列文件：

這項功能僅適用於在 Linux 上執行的代理程式。這項功能不適用於 Windows。

事前準備

在 VM 執行個體上安裝最新版 Monitoring 代理程式，並驗證其是否可正常運作。如要更新代理程式，請參閱更新代理程式一文。
設定 collectd，從應用程式取得監控資料。透過 read 外掛程式，Collectd 支援許多應用程式架構和標準監控端點。請尋找最適合您的讀取外掛程式。
(選用) 為方便起見，請更新 MANPATH 變數，然後執行 mandb，將代理程式的 collectd 參考文件新增至系統的 man 頁面：
```
export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
sudo mandb
```
這些說明文件頁面適用於 stackdriver-collectd。

重要檔案與目錄

安裝代理程式後會建立以下檔案和目錄；這些檔案和目錄與使用 Monitoring 代理程式 (collectd) 相關：

/etc/stackdriver/collectd.conf: 代理程式使用的 collectd 設定檔。編輯此檔案即可變更一般設定。

注意： 監控代理程式不會使用系統預設的 collectd 設定 /etc/collectd.conf。
/etc/stackdriver/collectd.d/: 使用者新增的設定檔的目錄。如要從代理程式傳送使用者定義的指標，請將下方討論的必要設定檔放在這個目錄中。為確保回溯相容性，代理程式也會在 /opt/stackdriver/collectd/etc/collectd.d/ 中尋找檔案。
/opt/stackdriver/collectd/share/man/*: collectd 代理程式版本的說明文件。您可以將這些頁面新增至系統的 man 頁面集；詳情請參閱「事前準備」。
/etc/init.d/stackdriver-agent: 代理程式的初始化指令碼。

Monitoring 處理 collectd 指標的方式

Monitoring 代理程式會在背景中處理 collectd 指標，並將這些指標傳送到 Monitoring。Monitoring 會將每個指標視為以下其中一個類別的成員：

使用者定義的指標。具有中繼資料鍵 stackdriver_metric_type 和單一資料來源的 Collectd 指標會視為使用者定義指標，並使用 Monitoring API 中的 projects.timeSeries.create 方法傳送至 Monitoring。
收錄的指標。所有其他 collectd 指標都會透過內部 API 傳送至 Monitoring。系統只會接受並處理精選指標清單中的指標。
捨棄的指標。如果收集到的指標不在精選指標清單中，也不是使用者定義的指標，則 Monitoring 會自動捨棄這些指標。代理本身不會知道哪些指標獲得接受或遭到捨棄。

使用代理程式撰寫使用者定義的指標

您可以設定代理程式，將指標資料點傳送至 Monitoring。每個點都必須與使用者定義的指標相關聯，而您可以使用指標描述元定義指標。如要瞭解這些概念，請參閱「指標、時間序列和資源」，並詳閱「時間序列結構」和「使用者定義指標總覽」。

您可以將 collectd 指標視為使用者定義的指標，方法是在指標中加入適當的中繼資料：

stackdriver_metric_type：(必填) 匯出指標的名稱。範例：custom.googleapis.com/my_custom_metric。
label:[LABEL]：(選用) 匯出指標的其他標籤。舉例來說，如果您想要名為 color 的監控 STRING 標籤，則中繼資料鍵會是 label:color，而鍵的值可能是 "blue"。每個指標類型最多可以有 10 個標籤。

您可以使用 collectd 篩選器鏈來修改指標的中繼資料。由於篩選器鏈結無法修改資料來源清單，且使用者定義的指標僅支援單一資料來源，因此您想透過這項功能使用的任何收集指標都必須有單一資料來源。

範例

在這個範例中，我們會監控兩個 Nginx 服務 (my_service_a 和 my_service_b) 的有效 Nginx 連線。我們會使用使用者定義的指標，將這些資料傳送至 Monitoring。請採取下列步驟：

識別每個 Nginx 服務的 collectd 指標。
定義 Monitoring 指標描述元。
設定 collectd 篩選器鏈，將中繼資料新增至 collectd 指標，使其符合 Monitoring 代理程式的期望條件。

連入的 collectd 指標

Collectd 會預期指標包含下列元件。前五個元件構成了指標的「ID」：

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

在本範例中，您要以使用者定義指標傳送的指標具有下列值：

元件	預期的值
主機	any
外掛程式	`curl_json`
外掛程式執行個體	`nginx_my_service_a` 或 `nginx_my_service_b`¹
類型	`gauge`
型別執行個體	`active-connections`
`[value]`	任何值²

附註：
¹ 在這個範例中，這個值會同時編碼應用程式 (Nginx) 和已連線的服務名稱。
² 這個值通常是時間戳記和雙精度數字。 Monitoring 會處理各種值的解讀細節。監控代理程式不支援複合值。

Monitoring 指標描述元與時間序列

在 Monitoring 端，為使用者定義的指標設計指標描述元。以下描述元適合用於本範例中的資料：

名稱：custom.googleapis.com/nginx/active_connections
標籤：
- service_name (STRING)：連線至 Nginx 的服務名稱。
種類：GAUGE
類型：DOUBLE

設計指標描述元後，您可以使用 projects.metricDescriptors.create 建立指標描述元，也可以讓系統根據時間序列中繼資料為您建立，詳情請參閱下文。詳情請參閱本頁的「建立指標描述元」。

由於定義指標描述元的方式，這個指標描述元的時間序列資料必須包含下列資訊：

指標類型：custom.googleapis.com/nginx/active_connections
指標標籤值：
- service_name："my_service_a" 或 "my_service_b"

代理程式會自動取得所有指標的其他時間序列資訊，包括相關聯的受監控資源 (傳送資料的 VM 執行個體) 和指標的資料點。因此您無須採取任何特別行動。

您的篩選器鏈

建立 /opt/stackdriver/collectd/etc/collectd.d/nginx_curl_json.conf 檔案，其中包含下列程式碼：

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>

載入新設定

在 VM 執行個體上執行下列指令，重新啟動代理程式，納入新設定。

sudo service stackdriver-agent restart

使用者定義的指標資訊會開始流入「監控」頁面。

參考資料與最佳做法

指標描述元與時間序列

如要瞭解 Cloud Monitoring 指標，請參閱「指標、時間序列和資源」。詳情請參閱「使用者定義指標總覽」和「時序結構」。

指標描述元。指標描述元包含以下重要部分：

類型的表單 custom.googleapis.com/[NAME1]/.../[NAME0]。例如：
```
custom.googleapis.com/my_measurement
custom.googleapis.com/instance/network/received_packets_count
custom.googleapis.com/instance/network/sent_packets_count
```
命名方式建議採用階層式，讓使用者更容易追蹤指標。指標類型不得包含連字號；如需確切的命名規則，請參閱「命名指標類型和標籤」。
最多 10 個標籤，用於註解指標資料，例如 device_name、fault_type 或 response_code。指標描述元中未指定標籤的值。
資料點的種類和值類型，例如「類型為 double 的計量表值」。詳情請參閱 MetricKind 和 ValueType。

時間序列。指標資料點具有下列重要部分：

相關聯指標描述元的類型。
所有指標描述元標籤的值。
與指標描述元的類型和種類一致的含時間戳記值。
受監控的資源，也就是資料的來源，通常是 VM 執行個體。系統會內建資源的空格，因此描述元不需要為其分隔標籤。

建立指標描述元

您不必預先建立指標描述元。當資料點抵達 Monitoring 時，系統會使用該點的指標類型、標籤和值，自動建立計量表或累計指標描述元。詳情請參閱「自動建立指標描述元」。

但是，建立自己的指標描述元有一些好處：

您可為指標及其標籤納入一些體貼的說明文件。
您可以指定指標的其他種類與類型。代理程式唯一支援的 (種類、類型) 組合為 (GAUGE、DOUBLE) 與 (CUMULATIVE、INT64)。詳情請參閱「指標種類和值類型」。
您可以指定 STRING 以外的標籤類型。

如果您將資料點寫入 Monitoring，但使用的指標類型未定義，系統就會為該資料點建立新的指標描述元。如果您要偵錯寫入指標資料的程式碼，這種行為可能會造成問題，因為指標類型拼字錯誤會導致指標描述元不實。

在您建立指標描述元之後，或在系統為您建立指標描述元之後，就無法對指標描述元進行變更。例如，您無法新增或移除標籤。您只能刪除指標描述元 (這樣會刪除其所有資料)，然後以您想要的方式重新建立描述元。

如要進一步瞭解如何建立指標描述元，請參閱「建立指標」。

定價

如要瞭解 Cloud Monitoring 的定價，請參閱「Google Cloud Observability 定價」頁面。

限制

Cloud Monitoring 會限制每個專案中的指標時間序列數量，以及使用者定義的指標描述元數量。詳情請參閱「配額與限制」。

如果您發現自己建立的指標描述元不再需要，可以使用 Monitoring API 尋找並刪除描述元。詳情請參閱 projects.metricDescriptors。

疑難排解

本節說明如何設定 Monitoring 代理程式的 write_log 外掛程式，傾印整組指標點，包括中繼資料。這可以用來判定哪些資料點需要轉換，以及確保您的轉換行為能夠符合預期。

啟用 write_log

write_log 外掛程式包含在 stackdriver-agent 套件中。如要啟用外掛程式，請按照下列步驟操作：

以 root 身分編輯下列設定檔：
```
/etc/stackdriver/collectd.conf
```
在 LoadPlugin write_gcm 後方新增：
```
LoadPlugin write_log
```
在 <Plugin "write_gcm">…</Plugin> 後方新增：
```
<Plugin "write_log">
  Format JSON
</Plugin>
```
搜尋 <Target "write">…</Target>，並在每個 Plugin "write_gcm" 後方新增：
```
Plugin "write_log"
```
儲存變更並重新啟動代理程式：
```
sudo service stackdriver-agent restart
```

這些變更會為回報的每個指標值列印一行記錄，包括完整的 collectd ID、中繼資料項目和值。

write_log 的輸出

如果上一個步驟成功，您應該會在系統記錄中看到 write_log 的輸出內容：

以 Debian 為基礎的 Linux：/var/log/syslog
以 Red Hat 為基礎的 Linux：/var/log/messages

以下範例行已經過格式設定，使其更容易在本文件中閱讀。

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