Events with a Custom Agent Check

Submission

To submit an event from a custom Agent Check use the event(<EVENT_DICT>) function:

self.event(
            {
              "timestamp": <TIMESTAMP_EPOCH>,
              "event_type": "<EVENT_NAME>",
              "msg_title": "<TITLE>",
              "msg_text": "<MESSAGE>",
              "aggregation_key": "<AGGREGATION_KEY>",
              "alert_type": "<ALERT_TYPE>",
              "source_type_name": "<SOURCE_TYPE>",
              "host": "<HOSTNAME>",
              "tags": ["<TAGS>"],
              "priority": "<PRIORITY>"
            }
)

The following keys and data types are available in the event dictionary:

KeyTypeRequiredDescription
timestampIntegerYesThe epoch timestamp for the event
event_typeStringYesThe event name
msg_titleStringYesThe title of the event
msg_textStringYesThe text body of the event
aggregation_keyStringNoA key to use for aggregating events
alert_typeStringNoerror, warning, success, or info (defaults to info)
source_type_nameStringNoThe source type name
hostStringNoThe host name
tagsList of stringsNoA list of tags associated with this event.
priorityStringNoSpecifies the priority of the event (normal or low).

Example

This is an example of using a custom Agent check to send one event periodically. See Writing a Custom Agent Check for more details.

  1. Create a new directory event_example.d/ in the conf.d/ folder at the root of your Agent’s configuration directory.

  2. In the event_example.d/ folder, create a configuration file named event_example.yaml with the following content:

    instances: [{}]

  3. Up one level from the conf.d/ folder, go to the checks.d/ folder.

  4. In this folder, create a custom check file named event_example.py with the following content:

    event_example.py

        from datadog_checks.base import AgentCheck

    __version__ = "1.0.0"

    class MyClass(AgentCheck):
        def check(self, instance):
            self.event(
                {
                    "timestamp": time.time(),
                    "event_type": "Error",
                    "msg_title": "Example Event",
                    "msg_text": "This is an example event coming from Datadog.",
                    "alert_type": "error",
                }
            )

  5. Restart the Agent.

  6. For validation, run the Agent’s status command and look for event_example under the Checks section:

    =========
Collector
=========

  Running Checks
  ==============

    (...)

    event_example (1.0.0)
    ---------------------
      Instance ID: event_example:d884b5186b651429 [OK]
      Total Runs: 2
      Metric Samples: Last Run: 0, Total: 0
      Events: Last Run: 1, Total: 2
      Service Checks: Last Run: 0, Total: 0
      Average Execution Time : 0s

    (...)

Further reading

Additional helpful documentation, links, and articles:

Writing a Custom Agent CheckDOCUMENTATION more more