Install & Compatibility
Where this runs
tested against v37.40.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 20.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.8s · import 0.000s · 21MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AgentCheck
✓ from datadog_checks.base.checks.base import AgentCheck
✗ from datadog_checks.base import AgentCheck
To create a custom Datadog Agent check, define a Python class that inherits from `AgentCheck` and implements a `check(self, instance)` method. The `check` method is invoked by the Agent to collect and submit data. Metrics are submitted using methods like `self.gauge()`, `self.count()`, `self.service_check()`, etc. Ensure your check file includes a `__version__` variable. For the Agent to discover and run the check, place the Python file in the Agent's `checks.d` directory and a corresponding YAML configuration file in `conf.d`.
import os
from datadog_checks.base.checks import AgentCheck
__version__ = "1.0.0"
class MyCustomCheck(AgentCheck):
def check(self, instance):
# The 'instance' dictionary contains configuration for this check instance from its YAML file.
# E.g., if your my_custom_check.yaml has 'instances: [{ 'foo': 'bar' }]'
# then 'instance' here would be { 'foo': 'bar' }.
# Submit a simple gauge metric
self.gauge('my_app.metric.hello_world', 1, tags=['env:dev', 'region:us-east-1'])
self.log.info("Submitted my_app.metric.hello_world")
# Example of getting configuration from instance
custom_value = instance.get('custom_config_key', 'default_value')
self.log.debug(f"Custom config value: {custom_value}")
# To run this, place in checks.d/my_custom_check.py and create conf.d/my_custom_check.yaml:
# init_config:
# instances:
# - custom_config_key: 'my_special_value'
Debug
Known issues
breakingDatadog Agent v7+ requires Python 3 for all custom checks and integrations. If you are migrating from Agent v5 or v6, which supported Python 2.7, your custom checks will need to be updated for Python 3 compatibility.fixMigrate your custom check code to Python 3. The official 'Python 3 Custom Check Migration' guide provides details, including changes to import paths like `AgentCheck`.
affects: < 7.0.0 (for Agent)
gotchaAvoid using Python's standard `subprocess` or `multiprocessing` modules directly within your Agent checks. The Agent's embedded Python interpreter runs in a multi-threaded Go runtime, and direct usage of these modules can lead to crashes, stuck, or zombie processes.fixAlways use `datadog_checks.base.utils.subprocess_output.get_subprocess_output` for running external commands from your checks.
affects: All
gotchaCustom checks may appear to run without errors but fail to report metrics if the output from `get_subprocess_output` is not processed into a numerical type (int or float) or if the Agent user lacks the necessary file/directory permissions to execute commands.fixEnsure that any string output from `get_subprocess_output` is explicitly converted to an `int` or `float` before being passed to metric submission methods (e.g., `self.gauge`). Verify that the `dd-agent` user has appropriate read/execute permissions for all referenced files and commands.
affects: All
gotchaA custom check will not be executed by the Datadog Agent if its corresponding YAML configuration file in `conf.d` does not contain at least one instance under the `instances:` key, even if it's an empty dictionary.fixEnsure your check's YAML configuration (e.g., `my_check.yaml`) has an `instances:` section with at least one entry, for example: `instances: [{}]`. affects: All
Upgrade
Version history
37.40.0latest on PyPI · released Jun 10, 2026
Audit
Dependencies
pythonrequiredAgent v7+ requires Python 3 for custom checks and integrations.
datadog-checks-devoptionalToolkit for local development, testing, and dependency management of Datadog checks.