本頁面由 Cloud Translation API 翻譯而成。

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

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

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

將應用程式指標匯出至 Monitoring 的另一個替代方法是使用 StatsD。Cloud Monitoring 提供預設設定，可將 StatsD 指標對應至使用者定義指標。如果您對該對應感到滿意，就不需要如下所述的自訂步驟。詳情請參閱 StatsD 外掛程式。

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

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

事前準備

在 VM 執行個體上安裝最新版 Monitoring 代理程式，並驗證其是否可正常運作。如要更新代理程式，請參閱更新代理程式一文。
設定 collectd 以從應用程式取得監控資料。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。
收錄的指標。其他所有收集的指標會使用內部 API 傳送至 Monitoring。只有收錄的指標清單中的指標會獲得接受及處理。
捨棄的指標。針對未在收錄的指標清單且並非使用者定義指標的 Collectd 指標，Monitoring 會予以捨棄，而不會產生任何通知。代理程式本身並不知道哪些指標會獲得接受或捨棄。

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

您將設定代理程式，將指標資料點傳送至 Monitoring。每個指標資料點都必須與您使用指標描述元定義的使用者定義指標相關聯。「指標、時間序列和資源」一文中有相關概念簡介；如需詳細說明則請參閱「時間序列結構」和「使用者定義指標總覽」。

您可將正確的中繼資料新增至指標，以將 collectd 指標當成使用者定義指標處理：

stackdriver_metric_type：(必要) 所匯出之指標的名稱。範例：custom.googleapis.com/my_custom_metric。
label:[LABEL]：(選用) 匯出指標的其他標籤。例如，如果您需要一個名為 color 的 Monitoring 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 方面，請為使用者定義的指標設計指標描述元。以下描述符是本例資料的合理選擇：

名稱：custom.googleapis.com/nginx/active_connections
標籤：
- service_name (文字)：連線至 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。指標描述元中未指定標籤的值。
資料點的種類和值類型，例如「倍精準數類型的取樣值」。詳情請參閱 MetricKind 和 ValueType。

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

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

建立指標描述元

您不必事先建立指標描述元。當資料點傳送至監控時，系統會使用該點的指標類型、標籤和值，自動建立量測儀或累積指標描述符。詳情請參閱「自動建立指標描述元」。

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

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

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

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

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

定價

一般來說，Cloud Monitoring 系統指標是免費的，但外部系統、代理程式或應用程式的指標則不包含在內。計費指標會依據擷取的位元組數或樣本數計費。

如要進一步瞭解 Cloud Monitoring 的定價，請參閱下列文件：

限制

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