PMDASTATSD(1)

📦
version 7.2.2 · 3 versions
, in fedora 43, fedora 44

PMDASTATSD 💅✨

ok so this is the manual for pmdastatsd — like, from the General Commands Manual section (section 1, bestie). It's the StatsD protocol performance metric domain agent (PMDA). Yeah. We're doing this. Grab a snack 🍓

🌸 NAME 🌸

pmdastatsd — the StatsD protocol performance metric domain agent (PMDA). that's the whole name section, she's short and she knows it 💖

✨ SYNOPSIS ✨

$PCP_PMDAS_DIR/statsd/pmdastatsd [-D debug] [-Z maximum udp packet size]
[-P port] [-v] [-g] [-o debug output filename] [-s] [-r parser type] [-a
port] [-z maximum of unprocessed packets]

no cap that's a LOT of flags but we'll get through them together 🫶

💜 DESCRIPTION 💜

okay so picture this: StatsD is a simple, text-based UDP protocol for receiving monitoring data of applications, and it lives in a client-server architecture. very demure, very mindful.

pmdastatsd is a Performance Metrics Domain Agent that scoops up StatsD data, aggregates it, and makes it available to literally any Performance Co-Pilot client. which is ideal for easily tracking stats in your application. iconic behaviour honestly.

the statsd PMDA supports these metric types: Counter, Gauge, and Duration — and Duration comes with instances for minimum, maximum, median, average, 90th percentile, 95th percentile, 99th percentile, count and standard deviation. she's thorough 💅

she also offers:

  • multiple parsing options: Ragel or handwritten/custom parser 🌈
  • multiple aggregating options for the duration metric type: basic histogram or HDR histogram 🎀
  • support for a custom form of labels
  • logging
  • exports of multiple metrics about herself (self-obsessed, we love that for her 👑)
  • and she may be configured either with an ini file or command line options

🎀 CONFIGURATION 🎀

here's the tea on the pmdastatsd command line options, bestie:

  • -Z, --max-udp=<value> — the maximum allowed packet size. anything larger than this gets thrown away 🗑️. Default: 1472
  • -P, --port=<value> — which port the agent will listen to for incoming traffic. Default: 8125
  • -v, --verbose — verbosity level. prints info about agent execution into the logfile. valid values are 0-2.
    • 0 = the default value. shows config information, read socket state, and the first 100 dropped messages.
    • 1 = shows PMNS and related information.
    • 2 = the most detailed verbosity level, and also shows dropped messages above 100.
    • and yeah, all levels include those below them. nesting doll vibes 🪆
  • -o, --debug-output-filename=<value> — you can send a USR1 signal that 'asks' the agent to output basic information about all aggregated metrics into a $PCP_LOG_DIR/pmcd/statsd_{name} file. Default: 0
  • -s, --version — a flag controlling whether or not to log the current agent version on start. Default: 0
  • -p, --parser-type=<value> — a flag specifying which parser to use for incoming packets; Basic = 0, Ragel = 1. the Ragel parser includes better logging when verbose = 2. Default: 0
  • -a, --duration-aggregation-type=<value> — a flag specifying which aggregation scheme to use for duration metrics; basic histogram = 0, HDR histogram = 1. Default: 1
  • -z, -max-unprocessed-packets=<value> — the maximum size of the packet queue that the agent will save in memory. there are 2 queues: one for packets that are waiting to be parsed, and one for parsed packets before they are aggregated. Default: 2048

the agent also goes looking for a pmdastatsd.ini file in the $PCP_PMDAS_DIR/statsd directory. and over there you can specify the same options, just with slightly different names, like so:

max_udp_packet_size=<value>
port=<value>
verbose=<value>
debug=<value>
debug_output_filename=<value>
version=<value>
parser_type=<value>
duration_aggregation_type=<value>
max_unprocessed_packets=<value>

if an option shows up in both pmdastatsd.ini and the command line, then the command line wins, periodt. and most of the time you're gonna want to configure the agent with an ini file anyway, because the agent should never be executed directly 🚫 (yes really, put it down).

location of the log file, since you asked: by default, a log file named statsd.log gets written in the current directory of pmcd(1) when pmdastatsd is started — that's $PCP_LOG_DIR/pmcd. and if the log file cannot be created or is not writable, the output goes to standard error instead. flexible queen 💅

🦋 INSTALLATION 🦋

if you wanna install pmdastatsd, do this as root:

# cd $PCP_PMDAS_DIR/statsd
# ./Install

and to uninstall, as root:

# cd $PCP_PMDAS_DIR/statsd
# ./Remove

pmdastatsd is launched by pmcd(1) and should never be executed directly. the Install and Remove scripts are the ones that notify pmcd(1) when the agent is installed or removed. they're the messengers, let them do their job 🫶

✨ USAGE ✨

okay so once you've started her up, pmdastatsd just sits there listening on the port you told her about, waiting for content shaped like this:

<metricname>:<value>|<type>

and bestie, you can pack multiple of those into one single datagram, split by a newline character, so this right here:

<metricname>:<value>|<type>\n<metricname>:<value>|<type>

is completely valid too. and the rules for each of those lil variables? here's the vibe check:

<metricname> = [a-z][a-zA-Z0-9_.]*
<value> = described further in each metric type subsection
<type> = One of the following: c , g or ms

if you've got verbose logging turned on, the agent will literally log every single message it parses, plus all the related failures. no secrets, she's an open book 💖

and every recorded metric, if it got parsed and aggregated successfully, gets made available under the statsd.* namespace. slay.

🌸 1 Counter metric 🌸

stores metrics as simple counters — she just adds whatever comes in to whatever's already there. simple as.

<metricname>:<value>|c

where value is a positive number.

Example:

after aggregating these messages:

metric:20|c
metric:10|c
metric:3.3|c

the value available to PCP will be:

# pminfo --fetch statsd.metric

    inst [0 or '/'] value 33.3

🦋 2 Gauge metric 🦋

stores metrics as modifiable values, and you've got options — you can either set, increment or decrement them. main character energy tbh.

<metricname>:<value>|g

where value can be in a form of:

  • '-{value}' — when a negative value is supplied, the agent will subtract the value stored with the value passed
  • '+{value}' — when a positive value with a leading plus sign is supplied, the agent will add the passed value to the value stored
  • '{value}' — when a value without any leading sign is supplied, the agent will set the metric to the passed value

the initial value for a metric of gauge type is 0.

Example:

after aggregating these messages:

metric:20|g
metric:+10|g
metric:-3.3|g

the value available to PCP will be:

# pminfo --fetch statsd.metric

    inst [0 or '/'] value 26.7

🎀 3 Duration metric 🎀

aggregates values either via HDR histogram or just straight up stores all the values and then calculates instances from every value it received.

<metricname>:<value>|ms

where value is a positive number.

Example:

with a larger message count, the values may vary based on the selected duration aggregation scheme. (iykyk)

after aggregating these messages:

metric:10|ms
metric:20|ms

the 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 a given metricname with a specified type, the agent will no longer aggregate any messages with the same metricname but a different type — she'll just throw them away. periodt. 💀

💜 4 Labels 💜

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

metric,tagX=X,tagW=W:5|c

OR

metric:5|ms|#tagX:X,tagW:W

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

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

both formats are interchangeable and you may combine them together. when a key is not unique, the right most value takes precedence. so this is valid:

metric,tagX=1:5|c|#tagX:2

the pair with key tagX will have value of 2. the way that just works ✨

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 the resulting instance name and label descriptor.

Single label:

metric,tagX=X:5|c

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 a payload with multiple labels. when multiple labels are supplied they are split in the instance name by '::'. Example:

metric,tagX=X,tagW=W:5|c

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 a labeled value to such a metric creates another 9 (as there are that many hardcoded) instances. yes really. 🙈

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 the instance name in the following manner:

# pminfo --fetch --labels statsd.metric

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

👑 5 Hardcoded stats 👑

the agent also exports metrics about herself — she's got main character energy and she's keeping receipts:

  • 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 be processed. and while it's not yet reserved, the whole statsd.pmda.* namespace is not recommended to use for user metrics. don't do it bestie, just don't.

📁 FILES 📁

  • $PCP_PMCDCONF_PATH — command line options used to launch pmdastatsd
  • $PCP_PMDAS_DIR/statsd/Install — installation script for the pmdastatsd agent
  • $PCP_PMDAS_DIR/statsd/Remove — undo installation script for the pmdastatsd agent
  • $PCP_LOG_DIR/pmcd/statsd.log — default log file for error messages and other information from pmdastatsd

🌈 PCP ENVIRONMENT 🌈

environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. on each installation, the file /etc/pcp.conf contains the local values for these variables. the $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

🔥 DEBUGGING OPTIONS 🔥

the -D or --debug option enables the output of additional diagnostics on stderr to help triage problems, although ngl the information is sometimes cryptic and primarily intended to provide guidance for developers rather than for end-users. debug is a comma separated list of debugging options; use pmdbg(1) with the -l option to obtain a list of the available debugging options and their meaning.

🫶 SEE ALSO 🫶

PCPIntro(1), pmcd(1), pcp.conf(5) and pcp.env(5).

and that's the whole page, bestie!! 💖✨ this one comes to you from the Performance Co-Pilot crew, under the PCP banner, and yes — it's the PMDASTATSD(1) manual page, dated right there in the footer. go forth and statsd responsibly 🎀🦋💅

📦 where this page comes from