Datadog Checks Base

Common errors

• ImportError: cannot import name 'AgentCheck' from 'datadog_checks.checks' (likely /opt/datadog-agent/embedded/lib/python3.x/site-packages/datadog_checks/checks/__init__.py)

  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`.
  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`.

• Custom check runs but no metrics are reported in Datadog.

  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.
  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.

• datadog_checks.base.errors.ConfigurationError: InstanceConfig:api_key - Input should be a valid string

  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.
  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.

• Datadog Agent status shows 'Check: my_custom_check [ERROR]' or custom check not listed.

  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.
  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.

Warnings

• breaking 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.
  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`.
• gotcha 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.
  Fix: Always use `datadog_checks.base.utils.subprocess_output.get_subprocess_output` for running external commands from your checks.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Ensure your check's YAML configuration (e.g., `my_check.yaml`) has an `instances:` section with at least one entry, for example: `instances: [{}]`.

Install

• pip install datadog-checks-base Install latest version

Imports

• AgentCheck
  wrong:

  from datadog_checks.checks import AgentCheck

  correct:

  from datadog_checks.base.checks import AgentCheck

  The import path for AgentCheck changed with Python 3 and Agent v7+ for standardized namespacing.
• get_subprocess_output

  from datadog_checks.base.utils.subprocess_output import get_subprocess_output

  Recommended way to run subprocesses within a Datadog Agent check.

Quickstart

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'