tag_configurations

Creates, updates, deletes, gets or lists a tag_configurations resource.

Overview

Name	tag_configurations
Type	Resource
Id	datadog.metrics.tag_configurations

Fields

The following fields are returned by SELECT queries:

list_tag_configuration_by_name

Name	Datatype	Description
id	string	The metric name for this resource. (example: test.metric.latency)
attributes	object	Object containing the definition of a metric tag configuration attributes.
type	string	The metric tag configuration resource type. (default: manage_tags, example: manage_tags)

list_tag_configurations

Name	Datatype	Description

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_tag_configuration_by_name	select	metric_name, region		Returns the tag configuration for the given metric name.
list_tag_configurations	select	region	filter[configured], filter[tags_configured], filter[metric_type], filter[include_percentiles], filter[queried], filter[tags], filter[related_assets], window[seconds], page[size], page[cursor]	Returns all metrics that can be configured in the Metrics Summary page or with Metrics without Limits™ (matching additional filters if specified). Optionally, paginate by using the page[cursor] and/or page[size] query parameters. To fetch the first page, pass in a query parameter with either a valid page[size] or an empty cursor like page[cursor]=. To fetch the next page, pass in the next_cursor value from the response as the new page[cursor] value. Once the meta.pagination.next_cursor value is null, all pages have been retrieved.
create_tag_configuration	insert	metric_name, region, data__data		Create and define a list of queryable tag keys for an existing count/gauge/rate/distribution metric. Optionally, include percentile aggregations on any distribution metric. By setting exclude_tags_mode to true, the behavior is changed from an allow-list to a deny-list, and tags in the defined list are not queryable. Can only be used with application keys of users with the Manage Tags for Metrics permission.
create_bulk_tags_metrics_configuration	insert	region, data__data		Create and define a list of queryable tag keys for a set of existing count, gauge, rate, and distribution metrics. Metrics are selected by passing a metric name prefix. Use the Delete method of this API path to remove tag configurations. Results can be sent to a set of account email addresses, just like the same operation in the Datadog web app. If multiple calls include the same metric, the last configuration applied (not by submit order) is used, do not expect deterministic ordering of concurrent calls. The exclude_tags_mode value will set all metrics that match the prefix to the same exclusion state, metric tag configurations do not support mixed inclusion and exclusion for tags on the same metric. Can only be used with application keys of users with the Manage Tags for Metrics permission.
update_tag_configuration	update	metric_name, region, data__data		Update the tag configuration of a metric or percentile aggregations of a distribution metric or custom aggregations of a count, rate, or gauge metric. By setting exclude_tags_mode to true the behavior is changed from an allow-list to a deny-list, and tags in the defined list will not be queryable. Can only be used with application keys from users with the Manage Tags for Metrics permission. This endpoint requires a tag configuration to be created first.
delete_tag_configuration	delete	metric_name, region		Deletes a metric's tag configuration. Can only be used with application keys from users with the Manage Tags for Metrics permission.
delete_bulk_tags_metrics_configuration	delete	region		Delete all custom lists of queryable tag keys for a set of existing count, gauge, rate, and distribution metrics. Metrics are selected by passing a metric name prefix. Results can be sent to a set of account email addresses, just like the same operation in the Datadog web app. Can only be used with application keys of users with the Manage Tags for Metrics permission.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
metric_name	string	The name of the metric. (example: dist.http.endpoint.request)
region	string	(default: datadoghq.com)
filter[configured]	boolean	Filter custom metrics that have configured tags. (example: true)
filter[include_percentiles]	boolean	Filter distributions with additional percentile aggregations enabled or disabled. (example: true)
filter[metric_type]	string	Filter metrics by metric type.
filter[queried]	boolean	(Preview) Filter custom metrics that have or have not been queried in the specified window[seconds]. If no window is provided or the window is less than 2 hours, a default of 2 hours will be applied. (example: true)
filter[related_assets]	boolean	(Preview) Filter metrics that are used in dashboards, monitors, notebooks, SLOs. (example: true)
filter[tags]	string	Filter metrics that have been submitted with the given tags. Supports boolean and wildcard expressions. Can only be combined with the filter[queried] filter. (example: env IN (staging,test) AND service:web)
filter[tags_configured]	string	Filter tag configurations by configured tags. (example: app)
page[cursor]	string	String to query the next page of results. This key is provided with each valid response from the API in meta.pagination.next_cursor. Once the meta.pagination.next_cursor key is null, all pages have been retrieved.
page[size]	integer (int32)	Maximum number of results returned.
window[seconds]	integer (int64)	The number of seconds of look back (from now) to apply to a filter[tag] or filter[queried] query. Default value is 3600 (1 hour), maximum value is 2,592,000 (30 days). (example: 3600)

SELECT examples

list_tag_configuration_by_name

Returns the tag configuration for the given metric name.

SELECT
id,
attributes,
type
FROM datadog.metrics.tag_configurations
WHERE metric_name = '{{ metric_name }}' -- required
AND region = '{{ region }}' -- required
;

list_tag_configurations

Returns all metrics that can be configured in the Metrics Summary page or with Metrics without Limits™ (matching additional filters if specified).
Optionally, paginate by using the page[cursor] and/or page[size] query parameters.
To fetch the first page, pass in a query parameter with either a valid page[size] or an empty cursor like page[cursor]=. To fetch the next page, pass in the next_cursor value from the response as the new page[cursor] value.
Once the meta.pagination.next_cursor value is null, all pages have been retrieved.

SELECT
*
FROM datadog.metrics.tag_configurations
WHERE region = '{{ region }}' -- required
AND filter[configured] = '{{ filter[configured] }}'
AND filter[tags_configured] = '{{ filter[tags_configured] }}'
AND filter[metric_type] = '{{ filter[metric_type] }}'
AND filter[include_percentiles] = '{{ filter[include_percentiles] }}'
AND filter[queried] = '{{ filter[queried] }}'
AND filter[tags] = '{{ filter[tags] }}'
AND filter[related_assets] = '{{ filter[related_assets] }}'
AND window[seconds] = '{{ window[seconds] }}'
AND page[size] = '{{ page[size] }}'
AND page[cursor] = '{{ page[cursor] }}'
;

INSERT examples

create_tag_configuration

Create and define a list of queryable tag keys for an existing count/gauge/rate/distribution metric.
Optionally, include percentile aggregations on any distribution metric. By setting exclude_tags_mode
to true, the behavior is changed from an allow-list to a deny-list, and tags in the defined list are
not queryable. Can only be used with application keys of users with the Manage Tags for Metrics
permission.

INSERT INTO datadog.metrics.tag_configurations (
data__data,
metric_name,
region
)
SELECT 
'{{ data }}' /* required */,
'{{ metric_name }}',
'{{ region }}'
RETURNING
data
;

create_bulk_tags_metrics_configuration

Create and define a list of queryable tag keys for a set of existing count, gauge, rate, and distribution metrics.
Metrics are selected by passing a metric name prefix. Use the Delete method of this API path to remove tag configurations.
Results can be sent to a set of account email addresses, just like the same operation in the Datadog web app.
If multiple calls include the same metric, the last configuration applied (not by submit order) is used, do not
expect deterministic ordering of concurrent calls. The exclude_tags_mode value will set all metrics that match the prefix to
the same exclusion state, metric tag configurations do not support mixed inclusion and exclusion for tags on the same metric.
Can only be used with application keys of users with the Manage Tags for Metrics permission.

INSERT INTO datadog.metrics.tag_configurations (
data__data,
region
)
SELECT 
'{{ data }}' /* required */,
'{{ region }}'
RETURNING
data
;

Manifest

# Description fields are for documentation purposes
- name: tag_configurations
  props:
    - name: metric_name
      value: string
      description: Required parameter for the tag_configurations resource.
    - name: region
      value: string
      description: Required parameter for the tag_configurations resource.
    - name: data
      value: object
      description: |
        Request object to bulk configure tags for metrics matching the given prefix.

UPDATE examples

update_tag_configuration

Update the tag configuration of a metric or percentile aggregations of a distribution metric or custom aggregations
of a count, rate, or gauge metric. By setting exclude_tags_mode to true the behavior is changed
from an allow-list to a deny-list, and tags in the defined list will not be queryable.
Can only be used with application keys from users with the Manage Tags for Metrics permission. This endpoint requires
a tag configuration to be created first.

UPDATE datadog.metrics.tag_configurations
SET 
data__data = '{{ data }}'
WHERE 
metric_name = '{{ metric_name }}' --required
AND region = '{{ region }}' --required
AND data__data = '{{ data }}' --required
RETURNING
data;

DELETE examples

delete_tag_configuration

Deletes a metric's tag configuration. Can only be used with application
keys from users with the Manage Tags for Metrics permission.

DELETE FROM datadog.metrics.tag_configurations
WHERE metric_name = '{{ metric_name }}' --required
AND region = '{{ region }}' --required
;

delete_bulk_tags_metrics_configuration

Delete all custom lists of queryable tag keys for a set of existing count, gauge, rate, and distribution metrics.
Metrics are selected by passing a metric name prefix.
Results can be sent to a set of account email addresses, just like the same operation in the Datadog web app.
Can only be used with application keys of users with the Manage Tags for Metrics permission.

DELETE FROM datadog.metrics.tag_configurations
WHERE region = '{{ region }}' --required
;