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
list_tag_configurations

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.
`relationships`	`object`	Relationships for a metric.
`type`	`string`	The metric tag configuration resource type. (manage_tags) (default: manage_tags, example: manage_tags)

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.
`relationships`	`object`	Relationships for a metric.
`type`	`string`	The metric resource type. (metrics) (default: metrics, example: metrics)

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`		Returns the tag configuration for the given metric name.<br /><br />A metric may exist and submit data without having a tag configuration. If no tag configuration exists<br />for the metric, this endpoint returns `404 Not Found`. This response does not indicate that the metric<br />itself is missing.
`list_tag_configurations`	`select`		`filter[configured]`, `filter[is_configurable]`, `filter[tags_configured]`, `filter[metric_type]`, `filter[include_percentiles]`, `filter[queried]`, `filter[queried][window][seconds]`, `filter[tags]`, `filter[related_assets]`, `include`, `sort`, `window[seconds]`, `page[size]`, `page[cursor]`	Get a list of actively reporting metrics for your organization. Pagination is optional using the `page[cursor]` and `page[size]` query parameters.<br /><br />Query parameters use bracket notation (for example, `filter[tags]`, `filter[queried][window][seconds]`). Pass them as standard URL query strings, URL-encoding the brackets if your client does not handle them. For example: `GET /api/v2/metrics?filter[tags]=env:prod&window[seconds]=86400&page[size]=500`.
`create_tag_configuration`	`insert`	`metric_name`, `data`		Create and define a list of queryable tag keys for an existing count/gauge/rate/distribution metric.<br />Optionally, include percentile aggregations on any distribution metric. By setting `exclude_tags_mode`<br />to true, the behavior is changed from an allow-list to a deny-list, and tags in the defined list are<br />not queryable. Can only be used with application keys of users with the `Manage Tags for Metrics`<br />permission.
`update_tag_configuration`	`update`	`metric_name`, `data`		Update the tag configuration of a metric or percentile aggregations of a distribution metric or custom aggregations<br />of a count, rate, or gauge metric. By setting `exclude_tags_mode` to true the behavior is changed<br />from an allow-list to a deny-list, and tags in the defined list will not be queryable.<br />Can only be used with application keys from users with the `Manage Tags for Metrics` permission. This endpoint requires<br />a tag configuration to be created first.
`delete_tag_configuration`	`delete`	`metric_name`		Deletes a metric's tag configuration. Can only be used with application<br />keys from users with the `Manage Tags for Metrics` permission.<br />Note: This operation is irreversible.

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)
`site`	`string`	The Datadog site (region) for your organization, for example datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com, ap2.datadoghq.com, datadoghq.eu, ddog-gov.com. Resolved from the DD_SITE environment variable when set. Optional: defaults to datadoghq.com, or the value of the DD_SITE environment variable when set; a WHERE value overrides both.
`filter[configured]`	`boolean`	Only return custom metrics that have been configured (`true`) or not configured (`false`) with Metrics Without Limits. (example: true)
`filter[include_percentiles]`	`boolean`	Only return distribution metrics that have percentile aggregations enabled (true) or disabled (false). (example: true)
`filter[is_configurable]`	`boolean`	Only return metrics that are eligible (`true`) or ineligible (`false`) for configuration with Metrics Without Limits. (example: true)
`filter[metric_type]`	`string`	Only return metrics of the given metric type.
`filter[queried]`	`boolean`	Only return metrics that have been queried (true) or not queried (false) in the look back window. Set the window with `filter[queried][window][seconds]`; if omitted, a default window is used. (example: true)
`filter[queried][window][seconds]`	`integer (int64)`	This parameter has no effect unless `filter[queried]` is also set. Only return metrics that have been queried or not queried in the specified window. The default value is 2,592,000 seconds (30 days), the maximum value is 15,552,000 seconds (180 days), and the minimum value is 1 second. For example: `filter[queried]=true&filter[queried][window][seconds]=604800`. (example: 15552000)
`filter[related_assets]`	`boolean`	Only return metrics that are used in at least one dashboard, monitor, notebook, or SLO. (example: true)
`filter[tags]`	`string`	Only return metrics that were submitted with tags matching this expression. You can use AND, OR, IN, and wildcards. For example: `filter[tags]=env IN (staging,test) AND service:web`. (example: env IN (staging,test) AND service:web)
`filter[tags_configured]`	`string`	Only return metrics that have the given tag key(s) in their Metrics Without Limits configuration (included or excluded). (example: app,env)
`include`	`string`	Include related resources in the response. Set to `metric_volumes` to include indexed and ingested volume counts for each metric. (example: metric_volumes)
`page[cursor]`	`string`	Cursor for pagination. Use `page[size]` to opt-in to pagination and get the first page; for subsequent pages, use the value from `meta.pagination.next_cursor` in the response. Pagination is complete when `next_cursor` is null.
`page[size]`	`integer (int32)`	Maximum number of results per page. Send `page[size]` on the first request to opt in to pagination. On each subsequent request, send `page[cursor]` set to the value of `meta.pagination.next_cursor` from the previous response. The default value is 10000, the maximum value is 10000, and the minimum value is 1.
`sort`	`string`	Sort results by metric volume. Prefix a key with `-` for descending order. Supported keys: `metric_volumes.indexed_volume`, `metric_volumes.ingested_volume`, `metric_volumes.indexed_volume_delta`, `metric_volumes.ingested_volume_delta`. Requires a paginated request (`page[size]` or `page[cursor]`). (example: -metric_volumes.indexed_volume)
`window[seconds]`	`integer (int64)`	Only return metrics that have been actively reporting in the specified window. The default value is 3600 seconds (1 hour), the maximum value is 2,592,000 seconds (30 days), and the minimum value is 1 second. (example: 3600)

`SELECT` examples

list_tag_configuration_by_name
list_tag_configurations

Returns the tag configuration for the given metric name. A metric may exist and submit data without having a tag configuration. If no tag configuration exists for the metric, this endpoint returns 404 Not Found. This response does not indicate that the metric itself is missing.

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

Get a list of actively reporting metrics for your organization. Pagination is optional using the page[cursor] and page[size] query parameters. Query parameters use bracket notation (for example, filter[tags], filter[queried][window][seconds]). Pass them as standard URL query strings, URL-encoding the brackets if your client does not handle them. For example: GET /api/v2/metrics?filter[tags]=env:prod&window[seconds]=86400&page[size]=500.

SELECT
id,
attributes,
relationships,
type
FROM datadog.metrics.tag_configurations
WHERE filter[configured] = '{{ filter[configured] }}'
AND filter[is_configurable] = '{{ filter[is_configurable] }}'
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[queried][window][seconds] = '{{ filter[queried][window][seconds] }}'
AND filter[tags] = '{{ filter[tags] }}'
AND filter[related_assets] = '{{ filter[related_assets] }}'
AND include = '{{ include }}'
AND sort = '{{ sort }}'
AND window[seconds] = '{{ window[seconds] }}'
AND page[size] = '{{ page[size] }}'
AND page[cursor] = '{{ page[cursor] }}'
;

`INSERT` examples

create_tag_configuration
Manifest

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,
metric_name
)
SELECT 
'{{ data }}' /* required */,
'{{ metric_name }}'
RETURNING
data
;

# Description fields are for documentation purposes
- name: tag_configurations
props:
  - name: metric_name
    value: "{{ metric_name }}"
    description: Required parameter for the tag_configurations resource.
  - name: data
    description: |
      Object for a single metric to be configure tags on.
    value:
      attributes:
        aggregations:
          - space: "{{ space }}"
            time: "{{ time }}"
        exclude_tags_mode: {{ exclude_tags_mode }}
        include_percentiles: {{ include_percentiles }}
        metric_type: "{{ metric_type }}"
        tags:
          - "{{ tags }}"
      id: "{{ id }}"
      type: "{{ type }}"

`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 }}'
WHERE 
metric_name = '{{ metric_name }}' --required
AND 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. Note: This operation is irreversible.

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

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​