Metricly StatsD


The Metricly StatsD server is already installed as part of the Linux Agent. We recommend setting up a Metricly StatsD integration if you do not have a StatsD server already. The Metricly StatsD integration interprets, aggregates, and forwards custom metrics generated from your application. Using the values instrumented from your application’s key actions and data (method calls, database queries, etc.), Metricly aggregates the values, associates them with corresponding metrics, and analyzes them in our analytics cycles. Metrics are taken into the server using the specified UDP format:|metrictype|@samplerate|#tag1:value1, tag2,
If you have a StatsD server already and want to send your instrumented data to Metricly, we recommend using our Etsy StatsD integration. Read more about the Etsy StatsD integration here.


If you haven’t installed the Linux agent already, see the instructions on this page for how to install it. If you need to disable the Linux integration or view the unique API key assigned to your account, navigate to the Integrations page under the user account drop-down menu and click the integration designated as Infrastructure under the Integration column.

Server Setup

    1. Navigate to the Linux Agent configuration file and open it.
      The configuration file is typically found at /opt/netuitive-agent/conf/netuitive-agent.conf.
    2. Change the enabled setting to True in the [[[statsd]]] section of the file.
    3. Optionally, adjust the listen (listen_port and listen_ip) and forward (forward_ipforward_port, and forward) options. The listen settings are used to tell the Linux Agent where to “listen” for statistics (metrics); typically the server that your application is located. The forward settings are used to tell the Linux Agent where to send the information.
    4. Restart the Linux Agent.


Metricly StatsD will collect and organize your data as your application calls functions and methods. This data is flushed to the Metricly StatsD server every 60 seconds by default, and then aggregated in Metricly’s five-minute batch analytics cycle. After Metricly analyzes your data, it’s then graphed for you to see. The Metricly StatsD server will place all of your metrics under the StatsD namespace in the Metrics page. Metrics about the Metricly StatsD server itself are organized under the metricly-statsd namespace in the Metrics page.

Before you begin instrumenting custom metrics, you’ll need to find a language library to “talk” to the Metricly StatsD server using certain metric types. Metricly StatsD supports the following metric types:

Your client library may support different metric types, but Metricly StatsD will only be able to use the metric types listed below.
  • Counters: Count how many times an event occurs.
  • Timers: Measure in milliseconds how long an action took.
  • Gauge: An arbitrary, persistent value (e.g., a fuel meter).
  • Sets: A number of unique elements received over a set interval.
  • Histograms: The statistical distribution of a set of values.

Counter Example

  • Each time a different language is given in the function below, a metric’s value increments by one. If a language is not found, another metric is created to show how many times a language was not found.
    var Client = require('node-statsd-client').Client;
    var metriclyStatsd = new Client("localhost", 8125);
    function translateHello(language) {
        if (language == "German") {
            return "Hallo";
        if (language == "Spanish") {
            return "Hola";
        if (language == "French") {
            return "Bonjour";
        else {
            return "Sorry, I don't recognize that language.";
    var languageName = prompt("Please enter which language you want to translate 'Hello' to:");

Timer Example

  • We want to see how long it takes for our PHP server to count to 10000.
        $start = microtime(true);
        for ($x=0; $x<10000; $x++) {}
        $end = microtime(true);
        $finalTime = $end-$start;
        echo 'It took ' . $finalTime . ' seconds!';
        .timing('', $finalTime, 1);

Gauge Example

  • Each time you order a pizza, you want to know what percentage of the pizza you ate.
    #!/usr/bin/my ruby srv
        require 'rubygems' if RUBY_VERSION < '1.9.0'
        require './statsdclient.rb'
    = 'localhost'
        Statsd.port = 8125
        class Numeric
          def percent_of(n)
            self.to_f / n.to_f * 100.0
        def prompt(*args)
        #input variables
        total_pizza_slices = 0
        eaten = 0
        #user prompts
        total_pizza_slices = prompt "How many total slices made up the pizza? "
        eaten = prompt "How many slices did you eat? "
        percent_eaten = eaten.percent_of(total_pizza_slices)
        p "You ate #{percent_eaten} of the pizza!"
        Statsd.gauge('', percent_eaten)


You can also pass in tags to any of your metrics like so:

metricly_statsd.increment('login.errors', tags=['name', 'value'])

Be sure to reference the reserved tags section before you begin passing in tags.

Additional Configuration Options

Option Default Description
enabled True Enable collecting Metricly StatsD metrics.
interval 60 The interval (in seconds) at which to collect metrics.
listen_port 8125 User Datagram Protocol (UDP) port to listen on.
listen_ip IP address to listen on.
element_type SERVER Element type applied to your metricly-statsd server instance in Metricly.
prefix statsd Prefix applied to your metricly-statsd metrics in Metricly.
forward_ip IP address to forward StatsD messages to.
forward_port 9125 UDP port to forward StatsD messages to.
forward False Enable StatsD forwarding.


Redhat 6 and 7
CentOS 6 and 7
Amazon Linux (latest)
Ubuntu 12, 14, 15, and 16
Debian 7, 8, and 9


Linux Agent
  • CPU:
  • Diskspace:
  • Disk Usage:
  • Load Average:
  • Memory:
  • Network:
  • VM Stat:

Additional Information

Metricly StatsD Reserved Metric Tags

Metricly already uses a few tags, so be mindful when passing in tags with StatsD metrics.

  • h: Sets the hostname (element ID) of the element.
    The h tag should be replaced with caution, as replacing it with a custom value will create a separate, extra element.
  • un: Sets the unit of the metric you’re creating. An exhaustive list of the units Metricly supports can be found here.
  • sds: Defines the strategy for replacing missing data. You can either replace missing data with a zero (ReplaceWithZero) or take no strategy at all (None). You should schedule a data push at least once in every five-minute cycle. If you cannot send data every five minutes, you should consider sending zeroes.
  • ty: Sets the type of the element in Metricly (e.g., SERVER).