{"id":8068,"library":"datadog-checks-base","title":"Datadog Checks Base","description":"datadog-checks-base provides the foundational Python classes and utilities for developing custom Datadog Agent integrations, also known as Checks. It functions both within the Datadog Agent's embedded Python interpreter and in local development environments for testing and validation. The library is currently at version 37.35.0 and maintains an active release cadence, frequently updated to align with new Datadog Agent and integration functionalities.","status":"active","version":"37.35.0","language":"en","source_language":"en","source_url":"https://github.com/DataDog/integrations-core","tags":["monitoring","observability","datadog","agent","checks","custom checks","integrations"],"install":[{"cmd":"pip install datadog-checks-base","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Agent v7+ requires Python 3 for custom checks and integrations.","package":"python","optional":false},{"reason":"Toolkit for local development, testing, and dependency management of Datadog checks.","package":"datadog-checks-dev","optional":true}],"imports":[{"note":"The import path for AgentCheck changed with Python 3 and Agent v7+ for standardized namespacing.","wrong":"from datadog_checks.checks import AgentCheck","symbol":"AgentCheck","correct":"from datadog_checks.base.checks import AgentCheck"},{"note":"Recommended way to run subprocesses within a Datadog Agent check.","symbol":"get_subprocess_output","correct":"from datadog_checks.base.utils.subprocess_output import get_subprocess_output"}],"quickstart":{"code":"import os\nfrom datadog_checks.base.checks import AgentCheck\n\n__version__ = \"1.0.0\"\n\nclass MyCustomCheck(AgentCheck):\n    def check(self, instance):\n        # The 'instance' dictionary contains configuration for this check instance from its YAML file.\n        # E.g., if your my_custom_check.yaml has 'instances: [{ 'foo': 'bar' }]'\n        # then 'instance' here would be { 'foo': 'bar' }.\n        \n        # Submit a simple gauge metric\n        self.gauge('my_app.metric.hello_world', 1, tags=['env:dev', 'region:us-east-1'])\n        self.log.info(\"Submitted my_app.metric.hello_world\")\n\n        # Example of getting configuration from instance\n        custom_value = instance.get('custom_config_key', 'default_value')\n        self.log.debug(f\"Custom config value: {custom_value}\")\n\n        # To run this, place in checks.d/my_custom_check.py and create conf.d/my_custom_check.yaml:\n        # init_config:\n        # instances:\n        #   - custom_config_key: 'my_special_value'\n","lang":"python","description":"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`."},"warnings":[{"fix":"Migrate your custom check code to Python 3. The official 'Python 3 Custom Check Migration' guide provides details, including changes to import paths like `AgentCheck`.","message":"Datadog 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.","severity":"breaking","affected_versions":"< 7.0.0 (for Agent)"},{"fix":"Always use `datadog_checks.base.utils.subprocess_output.get_subprocess_output` for running external commands from your checks.","message":"Avoid 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure 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.","message":"Custom 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your check's YAML configuration (e.g., `my_check.yaml`) has an `instances:` section with at least one entry, for example: `instances: [{}]`.","message":"A 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Update the import statement in your custom check's Python file from `from datadog_checks.checks import AgentCheck` to `from datadog_checks.base.checks import AgentCheck`.","cause":"This error typically occurs when a custom check, originally written for an older Agent (Python 2 or early Python 3), uses the old import path for `AgentCheck`.","error":"ImportError: cannot import name 'AgentCheck' from 'datadog_checks.checks' (likely /opt/datadog-agent/embedded/lib/python3.x/site-packages/datadog_checks/checks/__init__.py)"},{"fix":"When using `get_subprocess_output`, ensure the collected value is explicitly cast to `int` or `float` before `self.gauge()` or `self.count()`. Also, check filesystem permissions for the Agent user (`dd-agent`) to ensure it can execute the necessary commands and read relevant files.","cause":"This can be caused by the output of external commands not being converted to a numerical type before metric submission, or by insufficient file/command permissions for the `dd-agent` user.","error":"Custom check runs but no metrics are reported in Datadog."},{"fix":"Review the check's `conf.yaml` file and the main `datadog.yaml` file. Ensure all required parameters are present, correctly formatted, and that sensitive information like API keys are properly configured and accessible to the Agent. Consult the specific check's documentation for required configuration fields.","cause":"A required configuration parameter for an Agent check (such as an API key) is missing, malformed, or not accessible from the check's configuration.","error":"datadog_checks.base.errors.ConfigurationError: InstanceConfig:api_key - Input should be a valid string"},{"fix":"Verify that `my_custom_check.py` is located in the Agent's `checks.d` directory and `my_custom_check.yaml` is in the `conf.d` directory, with identical base names. After making changes, restart the Datadog Agent (`sudo systemctl restart datadog-agent` on Linux) to reload the configuration.","cause":"The Agent cannot find or correctly load the custom check. Common reasons include incorrect file placement, a mismatch between the Python check file name and its YAML configuration file name, or the Agent not being restarted after file changes.","error":"Datadog Agent status shows 'Check: my_custom_check [ERROR]' or custom check not listed."}]}