此页面由 Cloud Translation API 翻译。

代理中用户定义的指标

本指南介绍如何配置 Monitoring 代理以识别您的应用指标并将其导出到 Cloud Monitoring。

Monitoring 代理是一个 collectd 守护进程。除了将许多预定义的系统和第三方指标导出到 Cloud Monitoring 之外，该代理还可以将您自己 collectd 应用指标作为用户定义指标导出到 Monitoring。您的 collectd 插件也可以导出到 Monitoring。

将应用指标导出到 Monitoring 的另一种方法是使用 StatsD。Cloud Monitoring 提供默认配置，从 StatsD 指标切换到用户定义的指标。如果您对该映射感到满意，则无需执行下述自定义步骤。如需了解详情，请参阅 StatsD 插件。

如需详细了解指标，请参阅以下文档：

此功能仅适用于在 Linux 上运行的代理。此功能不适用于 Windows。

准备工作

在虚拟机实例上安装最新的 Monitoring 代理，并验证其是否能正常工作。要更新您的代理，请参阅更新代理。
配置 collectd，以便从应用中获得监控数据。 Collectd 通过其读取插件支持多个应用框架和标准监控端点。找到适合您的读取插件。
（可选）为方便起见，您可以将代理的 collectd 参考文档添加到您系统的 man 页面，方法是更新 MANPATH 变量并运行 mandb：
```
export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
sudo mandb
```
手册页面适用于 stackdriver-collectd。

重要文件和目录

通过安装代理创建的以下文件和目录与使用 Monitoring 代理 (collectd) 相关：

/etc/stackdriver/collectd.conf: 代理使用的 collectd 配置文件。请修改此文件以更改常规配置。

注意：Monitoring 代理不使用系统默认的 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: 代理的 init 脚本。

Monitoring 如何处理 collectd 指标

在后台，Monitoring 代理会处理 collectd 指标并将其发送到 Monitoring，Monitoring 会将每个指标视为以下类别中的一个：

用户定义的指标。具有元数据键的 collectd 指标 stackdriver_metric_type 和单个处理数据源时指定为用户定义的指标，并发送到使用 projects.timeSeries.create 方法。
特选指标。所有其他 collectd 指标都是通过内部 API 发送到 Monitoring 的。仅接受和处理特选指标列表中的指标。
舍弃的指标。精选指标中没有的 collectd 指标非用户定义的指标会被系统以静默方式舍弃，监控。代理本身不知道哪些指标被接受或被舍弃。

使用代理写入用户定义的指标

您可以将代理配置为将指标数据点发送到监控。每个点都必须与一个用户定义的指标，您可以使用指标描述符进行定义。如需了解这些概念，请参阅指标、时序和资源时序的结构和用户定义的指标概览。

您可以通过以下方法将 collectd 指标视为用户定义的指标为指标添加适当的元数据：

stackdriver_metric_type：（必填）导出的指标的名称。示例：custom.googleapis.com/my_custom_metric。
label:[LABEL]：（可选）导出指标的附加标签。例如，如果您想要一个名为 color 的 Monitoring STRING 标签，则您的元数据键将为 label:color，该键的值可以是 "blue"。每个指标类型最多可以有 10 个标签。

您可以使用 collectd 过滤条件链来修改指标的元数据。由于过滤条件链无法修改数据源列表，并且用户定义的指标仅支持单个数据源、任何 collectd 指标您要用于此设施的数据源必须具有单一数据源。

示例

在此示例中，我们将监控来自两个 Nginx 服务（my_service_a 和 my_service_b）的活动 Nginx 连接。我们会将这些信息发送给使用用户定义的指标进行监控。具体步骤如下：

识别每个 Nginx 服务的 collectd 指标。
定义 Monitoring 指标描述符。
配置 collectd 过滤条件链，以将元数据添加到 collectd 指标，从而满足 Monitoring 代理的期望。

传入的 collectd 指标

Collectd 预计指标将由以下组件组成：前五个组件构成指标的 collectd 标识符：

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

在本示例中，您希望作为用户定义的指标发送的指标具有以下值：

组件	预期值
主机	任何
插件	`curl_json`
插件实例	`nginx_my_service_a` 或 `nginx_my_service_b`¹
类型	`gauge`
类型实例	`active-connections`
`[value]`	任意值²

备注：
¹ 在此示例中，该值对应用 (Nginx) 和已连接服务的名称进行编码。
² 该值通常是一个时间戳，且是双精度数字。Monitoring 负责处理有关解读各种类型的值。以下字段不支持复合值： Monitoring 代理。

Monitoring 指标描述符和时间序列

在 Monitoring 中，为您的用户定义指标设计指标描述符。对于数据：

名称：custom.googleapis.com/nginx/active_connections
标签：
- service_name（STRING）：与 Nginx 关联的服务的名称。
种类：GAUGE
类型：DOUBLE

设计好指标描述符后，您可以使用 projects.metricDescriptors.create, 也可以让 Google 为您从时序元数据中选取，如下文所述。如需了解详情，请参阅此页面中的创建指标描述符。

鉴于指标描述符的定义方式，该指标描述符的时间序列数据必须包含以下信息：

指标类型：custom.googleapis.com/nginx/active_connections
指标标签值：
- service_name："my_service_a" 或 "my_service_b"

对于所有指标，代理会自动获取其他时间序列信息，包括相关联的受监控资源（发送数据的虚拟机实例）和指标的数据点。您无需执行任何特殊操作。

您的过滤条件链

创建一个文件，/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>

加载新配置

通过在虚拟机实例上执行以下命令，重启您的代理以选择新配置：

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。

时间序列。指标数据点具备以下重要部分：

关联的指标描述符的类型。
所有指标描述符标签的值。
与指标描述符的值类型一致的带时间戳的值，以及种类。
数据所属的受监控的资源，通常是虚拟机实例。资源的空间是内置的，因此描述符不需要单独的标签。

创建指标描述符

您不必提前创建指标描述符。当数据点到达 Monitoring 时，系统可使用该数据点的指标类型、标签和值自动创建 gauge 或 cumulative 指标描述符。如需了解详情，请参阅自动创建指标描述符。

不过，自行创建指标描述符具有以下优势：

您可以为指标及其标签添加一些周到的文档。
您可以指定其他指标种类和类型。代理仅支持下列（种类，类型）组合：(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 标识符、元数据条目和值）打印一行日志。

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