Service Check Submission: Agent Check

To submit a service check to Datadog within a custom Agent check, use the predefined service_check() function in the AgentCheck class.

self.service_check(name, status, tags=None, hostname=None, message=None)

Find below the different parameters and data types available for the service_check() function:

ParameterTypeRequiredDefault ValueDescription
namestringyes-The name of the service check.
statusintyes-A constant describing the service status: 0 for OK, 1 for Warning, 2 for Critical, and 3 for Unknown.
tagslist of stringsnoNoneA list of tags to associate with this Service Check.
hostnamestringnocurrent hostA hostname to associate with this Service check. Defaults to the current host.
messagestringnoNoneAdditional information or a description of why this status occurred.


Here is an example of a dummy Agent check sending only one service check periodically. See Writing a Custom Agent Check to learn more.

  1. Create a new directory, service_check_example.d/, in the conf.d/ folder of your Agent.

  2. In your service_check_example.d/ folder, create an empty configuration file named service_check_example.yaml with the following content:

    instances: [{}]
  3. Up one level from the conf.d/ folder, go to the checks.d/ folder.

  4. Within this folder, create a custom check file named with the content below:

    from datadog_checks.base import AgentCheck
    __version__ = "1.0.0"
    class MyClass(AgentCheck):
        def check(self, instance):
            self.service_check('example_service_check', 0, message='Example application is up and running.')
  5. Restart the Agent

  6. Ensure that your custom check is correctly running with the Agent status command. You should see something like this:

      Running Checks
        service_check_example (1.0.0)
          Instance ID: service_check_example:d884b5186b651429 [OK]
          Total Runs: 1
          Metric Samples: Last Run: 0, Total: 0
          Events: Last Run: 0, Total: 0
          Service Checks: Last Run: 1, Total: 1
          Average Execution Time : 2ms
  7. Finally, see your Datadog service check summary to see your service check reporting:

Service Checks

Further reading

Additional helpful documentation, links, and articles: