This page walks Technology Partners through how to create a Datadog Agent integration, which you can list as out-of-the-box on the Integrations page, or for a price on the Marketplace page. Agent-based integrations

Agent-based integrations use the Datadog Agent to submit data through checks written by the developer. Checks can emit metrics, events, and service checks into a customer’s Datadog account. The Agent itself can submit logs as well, but that is configured outside of the check.

The implementation code for these integrations is hosted by Datadog. Agent integrations are best suited for collecting data from systems or applications that live in a local area network (LAN) or virtual private cloud (VPC). Creating an Agent integration requires you to publish and deploy your solution as a Python wheel (.whl).

You can include out-of-the-box assets such as monitors, dashboards, and log pipelines with your Agent-based integration. When a user clicks Install on your integration tile, they are prompted to follow the setup instructions, and all out-of-the-box dashboards will appear in their account. Other assets, such as log pipelines, will appear for users after proper installation and configuration of the integration. Development process

The process to build an Agent-based integration looks like this:

• Once you’ve been accepted to the Datadog Partner Network, you will meet with the Datadog Technology Partner team to discuss your offering and use cases.
• Request a Datadog sandbox account for development through the Datadog Partner Network portal.
• Begin development of your integration, which includes writing the integration code on your end as well as building and installing a Python wheel (.whl).
• Test your integration in your Datadog sandbox account.
• Once your development work is tested and complete, populate your tile assets by providing information like setup instructions, images, support information, and more that will make up your integration tile that’s displayed on the Integrations or Marketplace page.
• Once your pull request is submitted and approved, the Datadog Technology Partner team will schedule a demo for a final review of your integration.
• You will have the option of testing the tile and integration in your Datadog sandbox account before publishing, or immediately publishing the integration for all customers.

The required Datadog Agent integration development tools include the following:

• Python v3.11, pipx, and the Agent Integration Developer Tool (ddev). For installation instructions, see Install the Datadog Agent Integration Developer Tool.
• Docker to run the full test suite.
• The git command line or GitHub Desktop client.

Select a tab for instructions on building an out-of-the-box Agent-based integration on the Integrations page, or an Agent-based integration on the Marketplace page.

• Build an out-of-the-box integration
• Build a Marketplace integration

To build an out-of-the-box integration:

Create a dd directory:

 mkdir $HOME/dd && cd $HOME/dd

The Datadog Development Toolkit expects you to work in the $HOME/dd/ directory. This is not mandatory, but working in a different directory requires additional configuration steps.

• Fork the integrations-extras repository.
• Clone your fork into the dd directory:

  git clone git@github.com:<YOUR USERNAME>/integrations-extras.git

Create a feature branch to work in:

  git switch -c <YOUR INTEGRATION NAME> origin/master

Configure the developer tool

The Agent Integration Developer Tool allows you to create scaffolding when you are developing an integration by generating a skeleton of your integration tile’s assets and metadata. For instructions on installing the tool, see Install the Datadog Agent Integration Developer Tool.

To configure the tool for the integrations-extras repository:

  Optionally, if your integrations-extras repo is somewhere other than $HOME/dd/, adjust the ddev configuration file:

  ddev config set extras "/path/to/integrations-extras"

Set integrations-extras as the default working repository:

ddev config set repo extras

Create your integration

Once you’ve downloaded Docker, installed an appropriate version of Python, and prepared your development environment, you can start creating an Agent-based integration.

The following instructions use an example integration called Awesome. Follow along using the code from Awesome, or replace Awesome with your own code, as well as the name of your integration within the commands. For example, use ddev create <your-integration-name> instead of ddev create Awesome. Create scaffolding for your integration

The ddev create command runs an interactive tool that creates the basic file and path structure (or scaffolding) necessary for an Agent-based integration.

  Before you create your first integration directory, try a dry-run using the -n/--dry-run flag, which doesn’t write anything to the disk:

  ddev create -n Awesome

This command displays the path where the files would have been written, as well as the structure itself. Make sure the path in the first line of output matches your repository location.

Run the command without the -n flag. The tool asks you for an email and name and then creates the files you need to get started with an integration. If you are creating an integration for the Datadog Marketplace, ensure that your directory follows the pattern of {partner name}_{integration name}.

ddev create Awesome

Write an Agent check

At the core of each Agent-based integration is an Agent Check that periodically collects information and sends it to Datadog.

Checks inherit their logic from the AgentCheck base class and have the following requirements:

  Integrations running on the Datadog Agent v7 or later must be compatible with Python 3. Integrations running on the Datadog Agent v5 and v6 still use Python 2.7.
  Checks must derive from AgentCheck.
  Checks must provide a method with this signature: check(self, instance).
  Checks are organized in regular Python packages under the datadog_checks namespace. For example, the code for Awesome lives in the awesome/datadog_checks/awesome/ directory.
  The name of the package must be the same as the check name.
  There are no restrictions on the name of the Python modules within that package, nor on the name of the class implementing the check.

Implement check logic

For Awesome, the Agent Check is composed of a service check named awesome.search that searches for a string on a web page. It results in OK if the string is present, WARNING if the page is accessible but the string was not found, and CRITICAL if the page is inaccessible.