# pmdastatsd

## NAME



           **pmdastatsd** - **StatsD** protocol performance metric domain agent
           (PMDA)
    


## 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_]
    


## DESCRIPTION



           **StatsD** is simple, text-based UDP protocol for receiving monitoring
           data of applications in architecture client-server.  **pmdastatsd** is
           an Performance Metrics Domain Agent that collects **StatsD** data,
           aggregates them and makes them available to any Performance Co-
           Pilot client, which is ideal for easily tracking stats in your
           application.
    
           The **statsd** PMDA supports Counter, Gauge and Duration (with
           instances for minimum, maximum, median, average, 90th percentile,
           95th percentile, 99th percentile, count and standard deviation)
           metric types, offers multiple parsing options: **Ragel** or
           **handwritten/custom parser** , offers multiple aggregating options for
           duration metric type: **basic histogram** or **HDR histogram** , supports
           custom form of **labels** , **logging** , exports multiple metrics about
           itself and may be configured either with an ini file or command
           line options.
    


## CONFIGURATION



           A brief description of the **pmdastatsd** command line options
           follows:
    
           **-Z, --max-udp= <value>**
                Maximum allowed packet size, any larger then this will be
                thrown away.  Default: _1472_
    
           **-P, --port= <value>**
                Which port agent will listen to for incoming traffic.
                Default: _8125_
    
           **-v, --verbose**
                Verbosity level.  Prints info about agent execution into
                logfile. Valid values are 0-2. 0 = Default value, shows
                config information, read socket state, and first 100 dropped
                messages. 1 = Shows PMNS and related information. 2 = Most
                detailed verbosity level, also shows dropped messages above
                100.  All levels include those below.
    
           **-o, --debug-output-filename= <value>**
                You can send USR1 signal that 'asks' agent to output basic
                information about all aggregated metric into a
                $PCP_LOG_DIR/pmcd/statsd_{name} file.  Default: _0_
    
           **-s, --version**
                Flag controlling whether or not to log current agent version
                on start.  Default: _0_
    
           **-p, --parser-type= <value>**
                Flag specifying which parser to use for incoming packets;
                Basic = _0_ , Ragel = _1._  Ragel parser includes better logging
                when verbose = _2._  Default: _0_
    
           **-a, --duration-aggregation-type= <value>**
                Flag specifying which aggregation scheme to use for duration
                metrics; basic histogram = _0_ , HDR histogram = _1_.  Default: _1_
    
           **-z, -max-unprocessed-packets= <value>**
                Maximum size of 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 looks for a _pmdastatsd.ini_ file in the
           **$PCP_PMDAS_DIR/statsd** directory.  There, the same options may be
           specified, albeit with slightly different names as follows:
    
                **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>**
    
           Should an option be specified in both _pmdastatsd.ini_ and command
           line, then the latter takes precedence.  Most of the time you will
           want to configure the agent with an ini file, as the agent should
           never be executed directly.
    
           Location of the log file.  By default, a log file named _statsd.log_
           is written in the current directory of pmcd(1) when **pmdastatsd** is
           started, i.e.  **$PCP_LOG_DIR/pmcd**.  If the log file cannot be
           created or is not writable, output is written to standard error
           instead.
    


## INSTALLATION



           If you want to install the **pmdastatsd** , do the following as root:
    
                # cd $PCP_PMDAS_DIR/statsd
                # ./Install
    
           To uninstall, do the following 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 notify pmcd(1) when the
           agent is installed or removed.
    


## USAGE



           Once started, **pmdastatsd** will listen on specified _port_ for any
           content in a form of:
    
               **< metricname>:<value>|<type>**
    
           There may be multiple such messages in single datagram, split by a
           newline character, so this:
    
               **< metricname>:<value>|<type>\n<metricname>:<value>|<type>**
    
           is valid as well.  Constraints for each of the above variables
           are:
    
               **< 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 _verbose_ logging is turned on, agent will log every message
           parsed and related failures.
    
           All recorded metrics will, if parsed and aggregated successfully,
           be made available under **statsd.*** namespace.
    
       **1 Counter metric**
           Stores metrics as simple counters, adding any incoming values to
           already existing ones.
    
               **< metricname>:<value>|c**
    
           Where **value** is positive number.
    
           **Example:**
    
           After aggregating following messages:
    
               **metric:20|c**
               **metric:10|c**
               **metric:3.3|c**
    
           Value available to PCP will be:
    
               # pminfo --fetch statsd.metric
    
                   inst [0 or '/'] value 33.3
    
       **2 Gauge metric**
           Stores metrics as modifiable values, with an option to either set,
           increment or decrement values.
    
               **< metricname>:<value>|g**
    
           Where **value** can be in a form of:
    
               **'-{value}'** , when negative value is supplied agent will
               subtract value stored with the value passed
    
               **'+{value}'** , when 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.
    
           Initial value for metric of gauge type is 0.
    
           **Example:**
    
           After aggregating following messages:
    
               **metric:20|g**
               **metric:+10|g**
               **metric:-3.3|g**
    
           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 simply stores all
           values and then calculates instances from all values received.
    
               **< metricname>:<value>|ms**
    
           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:
    
               **metric:10|ms**
               **metric:20|ms**
    
           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.
    
       **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_ 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:
    
               **metric,tagX=1:5|c|#tagX:2**
    
           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:
    
               **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 payload with multiple labels.
           When multiple labels are supplied they are split in 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 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'}
                   ...
    
       **5 Hardcoded stats**
           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.
    


## 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 the
           information is sometimes cryptic and primarily intended to provide
           guidance for developers rather 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.
    


* * *