Differences

This shows you the differences between two versions of the page.

--- devops:monitoring:datadog:integrations [2025/02/14 10:04] – created 85.219.17.206
+++ devops:monitoring:datadog:integrations [2025/02/14 10:15] (current) – 85.219.17.206
@@ Line 1: / Line 1: @@
-Create an Agent Integration
+====== Create an Agent Integration ======
-Docs >  Developers >  Build an Integration >  Create an Agent Integration
-Overview
+===== 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, or for a price on the Marketplace page.
@@ Line 15: / Line 15: @@
 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.
+  * 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.
+  * 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).
+  * 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.
+  * 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 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.
+  * 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.
+  * 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.
-Prerequisites
+==== Prerequisites ====
 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.
+  * 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.
+  * Docker to run the full test suite.
-    The git command line or GitHub Desktop client.
+  * 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 an out-of-the-box integration
-    Build a Marketplace integration
+  *  Build a Marketplace integration
 To build an out-of-the-box integration:
@@ Line 40: / Line 40: @@
 Create a dd directory:
-mkdir $HOME/dd && cd $HOME/dd
+   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.
+  * Fork the integrations-extras repository.
+  *
-    Clone your fork into the dd directory:
+  * Clone your fork into the dd directory:
     git clone git@github.com:<YOUR USERNAME>/integrations-extras.git
@@ Line 52: / Line 52: @@
 Create a feature branch to work in:
-git switch -c <YOUR INTEGRATION NAME> origin/master
+    git switch -c <YOUR INTEGRATION NAME> origin/master
 Configure the developer tool
@@ Line 88: / Line 88: @@
 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.
-To learn how to submit metrics with your Agent Check, see Custom Agent Check.
-The code contained within awesome/datadog_checks/awesome/check.py looks something like this:
-check.py
-import requests
-from datadog_checks.base import AgentCheck, ConfigurationError
-class AwesomeCheck(AgentCheck):
-    """AwesomeCheck derives from AgentCheck, and provides the required check method."""
-    def check(self, instance):
-        url = instance.get('url')
-        search_string = instance.get('search_string')
-        # It's a very good idea to do some basic sanity checking.
-        # Try to be as specific as possible with the exceptions.
-        if not url or not search_string:
-            raise ConfigurationError('Configuration error, please fix awesome.yaml')
-        try:
-            response = requests.get(url)
-            response.raise_for_status()
-        # Something went horribly wrong
-        except Exception as e:
-            # Ideally we'd use a more specific message...
-            self.service_check('awesome.search', self.CRITICAL, message=str(e))
-        # Page is accessible
-        else:
-            # search_string is present
-            if search_string in response.text:
-                self.service_check('awesome.search', self.OK)
-            # search_string was not found
-            else:
-                self.service_check('awesome.search', self.WARNING)
-To learn more about the base Python class, see Anatomy of a Python Check.
-Write validation tests
-There are two types of tests:
-    Unit tests for specific functionality
-    Integration tests that execute the check method and verify proper metrics collection
-pytest and hatch are used to run the tests. Tests are required in order to publish your integration.
-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.
-Open the file at awesome/tests/test_awesome.py and replace the contents with the following:
-test_awesome.py
-import pytest
-    # Don't forget to import your integration
-from datadog_checks.awesome import AwesomeCheck
-from datadog_checks.base import ConfigurationError
-@pytest.mark.unit
-def test_config():
-    instance = {}
-    c = AwesomeCheck('awesome', {}, [instance])
-    # empty instance
-    with pytest.raises(ConfigurationError):
-        c.check(instance)
-    # only the url
-    with pytest.raises(ConfigurationError):
-        c.check({'url': 'http://foobar'})
-    # only the search string
-    with pytest.raises(ConfigurationError):
-        c.check({'search_string': 'foo'})
-    # this should not fail
-    c.check({'url': 'http://foobar', 'search_string': 'foo'})
-pytest has the concept of markers that can be used to group tests into categories. Notice that test_config is marked as a unit test.
-The scaffolding is set up to run all the tests located in awesome/tests. To run the tests, run the following command:
-ddev test awesome
-Write an integration test
-The unit test above doesn’t check the collection logic. To test the logic, you need to create an environment for an integration test and write an 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.
-To create an environment for the integration test, create a docker-compose file at awesome/tests/docker-compose.yml with the following contents:
-docker-compose.yml
-version: "3"
-services:
-  nginx:
-    image: nginx:stable-alpine
-    ports:
-      - "8000:80"
-Next, open the file at awesome/tests/conftest.py and replace the contents with the following:
-conftest.py
-import os
-import pytest
-from datadog_checks.dev import docker_run, get_docker_hostname, get_here
-URL = 'http://{}:8000'.format(get_docker_hostname())
-SEARCH_STRING = 'Thank you for using nginx.'
-INSTANCE = {'url': URL, 'search_string': SEARCH_STRING}
-@pytest.fixture(scope='session')
-def dd_environment():
-    compose_file = os.path.join(get_here(), 'docker-compose.yml')
-    # This does 3 things:
-    #
-    # 1. Spins up the services defined in the compose file
-    # 2. Waits for the url to be available before running the tests
-    # 3. Tears down the services when the tests are finished
-    with docker_run(compose_file, endpoints=[URL]):
-        yield INSTANCE
-@pytest.fixture
-def instance():
-    return INSTANCE.copy()
-Add an integration test
-After you’ve setup an environment for the integration test, add an integration test to the awesome/tests/test_awesome.py file:
-test_awesome.py
-@pytest.mark.integration
-@pytest.mark.usefixtures('dd_environment')
-def test_service_check(aggregator, instance):
-    c = AwesomeCheck('awesome', {}, [instance])
-    # the check should send OK
-    c.check(instance)
-    aggregator.assert_service_check('awesome.search', AwesomeCheck.OK)
-    # the check should send WARNING
-    instance['search_string'] = 'Apache'
-    c.check(instance)
-    aggregator.assert_service_check('awesome.search', AwesomeCheck.WARNING)
-To speed up development, use the -m/--marker option to run integration tests only:
-ddev test -m integration awesome
-Your integration is almost complete. Next, add the necessary check assets.
-Populate integration assets
-The following set of assets created by the ddev scaffolding must be populated with relevant information to your integration:
-README.md
-    This contains the documentation for your Agent Check, how to set it up, which data it collects, and support information.
-spec.yaml
-    This is used to generate the conf.yaml.example using the ddev tooling. For more information, see Configuration Specification.
-conf.yaml.example
-    This contains default (or example) configuration options for your Agent Check. Do not edit this file by hand. It is generated from the contents of spec.yaml. For more information, see the Configuration file reference documentation.
-manifest.json
-    This contains the metadata for your Agent Check such as the title and categories. For more information, see the Manifest file reference documentation.
-metadata.csv
-    This contains the list of all metrics collected by your Agent Check. For more information, see the Metrics metadata file reference documentation.
-service_check.json
-    This contains the list of all Service Checks collected by your Agent Check. For more information, see the Service check file reference documentation.
-For more information about the README.md and manifest.json files, see Create a Tile and Integrations Asset Reference.
-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.
-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.
-Once your pyproject.toml is ready, create a wheel using one of the following options:
-    (Recommended) With the ddev tooling: ddev release build <INTEGRATION_NAME>.
-    Without the ddev tooling: cd <INTEGRATION_DIR> && pip wheel . --no-deps --wheel-dir dist.
-Install the wheel
-The wheel is installed using the Agent integration command, available in Agent v6.10.0 or later. Depending on your environment, you may need to execute this command as a specific user or with specific privileges:
-Linux (as dd-agent):
-sudo -u dd-agent datadog-agent integration install -w /path/to/wheel.whl
-OSX (as admin):
-sudo datadog-agent integration install -w /path/to/wheel.whl
-Windows PowerShell (Ensure that your shell session has administrator privileges):
-Agent v6.11 or earlier
-Agentv6.12 or later
-& "C:\Program Files\Datadog\Datadog Agent\bin\agent.exe" integration install -w /path/to/wheel.whl
-For installing your wheel to test in Kubernetes environments:
-    Mount the .whl file into an initContainer.
-    Run the wheel install in the initContainer.
-    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.
-Populate your tile and publish your integration
-Once you have created your Agent-based integration, see the Create a tile documentation for information on populating the remaining required assets that appear on your integration tile, and opening a pull request.
-Update your integration
-To update your integration, edit the relevant files and open a new pull request to your integration’s directory in the integrations-extras or marketplace repository.
-    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 making updates to assets such as dashboards and monitor templates, or non-code files such as README.md and manifest.json, no further action is needed from the developer after the corresponding pull requests have been merged. These changes will show up for the customer without any action on their end.
-Bumping an integration version
-In addition to any code changes, the following is required when bumping an integration version:
-    Update __about__.py to reflect the new version number. This file can be found in your integration’s directory under /datadog_checks/<your_check_name>/__about__.py.
-    Add an entry to the CHANGELOG.md file that adheres to the following format:
-    ## Version Number / Date
-    ***Added***:
-    * New feature
-    * New feature
-    ***Fixed***:
-    * Bug fix
-    * Bug fix
-    Update all references to the version number mentioned in README.md and elsewhere. Installation instructions in README.md often include the version number, which needs to be updated.