來自代理程式的自訂指標

本指南說明如何設定 Stackdriver Monitoring 代理程式來辨識應用程式指標,以及將該指標匯出至 Stackdriver。

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

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

如果您對 Stackdriver 的自訂指標不熟悉,請參閱指標、時間序列和資源指標類型架構使用自訂指標說明文章。

事前準備

  • 在 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 設定檔。編輯此檔案即可變更一般設定。

/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 指標使用內部 APU 傳送至 Monitoring。只有收錄的指標清單中的指標會獲得接受及處理。

  • 捨棄的指標。針對未在收錄的指標清單且並非自訂指標的 Collectd 指標,Monitoring 會予以捨棄,而不會產生任何通知。代理程式本身並不知道哪些指標會獲得接受或捨棄。

使用代理程式寫入自訂指標

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

您可將正確的中繼資料新增至指標,以將 collectd 指標當成自訂指標處理:

  • stackdriver_metric_type:(必要) 所匯出之指標的名稱。 例如:custom.googleapis.com/my_custom_metric

  • label:[LABEL]:(選用) 匯出之指標的其他標籤。例如,如果您需要一個名為 color 的 Monitoring STRING 標籤,那麼您的中繼資料鍵就會是 label:color,鍵的值可能是 "blue"。每個指標類型最多可以有 10 個標籤。

您可以使用 collectd 篩選器鏈來修改指標的中繼資料。由於篩選器鏈無法修改資料來源的清單,且自訂指標只支援單一資料來源,因此您想要與此服務供應商一起使用的任何 collectd 指標都必須具有單一資料來源。

範例

在此範例中,我們將從兩個 Nginx 服務監控有效的 Nginx 連線,這兩個服務是 my_service_amy_service_b。我們會使用自訂指標將這兩個服務傳送至 Monitoring。請採取下列步驟:

  1. 識別每個 Nginx 服務的 collectd 指標。

  2. 定義 Monitoring 指標描述元。

  3. 設定 collectd 篩選器鏈,將中繼資料新增至 collectd 指標,使其符合 Monitoring 代理程式的期望條件。

連入的 collectd 指標

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

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

在此範例中,您要傳送做為自訂指標的指標具有以下值:

元件 預期的值
主機 不限
外掛程式 curl_json
外掛程式執行個體 nginx_my_service_a
nginx_my_service_b1
類型 gauge
類型執行個體 active-connections
[value] 任何值2

附註
1 在範例中,這個值對應用程式 (Nginx) 與連線的服務名稱進行了編碼。
2 這個值通常是時間戳記與雙精確度數字。 Monitoring 會處理解譯各種值的詳細資料。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 name:
      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 custom metrics. The rule returns to
  # the default "PreCache" chain. The default processing
  # will write all metrics to Stackdriver Monitoring,
  # which will drop any unrecognized metrics: ones that are not
  # in the list of curated metrics and do not have
  # the custom metric metadata.
  <Rule "go_back">
    Target "return"
  </Rule>
</Chain>

載入新設定

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

sudo service stackdriver-agent restart

您的自訂指標資訊將開始流入 Monitoring。

參考資料與最佳做法

指標描述元與時間序列

如需 Stackdriver 指標的介紹,請參閱指標、時間序列和資源一文。更多詳細資料請參閱「使用自訂指標」與「指標類型架構」。

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

  • 格式如下的「名稱」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
    

    自訂指標名稱必須以 custom.googleapis.com/ 開頭。命名方式建議採用階層式,讓使用者更容易追蹤指標。指標名稱不得包含連字號;如需確切的命名規則,請參閱指標與標籤名稱的規則一文。

  • 指標資料最多只能註解 10 個標籤,例如 device_namefault_typeresponse_code。標籤的值不會在指標描述元中指定。

  • 資料點的種類與類型,例如「倍精準數類型的取樣值」。詳情請參閱 MetricKind 以及 ValueType

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

  • 關聯指標描述元的名稱。

  • 所有指標描述元標籤的值。

  • 加上時間戳記的值包含指標描述元的類型與種類。

  • 受控資源資料的來源,通常是 VM 執行個體。系統會內建資源的空格,因此描述元不需要為其分隔標籤。

建立指標描述元

您不必提前建立指標描述元。 當資料點到達 Monitoring 時,資料點的指標名稱、標籤與資料點的值可用來自動建立取樣或累計指標描述元。詳情請參閱自動建立自訂指標一文。

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

  • 您可為指標及其標籤納入一些體貼的說明文件。

  • 您可以指定指標的其他種類與類型。代理程式唯一支援的 (種類、類型) 組合為 (GAUGE、DOUBLE) 與 (CUMULATIVE、INT64)。詳情請參閱指標種類與值類型一文。

  • 您可以指定 STRING 以外的標籤類型。

如果您將資料點寫入至 Monitoring,而 Monitoring 使用未定義的指標名稱,則「將」為資料點建立新指標描述元。如果您正在為編寫指標資料的程式碼偵錯,這就可能會發生問題,因為拼錯指標名稱將會導致產生錯誤的指標描述元。

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

如要進一步瞭解如何建立指標描述元,請參閱定義指標一文。

費用與限制

Stackdriver 會根據收到的指標資料量對 collectd 指標收費,包括使用者定義的指標與代理程式指標。 詳情請參閱 Stackdriver 定價一文。

除了定價以外,Stackdriver 還對每個 GCP 專案中的指標時間序列數目及使用者定義的指標描述元數目設限。 詳情請參閱配額與限制一文。

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

疑難排解

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

啟用 write_log

write_log 外掛程式隨附於 stackdriver-agent 套件,啟用方式如下:

  1. root 身分編輯下列設定檔:

    /etc/stackdriver/collectd.conf
    
  2. LoadPlugin write_gcm 之後,加上:

    LoadPlugin write_log
    
  3. <Plugin "write_gcm">…</Plugin> 之後,加上:

    <Plugin "write_log">
      Format JSON
    </Plugin>
    
  4. 搜尋 <Target "write">…</Target> 並在每個 Plugin "write_gcm" 之後,加上:

    Plugin "write_log"
    
  5. 儲存變更並重新啟動代理程式:

    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"}]
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Stackdriver Monitoring
需要協助嗎?請前往我們的支援網頁