<commit_before>---
title: Writing an Agent Check
sidebar:
  nav:
    - header: Guide to Agent Checks
    - text: Overview
      href: "#overview"
    - text: Setup
      href: "#setup"
    - text: The AgentCheck Interface
      href: "#interface"
    - text: Configuration
      href: "#config"
    - text: Directory Structure
      href: "#directory"
    - text: Your First Check
      href: "#first"
    - text: An HTTP Check
      href: "#http"
---

<div class="alert alert-block">
This guide requires an agent version >= 3.2.0. Older versions of the agent do
not include the `AgentCheck` interface that we'll be using.
</div>


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

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

The Datadog Agent collects a variety of metrics and events from your system,
from system metrics (CPU, Load, Memory) to metrics from a speficic application
or service running on your system (Postgresql, Memcached, etc.).

Upon installation, the Agent is able to give you a quick and clear view of
what's happening across your infrastructure. It supports a wide variety of integrations, and has a simple interface for writing your own checks.

In this guide, we will first show you what is available in the AgentCheck
interface, then we'll walk step-by-step through the writing of a simple check
that will the status of configured HTTP endpoints. Any custom checks will be
included in the main check run loop, meaning they will run every check interval,
which defaults to 15 seconds.

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

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

If you have not already setup the Agent, then you should check out the agent
setup instructions available at: <a href="http://app.datadoghq.com/account/settings#agent">http://app.datadoghq.com/account/settings#agent</a>.
This page will guide you through installing the agent for your particular OS.

If you run into any issues during the setup, don't hesistate to pop by our
<a href="irc://irc.freenode.net/datadog">chat room</a> where we'll be happy to
answer any questions you might have.

<!--
======================================================
INTERFACE
======================================================
-->

<h3 id="interface">The AgentCheck Interface</h3>

All custom checks inherit from the `AgentCheck` class found in `checks/__init__.py`
and require a `check()` method that takes one argument, `instance` which is a
`dict` having the configuration of a particular instance. The `check` method is
run once per instance defined in the check configuration (discussed later)

#### Sending metrics

Sendings metrics in a check is easy! If you're already familiar with the
methods available in DogstatsD, then the transition will be very simple. If
you're not already familiar with that interface, you'll find sending metrics is
a breeze.

You have the following methods available to you:

<%= snippet_code_block("guides-agentchecks-methods.py") %>

All of these methods take the following arguments:

- `metric`: The name of the metric
- `value`: The value for the metric (defaults to 1 on increment, -1 on decrement)
- `tags`: (optional) A list of tags to associate with this metric.
- `hostname`: (optional) A hostname to associate with this metric. Defaults to the current host.
- `device_name`: (optional) A device name to associate with this metric.

These methods may be called from anywhere within your check logic. At the end of
your `check` function, all metrics that were submitted will be collected and
flushed out with the other agent metrics.

#### Sending events

At any time during your check, you can make a call to `self.event(...)` with one argument: the payload of the event. Your event should be structured like this:

<%= snippet_code_block("guides-agentchecks-event.py") %>

At the end of your check, all events will be collected and flushed with the rest
of the agent payload.

#### Logging

As part of the parent class, you're given a logger at `self.log`, so you can do
things like `self.log.info('hello')`. The log handler will be `checks.{name}`
where `{name}` is the name of your check (based on the filename of the check
module).

<!--
======================================================
CONFIGURATION
======================================================
-->

<h3 id="config">Configuration</h3>

Each check will have a configuration file that will be placed in the `conf.d`
directory. Configuration is written using [YAML](http://www.yaml.org/). The
file name should match the name of the check module (e.g.: `haproxy.py` and
`haproxy.yaml`).

The configuration file has the following structure:

<%= snippet_code_block("guides-agentchecks-config.yaml") %>

#### init_config

The *init_config* section allows you to have an arbitrary number of global
configuration options that will be available on every run of the check in
`self.init_config`.

#### instances

The *instances* section is a list of instances that this check will be run
against. Your actual `check()` method is run once per instance. This means that
every check will support multiple instances out of the box.

<!--
======================================================
DIRECTORY STRUCTURE
======================================================
-->

<h3 id="directory">Directory Structure</h3>

Before starting your first check it is worth understanding the checks directory
structure. There are two places that you will need to add files for your check.
The first is the `checks.d` folder, which lives in your Agent root.

For all Linux systems, this means you will find it at:

    /usr/share/datadog/checks.d/

For Windows Server >= 2008 you'll find it at:

    C:\Program Files (x86)\Datadog\Agent\checks.d\

    OR

    C:\Program Files\Datadog\Agent\checks.d\

The other folder that you need to care about is `conf.d` which lives in the
agent configuration root.

For Linux, you'll find it at:

    /etc/dd-agent/conf.d/

For Windows, you'll find it at:

    C:\ProgramData\Datadog\conf.d\

    OR

    C:\Documents and Settings\All Users\Datadog\conf.d\

<!--
======================================================
FIRST CHECK
======================================================
-->

<h3 id="first">Your First Check</h3>

To start off simple, we'll write a check that does nothing more than send a
value of 1 for the metric `hello.world`. The configuration file will be very
simple, including no real information. This will go into `conf.d/hello.yaml`:

<%= snippet_code_block("guides-agentchecks-hello-config.yaml") %>

The check itself will inherit from `AgentCheck` and send a gauge of `1` for<commit_msg>explicity note that checks.d files must match in name<commit_after>---
title: Writing an Agent Check
sidebar:
  nav:
    - header: Guide to Agent Checks
    - text: Overview
      href: "#overview"
    - text: Setup
      href: "#setup"
    - text: The AgentCheck Interface
      href: "#interface"
    - text: Configuration
      href: "#config"
    - text: Directory Structure
      href: "#directory"
    - text: Your First Check
      href: "#first"
    - text: An HTTP Check
      href: "#http"
---

<div class="alert alert-block">
This guide requires an agent version >= 3.2.0. Older versions of the agent do
not include the `AgentCheck` interface that we'll be using.
</div>


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

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

The Datadog Agent collects a variety of metrics and events from your system,
from system metrics (CPU, Load, Memory) to metrics from a speficic application
or service running on your system (Postgresql, Memcached, etc.).

Upon installation, the Agent is able to give you a quick and clear view of
what's happening across your infrastructure. It supports a wide variety of integrations, and has a simple interface for writing your own checks.

In this guide, we will first show you what is available in the AgentCheck
interface, then we'll walk step-by-step through the writing of a simple check
that will the status of configured HTTP endpoints. Any custom checks will be
included in the main check run loop, meaning they will run every check interval,
which defaults to 15 seconds.

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

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

If you have not already setup the Agent, then you should check out the agent
setup instructions available at: <a href="http://app.datadoghq.com/account/settings#agent">http://app.datadoghq.com/account/settings#agent</a>.
This page will guide you through installing the agent for your particular OS.

If you run into any issues during the setup, don't hesistate to pop by our
<a href="irc://irc.freenode.net/datadog">chat room</a> where we'll be happy to
answer any questions you might have.

<!--
======================================================
INTERFACE
======================================================
-->

<h3 id="interface">The AgentCheck Interface</h3>

All custom checks inherit from the `AgentCheck` class found in `checks/__init__.py`
and require a `check()` method that takes one argument, `instance` which is a
`dict` having the configuration of a particular instance. The `check` method is
run once per instance defined in the check configuration (discussed later)

#### Sending metrics

Sendings metrics in a check is easy! If you're already familiar with the
methods available in DogstatsD, then the transition will be very simple. If
you're not already familiar with that interface, you'll find sending metrics is
a breeze.

You have the following methods available to you:

<%= snippet_code_block("guides-agentchecks-methods.py") %>

All of these methods take the following arguments:

- `metric`: The name of the metric
- `value`: The value for the metric (defaults to 1 on increment, -1 on decrement)
- `tags`: (optional) A list of tags to associate with this metric.
- `hostname`: (optional) A hostname to associate with this metric. Defaults to the current host.
- `device_name`: (optional) A device name to associate with this metric.

These methods may be called from anywhere within your check logic. At the end of
your `check` function, all metrics that were submitted will be collected and
flushed out with the other agent metrics.

#### Sending events

At any time during your check, you can make a call to `self.event(...)` with one argument: the payload of the event. Your event should be structured like this:

<%= snippet_code_block("guides-agentchecks-event.py") %>

At the end of your check, all events will be collected and flushed with the rest
of the agent payload.

#### Logging

As part of the parent class, you're given a logger at `self.log`, so you can do
things like `self.log.info('hello')`. The log handler will be `checks.{name}`
where `{name}` is the name of your check (based on the filename of the check
module).

<!--
======================================================
CONFIGURATION
======================================================
-->

<h3 id="config">Configuration</h3>

Each check will have a configuration file that will be placed in the `conf.d`
directory. Configuration is written using [YAML](http://www.yaml.org/). The
file name should match the name of the check module (e.g.: `haproxy.py` and
`haproxy.yaml`).

The configuration file has the following structure:

<%= snippet_code_block("guides-agentchecks-config.yaml") %>

#### init_config

The *init_config* section allows you to have an arbitrary number of global
configuration options that will be available on every run of the check in
`self.init_config`.

#### instances

The *instances* section is a list of instances that this check will be run
against. Your actual `check()` method is run once per instance. This means that
every check will support multiple instances out of the box.

<!--
======================================================
DIRECTORY STRUCTURE
======================================================
-->

<h3 id="directory">Directory Structure</h3>

Before starting your first check it is worth understanding the checks directory
structure. There are two places that you will need to add files for your check.
The first is the `checks.d` folder, which lives in your Agent root.

For all Linux systems, this means you will find it at:

    /usr/share/datadog/checks.d/

For Windows Server >= 2008 you'll find it at:

    C:\Program Files (x86)\Datadog\Agent\checks.d\

    OR

    C:\Program Files\Datadog\Agent\checks.d\

The other folder that you need to care about is `conf.d` which lives in the
agent configuration root.

For Linux, you'll find it at:

    /etc/dd-agent/conf.d/

For Windows, you'll find it at:

    C:\ProgramData\Datadog\conf.d\

    OR

    C:\Documents and Settings\All Users\Datadog\conf.d\

<!--
======================================================
FIRST CHECK
======================================================
-->

<h3 id="first">Your First Check</h3>

<div class="alert alert-block">
The names of the configuration and check files must match. If you check
is called <code>mycheck.py</code> your configuration file <em>must</em> be
named <code>mycheck.yaml</code>.
</div>

To start off simple, we'll write a check that does nothing more than send a
value of 1 for the metric `hello.world`. The configuration file will be very
simple, including no real information. This will go into `conf.d/hello.yaml`:

<%= snippet_code_block("guides-agentchecks-hello-config.yaml") %>

The check itself will inherit from `AgentCheck` and send a gauge of `1` for
{'fraction_non_alphanumeric': 0.17428198433420367, 'fraction_numerical': 0.0039164490861618795, 'mean_word_length': 4.435159637366969, 'pattern_counts': {'":': 0, '<': 67, '<?xml version=': 0, '>': 71, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, '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': '1342048', 'n_tokens_mistral': 3734, 'n_tokens_neox': 3495, 'n_words': 1716}