---
title: Events with a Custom Agent Check
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: Docs > Event Management > Events Guides > Events with a Custom Agent Check
---

# Events with a Custom Agent Check

## Submission{% #submission %}

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

```text
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:

| Key                | Type            | Required | Description                                                   |
| ------------------ | --------------- | -------- | ------------------------------------------------------------- |
| `timestamp`        | Integer         | Yes      | The epoch timestamp for the event                             |
| `event_type`       | String          | Yes      | The event name                                                |
| `msg_title`        | String          | Yes      | The title of the event                                        |
| `msg_text`         | String          | Yes      | The text body of the event                                    |
| `aggregation_key`  | String          | No       | A key to use for aggregating events                           |
| `alert_type`       | String          | No       | `error`, `warning`, `success`, or `info` (defaults to `info`) |
| `source_type_name` | String          | No       | The source type name                                          |
| `host`             | String          | No       | The host name                                                 |
| `tags`             | List of strings | No       | A list of tags associated with this event.                    |
| `priority`         | String          | No       | Specifies the priority of the event (`normal` or `low`).      |

### Example{% #example %}

This is an example of using a custom Agent check to send one event periodically. See [Writing a Custom Agent Check](https://docs.datadoghq.com/extend/custom_checks/write_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](https://docs.datadoghq.com/agent/configuration/agent-configuration-files/#agent-configuration-directory).

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

   ```yaml
   instances: [{}]
   ```

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

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

In the `event_example.py` file:

   ```python
       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",
                   }
               )
       
```

1. [Restart the Agent](https://docs.datadoghq.com/agent/configuration/agent-commands/#restart-the-agent).

1. For validation, run the [Agent's status command](https://docs.datadoghq.com/agent/configuration/agent-commands/#agent-information) 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{% #further-reading %}

- [Writing a Custom Agent Check](https://docs.datadoghq.com/extend/custom_checks/write_agent_check/)