<commit_before>---
title: Getting Started with Metrics
sidebar:
  nav:
    - header: Guide to Metrics
    - text: Overview
      href: "#overview"
    - text: Setup
      href: "#setup"
    - header: Metric Types
    - text: Counters
      href: "#counters"
    - text: Gauges
      href: "#gauges"
    - text: Histograms
      href: "#histograms"
    - text: Sets
      href: "#sets"
    - header: Options
    - text: Tags
      href: "#tags"
    - text: Sample Rates
      href: "#sample-rates"
    - header: Epilogue
    - text: Other Submission Methods
      href: "#methods"
---

<div class="alert alert-info">
This tutorial teaches how to send your application's custom metrics to Datadog.
If you need any help getting started, pop by our <a href="irc://irc.freenode.net/datadog">chat room</a>.
</div>

<!--
======================================================
OVERVIEW
======================================================
-->

<h3 id="overview">Overview</h3>

Sending your application's custom metrics to Datadog will let you correlate
what's happening with your application, your users and your system.

Metrics are collected by sending them to StatsD, a small metrics aggregation
server that is bundled with the Datadog Agent. You can read about how it works <a
href="/guides/dogstatsd/">here</a>. If you want to dive into code right away,
read on.

In this tutorial, we'll cover some common instrumentation use cases, like:

- How to count web page views
- How to time database queries
- How to measure the amount of free memory

<!--
======================================================
SETUP
======================================================
-->

<h3 id="setup">Setup</h3>

First off, <a href="https://app.datadoghq.com/account/settings#agent">install</a>
the Datadog Agent (version 3 or greater), which
contains our StatsD server, and make sure it's running.

Next, let's set up a client library for your language.

<%= code_tabs("setup") %>

<div class="tab-content">

  <div class="tab-pane active fade in" id="setup-python">
First, install the module:
<%= snippet_code_block("guides-metrics-setup-python.sh") %>
And import it, so it's ready to use:
<%= snippet_code_block("guides-metrics-setup.py") %>
  </div>

  <div class="tab-pane fade in" id="setup-ruby">
First, install the module:
<%= console <<EOF
$ gem install dogstatsd-ruby
EOF
%>
And add it to your code:
<%= ruby <<EOF
# Import the library
require 'statsd'

# Create a statsd client instance.
statsd = Statsd.new
EOF
%>
  </div>
  <p>Now we're ready to roll.</p>
  <div class="alert info-block">
    This tutorial has examples for Python and Ruby, but check out the 
    <a href="/libraries/">libraries page</a> if you use another language.
  </div>

</div>

<!--
======================================================
COUNTERS
======================================================
-->


<h3 id="counters">Counters</h3>

Counters are used to (ahem) count things. Let's walk through a common example -
counting web page views. To achieve this, we'll increment a metric called
`web.page_views` each time our `render_page` function is called.

<%= code_tabs("counters-page-views") %>

<div class="tab-content">
  <div class="tab-pane active fade in" id="counters-page-views-python">
<%= python <<EOF
def render_page():
    """ Render a web page. """
    statsd.increment('web.page_views')
    return 'Hello World!'
EOF
%>
  </div>
  <div class="tab-pane fade in" id="counters-page-views-ruby">
<%= ruby <<EOF
def render_page()
  # Render a web page.
  statsd.increment('web.page_views')
  return 'Hello World!'
end
EOF
%>
  </div>
</div>

That's it. With this one line of code we can start graphing the data.
Here's an example:

<img src="/static/images/graph-guides-metrics-page-views.png" style="width:100%">

We can also count by arbitrary numbers. Suppose we wanted to count the number
of bytes processed by a file uploading service, we'll increment a metric
called `file_service.bytes_uploaded` by the size of the file each time our
`upload_file` function is called:

<%= code_tabs("counters-uploaded") %>

<div class="tab-content">
  <div class="tab-pane active fade in" id="counters-uploaded-python">
<%= python <<EOF
def upload_file(file):
    statsd.increment('file_service.bytes_uploaded', file.size())
    save_file(file)
    return 'File uploaded!'
EOF
%>
  </div>
  <div class="tab-pane fade in" id="counters-uploaded-ruby">
<%= ruby <<EOF
def upload_file(file)
  statsd.increment('file_service.bytes_uploaded', file.size())
  save_file(file)
  return 'File uploaded!'
end
EOF
%>
  </div>
</div>

<h3 id="gauges">Gauges</h3>

Gauges measure the value of a particular thing over time. Suppose a developer
wanted to track the amount of free memory on a machine, we can periodically
sample that value as the metric `system.mem.free`:

<commit_msg>note that counters are normalized per-second<commit_after>---
title: Getting Started with Metrics
sidebar:
  nav:
    - header: Guide to Metrics
    - text: Overview
      href: "#overview"
    - text: Setup
      href: "#setup"
    - header: Metric Types
    - text: Counters
      href: "#counters"
    - text: Gauges
      href: "#gauges"
    - text: Histograms
      href: "#histograms"
    - text: Sets
      href: "#sets"
    - header: Options
    - text: Tags
      href: "#tags"
    - text: Sample Rates
      href: "#sample-rates"
    - header: Epilogue
    - text: Other Submission Methods
      href: "#methods"
---

<div class="alert alert-info">
This tutorial teaches how to send your application's custom metrics to Datadog.
If you need any help getting started, pop by our <a href="irc://irc.freenode.net/datadog">chat room</a>.
</div>

<!--
======================================================
OVERVIEW
======================================================
-->

<h3 id="overview">Overview</h3>

Sending your application's custom metrics to Datadog will let you correlate
what's happening with your application, your users and your system.

Metrics are collected by sending them to StatsD, a small metrics aggregation
server that is bundled with the Datadog Agent. You can read about how it works <a
href="/guides/dogstatsd/">here</a>. If you want to dive into code right away,
read on.

In this tutorial, we'll cover some common instrumentation use cases, like:

- How to count web page views
- How to time database queries
- How to measure the amount of free memory

<!--
======================================================
SETUP
======================================================
-->

<h3 id="setup">Setup</h3>

First off, <a href="https://app.datadoghq.com/account/settings#agent">install</a>
the Datadog Agent (version 3 or greater), which
contains our StatsD server, and make sure it's running.

Next, let's set up a client library for your language.

<%= code_tabs("setup") %>

<div class="tab-content">

  <div class="tab-pane active fade in" id="setup-python">
First, install the module:
<%= snippet_code_block("guides-metrics-setup-python.sh") %>
And import it, so it's ready to use:
<%= snippet_code_block("guides-metrics-setup.py") %>
  </div>

  <div class="tab-pane fade in" id="setup-ruby">
First, install the module:
<%= console <<EOF
$ gem install dogstatsd-ruby
EOF
%>
And add it to your code:
<%= ruby <<EOF
# Import the library
require 'statsd'

# Create a statsd client instance.
statsd = Statsd.new
EOF
%>
  </div>
  <p>Now we're ready to roll.</p>
  <div class="alert info-block">
    This tutorial has examples for Python and Ruby, but check out the 
    <a href="/libraries/">libraries page</a> if you use another language.
  </div>

</div>

<!--
======================================================
COUNTERS
======================================================
-->


<h3 id="counters">Counters</h3>

Counters are used to (ahem) count things. Let's walk through a common example -
counting web page views. To achieve this, we'll increment a metric called
`web.page_views` each time our `render_page` function is called.

<%= code_tabs("counters-page-views") %>

<div class="tab-content">
  <div class="tab-pane active fade in" id="counters-page-views-python">
<%= python <<EOF
def render_page():
    """ Render a web page. """
    statsd.increment('web.page_views')
    return 'Hello World!'
EOF
%>
  </div>
  <div class="tab-pane fade in" id="counters-page-views-ruby">
<%= ruby <<EOF
def render_page()
  # Render a web page.
  statsd.increment('web.page_views')
  return 'Hello World!'
end
EOF
%>
  </div>
</div>

That's it. With this one line of code we can start graphing the data.
Here's an example:

<img src="/static/images/graph-guides-metrics-page-views.png" style="width:100%">

We can also count by arbitrary numbers. Suppose we wanted to count the number
of bytes processed by a file uploading service, we'll increment a metric
called `file_service.bytes_uploaded` by the size of the file each time our
`upload_file` function is called:

<%= code_tabs("counters-uploaded") %>

<div class="tab-content">
  <div class="tab-pane active fade in" id="counters-uploaded-python">
<%= python <<EOF
def upload_file(file):
    statsd.increment('file_service.bytes_uploaded', file.size())
    save_file(file)
    return 'File uploaded!'
EOF
%>
  </div>
  <div class="tab-pane fade in" id="counters-uploaded-ruby">
<%= ruby <<EOF
def upload_file(file)
  statsd.increment('file_service.bytes_uploaded', file.size())
  save_file(file)
  return 'File uploaded!'
end
EOF
%>
  </div>
</div>
<br>
Counters are normalized to per-second units. From the "Web Page Views" 
example above, if one person visited the site per second, the graph would be 
a straight line at one. To increment or measure values over time please see 
<a href='#gauges'>gauges</a>.


<h3 id="gauges">Gauges</h3>

Gauges measure the value of a particular thing over time. Suppose a developer
wanted to track the amount of free memory on a machine, we can periodically
sample that value as the metric `system.mem.free`:


{'fraction_non_alphanumeric': 0.18329326923076922, 'fraction_numerical': 0.002403846153846154, 'mean_word_length': 4.1257700205338805, 'pattern_counts': {'":': 0, '<': 140, '<?xml version=': 0, '>': 116, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6171560', 'n_tokens_mistral': 3185, 'n_tokens_neox': 3004, 'n_words': 1093}