StatsD is a protocol for submitting metrics and a daemon for metric dataaggregation. By configuring the Monitoring agent's StatsD plugin,you make the agent function as a StatsD daemon that writes metrics toMonitoring.

Using the StatsD plugin with its default configuration is the easiest way to getyour user-defined metrics into Monitoring. The StatsD plugin isonly available in the Linux Stackdriver Monitoring agent.

The Monitoring agent can also export other collectdmetrics as user-defined metrics, but there is no simple default configuration.SeeUser-defined metrics from the agent for details.

This functionality is only available for agents running on Linux. It isnot available on Windows.

Discovery

Monitoring doesn't automatically detect StatsD. To use StatsDmetrics, configure the StatsD plugin as described in the next section.

Configuring the StatsD plugin

Prerequisites

The StatsD plugin requires version 5.5.2-356 or later of theMonitoring agent. To update the agent, seeUpdating the agent.

Enabling the plugin

Do the following on your supported VM instance running Linux:

1. Downloadstatsd.conf and place it in/etc/stackdriver/collectd.d/, using the following command:

   (cd /etc/stackdriver/collectd.d/ && sudo curl -O https://raw.githubusercontent.com/Stackdriver/stackdriver-agent-service-configs/master/etc/collectd.d/statsd.conf)

2. The default configuration file instructs the agent to accept StatsD metricson the default StatsD port,8125.

   If you want to send some metrics to your own StatsD daemon and other metricsto the agent's StatsD daemon, then change the port settings in theconfiguration file.

3. Restart the Monitoring agent to pick up the StatsD configurationby running the following command:

   sudo service stackdriver-agent restart

For more information on thecollectdstatsd plugin, seePlugin:StatsD.

Default mapping to user-defined metrics

To get you started quickly, the agent's StatsD plugin comes with a defaultcollectd configuration that maps from StatsD metrics to Stackdriveruser-defined metrics:

• All metrics from the StatsD plugin havestatsd in the collectdplugincomponent.

• Each StatsDmetric type—held in the collectdtypecomponent—has a corresponding user-defined metric type name.

• The StatsDmetric name—held in the collectdtype_instancecomponent—is stored as the value of a label namedmetric.

  The value of themetric label is different for the metric typeTimer: itincludes both the metric name and a counter name: average, upper, lower,sum, percentile-50, and percentile-95.

For example, the following table shows how the supported StatsD metric types andthe metric's name are mapped to Monitoring user-defined metrics:

Notes:
¹ There is an incoming sequence of statsd timer metrics with thesame name. The agent aggregates StatsD timer metrics and exports summary datato 7 different time series.

For more information on StatsD types, see theStatsD specification.

Customizing exported metrics

The default StatsD configuration is designed to get you started quickly. Thissection helps you customize the configuration to suit more complex needs.

You should be familiar with user-defined metrics. For anintroduction to metrics, seeMetrics, Time Series, and Resources.For more information, seeUser-defined metrics overview.

You can customize the following things:

• You can change the values assigned to the defaultmetric label. Using morelabel values results in more time series in your user-defined metric.Using fewer label values results in fewer time series.

• You can change the user-defined metric types. You don't have to use thepredefined types provided in the default configuration. For example,you could identify metrics with a certain name and use a differentuser-defined metric type for them.

• If you change the user-defined metric types, then you can can also changethe labels associated with each type. The default configuration has a singlelabel, but you can add more labels or change the label key.

If you change the metric types, you should define your new user-defined metrictypes in the Monitoring API. For details, see the following section,Designing a metric type.

Example

Assume that you are using StatsD to monitor an application consisting of twoservices,my_service_a andmy_service_b. For each service, you want toexport to Monitoring a counter metric that represents the number offailed requests. You don't want to use the default StatsD metric types.

Incoming collectd metrics

Before defining your own metric types, it is important to understand thestructure of a collectd metric and how a StatsD metric by default maps intouser-defined metrics.

Collectd metrics, including StatsD metrics, include the following components:

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

In this example, the StatsD metrics that you want to export have the followingidentifiers in collectd:

Notes:
¹ The StatsD plugin currently leaves this component empty.
² A StatsD Counter metric is mapped to the collectdderive type.³ For example, a type instance might bemy_service_a.GET.500.⁴ [VALUE] is typically a timestamp and a double-precision number.

The following table shows how this metric would be mapped by default:

The default mapping might present some difficulties for you:

• This particular counter metric ([SERVICE_NAME].GET.[CODE]) is in the sameuser-defined metric type as all other counter metrics. You can't easily getjust this metric's data, because Stackdriver doesn't presently supportregular expression searches on labels.

• You can't easily get data for individual services or individual responsecodes in your data. For example, you can't easily get the total number oferrors (of all kinds) that occurred inmy_service_a.

• The default configuration exports all StatsD metrics to Stackdriver, whichcould be costly if you are only interested in certain metrics.

Designing a metric type

For a full discussion of creating metric types, seeCreate a user-defined metric type.

The following user-defined metric type is a reasonable choice for the data inthis example, because it holds only the StatsD metric you are interested in andbecause its choice of labels helps to better organize the data:

• Type:custom.googleapis.com/http/request_errors
• Labels:
  • service_name (STRING): The name of the service.
  • response_code (INT64): The HTTP response code.
• Kind: CUMULATIVE
• Value type: INT64

The following table shows the desired mapping from StatsD to Stackdriver:

Once you've designed the metric type, create it usingmetricDescriptors.create.For information about letting Monitoring create the metric typefor you, seeAuto-creation of metric descriptors.

Mapping configuration

To export the StatsD metric to the new user-defined metric type,replace the contents of the default StatsD plugin configuration,/etc/stackdriver/collectd.d/statsd.conf,with the following code:

<Pluginstatsd>Host"127.0.0.1"Port"8125"DeleteSetstrueTimerPercentile50.0TimerPercentile95.0TimerLowertrueTimerUppertrueTimerSumtrueTimerCounttrue</Plugin>LoadPluginmatch_regexLoadPlugintarget_setLoadPlugintarget_replace#Insertanewruleinthedefault"PreCache"chain,todivertyourmetrics.PreCacheChain"PreCache"<Chain"PreCache">#Thefollowingruledoesalltheworkforyourmetric:<Rule"rewrite_request_errors">#Doacarefulmatchforjustyourmetrics;ifitfails,dropdown#tothenextrule:<Matchregex>Plugin"^statsd$"TypeInstance"^.*\\.GET\\..*$"#Matchontypeinstance.</Match><Target"set">#Specifythemetricdescriptortype:MetaData"stackdriver_metric_type""custom.googleapis.com/http/request_errors"#Initializethelabelsfromthe"type_instance"label;cleanthevaluesupinthenextTargetbelow.MetaData"label:service_name""%{type_instance}"MetaData"label:response_code""%{type_instance}"</Target><Target"replace">#Remove".GET.[code]"togettherealservicename.MetaData"label:service_name""\\.GET\\.[0-9]*$"""#Remove"[service].GET."togettherealresponsecode.MetaData"label:response_code""^[^\\.]*\\.GET\\."""</Target></Rule></Chain>

sudo service stackdriver-agent restart

Customizing the StatsD plugin is the same as customization of collectdmetrics for Monitoring.For more information, see the Reference and Troubleshootingsections ofUser-defined metrics from the agent.