StatsD 插件

StatsD 是一种用于提交指标的协议,也是一种用于指标数据聚合的守护进程。通过配置 Monitoring 代理的 StatsD 插件,可以使代理用作向 Monitoring 写入指标的 StatsD 守护进程。

使用 StatsD 插件及其默认配置是将用户定义的指标写入 Monitoring 的最简单的方法。StatsD 插件仅在 Linux Stackdriver Monitoring 代理中可用。

Monitoring 代理还可以将其他 collectd 指标导出为用户定义的指标,但没有简单的默认配置。如需了解详情,请参阅代理中用户定义的指标

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

《发现》杂志

Monitoring 不会自动检测 StatsD。要使用 StatsD 指标,请按照下一部分中的说明配置 StatsD 插件。

配置 StatsD 插件

前提条件

StatsD 插件需要 5.5.2-356 或更高版本的 Monitoring 代理。要更新代理,请参阅更新代理

启用插件

在运行 Linux 且受支持的虚拟机实例上执行以下操作:

  1. 下载 statsd.conf,并使用以下命令将其放置在 /etc/stackdriver/collectd.d/ 中:

    (cd /etc/stackdriver/collectd.d/ && sudo curl -O https://raw.githubusercontent.com/Stackdriver/stackdriver-agent-service-configs/master/etc/collectd.d/statsd.conf)
    
  2. 默认配置文件会指示代理接受默认 StatsD 端口 8125 上的 StatsD 指标。

    如果想将一些指标发送到您自己的 StatsD 守护进程,将其他指标发送到代理的 StatsD 守护进程,请更改配置文件中的端口设置。

  3. 通过运行以下命令,重启 Monitoring 代理以选择 StatsD 配置:

    sudo service stackdriver-agent restart
    

如需详细了解 collectd statsd 插件,请参阅 Plugin:StatsD

到用户定义的指标的默认映射

为了帮助您快速上手,代理的 StatsD 插件附带了默认的 collectd 配置,可将 StatsD 指标映射到 Stackdriver 用户定义的指标:

  • 来自 StatsD 插件的所有指标都在 collectd plugin 组成部分中具有 statsd

  • 在 collectd type 组成部分中保存的每个 StatsD 指标类型都具有对应的用户定义的指标类型名称。

  • 在 collectd type_instance 组成部分中保存的 StatsD 指标名称存储为名为 metric 标签的值。

    metric 标签的值不同于指标类型 Timer:它包括指标名称和一个计数器名称:average、upper、lower、sum、percentile-50、percentile-95。

例如,下表显示了支持的 StatsD 指标类型和指标名称与 Monitoring 用户定义指标之间的映射方式:

StatsD 类型 StatsD 名称 Stackdriver 指标类型 指标种类 值类型 指标标签
计数器 my.counter custom.googleapis.com/statsd/derive 累计 Int64 metric:my.counter
采样平均值 my.gauge custom.googleapis.com/statsd/gauge 采样平均值 双精度浮点数 metric:my.gauge
设置 my.set custom.googleapis.com/statsd/objects 采样平均值 双精度浮点数 metric:my.set
计时器 1 my.timer custom.googleapis.com/statsd/latency 采样平均值 双精度浮点数 metric:my.timer-average
(相同) (相同) (相同) metric:my.timer-upper
(相同) (相同) (相同) metric:my.timer-lower
(相同) (相同) (相同) metric:my.timer-sum
(相同) (相同) (相同) metric:my.timer-percentile-50
(相同) (相同) (相同) metric:my.timer-percentile-95
custom.googleapis.com/statsd/gauge 采样平均值 (相同) metric:my.timer-count

注意
1 有一个具有相同名称的 statsd 计时器指标的传入序列。代理会汇总 StatsD 计时器指标,并将摘要数据导出到 7 个不同的时间序列。

如需详细了解 StatsD 类型,请参阅 StatsD 规范

自定义导出的指标

默认的 StatsD 配置旨在让您快速上手。本部分可帮助您自定义配置,以适应更复杂的需求。

您需要熟悉用户定义的指标。如需了解指标,请参阅指标、时间序列和资源。如需了解详情,请参阅用户定义的指标概览

您可以自定义以下内容:

  • 您可以更改分配给默认 metric 标签的值。使用的标签值越多,用户定义的指标中产生的时序就越多。使用的标签值越少,产生的时序就越少。

  • 您可以更改用户定义的指标类型。您不必使用默认配置中提供的预定义类型。例如,您可以使用特定名称标识指标,并为它们使用不同的用户定义指标类型。

  • 如果您更改用户定义的指标类型,则还可以更改与每种类型关联的标签。默认配置有单个标签,但您可以添加更多标签或更改标签键。

如果您更改指标类型,则应在 Monitoring API 中定义新的用户定义指标类型。如需了解详情,请参阅下一部分,即设计指标类型

示例

假设您在使用 StatsD 监控一个包括 my_service_amy_service_b 两项服务的应用。对于每项服务,您希望将表示失败请求数量的计数器指标导出到 Monitoring。您不想使用默认的 StatsD 指标类型。

传入的 collectd 指标

在定义自己的指标类型之前,请务必了解 collectd 指标的结构,以及默认情况下 StatsD 指标与用户定义的指标之间的映射方式。

包括 StatsD 指标在内的 collectd 指标包含以下组成部分:

    Host, Plugin, Plugin-instance, Type, Type-instance

在此示例中,您要导出的 StatsD 指标在 collectd 中具有以下标识符:

组件 预期值
主机 任何
插件 statsd
插件实例 未设置1
类型 derive2
类型实例 [SERVICE_NAME].GET.[CODE]3
[VALUE] 任意值4

注意
1 StatsD 插件当前将此组成部分留空。
2 StatsD 计数器指标会映射到 collectd derive 类型。3 例如,类型实例可能为 my_service_a.GET.5004 [VALUE] 通常是一个时间戳和一个双精度数字。

下表显示了默认情况下此指标的映射方式:

StatsD 类型 StatsD 名称 Stackdriver 指标类型 指标种类 值类型 指标标签
计数器 my_service_a.GET.500 custom.googleapis.com/statsd/derive 累计 Int64 metric:my_servce_a.GET.500
计数器 my_service_b.GET.403 custom.googleapis.com/statsd/derive 累计 Int64 metric:my_servce_b.GET.403

默认的映射可能会给您带来一些困难:

  • 该特定计数器指标 ([SERVICE_NAME].GET.[CODE]) 与所有其他计数器指标属于相同的用户定义指标类型。您无法轻松地仅获取该指标的数据,因为 Stackdriver 目前不支持对标签进行正则表达式搜索。

  • 您无法轻松获取个别服务的数据,或数据中的个别响应代码。例如,您无法轻松获取 my_service_a 中发生的(所有种类的)错误总数。

  • 默认配置会将所有 StatsD 指标导出到 Stackdriver,如果您只对某些指标感兴趣,则这可能会造成费用过高。

设计指标类型

如需全面了解如何创建指标类型,请参阅创建用户定义的指标类型

以下用户定义的指标类型是本示例中数据的合理选择,因为它仅包含您感兴趣的 StatsD 指标,并且选择的标签有助于更好地整理数据:

  • 类型:custom.googleapis.com/http/request_errors
  • 标签:
    • service_name(STRING):服务的名称。
    • response_code(INT64):HTTP 响应代码。
  • 种类:累计
  • 值类型:INT64

下表显示了 StatsD 到 Stackdriver 的所需映射:

StatsD 类型 StatsD 名称 Stackdriver 指标类型 指标种类 值类型 指标标签
计数器 my_service_a.GET.500 custom.googleapis.com/http/request_errors 累计 Int64 service_name:my_service_a, response_code:500
计数器 my_service_b.GET.403 custom.googleapis.com/http/request_errors 累计 Int64 service_name:my_service_b, response_code:403

设计了指标类型后,请使用 metricDescriptors.create 进行创建。 如需了解如何让 Monitoring 为您创建指标类型,请参阅自动创建指标描述符

映射配置

如需将 StatsD 指标导出到新的用户定义指标类型,请使用以下代码替换默认的 StatsD 插件配置 /etc/stackdriver/collectd.d/statsd.conf 的内容:

<Plugin statsd>
  Host "127.0.0.1"
  Port "8125"
  DeleteSets true
  TimerPercentile 50.0
  TimerPercentile 95.0
  TimerLower true
  TimerUpper true
  TimerSum true
  TimerCount true
</Plugin>

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">
  # The following rule does all the work for your metric:
  <Rule "rewrite_request_errors">
    # Do a careful match for just your metrics; if it fails, drop down
    # to the next rule:
    <Match regex>
      Plugin "^statsd$"
      TypeInstance "^.*\\.GET\\..*$"    # Match on type instance.
    </Match>

    <Target "set">
      # Specify the metric descriptor type:
      MetaData "stackdriver_metric_type" "custom.googleapis.com/http/request_errors"
      # Initialize the labels from the "type_instance" label; clean the values up in the next Target below.
      MetaData "label:service_name" "%{type_instance}"
      MetaData "label:response_code" "%{type_instance}"
    </Target>

    <Target "replace">
      # Remove ".GET.[code]" to get the real service name.
      MetaData "label:service_name" "\\.GET\\.[0-9]*$" ""
      # Remove "[service].GET." to get the real response code.
      MetaData "label:response_code" "^[^\\.]*\\.GET\\." ""
    </Target>
  </Rule>
</Chain>

重启代理

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

sudo service stackdriver-agent restart

您的用户定义的指标信息会立即开始传输至 Monitoring。

后续步骤

自定义 StatsD 插件与为 Monitoring 自定义 collectd 指标相同。如需了解详情,请参阅代理中的用户定义指标的“参考”和“问题排查”部分。