pmdastatsd - Man Page

Stores metrics as simple counters, adding any incoming values to already existing ones.

Where value is positive number.

Example:

After aggregating following messages:

Value available to PCP will be:

# pminfo --fetch statsd.metric

    inst [0 or '/'] value 33.3

Stores metrics as modifiable values, with an option to either set, increment or decrement values.

Where value can be in a form of:

Initial value for metric of gauge type is 0.

Example:

After aggregating following messages:

Value available to PCP will be:

# pminfo --fetch statsd.metric

    inst [0 or '/'] value 26.7

Aggregates values either via HDR histogram or simply stores all values and then calculates instances from all values received.

Where value is a positive number.

Example:

With larger message count, the values may vary based on selected duration aggregation scheme.

After aggregating following messages:

Values available to PCP will be:

# pminfo --fetch statsd.metric

    inst[0 or '/min'] value 10
    inst[1 or '/max'] value 20
    inst[2 or '/median'] value 10
    inst[3 or '/average'] value 15
    inst[4 or '/percentile90'] value 20
    inst[5 or '/percentile95'] value 20
    inst[6 or '/percentile99'] value 20
    inst[7 or '/count'] value 2
    inst[8 or '/std_deviation'] value 5

Note:

Once you send given metricname with specified type, the agent will no longer aggregate any messages with same. metricname but different type and will throw them away.

StatsD datagrams may also contain key:value pairs separated by commas like so:

Where tagX is a key, X is a value and tagW is a key, W is a value.

Both key and value of such a pair are [a-ZA-Z0-9_.]{1,}.

Both formats are interchangeable and you may combine them together. When key is not unique, right most value takes precedence. This is valid:

Pair with key tagX will have value of 2.

You may use these labels to map specific values to some PCP instances. PCP labels are also assigned to these PCP instances. Pairs are ordered by key in resulting instance name and label descriptor.

Single label:

Such a payload would map to PCP as follows (non-related labels were omitted):

# pminfo --fetch --labels statsd.metric

    inst [0 or '/tagX=X'] value 5
    inst [0 or '/tagX=X'] labels {'tagX':'X'}

As shown earlier you may also send payload with multiple labels. When multiple labels are supplied they are split in instance name by '::'. Example:

This resolves to:

# pminfo --fetch --labels statsd.metric

    inst [0 or '/tagX=X::tagW=W'] value 5
    inst [0 or '/tagX=X::tagW=W'] labels {'tagX':'X','tagW':'W'}

Note:

Be mindful of the fact that duration metric type already maps to instances even without any labels. Sending labeled value to such a metric creates another 9 (as there are that many hardcoded) instances.

Example:

metric:200|ms
metric:100|ms
metric,target=cpu2:10|ms
metric,target=cpu2:100|ms
metric,target=cpu2:1000|ms

Creates 18 instances. Duration data type and label name compose instance name in following manner:

# pminfo --fetch --labels statsd.metric

    ...
    inst [10 or '/max::target=cpu0'] value 1000
    inst [10 or '/max::target=cpu0'] labels {'target':'cpu0'}
    ...

Agent also exports metrics about itself:

statsd.pmda.received

Number of datagrams that the agent has received

statsd.pmda.parsed

Number of datagrams that were successfully parsed

statsd.pmda.dropped

Number of datagrams that were dropped

statsd.pmda.aggregated

Number of datagrams that were aggregated

statsd.pmda.metrics_tracked

This metric has 3 instances. counter - Number of tracked counter metrics. gauge - Number of tracked gauge metrics. duration - Number of tracked duration metrics. total - Number of tracked metrics total.

statsd.pmda.time_spent_parsing

Total time in microseconds spent parsing metrics. Includes time spent parsing a datagram and failing midway.

statsd.pmda.time_spent_aggregating

Total time in microseconds spent aggregating metrics. Includes time spent aggregating a metric and failing midway.

statsd.pmda.settings.max_udp_packet_size

Maximum UDP packet size

statsd.pmda.settings.max_unprocessed_packets

Maximum size of unprocessed packets Q

statsd.pmda.settings.verbose

Verbosity flag

statsd.pmda.settings.debug_output_filename

Debug output filename

statsd.pmda.settings.port

Port that is listened to

statsd.pmda.settings.parser_type

Used parser type

statsd.pmda.settings.duration_aggregation_type

Used duration aggregation type

These names are blacklisted for user usage. No messages with these names will processed. While not yet reserved, the whole statsd.pmda.* namespace is not recommended to use for user metrics.