From 309b2494a01fff920107ae3ed5ea056d3b0c359a Mon Sep 17 00:00:00 2001 From: Dominic Medina Date: Wed, 29 Oct 2025 20:26:39 +0000 Subject: [PATCH 01/12] add Developer Platform instructions --- .../integrations/agent_integration.md | 289 ++++++------------ 1 file changed, 99 insertions(+), 190 deletions(-) diff --git a/content/en/developers/integrations/agent_integration.md b/content/en/developers/integrations/agent_integration.md index 233d7c3291add..6bfb574c4fe5a 100644 --- a/content/en/developers/integrations/agent_integration.md +++ b/content/en/developers/integrations/agent_integration.md @@ -20,175 +20,96 @@ description: Learn how to develop and publish a Datadog Agent integration. --- ## Overview -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][23], or for a price on the [Marketplace page][24]. +This page guides Technology Partners through creating an official Datadog agent integration. Agent integrations are best suited for collecting telemetry from software or systems that run on customer-managed infrastructure, where the Datadog Agent can be installed. -An Agent-based integration uses the [Datadog Agent][17] to submit data through custom checks written by developers. These checks can emit [metrics][34], [events][18], [service checks][25], and [logs][36] into a customer's Datadog account. +An Agent-based integration uses the [Datadog Agent][1] to submit data through custom agent checks written by approved Technolgoy Partners. These checks can emit [metrics][2], [events][3], [service checks][4], and [logs][5] into a customer's Datadog account. Agent-based integrations are published as a Python packages that easily allows customers to [install][6] via the Datadog Agent. -## When to use Agent-based integrations +## Building an agent-based integration +These steps assume you've [joined the Datadog Partner Network][7], have access to a partner developer organization, and have [created a listing in the Developer Platform][8]. -Agent integrations are best suited for collecting data from systems or applications running with a: -- Local Area Network (LAN) -- Virtual Private Cloud (VPC) -Agent-based integrations require publishing and deploying as a Python wheel (.whl). +1. [Install the required development tools](#preqrequisites). +2. [Configure the Datadog Agent integration developer tool](#configure-ddev). +3. [Create the scaffolding for your integration](#create-scaffolding-for-your-integration). +4. [Write your agent check](#write-your-agent-check). +5. Test your integration +6. Open a GitHub pull request with the code for your Agent check. +7. Submit +### Preqrequisites -## Development process +- Python v3.12 installed. +- [pipx][9] to install the development tooling and dependencies. +- [Datadog Agent Integration Developer Tool][10] (`ddev`) to create the necessary scaffolding. +- [Docker][11] to run the full test suite. +- Git ([command line][12] or [GitHub Desktop client][13]). -The process to build an Agent-based integration looks like this: +### Configure ddev -1. Join the Datadog Partner Network - - Apply to the [Datadog Partner Network][32]. Once accepted, an introductory call will be scheduled with the Datadog Technology Partner team. -2. Set up your development environment - - Request a Datadog sandbox account through the Datadog Partner Network portal. - - Install the necessary development tools. -3. Create your integration - - Within your Datadog sandbox, navigate to **Developer Platform** > **add a new listing**. - - Fill in the details describing your integration. -4. Build your agent check and test your integration - - Create your Agent Check following [these steps](#write-an-agent-check). -4. Submit for review - - Submit your integration content through the Developer Platform. - - Open a GitHub pull request with the code for your Agent check. - - The Datadog team will schedule a final demo to review your integration. - -## Prerequisites - -The required Datadog Agent integration development tools include the following: - -- Python v3.12, [pipx][2], and the Agent Integration Developer Tool (`ddev`). For installation instructions, see [Install the Datadog Agent Integration Developer Tool][3]. -- [Docker][4] to run the full test suite. -- The git [command line][5] or [GitHub Desktop client][19]. - -
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.
- -{{< tabs >}} -{{% tab "Build an out-of-the-box integration" %}} - -To build an out-of-the-box integration: - -Create a `dd` directory: - -```shell -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. - -1. Fork the [`integrations-extras` repository][101]. - -1. Clone your fork into the `dd` directory: +1. Create a `dd` directory. The Datadog Agent developer tool expects you to work in the `$HOME/dd/` directory. ```shell - git clone git@github.com:/integrations-extras.git + mkdir $HOME/dd && cd $HOME/dd ``` -1. Create a feature branch to work in: +2. Clone or fork the appropriate repo based on your integration + + - **If building an out-of-the-box integration** + 1. Fork the [Datadog/integrations-extras][14] repository. + 2. Then clone your fork into the `dd` directory: + ```shell + git clone git@github.com:/integrations-extras.git + ``` + + - **If building a Marketplace integration** + 1. Request access to the [Datadog/marketplace][15] repository from your Datadog contact if you don't already have write access. + 2. Clone the `marketplace` repository: + ```shell + git clone git@github.com:DataDog/marketplace.git + ``` +3. Create a feature branch to work in: ```shell - git switch -c origin/master + cd + git switch -c origin/master ``` -## Configure the developer tool +4. Set the appropriate default working respository: + + - **If building an out-of-the-box integration** + ```shell + ddev config set repo extras + ``` -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][102]. + - **If building a Marketplace integration** + ```shell + ddev config set repo marketplace + ``` -To configure the tool for the `integrations-extras` repository: + - **If you set a custom location for your repo outside `$HOME/dd/`** + ```shell + ddev config set repos. "/path/to/" + ddev config set repo + ``` -1. Optionally, if your `integrations-extras` repo is somewhere other than `$HOME/dd/`, adjust the `ddev` configuration file: - ```shell - ddev config set repos.extras "/path/to/integrations-extras" - ``` +### Create the scaffolding -1. Set `integrations-extras` as the default working repository: - ```shell - ddev config set repo extras - ``` - -[101]: https://github.com/Datadog/integrations-extras -[102]: https://docs.datadoghq.com/developers/integrations/python - -{{% /tab %}} - -{{% tab "Build a Marketplace integration" %}} - -To build an integration: - -1. See [Build a Marketplace Offering][102] to request access to the [Marketplace repository][101]. -1. Create a `dd` directory: - - ```shell - mkdir $HOME/dd``` - - The Datadog Development Toolkit command expects you to be working in the `$HOME/dd/` directory. This is not mandatory, but working in a different directory requires additional configuration steps. - -1. Once you have been granted access to the Marketplace repository, create the `dd` directory and clone the `marketplace` repository: - - ```shell - git clone git@github.com:DataDog/marketplace.git``` +Use the `ddev create` command to generate the basic file and directory structure for an agent-based integration. -1. Create a feature branch to work in: +1. Test the setup first with a dry run (`-n` or `--dry-run`), which shows the paths and structure without writing to disk. Verify the output path matches the expected repository. ```shell - git switch -c origin/master``` - -## Install and configure the Datadog development toolkit - -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][103]. - -Once you have installed the Agent Integration Developer Tool, configure it for the Marketplace repository. - -1. Set `marketplace` as the default working repository: - - ```shell - - ddev config set repos.marketplace $HOME/dd/marketplace - ddev config set repo marketplace - ``` - -1. If you used a directory other than `$HOME/dd` to clone the `marketplace` directory, use the following command to set your working repository: - - ```shell - - ddev config set repos.marketplace - ddev config set repo marketplace - ``` - -[101]: https://github.com/Datadog/marketplace -[102]: https://docs.datadoghq.com/developers/integrations/marketplace_offering -[103]: https://docs.datadoghq.com/developers/integrations/python - -{{% /tab %}} - -{{< /tabs >}} - -## 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 ` 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. - -1. 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: - ```shell - ddev create -n Awesome + ddev create -nt check_only --skip-manifest ``` - 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. - -1. 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}.
+2. When ready, run the command without `-n` to create the files. The tool will prompt you for integration details. ```shell - ddev create Awesome + ddev create -t check_only --skip-manifest ``` -## Write an Agent check +### Write your agent check At the core of each Agent-based integration is an *Agent Check* that periodically collects information and sends it to Datadog. -[Checks][30] inherit their logic from the `AgentCheck` base class and have the following requirements: +[Checks][16] 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`. @@ -197,11 +118,13 @@ At the core of each Agent-based integration is an *Agent Check* that periodicall - 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 +#### Implement check logic + +The following example is for an integration name `Awesome`. -For Awesome, the Agent Check is composed of a [service check][25] 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. +The Agent Check is composed of a [service check][4] 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. -To learn how to submit metrics with your Agent Check, see [Custom Agent Check][7]. To learn how to submit logs from your Agent Check, see [Agent Integration Log Collection][36]. +To learn how to submit metrics with your Agent Check, see [Custom Agent Check][17]. To learn how to submit logs from your Agent Check, see [Agent Integration Log Collection][5]. The code contained within `awesome/datadog_checks/awesome/check.py` looks something like this: @@ -268,18 +191,18 @@ class AwesomeCheck(AgentCheck): }) {{< /code-block >}} -To learn more about the base Python class, see [Anatomy of a Python Check][8]. +To learn more about the base Python class, see [Anatomy of a Python Check][18]. -## Write validation tests +### Write validation tests There are two types of tests: - [Unit tests for specific functionality](#write-a-unit-test) - [Integration tests that execute the `check` method and verify proper metrics collection](#write-an-integration-test) -[pytest][9] and [hatch][10] are used to run the tests. Tests are required in order to publish your integration. +[pytest][19] and [hatch][20] are used to run the tests. Tests are required in order to publish your integration. -### Write a unit test +#### Write a unit test The first part of the `check` method for Awesome retrieves and verifies two elements from the configuration file. This is a good candidate for a unit test. @@ -322,11 +245,11 @@ The scaffolding is set up to run all the tests located in `awesome/tests`. To ru ddev test awesome ``` -### Write an integration test +#### Write an integration test The [unit test above](#write-a-unit-test) doesn't check the collection logic. To test the logic, you need to [create an environment for an integration test](#create-an-environment-for-the-integration-test) and [write an integration test](#add-an-integration-test). -#### Create an environment for the integration test +##### Create an environment for the integration test The toolkit uses `docker` to spin up an NGINX container and lets the check retrieve the welcome page. @@ -407,7 +330,7 @@ The `pyproject.toml` file provides the metadata that is used to package and buil All additional elements, including the metadata files, are not meant to be contained within the wheel, and are used elsewhere by the Datadog platform and ecosystem. -To learn more about Python packaging, see [Packaging Python Projects][16]. +To learn more about Python packaging, see [Packaging Python Projects][21]. Once your `pyproject.toml` is ready, create a wheel using one of the following options: @@ -416,7 +339,7 @@ Once your `pyproject.toml` is ready, create a wheel using one of the following o ## Install the wheel -The wheel is installed using the Agent `integration` command, available in [Agent v6.10.0 or later][17]. Depending on your environment, you may need to execute this command as a specific user or with specific privileges: +The wheel is installed using the Agent `integration` command, available in [Agent v6.10.0 or later][1]. Depending on your environment, you may need to execute this command as a specific user or with specific privileges: **Linux** (as `dd-agent`): ```bash @@ -452,13 +375,13 @@ For installing your wheel to test in Kubernetes environments: 2. Run the wheel install in the initContainer. 3. Mount the initContainer in the Agent container while it's running. -For customer install commands for both host and container environments, see the [Community and Marketplace Integrations documentation][35]. +For customer install commands for both host and container environments, see the [Community and Marketplace Integrations documentation][22]. ## Submit your code for review -Follow the steps outlined within the Developer Platform to submit your Agent check code for review in GitHub. The pull request will be released with your integration upon approval. +Open a pull request with your integration directory in the approriate repo, either [Datadog/integrations-extras][14] or [Datadog/marketplace][15]. The pull request will be review in parrallel with your Developer Platform submission. -## Update your integration +## Updating your integration * If you are editing or adding new integration code, a version bump is required. * If you are editing or adding new README content, manifest information, or assets such as dashboards and monitor templates, a version bump is not needed. @@ -496,39 +419,25 @@ In addition to any code changes, the following is required when bumping an integ {{< partial name="whats-next/whats-next.html" >}} -[1]: https://docs.datadoghq.com/developers/#creating-your-own-solution -[2]: https://github.com/pypa/pipx -[3]: https://docs.datadoghq.com/developers/integrations/python/ -[4]: https://docs.docker.com/get-docker/ -[5]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git -[6]: https://github.com/datadog/integrations-extras -[7]: /metrics/custom_metrics/agent_metrics_submission/?tab=count -[8]: https://github.com/DataDog/datadog-agent/blob/6.2.x/docs/dev/checks/python/check_api.md -[9]: https://docs.pytest.org/en/latest -[10]: https://github.com/pypa/hatch -[11]: https://datadoghq.dev/integrations-core/meta/config-specs/ -[12]: /developers/integrations/check_references/#configuration-file -[13]: /developers/integrations/check_references/#manifest-file -[14]: /developers/integrations/check_references/#metrics-metadata-file -[15]: /developers/integrations/check_references/#service-check-file -[16]: https://packaging.python.org/en/latest/tutorials/packaging-projects/ -[17]: https://docs.datadoghq.com/agent/ -[18]: https://docs.datadoghq.com/service_management/events/ -[19]: https://desktop.github.com/ -[20]: https://docs.datadoghq.com/developers/integrations/ -[21]: https://github.com/Datadog/integrations-extras -[22]: https://github.com/Datadog/marketplace -[23]: https://app.datadoghq.com/integrations -[24]: https://app.datadoghq.com/marketplace -[25]: https://docs.datadoghq.com/developers/service_checks/ -[26]: https://docs.datadoghq.com/logs/ -[27]: https://docs.datadoghq.com/monitors/ -[28]: https://docs.datadoghq.com/dashboards/ -[29]: https://docs.datadoghq.com/logs/log_configuration/pipelines/ -[30]: https://docs.datadoghq.com/glossary/#check -[31]: https://docs.datadoghq.com/developers/integrations/ -[32]: https://partners.datadoghq.com/ -[33]: https://docs.datadoghq.com/developers/integrations/check_references/ -[34]: https://docs.datadoghq.com/metrics/ -[35]: https://docs.datadoghq.com/agent/guide/use-community-integrations/ -[36]: https://docs.datadoghq.com/logs/log_collection/agent_checks/ +[1]: https://docs.datadoghq.com/agent/ +[2]: https://docs.datadoghq.com/metrics/ +[3]: https://docs.datadoghq.com/service_management/events/ +[4]: https://docs.datadoghq.com/developers/service_checks/ +[5]: https://docs.datadoghq.com/logs/log_collection/agent_checks/ +[6]: https://docs.datadoghq.com/agent/guide/integration-management/?tab=linux#install +[7]: /developers/integrations/?tab=integrations#join-the-datadog-partner-network +[8]: /developers/integrations/build_integration/#create-a-listing +[9]: https://github.com/pypa/pipx +[10]: https://docs.datadoghq.com/developers/integrations/python/ +[11]: https://docs.docker.com/get-docker/ +[12]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +[13]: https://desktop.github.com/ +[14]: https://github.com/Datadog/integrations-extras +[15]: https://github.com/DataDog/marketplace +[16]: https://docs.datadoghq.com/glossary/#check +[17]: /metrics/custom_metrics/agent_metrics_submission/?tab=count +[18]: https://github.com/DataDog/datadog-agent/blob/6.2.x/docs/dev/checks/python/check_api.md +[19]: https://docs.pytest.org/en/latest +[20]: https://github.com/pypa/hatch +[21]: https://packaging.python.org/en/latest/tutorials/packaging-projects/ +[22]: https://docs.datadoghq.com/agent/guide/use-community-integrations/ \ No newline at end of file From 98856f16c2d7186ee34d4a0574d6a77e233ab429 Mon Sep 17 00:00:00 2001 From: Dominic Medina Date: Thu, 30 Oct 2025 19:03:51 +0000 Subject: [PATCH 02/12] add testing section --- .../integrations/agent_integration.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/content/en/developers/integrations/agent_integration.md b/content/en/developers/integrations/agent_integration.md index 6bfb574c4fe5a..c35d14866e2e0 100644 --- a/content/en/developers/integrations/agent_integration.md +++ b/content/en/developers/integrations/agent_integration.md @@ -28,12 +28,11 @@ An Agent-based integration uses the [Datadog Agent][1] to submit data through cu These steps assume you've [joined the Datadog Partner Network][7], have access to a partner developer organization, and have [created a listing in the Developer Platform][8]. 1. [Install the required development tools](#preqrequisites). -2. [Configure the Datadog Agent integration developer tool](#configure-ddev). -3. [Create the scaffolding for your integration](#create-scaffolding-for-your-integration). +2. [Configure the Datadog Agent integration developer tool](#configure-the-datadog-agent-integration-developer-tool). +3. [Create the scaffolding for your integration](#create-the-scaffolding). 4. [Write your agent check](#write-your-agent-check). -5. Test your integration -6. Open a GitHub pull request with the code for your Agent check. -7. Submit +5. [Test your agent check](#test-your-agent-check). +7. [Submit your code for review](#submit-your-code-for-review). ### Preqrequisites @@ -43,7 +42,7 @@ These steps assume you've [joined the Datadog Partner Network][7], have access t - [Docker][11] to run the full test suite. - Git ([command line][12] or [GitHub Desktop client][13]). -### Configure ddev +### Configure the Datadog Agent integration developer tool 1. Create a `dd` directory. The Datadog Agent developer tool expects you to work in the `$HOME/dd/` directory. ```shell @@ -324,7 +323,11 @@ To speed up development, use the `-m/--marker` option to run integration tests o ``` Your integration is almost complete. Return to the Developer Platform in your sandbox to finalize your submission. -## Build the wheel +## Test your agent check + +Agent-based integrations are distributed as Python wheel (.whl) files that customers install through the Datadog Agent. Before publishing your integration, you can locally test it by manually bulding and installing the wheel package. + +### Build the wheel The `pyproject.toml` file provides the metadata that is used to package and build the wheel. The wheel contains the files necessary for the functioning of the integration itself, which includes the Agent Check, configuration example file, and artifacts generated during the wheel build. @@ -337,7 +340,7 @@ Once your `pyproject.toml` is ready, create a wheel using one of the following o - (Recommended) With the `ddev` tooling: `ddev release build `. - Without the `ddev` tooling: `cd && pip wheel . --no-deps --wheel-dir dist`. -## Install the wheel +### Install the wheel The wheel is installed using the Agent `integration` command, available in [Agent v6.10.0 or later][1]. Depending on your environment, you may need to execute this command as a specific user or with specific privileges: From fe141a2e73d6aa7fd3346bd29233969d86c6122d Mon Sep 17 00:00:00 2001 From: Dominic Medina Date: Fri, 31 Oct 2025 13:56:06 +0000 Subject: [PATCH 03/12] add tabs for ootb vs. marketplace --- .../integrations/agent_integration.md | 104 ++++++++++++------ 1 file changed, 68 insertions(+), 36 deletions(-) diff --git a/content/en/developers/integrations/agent_integration.md b/content/en/developers/integrations/agent_integration.md index c35d14866e2e0..df29a022e9f84 100644 --- a/content/en/developers/integrations/agent_integration.md +++ b/content/en/developers/integrations/agent_integration.md @@ -32,7 +32,7 @@ These steps assume you've [joined the Datadog Partner Network][7], have access t 3. [Create the scaffolding for your integration](#create-the-scaffolding). 4. [Write your agent check](#write-your-agent-check). 5. [Test your agent check](#test-your-agent-check). -7. [Submit your code for review](#submit-your-code-for-review). +6. [Submit your code for review](#submit-your-code-for-review). ### Preqrequisites @@ -43,50 +43,81 @@ These steps assume you've [joined the Datadog Partner Network][7], have access t - Git ([command line][12] or [GitHub Desktop client][13]). ### Configure the Datadog Agent integration developer tool +Use the Datadog Agent developer tool (ddev) to build and test your integration. The setup steps differ depending on whether you’re developing an [out-of-the-box (OOTB) integration or a Marketplace integration][23]. Select the appropriate tab below. -1. Create a `dd` directory. The Datadog Agent developer tool expects you to work in the `$HOME/dd/` directory. +{{< tabs >}} + +{{% tab "OOTB integration" %}} + +1. **Create a working directory** + The developer tool expects your work to be located in `$HOME/dd/`: ```shell mkdir $HOME/dd && cd $HOME/dd ``` -2. Clone or fork the appropriate repo based on your integration - - - **If building an out-of-the-box integration** - 1. Fork the [Datadog/integrations-extras][14] repository. - 2. Then clone your fork into the `dd` directory: - ```shell - git clone git@github.com:/integrations-extras.git - ``` - - - **If building a Marketplace integration** - 1. Request access to the [Datadog/marketplace][15] repository from your Datadog contact if you don't already have write access. - 2. Clone the `marketplace` repository: - ```shell - git clone git@github.com:DataDog/marketplace.git - ``` -3. Create a feature branch to work in: +2. **Fork the repository** + Fork the [Datadog/integrations-extras][14] repository to your GitHub account. + +3. **Clone your fork** + Clone your fork into the `dd` directory: ```shell - cd + git clone git@github.com:/integrations-extras.git + ``` + +4. **Create a feature branch** + Create and switch to a new branch for your integration: + ```shell + cd integrations-extras git switch -c origin/master ``` -4. Set the appropriate default working respository: - - - **If building an out-of-the-box integration** - ```shell - ddev config set repo extras - ``` +5. **Configure the default respository** + Set `extras` as the default working repository: + ```shell + ddev config set repo extras + ``` + If your repository is stored outside `$HOME/dd/`, specify the path before setting it as the default: + ```shell + ddev config set repos.extras "/path/to/integrations-extras" + ddev config set repo extras + ``` + +{{% /tab %}} - - **If building a Marketplace integration** - ```shell - ddev config set repo marketplace - ``` +{{% tab "Marketplace integration" %}} + +1. **Create a working directory** + The developer tool expects your work to be located in `$HOME/dd/`: + ```shell + mkdir $HOME/dd && cd $HOME/dd + ``` + +2. **Clone the repository** + Clone the [Datadog/marketplace][15] repository. If you don’t have access, request it from your Datadog contact. + ```shell + git clone git@github.com:DataDog/marketplace.git + ``` + +3. **Create a feature branch** + Create and switch to a new branch for your integration: + ```shell + cd marketplace + git switch -c origin/master + ``` + +4. **Configure the default repository** + Set `marketplace` as the default working repository: + ```shell + ddev config set repo marketplace + ``` + If your repository is stored outside `$HOME/dd/`, specify the path before setting it as the default: + ```shell + ddev config set repos.marketplace "/path/to/marketplace" + ddev config set repo marketplace + ``` +{{% /tab %}} - - **If you set a custom location for your repo outside `$HOME/dd/`** - ```shell - ddev config set repos. "/path/to/" - ddev config set repo - ``` +{{< /tabs >}} ### Create the scaffolding @@ -119,7 +150,7 @@ At the core of each Agent-based integration is an *Agent Check* that periodicall #### Implement check logic -The following example is for an integration name `Awesome`. +The following example is for an integration named `Awesome`. The Agent Check is composed of a [service check][4] 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. @@ -443,4 +474,5 @@ In addition to any code changes, the following is required when bumping an integ [19]: https://docs.pytest.org/en/latest [20]: https://github.com/pypa/hatch [21]: https://packaging.python.org/en/latest/tutorials/packaging-projects/ -[22]: https://docs.datadoghq.com/agent/guide/use-community-integrations/ \ No newline at end of file +[22]: https://docs.datadoghq.com/agent/guide/use-community-integrations/ +[23]: https://docs.datadoghq.com/developers/integrations/?tab=integrations#out-of-the-box-integrations-vs-marketplace-offerings \ No newline at end of file From 86f70bab877687363175565ecbb954216cb98dc0 Mon Sep 17 00:00:00 2001 From: Dominic Medina Date: Fri, 31 Oct 2025 17:15:14 +0000 Subject: [PATCH 04/12] rewrite more sections --- .../integrations/agent_integration.md | 141 ++++++++++-------- 1 file changed, 78 insertions(+), 63 deletions(-) diff --git a/content/en/developers/integrations/agent_integration.md b/content/en/developers/integrations/agent_integration.md index df29a022e9f84..3e1808f9c9b5b 100644 --- a/content/en/developers/integrations/agent_integration.md +++ b/content/en/developers/integrations/agent_integration.md @@ -20,27 +20,33 @@ description: Learn how to develop and publish a Datadog Agent integration. --- ## Overview -This page guides Technology Partners through creating an official Datadog agent integration. Agent integrations are best suited for collecting telemetry from software or systems that run on customer-managed infrastructure, where the Datadog Agent can be installed. +This page guides Technology Partners through the process of creating an official Datadog Agent integration. -An Agent-based integration uses the [Datadog Agent][1] to submit data through custom agent checks written by approved Technolgoy Partners. These checks can emit [metrics][2], [events][3], [service checks][4], and [logs][5] into a customer's Datadog account. Agent-based integrations are published as a Python packages that easily allows customers to [install][6] via the Datadog Agent. +Agent-based integrations are designed to collect telemetry from software or systems running on customer-managed infrastructure, where the Datadog Agent is installed or has network access. These integrations use the [Datadog Agent][1] to collect and submit data through custom agent checks developed by approved Technology Partners. + +Agent checks can emit [metrics][2], [events][3], [service checks][4], and [logs][5] into a customer's Datadog account. Each agent-based integration is as a Python package, allowing customers to easily [install][6] it through the Datadog Agent. ## Building an agent-based integration -These steps assume you've [joined the Datadog Partner Network][7], have access to a partner developer organization, and have [created a listing in the Developer Platform][8]. +Before you being, ensure that you've [joined the Datadog Partner Network][7], have access to a partner developer organization, and have [created a listing in the Developer Platform][8]. + +Follow these steps to create your agent-based integration: 1. [Install the required development tools](#preqrequisites). 2. [Configure the Datadog Agent integration developer tool](#configure-the-datadog-agent-integration-developer-tool). -3. [Create the scaffolding for your integration](#create-the-scaffolding). -4. [Write your agent check](#write-your-agent-check). -5. [Test your agent check](#test-your-agent-check). -6. [Submit your code for review](#submit-your-code-for-review). +3. [Generate your integration scaffolding](#generate-your-scaffolding). +4. [Develop your agent check](#develop-your-agent-check). +5. [Test your integration](#test-your-agent-check). +6. [Submit your code for review](#submit-your-code). ### Preqrequisites -- Python v3.12 installed. -- [pipx][9] to install the development tooling and dependencies. -- [Datadog Agent Integration Developer Tool][10] (`ddev`) to create the necessary scaffolding. -- [Docker][11] to run the full test suite. -- Git ([command line][12] or [GitHub Desktop client][13]). +You'll need the following tools installed: + +- Python v3.12 +- [pipx][9] for installing development tooling and dependencies +- [Datadog Agent Integration Developer Tool][10] (`ddev`) to generate scaffolding and manage integration development +- [Docker][11] to run the full test suite +- Git ([command line][12] or [GitHub Desktop client][13]) ### Configure the Datadog Agent integration developer tool Use the Datadog Agent developer tool (ddev) to build and test your integration. The setup steps differ depending on whether you’re developing an [out-of-the-box (OOTB) integration or a Marketplace integration][23]. Select the appropriate tab below. @@ -119,44 +125,53 @@ Use the Datadog Agent developer tool (ddev) to build and test your integration. {{< /tabs >}} -### Create the scaffolding +### Generate your scaffolding -Use the `ddev create` command to generate the basic file and directory structure for an agent-based integration. +Use the `ddev create` command to generate the initial file and directory structure for your agent-based integration. -1. Test the setup first with a dry run (`-n` or `--dry-run`), which shows the paths and structure without writing to disk. Verify the output path matches the expected repository. +1. **Run a dry run (recommended)** + Use the `-n` or `--dry-run` flag to preview the files that will be created, without writing anything to disk. Confirm that the output path matches the expected repository location. + ```shell + ddev create -nt check_only --skip-manifest + ``` - ```shell - ddev create -nt check_only --skip-manifest - ``` +2. **Generate the files** + Once verified, run the same command without the `-n` to create the scaffolding. The tool will prompt you for integration details. + ```shell + ddev create -t check_only --skip-manifest + ``` -2. When ready, run the command without `-n` to create the files. The tool will prompt you for integration details. +### Develop your agent check - ```shell - ddev create -t check_only --skip-manifest - ``` +Each agent-based integration centers around an agent check, a Python class that periodically collects telemetry and submits it to Datadog. -### Write your agent check +Agent [checks][16] inherit from the the `AgentCheck` base class and must meet the following requirements: -At the core of each Agent-based integration is an *Agent Check* that periodically collects information and sends it to Datadog. - -[Checks][16] 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. +- **Python compatibility**: + - Integrations for Datadog Agent v7+ must support Python 3. + - Integrations for Datadog Agent v5-v6 use Python 2.7. +- **Class inheritance**: Each check must subclass `AgentCheck`. +- **Entry point**: Each check must implement a `check(self, instance)` method. +- **Package structure**: Checks are organized under the `datadog_checks` namespace. For example, an integration named lives in: `/datadog_checks//`. +- **Naming**: + - The package name must match the check name. + - Python module and class names within the package can be freely chosen. #### Implement check logic -The following example is for an integration named `Awesome`. +The following example shows a simple integration named `Awesome`. -The Agent Check is composed of a [service check][4] 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. +This check defines a [service check][4] called `awesome.search`, which searches a webpage for a specific string: + - Returns `OK` if the string is found. + - Returns `WARNING` if the page loads but the string is missing. + - Returns `CRITICAL` if the page cannot be reached. -To learn how to submit metrics with your Agent Check, see [Custom Agent Check][17]. To learn how to submit logs from your Agent Check, see [Agent Integration Log Collection][5]. +To learn how to submit additional data from your check, see: +    - [Custom Agent Check][17] for submitting metrics. +    - [Agent Integration Log Collection][5] for collecting logs from your AgentCheck using `send_log`. Best for simple, single-source log emission. +    - [HTTP Crawler Tutorial][24] for collecting logs from multiple log sources, such as when pollin several endpoints or external HTTP APIs. -The code contained within `awesome/datadog_checks/awesome/check.py` looks something like this: +The file `awesome/datadog_checks/awesome/check.py` might look like this: {{< code-block lang="python" filename="check.py" collapsible="true" >}} @@ -352,7 +367,6 @@ To speed up development, use the `-m/--marker` option to run integration tests o ``` ddev test -m integration awesome ``` -Your integration is almost complete. Return to the Developer Platform in your sandbox to finalize your submission. ## Test your agent check @@ -360,9 +374,9 @@ Agent-based integrations are distributed as Python wheel (.whl) files that custo ### Build the wheel -The `pyproject.toml` file provides the metadata that is used to package and build the wheel. The wheel contains the files necessary for the functioning of the integration itself, which includes the Agent Check, configuration example file, and artifacts generated during the wheel build. +The `pyproject.toml` file provides the metadata that is used to package and build the wheel. The wheel contains the files necessary for the functioning of the integration itself, which includes the agent check, configuration example file, and artifacts generated during the wheel build. -All additional elements, including the metadata files, are not meant to be contained within the wheel, and are used elsewhere by the Datadog platform and ecosystem. +All additional elements, including the metadata files, are not meant to be contained within the wheel, and are used elsewhere by the Datadog. To learn more about Python packaging, see [Packaging Python Projects][21]. @@ -413,41 +427,41 @@ For customer install commands for both host and container environments, see the ## Submit your code for review -Open a pull request with your integration directory in the approriate repo, either [Datadog/integrations-extras][14] or [Datadog/marketplace][15]. The pull request will be review in parrallel with your Developer Platform submission. +Open a pull request with your integration directory in the approriate repo, either [Datadog/integrations-extras][14] or [Datadog/marketplace][15]. The pull request will be reviewed in parrallel with your Developer Platform submission. ## Updating your integration -* If you are editing or adding new integration code, a version bump is required. -* If you are editing or adding new README content, manifest information, or assets such as dashboards and monitor templates, a version bump is not needed. +After your integration is published, you can release updates through the Developer Platform. ### Bumping an integration version -In addition to any code changes, the following is required when bumping an integration version: -1. Update `__about__.py` to reflect the new version number. This file can be found in your integration's directory under `/datadog_checks//__about__.py`. -2. Add an entry to the **Release Notes** in the Developer Platform that adheres to the following format: - ``` - ## Version Number / Date in YYYY-MM-DD +You’ll need to bump the version number whenever you add, remove, or modify functionality (for example, when introducing new metrics, updating dashboards, or changing integration code). A version bump isn’t required for non-functional updates, such as changes to written content, branding, logos, or images. - ***Added***: +In Developer Platform, include a new entry in the **Release Notes** tab following this format: + ``` + ## Version Number / Date (YYYY-MM-DD) - * New feature - * New feature + ***Added***: - ***Fixed***: + * Description of new feature + * Description of new feature - * Bug fix - * Bug fix + ***Fixed***: - ***Changed***: + * Description of fix + * Description of fix - * Feature update - * Feature update + ***Changed***: - ***Removed***: + * Description of update or improvement + * Description of update or improvement - * Feature removal - * Feature removal - ``` -3. Update all references to the version number mentioned in installation instructions and elsewhere. Installation instructions often include the version number, which needs to be updated. + ***Removed***: + + * Description of removed feature + * Description of removed feature + ``` + +Make sure to update all references to the version number across the integration's documentation and installation instructions. ## Further reading @@ -475,4 +489,5 @@ In addition to any code changes, the following is required when bumping an integ [20]: https://github.com/pypa/hatch [21]: https://packaging.python.org/en/latest/tutorials/packaging-projects/ [22]: https://docs.datadoghq.com/agent/guide/use-community-integrations/ -[23]: https://docs.datadoghq.com/developers/integrations/?tab=integrations#out-of-the-box-integrations-vs-marketplace-offerings \ No newline at end of file +[23]: https://docs.datadoghq.com/developers/integrations/?tab=integrations#out-of-the-box-integrations-vs-marketplace-offerings +[24]: https://datadoghq.dev/integrations-core/tutorials/logs/http-crawler/ \ No newline at end of file From d0582a7d26c5112f5cd20f9c17799bfa7821d6cd Mon Sep 17 00:00:00 2001 From: Dominic Medina Date: Fri, 31 Oct 2025 17:19:35 +0000 Subject: [PATCH 05/12] fix formatting --- .../integrations/agent_integration.md | 30 +++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/content/en/developers/integrations/agent_integration.md b/content/en/developers/integrations/agent_integration.md index 3e1808f9c9b5b..853119202428d 100644 --- a/content/en/developers/integrations/agent_integration.md +++ b/content/en/developers/integrations/agent_integration.md @@ -49,40 +49,51 @@ You'll need the following tools installed: - Git ([command line][12] or [GitHub Desktop client][13]) ### Configure the Datadog Agent integration developer tool -Use the Datadog Agent developer tool (ddev) to build and test your integration. The setup steps differ depending on whether you’re developing an [out-of-the-box (OOTB) integration or a Marketplace integration][23]. Select the appropriate tab below. +Use the Datadog Agent developer tool to build and test your integration. The setup steps differ depending on whether you’re developing an [out-of-the-box (OOTB) integration or a Marketplace integration][23]. Select the appropriate tab below. {{< tabs >}} {{% tab "OOTB integration" %}} 1. **Create a working directory** + The developer tool expects your work to be located in `$HOME/dd/`: + ```shell mkdir $HOME/dd && cd $HOME/dd ``` 2. **Fork the repository** + Fork the [Datadog/integrations-extras][14] repository to your GitHub account. 3. **Clone your fork** + Clone your fork into the `dd` directory: + ```shell git clone git@github.com:/integrations-extras.git ``` 4. **Create a feature branch** + Create and switch to a new branch for your integration: + ```shell cd integrations-extras git switch -c origin/master ``` 5. **Configure the default respository** + Set `extras` as the default working repository: + ```shell ddev config set repo extras ``` + If your repository is stored outside `$HOME/dd/`, specify the path before setting it as the default: + ```shell ddev config set repos.extras "/path/to/integrations-extras" ddev config set repo extras @@ -93,34 +104,45 @@ Use the Datadog Agent developer tool (ddev) to build and test your integration. {{% tab "Marketplace integration" %}} 1. **Create a working directory** + The developer tool expects your work to be located in `$HOME/dd/`: + ```shell mkdir $HOME/dd && cd $HOME/dd ``` 2. **Clone the repository** + Clone the [Datadog/marketplace][15] repository. If you don’t have access, request it from your Datadog contact. + ```shell git clone git@github.com:DataDog/marketplace.git ``` -3. **Create a feature branch** +3. **Create a feature branch** + Create and switch to a new branch for your integration: + ```shell cd marketplace git switch -c origin/master ``` 4. **Configure the default repository** + Set `marketplace` as the default working repository: + ```shell ddev config set repo marketplace ``` + If your repository is stored outside `$HOME/dd/`, specify the path before setting it as the default: + ```shell ddev config set repos.marketplace "/path/to/marketplace" ddev config set repo marketplace ``` + {{% /tab %}} {{< /tabs >}} @@ -130,13 +152,17 @@ Use the Datadog Agent developer tool (ddev) to build and test your integration. Use the `ddev create` command to generate the initial file and directory structure for your agent-based integration. 1. **Run a dry run (recommended)** + Use the `-n` or `--dry-run` flag to preview the files that will be created, without writing anything to disk. Confirm that the output path matches the expected repository location. + ```shell ddev create -nt check_only --skip-manifest ``` 2. **Generate the files** + Once verified, run the same command without the `-n` to create the scaffolding. The tool will prompt you for integration details. + ```shell ddev create -t check_only --skip-manifest ``` From b4237b994546a2a05e29d8c5f7b6df4d1da8d0b2 Mon Sep 17 00:00:00 2001 From: Dominic Medina Date: Fri, 31 Oct 2025 17:26:15 +0000 Subject: [PATCH 06/12] fix link references --- .../developers/integrations/agent_integration.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/content/en/developers/integrations/agent_integration.md b/content/en/developers/integrations/agent_integration.md index 853119202428d..473bee73bfd2f 100644 --- a/content/en/developers/integrations/agent_integration.md +++ b/content/en/developers/integrations/agent_integration.md @@ -65,7 +65,7 @@ Use the Datadog Agent developer tool to build and test your integration. The set 2. **Fork the repository** - Fork the [Datadog/integrations-extras][14] repository to your GitHub account. + Fork the [Datadog/integrations-extras][101] repository to your GitHub account. 3. **Clone your fork** @@ -99,6 +99,8 @@ Use the Datadog Agent developer tool to build and test your integration. The set ddev config set repo extras ``` +[101]: https://github.com/Datadog/integrations-extras + {{% /tab %}} {{% tab "Marketplace integration" %}} @@ -113,7 +115,7 @@ Use the Datadog Agent developer tool to build and test your integration. The set 2. **Clone the repository** - Clone the [Datadog/marketplace][15] repository. If you don’t have access, request it from your Datadog contact. + Clone the [Datadog/marketplace][101] repository. If you don’t have access, request it from your Datadog contact. ```shell git clone git@github.com:DataDog/marketplace.git @@ -143,6 +145,8 @@ Use the Datadog Agent developer tool to build and test your integration. The set ddev config set repo marketplace ``` +[101]: https://github.com/DataDog/marketplace + {{% /tab %}} {{< /tabs >}} @@ -162,7 +166,7 @@ Use the `ddev create` command to generate the initial file and directory structu 2. **Generate the files** Once verified, run the same command without the `-n` to create the scaffolding. The tool will prompt you for integration details. - + ```shell ddev create -t check_only --skip-manifest ``` @@ -496,13 +500,13 @@ Make sure to update all references to the version number across the integration' [1]: https://docs.datadoghq.com/agent/ [2]: https://docs.datadoghq.com/metrics/ [3]: https://docs.datadoghq.com/service_management/events/ -[4]: https://docs.datadoghq.com/developers/service_checks/ +[4]: /developers/service_checks/ [5]: https://docs.datadoghq.com/logs/log_collection/agent_checks/ [6]: https://docs.datadoghq.com/agent/guide/integration-management/?tab=linux#install [7]: /developers/integrations/?tab=integrations#join-the-datadog-partner-network [8]: /developers/integrations/build_integration/#create-a-listing [9]: https://github.com/pypa/pipx -[10]: https://docs.datadoghq.com/developers/integrations/python/ +[10]: /developers/integrations/python/ [11]: https://docs.docker.com/get-docker/ [12]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git [13]: https://desktop.github.com/ @@ -515,5 +519,5 @@ Make sure to update all references to the version number across the integration' [20]: https://github.com/pypa/hatch [21]: https://packaging.python.org/en/latest/tutorials/packaging-projects/ [22]: https://docs.datadoghq.com/agent/guide/use-community-integrations/ -[23]: https://docs.datadoghq.com/developers/integrations/?tab=integrations#out-of-the-box-integrations-vs-marketplace-offerings +[23]: /developers/integrations/?tab=integrations#out-of-the-box-integrations-vs-marketplace-offerings [24]: https://datadoghq.dev/integrations-core/tutorials/logs/http-crawler/ \ No newline at end of file From 1fa363b0a88fa505ea189e7e898aee3dc113d9bb Mon Sep 17 00:00:00 2001 From: Dominic Medina Date: Fri, 31 Oct 2025 17:53:59 +0000 Subject: [PATCH 07/12] minor formatting fix --- .../integrations/agent_integration.md | 33 ++++++++++--------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/content/en/developers/integrations/agent_integration.md b/content/en/developers/integrations/agent_integration.md index 473bee73bfd2f..f262da12b31f0 100644 --- a/content/en/developers/integrations/agent_integration.md +++ b/content/en/developers/integrations/agent_integration.md @@ -182,7 +182,7 @@ Agent [checks][16] inherit from the the `AgentCheck` base class and must meet th - Integrations for Datadog Agent v5-v6 use Python 2.7. - **Class inheritance**: Each check must subclass `AgentCheck`. - **Entry point**: Each check must implement a `check(self, instance)` method. -- **Package structure**: Checks are organized under the `datadog_checks` namespace. For example, an integration named lives in: `/datadog_checks//`. +- **Package structure**: Checks are organized under the `datadog_checks` namespace. For example, an integration named `` lives in: `/datadog_checks//`. - **Naming**: - The package name must match the check name. - Python module and class names within the package can be freely chosen. @@ -467,29 +467,30 @@ After your integration is published, you can release updates through the Develop You’ll need to bump the version number whenever you add, remove, or modify functionality (for example, when introducing new metrics, updating dashboards, or changing integration code). A version bump isn’t required for non-functional updates, such as changes to written content, branding, logos, or images. In Developer Platform, include a new entry in the **Release Notes** tab following this format: - ``` - ## Version Number / Date (YYYY-MM-DD) + +``` +## Version Number / Date (YYYY-MM-DD) - ***Added***: +***Added***: - * Description of new feature - * Description of new feature +* Description of new feature +* Description of new feature - ***Fixed***: +***Fixed***: - * Description of fix - * Description of fix +* Description of fix +* Description of fix - ***Changed***: +***Changed***: - * Description of update or improvement - * Description of update or improvement +* Description of update or improvement +* Description of update or improvement - ***Removed***: +***Removed***: - * Description of removed feature - * Description of removed feature - ``` +* Description of removed feature +* Description of removed feature +``` Make sure to update all references to the version number across the integration's documentation and installation instructions. From d882931556965a9a3ebd3999ed845c688bbeb283 Mon Sep 17 00:00:00 2001 From: Dominic Medina Date: Mon, 3 Nov 2025 11:33:24 +0000 Subject: [PATCH 08/12] fix vale warnings --- .../integrations/agent_integration.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/content/en/developers/integrations/agent_integration.md b/content/en/developers/integrations/agent_integration.md index f262da12b31f0..56943d874ec36 100644 --- a/content/en/developers/integrations/agent_integration.md +++ b/content/en/developers/integrations/agent_integration.md @@ -40,7 +40,7 @@ Follow these steps to create your agent-based integration: ### Preqrequisites -You'll need the following tools installed: +Ensure following tools are installed: - Python v3.12 - [pipx][9] for installing development tooling and dependencies @@ -49,7 +49,7 @@ You'll need the following tools installed: - Git ([command line][12] or [GitHub Desktop client][13]) ### Configure the Datadog Agent integration developer tool -Use the Datadog Agent developer tool to build and test your integration. The setup steps differ depending on whether you’re developing an [out-of-the-box (OOTB) integration or a Marketplace integration][23]. Select the appropriate tab below. +Use the Datadog Agent developer tool to build and test your integration. The setup steps differ depending on whether you're developing an [out-of-the-box (OOTB) integration or a Marketplace integration][23]. Select the appropriate tab below. {{< tabs >}} @@ -115,7 +115,7 @@ Use the Datadog Agent developer tool to build and test your integration. The set 2. **Clone the repository** - Clone the [Datadog/marketplace][101] repository. If you don’t have access, request it from your Datadog contact. + Clone the [Datadog/marketplace][101] repository. If you don't have access, request it from your Datadog contact. ```shell git clone git@github.com:DataDog/marketplace.git @@ -157,7 +157,7 @@ Use the `ddev create` command to generate the initial file and directory structu 1. **Run a dry run (recommended)** - Use the `-n` or `--dry-run` flag to preview the files that will be created, without writing anything to disk. Confirm that the output path matches the expected repository location. + Use the `-n` or `--dry-run` flag to preview the files that are generated, without writing anything to disk. Confirm that the output path matches the expected repository location. ```shell ddev create -nt check_only --skip-manifest @@ -165,7 +165,7 @@ Use the `ddev create` command to generate the initial file and directory structu 2. **Generate the files** - Once verified, run the same command without the `-n` to create the scaffolding. The tool will prompt you for integration details. + After verifying, run the same command without the `-n` to create the scaffolding. Follow the prompts to provide integration details. ```shell ddev create -t check_only --skip-manifest @@ -175,7 +175,7 @@ Use the `ddev create` command to generate the initial file and directory structu Each agent-based integration centers around an agent check, a Python class that periodically collects telemetry and submits it to Datadog. -Agent [checks][16] inherit from the the `AgentCheck` base class and must meet the following requirements: +Agent [checks][16] inherit from the `AgentCheck` base class and must meet the following requirements: - **Python compatibility**: - Integrations for Datadog Agent v7+ must support Python 3. @@ -189,7 +189,7 @@ Agent [checks][16] inherit from the the `AgentCheck` base class and must meet th #### Implement check logic -The following example shows a simple integration named `Awesome`. +The following example shows logic for an integration named `Awesome`. This check defines a [service check][4] called `awesome.search`, which searches a webpage for a specific string: - Returns `OK` if the string is found. @@ -198,7 +198,7 @@ This check defines a [service check][4] called `awesome.search`, which searches To learn how to submit additional data from your check, see:     - [Custom Agent Check][17] for submitting metrics. -    - [Agent Integration Log Collection][5] for collecting logs from your AgentCheck using `send_log`. Best for simple, single-source log emission. +    - [Agent Integration Log Collection][5] for collecting logs from your AgentCheck using `send_log`. Best for single-source log emission.     - [HTTP Crawler Tutorial][24] for collecting logs from multiple log sources, such as when pollin several endpoints or external HTTP APIs. The file `awesome/datadog_checks/awesome/check.py` might look like this: @@ -275,7 +275,7 @@ There are two types of tests: - [Unit tests for specific functionality](#write-a-unit-test) - [Integration tests that execute the `check` method and verify proper metrics collection](#write-an-integration-test) -[pytest][19] and [hatch][20] are used to run the tests. Tests are required in order to publish your integration. +[pytest][19] and [hatch][20] are used to run the tests. Tests are required to publish your integration. #### Write a unit test @@ -410,7 +410,7 @@ All additional elements, including the metadata files, are not meant to be conta To learn more about Python packaging, see [Packaging Python Projects][21]. -Once your `pyproject.toml` is ready, create a wheel using one of the following options: +After your `pyproject.toml` is ready, create a wheel using one of the following options: - (Recommended) With the `ddev` tooling: `ddev release build `. - Without the `ddev` tooling: `cd && pip wheel . --no-deps --wheel-dir dist`. @@ -464,7 +464,7 @@ Open a pull request with your integration directory in the approriate repo, eith After your integration is published, you can release updates through the Developer Platform. ### Bumping an integration version -You’ll need to bump the version number whenever you add, remove, or modify functionality (for example, when introducing new metrics, updating dashboards, or changing integration code). A version bump isn’t required for non-functional updates, such as changes to written content, branding, logos, or images. +A version bump is needed whenever you add, remove, or modify functionality (for example, when introducing new metrics, updating dashboards, or changing integration code). It's not required for non-functional updates, such as changes to written content, branding, logos, or images. In Developer Platform, include a new entry in the **Release Notes** tab following this format: From 7fdb6198e8ed7bcc52de0107d42e668d1f8d95df Mon Sep 17 00:00:00 2001 From: Dominic Medina <115744456+dd-dominic@users.noreply.github.com> Date: Thu, 6 Nov 2025 11:54:00 +0000 Subject: [PATCH 09/12] Update content/en/developers/integrations/agent_integration.md Co-authored-by: Erica Ho <109224841+eho1307@users.noreply.github.com> --- content/en/developers/integrations/agent_integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/developers/integrations/agent_integration.md b/content/en/developers/integrations/agent_integration.md index 56943d874ec36..8faf627bf7232 100644 --- a/content/en/developers/integrations/agent_integration.md +++ b/content/en/developers/integrations/agent_integration.md @@ -24,7 +24,7 @@ This page guides Technology Partners through the process of creating an official Agent-based integrations are designed to collect telemetry from software or systems running on customer-managed infrastructure, where the Datadog Agent is installed or has network access. These integrations use the [Datadog Agent][1] to collect and submit data through custom agent checks developed by approved Technology Partners. -Agent checks can emit [metrics][2], [events][3], [service checks][4], and [logs][5] into a customer's Datadog account. Each agent-based integration is as a Python package, allowing customers to easily [install][6] it through the Datadog Agent. +Agent checks can emit [metrics][2], [events][3], [service checks][4], and [logs][5] into a customer's Datadog account. Each agent-based integration is as a Python package built on top of the Datadog Agent, allowing customers to easily [install][6] it through the Datadog Agent. ## Building an agent-based integration Before you being, ensure that you've [joined the Datadog Partner Network][7], have access to a partner developer organization, and have [created a listing in the Developer Platform][8]. From 06d84f7df9c53cf9b92745da2c531f314ed24ac8 Mon Sep 17 00:00:00 2001 From: Dominic Medina <115744456+dd-dominic@users.noreply.github.com> Date: Thu, 6 Nov 2025 11:55:03 +0000 Subject: [PATCH 10/12] Update content/en/developers/integrations/agent_integration.md Co-authored-by: Erica Ho <109224841+eho1307@users.noreply.github.com> --- content/en/developers/integrations/agent_integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/developers/integrations/agent_integration.md b/content/en/developers/integrations/agent_integration.md index 8faf627bf7232..a6c2f2f3093c4 100644 --- a/content/en/developers/integrations/agent_integration.md +++ b/content/en/developers/integrations/agent_integration.md @@ -27,7 +27,7 @@ Agent-based integrations are designed to collect telemetry from software or syst Agent checks can emit [metrics][2], [events][3], [service checks][4], and [logs][5] into a customer's Datadog account. Each agent-based integration is as a Python package built on top of the Datadog Agent, allowing customers to easily [install][6] it through the Datadog Agent. ## Building an agent-based integration -Before you being, ensure that you've [joined the Datadog Partner Network][7], have access to a partner developer organization, and have [created a listing in the Developer Platform][8]. +Before you begin, ensure that you've [joined the Datadog Partner Network][7], have access to a partner developer organization, and have [created a listing in the Developer Platform][8]. Follow these steps to create your agent-based integration: From 9591e8e675e8baf4c7dcf7a2ad09d1cd72c9eb1d Mon Sep 17 00:00:00 2001 From: Dominic Medina Date: Thu, 6 Nov 2025 12:23:07 +0000 Subject: [PATCH 11/12] address feedback --- .../integrations/agent_integration.md | 65 +++++++------------ 1 file changed, 24 insertions(+), 41 deletions(-) diff --git a/content/en/developers/integrations/agent_integration.md b/content/en/developers/integrations/agent_integration.md index a6c2f2f3093c4..a55e6777dc285 100644 --- a/content/en/developers/integrations/agent_integration.md +++ b/content/en/developers/integrations/agent_integration.md @@ -31,14 +31,14 @@ Before you begin, ensure that you've [joined the Datadog Partner Network][7], ha Follow these steps to create your agent-based integration: -1. [Install the required development tools](#preqrequisites). +1. [Install the required development tools](#prerequisites). 2. [Configure the Datadog Agent integration developer tool](#configure-the-datadog-agent-integration-developer-tool). 3. [Generate your integration scaffolding](#generate-your-scaffolding). 4. [Develop your agent check](#develop-your-agent-check). 5. [Test your integration](#test-your-agent-check). -6. [Submit your code for review](#submit-your-code). +6. [Submit your code for review](#submit-your-code-for-review). -### Preqrequisites +### Prerequisites Ensure following tools are installed: @@ -55,38 +55,28 @@ Use the Datadog Agent developer tool to build and test your integration. The set {{% tab "OOTB integration" %}} -1. **Create a working directory** - - The developer tool expects your work to be located in `$HOME/dd/`: +1. Create a working directory. The developer tool expects your work to be located in `$HOME/dd/`: ```shell mkdir $HOME/dd && cd $HOME/dd ``` -2. **Fork the repository** +2. Fork the [Datadog/integrations-extras][101] repository to your GitHub account. - Fork the [Datadog/integrations-extras][101] repository to your GitHub account. - -3. **Clone your fork** - - Clone your fork into the `dd` directory: +3. Clone your fork into the `dd` directory: ```shell git clone git@github.com:/integrations-extras.git ``` -4. **Create a feature branch** - - Create and switch to a new branch for your integration: +4. Create and switch to a new branch for your integration: ```shell cd integrations-extras git switch -c origin/master ``` -5. **Configure the default respository** - - Set `extras` as the default working repository: +5. Set `extras` as the default working repository: ```shell ddev config set repo extras @@ -105,34 +95,26 @@ Use the Datadog Agent developer tool to build and test your integration. The set {{% tab "Marketplace integration" %}} -1. **Create a working directory** - - The developer tool expects your work to be located in `$HOME/dd/`: +1. Create a working directory. The developer tool expects your work to be located in `$HOME/dd/`: ```shell mkdir $HOME/dd && cd $HOME/dd ``` -2. **Clone the repository** - - Clone the [Datadog/marketplace][101] repository. If you don't have access, request it from your Datadog contact. +2. Clone the [Datadog/marketplace][101] repository. If you don't have access, request it from your Datadog contact. ```shell git clone git@github.com:DataDog/marketplace.git ``` -3. **Create a feature branch** - - Create and switch to a new branch for your integration: +3. Create and switch to a new branch for your integration: ```shell cd marketplace git switch -c origin/master ``` -4. **Configure the default repository** - - Set `marketplace` as the default working repository: +4. Set `marketplace` as the default working repository: ```shell ddev config set repo marketplace @@ -155,6 +137,8 @@ Use the Datadog Agent developer tool to build and test your integration. The set Use the `ddev create` command to generate the initial file and directory structure for your agent-based integration. +
See the Configuration Method tab in the Developer Platform for the correct command for your integration.
+ 1. **Run a dry run (recommended)** Use the `-n` or `--dry-run` flag to preview the files that are generated, without writing anything to disk. Confirm that the output path matches the expected repository location. @@ -165,7 +149,7 @@ Use the `ddev create` command to generate the initial file and directory structu 2. **Generate the files** - After verifying, run the same command without the `-n` to create the scaffolding. Follow the prompts to provide integration details. + After verifying the directory location, run the same command without the `-n` to create the scaffolding. Follow the prompts to provide integration details. ```shell ddev create -t check_only --skip-manifest @@ -178,7 +162,7 @@ Each agent-based integration centers around an agent check, a Python class that Agent [checks][16] inherit from the `AgentCheck` base class and must meet the following requirements: - **Python compatibility**: - - Integrations for Datadog Agent v7+ must support Python 3. + - Integrations for Datadog Agent v7+ must support Python 3. All new integrations must target v7+. - Integrations for Datadog Agent v5-v6 use Python 2.7. - **Class inheritance**: Each check must subclass `AgentCheck`. - **Entry point**: Each check must implement a `check(self, instance)` method. @@ -192,14 +176,15 @@ Agent [checks][16] inherit from the `AgentCheck` base class and must meet the fo The following example shows logic for an integration named `Awesome`. This check defines a [service check][4] called `awesome.search`, which searches a webpage for a specific string: - - Returns `OK` if the string is found. - - Returns `WARNING` if the page loads but the string is missing. - - Returns `CRITICAL` if the page cannot be reached. +- Returns `OK` if the string is found. +- Returns `WARNING` if the page loads but the string is missing. +- Returns `CRITICAL` if the page cannot be reached. To learn how to submit additional data from your check, see: -    - [Custom Agent Check][17] for submitting metrics. -    - [Agent Integration Log Collection][5] for collecting logs from your AgentCheck using `send_log`. Best for single-source log emission. -    - [HTTP Crawler Tutorial][24] for collecting logs from multiple log sources, such as when pollin several endpoints or external HTTP APIs. + +- [Custom Agent Check][17] for submitting metrics. +- [Agent Integration Log Collection][5] for collecting logs from your AgentCheck using `send_log`. Best for single-source log emission. +- [HTTP Crawler Tutorial][24] for collecting logs from multiple log sources, such as when pollin several endpoints or external HTTP APIs. The file `awesome/datadog_checks/awesome/check.py` might look like this: @@ -406,8 +391,6 @@ Agent-based integrations are distributed as Python wheel (.whl) files that custo The `pyproject.toml` file provides the metadata that is used to package and build the wheel. The wheel contains the files necessary for the functioning of the integration itself, which includes the agent check, configuration example file, and artifacts generated during the wheel build. -All additional elements, including the metadata files, are not meant to be contained within the wheel, and are used elsewhere by the Datadog. - To learn more about Python packaging, see [Packaging Python Projects][21]. After your `pyproject.toml` is ready, create a wheel using one of the following options: @@ -457,7 +440,7 @@ For customer install commands for both host and container environments, see the ## Submit your code for review -Open a pull request with your integration directory in the approriate repo, either [Datadog/integrations-extras][14] or [Datadog/marketplace][15]. The pull request will be reviewed in parrallel with your Developer Platform submission. +Open a pull request with your integration directory in the appropriate repo, either [Datadog/integrations-extras][14] or [Datadog/marketplace][15]. The pull request is reviewed in parallel with your Developer Platform submission. ## Updating your integration From 8c69fd38e955616fa0692ed55d998b1b82b97ca7 Mon Sep 17 00:00:00 2001 From: Dominic Medina Date: Fri, 7 Nov 2025 12:12:41 +0000 Subject: [PATCH 12/12] clarify sample_tags format --- content/en/developers/integrations/check_references.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/developers/integrations/check_references.md b/content/en/developers/integrations/check_references.md index 3dffaea4956f0..ab60b51ae6962 100644 --- a/content/en/developers/integrations/check_references.md +++ b/content/en/developers/integrations/check_references.md @@ -129,7 +129,7 @@ You can find the complete list of mandatory and optional attributes for the `met | `integration` | Mandatory | The name of the integration that emits the metric. Must be the normalized version of the `tile.title` from the `manifest.json` file. Any character besides letters, underscores, dashes, and numbers are converted to underscores. For example: `Openstack Controller` -> `openstack_controller`, `ASP.NET` -> `asp_net`, and `CRI-o` -> `cri-o`. | | `short_name` | Mandatory | A human-readable, abbreviated version of the metric name. Do not repeat the integration name. For example, `postgresql.index_blocks_hit` should be shortened to `idx blks hit`. | | `curated_metric`| Optional | Marks which metrics for an integration are noteworthy for a given type (`cpu` and `memory` are both accepted). These are displayed in the UI above the other integration metrics. | -| `sample_tags` | Optional | List of example tags associated with the metric, separated by commas without spaces. For example, `host,region,deployment`. | +| `sample_tags` | Optional | List of example tags associated with the metric, separated by commas (no spaces) and enclosed in quotes. For example, `"host,region,deployment"`. | ## Further Reading