monitors

Datadog monitors

This module creates Datadog monitors. It accepts all the configuration parameters supported by the Datadog Terraform resource.

Usage

The datadog_monitors input takes a map of test definitions. You must supply the keys for the map, but the values can follow either of two schemas described below.

There are some optional additions to the monitor definition that are not part of the Datadog API schema. These are:

• force_delete (boolean): If true, when deleting the monitor, the monitor will be deleted even if it is referenced by other resources.
• validate (boolean): If false, the monitor will not be validated during the Terraform plan phase.
• enabled (boolean): If false, the monitor will not be created. This is to allow you to suppress a monitor created through merging configuration snippets.

Tags

This module provides special handling for tags. The tags attribute of a monitor definition in the Datadog API and the Terraform resource is a list of strings. However, the Cloud Posse (as well as AWS) default is to use a map of strings for tags. This module allows you to provide either a list or a map for the tags.

If you provide a list, it will be used as is. If you provide a map, it will be converted to a list of strings in the format key:value (or key if value is null). If you provide no tag settings at all, not even an empty list or map, the module will use the default tags from the null-label module.

API Schema (preferred)

Datadog provides a REST API for managing monitors. We refer to the responses to the API requests for monitor definitions (GET https://api.datadoghq.com/api/v1/monitor/{monitor_id}) as the "API Schema" for the tests. This should correspond to the documented API "Model" for Monitors plus additional information such as creation date, but if the documentation and the API response differ, we use the API response as the source of truth.

You can retrieve Monitor definitions from Datadog via the Datadog Web Console. Navigate to the monitor you want to retrieve, click the gear icon in the upper right (representing "settings"), and select "Export". This will display a JSON representation of the monitor definition. You can then click the "Copy" button to copy the JSON to the clipboard.

Example of JSON for monitors

Note that many elements of the monitor definition are optional, and the JSON representation will only include the elements that are set. This is an example of a monitor, not a comprehensive list of all possible elements.

{
  "name": "schedule-test",
  "type": "event-v2 alert",
  "query": "events(\"service:datadog-agent\").rollup(\"cardinality\", \"@evt.id\").current(\"1h\") > 2345",
  "message": "No message",
  "tags": [
    "test:examplemonitor",
    "Terratest"
  ],
  "options": {
    "thresholds": {
      "critical": 2345,
      "warning": 987
    },
    "enable_logs_sample": false,
    "notify_audit": false,
    "on_missing_data": "default",
    "include_tags": false,
    "scheduling_options": {
      "custom_schedule": {
        "recurrences": [
          {
            "rrule": "FREQ=DAILY;INTERVAL=1;BYHOUR=17;BYMINUTE=54",
            "timezone": "America/Los_Angeles"
          }
        ]
      },
      "evaluation_window": {
        "hour_starts": 7
      }
    }
  },
  "priority": 5
}

You can find other examples in the examples/complete/monitors-test/ directory.

You can then use the jsondecode() function in Terraform to convert the JSON to a Terraform object, and use that object as the value for the monitor definition. You can also transform the JSON to HCL other ways, however you prefer. The relevant point is that this module will accept the monitor definition in this schema. Any field in the API schema that does not have a counterpart in the Terraform schema will be ignored.

Special Notes

The alert_tags input is provided for convenience. It is used to add notification tags to the monitor message. However, it does not check to see if the tags are already present. If the tags are already present, they will still be added again.

important

If you define a monitor via JSON, and then you use alert_tags when creating it, and then export the JSON representation of the created monitor definition, it will not match because of the added tags.

Note that restricted_roles_map provides a convenient way to specify the restricted_roles attribute of the monitor. This is a map of monitors to sets of Datadog unique role identifiers. If provided, this will override the restricted_roles attribute of the monitor definition. If not provided, the restricted_roles attribute of the monitor definition will be used, if present.

important

Legacy schema (deprecated)

Historically, and preserved for backward compatibility, you can configure tests using the schema used in v1.3.0 and earlier. This schema flattens the monitor definition, pulling up the options attributes to the top level.

Note that not all fields are supported in this schema, and it is only preserved for backward compatibility. We recommend that you use the API schema going forward.

Requirements

Name	Version
terraform	>= 1.0.0
datadog	>= 3.36.0

Providers

Name	Version
datadog	>= 3.36.0

Modules

Name	Source	Version
this	cloudposse/label/null	0.25.0

Resources

Name	Type
datadog_monitor.default	resource

Inputs

Name	Description	Type	Default	Required
additional_tag_map	Additional key-value pairs to add to each map in tags_as_list_of_maps. Not added to tags or id. This is for some rare cases where resources want additional configuration of tags and therefore take a list of maps with tag key, value, and additional configuration.	map(string)	{}	no
alert_tags	List of alert tags to add to all alert messages, e.g. ["@opsgenie"] or ["@devops", "@opsgenie"]	list(string)	null	no
alert_tags_separator	Separator for the alert tags. All strings from the alert_tags variable will be joined into one string using the separator and then added to the alert message	string	"\n"	no
attributes	ID element. Additional attributes (e.g. workers or cluster) to add to id, in the order they appear in the list. New attributes are appended to the end of the list. The elements of the list are joined by the delimiter and treated as a single ID element.	list(string)	[]	no
context	Single object for setting entire context at once. See description of individual variables for details. Leave string and numeric variables as null to use default value. Individual variable settings (non-null) override settings in context object, except for attributes, tags, and additional_tag_map, which are merged.	any	{ "additional_tag_map": {}, "attributes": [], "delimiter": null, "descriptor_formats": {}, "enabled": true, "environment": null, "id_length_limit": null, "label_key_case": null, "label_order": [], "label_value_case": null, "labels_as_tags": [ "unset" ], "name": null, "namespace": null, "regex_replace_chars": null, "stage": null, "tags": {}, "tenant": null }	no
datadog_monitors	Map of Datadog monitor configurations. See the README for details on the expected structure. Keys will be used as monitor names if not provided in the name attribute. Attributes match Datadog "Create a monitor" API. For backward compatibility, attributes under options in the API schema that were previously allowed at the top level remain available at the top level if no options are provided. Because new_host_delay is deprecated, it is ignored unless set to zero.	any	n/a	yes
default_tags_enabled	If true, monitors without tags in their definitions will have tags from null-label added to them. Note that even an empty list or map of tags in the monitor definition will keep the default tags from being added.	bool	true	no
delimiter	Delimiter to be used between ID elements. Defaults to - (hyphen). Set to "" to use no delimiter at all.	string	null	no
descriptor_formats	Describe additional descriptors to be output in the descriptors output map. Map of maps. Keys are names of descriptors. Values are maps of the form {<br/> format = string<br/> labels = list(string)<br/>} (Type is any so the map values can later be enhanced to provide additional options.) format is a Terraform format string to be passed to the format() function. labels is a list of labels, in order, to pass to format() function. Label values will be normalized before being passed to format() so they will be identical to how they appear in id. Default is {} (descriptors output will be empty).	any	{}	no
enabled	Set to false to prevent the module from creating any resources	bool	null	no
environment	ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT'	string	null	no
id_length_limit	Limit id to this many characters (minimum 6). Set to 0 for unlimited length. Set to null for keep the existing setting, which defaults to 0. Does not affect id_full.	number	null	no
label_key_case	Controls the letter case of the tags keys (label names) for tags generated by this module. Does not affect keys of tags passed in via the tags input. Possible values: lower, title, upper. Default value: title.	string	null	no
label_order	The order in which the labels (ID elements) appear in the id. Defaults to ["namespace", "environment", "stage", "name", "attributes"]. You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present.	list(string)	null	no
label_value_case	Controls the letter case of ID elements (labels) as included in id, set as tag values, and output by this module individually. Does not affect values of tags passed in via the tags input. Possible values: lower, title, upper and none (no transformation). Set this to title and set delimiter to "" to yield Pascal Case IDs. Default value: lower.	string	null	no
labels_as_tags	Set of labels (ID elements) to include as tags in the tags output. Default is to include all labels. Tags with empty values will not be included in the tags output. Set to [] to suppress all generated tags. Notes: The value of the name tag, if included, will be the id, not the name. Unlike other null-label inputs, the initial setting of labels_as_tags cannot be changed in later chained modules. Attempts to change it will be silently ignored.	set(string)	[ "default" ]	no
name	ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'. This is the only ID element not also included as a tag. The "name" tag is set to the full id string. There is no tag with the value of the name input.	string	null	no
namespace	ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique	string	null	no
regex_replace_chars	Terraform regular expression (regex) string. Characters matching the regex will be removed from the ID elements. If not set, "/[^a-zA-Z0-9-]/" is used to remove all characters other than hyphens, letters and digits.	string	null	no
restricted_roles_map	Map of datadog_monitors map keys to sets of Datadog unique role IDs to restrict access to each monitor. If provided, it will override the restricted_roles attribute in the monitor definition.	map(set(string))	{}	no
stage	ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release'	string	null	no
tags	Additional tags (e.g. {'BusinessUnit': 'XYZ'}). Neither the tag keys nor the tag values will be modified by this module.	map(string)	{}	no
tenant	ID element _(Rarely used, not included by default)_. A customer identifier, indicating who this instance of a resource is for	string	null	no

Outputs

Name	Description
datadog_monitor_ids	IDs of the created Datadog monitors
datadog_monitor_names	Names of the created Datadog monitors
datadog_monitors	Datadog monitor outputs