Update a tag configuration

PATCH https://api.ap1.datadoghq.com/api/v2/metrics/{metric_name}/tagshttps://api.ap2.datadoghq.com/api/v2/metrics/{metric_name}/tagshttps://api.datadoghq.eu/api/v2/metrics/{metric_name}/tagshttps://api.ddog-gov.com/api/v2/metrics/{metric_name}/tagshttps://api.us2.ddog-gov.com/api/v2/metrics/{metric_name}/tagshttps://api.datadoghq.com/api/v2/metrics/{metric_name}/tagshttps://api.us3.datadoghq.com/api/v2/metrics/{metric_name}/tagshttps://api.us5.datadoghq.com/api/v2/metrics/{metric_name}/tags

Overview

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. This endpoint requires the metric_tags_write permission.

Arguments

Path Parameters

Name

Type

Description

metric_name [required]

string

The name of the metric.

Request

Body Data (required)

Expand All

Field

Type

Description

data [required]

object

Object for a single tag configuration to be edited.

attributes

object

Object containing the definition of a metric tag configuration to be updated.

aggregations

[object]

Deprecated. You no longer need to configure specific time and space aggregations for Metrics Without Limits.

space [required]

enum

A space aggregation for use in query. Allowed enum values: avg,max,min,sum

time [required]

enum

A time aggregation for use in query. Allowed enum values: avg,count,max,min,sum

exclude_tags_mode

boolean

When set to true, the configuration will exclude the configured tags and include any other submitted tags. When set to false, the configuration will include the configured tags and exclude any other submitted tags. Defaults to false. Requires tags property.

include_percentiles

boolean

Toggle to include/exclude percentiles for a distribution metric. Defaults to false. Can only be applied to metrics that have a metric_type of distribution.

tags

[string]

A list of tag keys that will be queryable for your metric.

default:

id [required]

string

The metric name for this resource.

type [required]

enum

The metric tag configuration resource type. Allowed enum values: manage_tags

default: manage_tags

{
  "data": {
    "type": "manage_tags",
    "id": "test.metric.latency",
    "attributes": {
      "tags": [
        "app"
      ]
    }
  }
}

Response

OK

Response object which includes a single metric’s tag configuration.

Expand All

Field

Type

Description

data

object

Object for a single metric tag configuration.

attributes

object

Object containing the definition of a metric tag configuration attributes.

aggregations

[object]

Deprecated. You no longer need to configure specific time and space aggregations for Metrics Without Limits.

space [required]

enum

A space aggregation for use in query. Allowed enum values: avg,max,min,sum

time [required]

enum

A time aggregation for use in query. Allowed enum values: avg,count,max,min,sum

created_at

date-time

Timestamp when the tag configuration was created.

exclude_tags_mode

boolean

When set to true, the configuration will exclude the configured tags and include any other submitted tags. When set to false, the configuration will include the configured tags and exclude any other submitted tags. Defaults to false. Requires tags property.

include_percentiles

boolean

Toggle to include or exclude percentile aggregations for distribution metrics. Only present when the metric_type is distribution.

metric_type

enum

The metric's type. Allowed enum values: gauge,count,rate,distribution

default: gauge

modified_at

date-time

Timestamp when the tag configuration was last modified.

tags

[string]

List of tag keys on which to group.

id

string

The metric name for this resource.

type

enum

The metric tag configuration resource type. Allowed enum values: manage_tags

default: manage_tags

{
  "data": {
    "attributes": {
      "aggregations": [
        {
          "space": "sum",
          "time": "sum"
        }
      ],
      "created_at": "2020-03-25T09:48:37.463835Z",
      "exclude_tags_mode": false,
      "include_percentiles": true,
      "metric_type": "count",
      "modified_at": "2020-03-25T09:48:37.463835Z",
      "tags": [
        "app",
        "datacenter"
      ]
    },
    "id": "test.metric.latency",
    "type": "manage_tags"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Unprocessable Entity

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too Many Requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                          ## default
# 

# Path parameters
export metric_name="dist.http.endpoint.request"
# Curl command
curl -X PATCH "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/metrics/${metric_name}/tags" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "group_by": [ "app", "datacenter" ], "include_percentiles": false }, "id": "http.endpoint.request", "type": "manage_tags" } } EOF
// Update a tag configuration returns "OK" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
)

func main() {
	// there is a valid "metric_tag_configuration" in the system
	MetricTagConfigurationDataID := os.Getenv("METRIC_TAG_CONFIGURATION_DATA_ID")

	body := datadogV2.MetricTagConfigurationUpdateRequest{
		Data: datadogV2.MetricTagConfigurationUpdateData{
			Type: datadogV2.METRICTAGCONFIGURATIONTYPE_MANAGE_TAGS,
			Id:   MetricTagConfigurationDataID,
			Attributes: &datadogV2.MetricTagConfigurationUpdateAttributes{
				Tags: []string{
					"app",
				},
			},
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewMetricsApi(apiClient)
	resp, r, err := api.UpdateTagConfiguration(ctx, MetricTagConfigurationDataID, body)

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `MetricsApi.UpdateTagConfiguration`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `MetricsApi.UpdateTagConfiguration`:\n%s\n", responseContent)
}

Instructions

First install the library and its dependencies and then save the example to main.go and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" go run "main.go"
// Update a tag configuration returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.MetricsApi;
import com.datadog.api.client.v2.model.MetricTagConfigurationResponse;
import com.datadog.api.client.v2.model.MetricTagConfigurationType;
import com.datadog.api.client.v2.model.MetricTagConfigurationUpdateAttributes;
import com.datadog.api.client.v2.model.MetricTagConfigurationUpdateData;
import com.datadog.api.client.v2.model.MetricTagConfigurationUpdateRequest;
import java.util.Collections;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    MetricsApi apiInstance = new MetricsApi(defaultClient);

    // there is a valid "metric_tag_configuration" in the system
    String METRIC_TAG_CONFIGURATION_DATA_ID = System.getenv("METRIC_TAG_CONFIGURATION_DATA_ID");

    MetricTagConfigurationUpdateRequest body =
        new MetricTagConfigurationUpdateRequest()
            .data(
                new MetricTagConfigurationUpdateData()
                    .type(MetricTagConfigurationType.MANAGE_TAGS)
                    .id(METRIC_TAG_CONFIGURATION_DATA_ID)
                    .attributes(
                        new MetricTagConfigurationUpdateAttributes()
                            .tags(Collections.singletonList("app"))));

    try {
      MetricTagConfigurationResponse result =
          apiInstance.updateTagConfiguration(METRIC_TAG_CONFIGURATION_DATA_ID, body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling MetricsApi#updateTagConfiguration");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Instructions

First install the library and its dependencies and then save the example to Example.java and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" java "Example.java"
"""
Update a tag configuration returns "OK" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.metrics_api import MetricsApi
from datadog_api_client.v2.model.metric_tag_configuration_type import MetricTagConfigurationType
from datadog_api_client.v2.model.metric_tag_configuration_update_attributes import (
    MetricTagConfigurationUpdateAttributes,
)
from datadog_api_client.v2.model.metric_tag_configuration_update_data import MetricTagConfigurationUpdateData
from datadog_api_client.v2.model.metric_tag_configuration_update_request import MetricTagConfigurationUpdateRequest

# there is a valid "metric_tag_configuration" in the system
METRIC_TAG_CONFIGURATION_DATA_ID = environ["METRIC_TAG_CONFIGURATION_DATA_ID"]

body = MetricTagConfigurationUpdateRequest(
    data=MetricTagConfigurationUpdateData(
        type=MetricTagConfigurationType.MANAGE_TAGS,
        id=METRIC_TAG_CONFIGURATION_DATA_ID,
        attributes=MetricTagConfigurationUpdateAttributes(
            tags=[
                "app",
            ],
        ),
    ),
)

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = MetricsApi(api_client)
    response = api_instance.update_tag_configuration(metric_name=METRIC_TAG_CONFIGURATION_DATA_ID, body=body)

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" python3 "example.py"
# Update a tag configuration returns "OK" response

require "datadog_api_client"
api_instance = DatadogAPIClient::V2::MetricsAPI.new

# there is a valid "metric_tag_configuration" in the system
METRIC_TAG_CONFIGURATION_DATA_ID = ENV["METRIC_TAG_CONFIGURATION_DATA_ID"]

body = DatadogAPIClient::V2::MetricTagConfigurationUpdateRequest.new({
  data: DatadogAPIClient::V2::MetricTagConfigurationUpdateData.new({
    type: DatadogAPIClient::V2::MetricTagConfigurationType::MANAGE_TAGS,
    id: METRIC_TAG_CONFIGURATION_DATA_ID,
    attributes: DatadogAPIClient::V2::MetricTagConfigurationUpdateAttributes.new({
      tags: [
        "app",
      ],
    }),
  }),
})
p api_instance.update_tag_configuration(METRIC_TAG_CONFIGURATION_DATA_ID, body)

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" rb "example.rb"
// Update a tag configuration returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_metrics::MetricsAPI;
use datadog_api_client::datadogV2::model::MetricTagConfigurationType;
use datadog_api_client::datadogV2::model::MetricTagConfigurationUpdateAttributes;
use datadog_api_client::datadogV2::model::MetricTagConfigurationUpdateData;
use datadog_api_client::datadogV2::model::MetricTagConfigurationUpdateRequest;

#[tokio::main]
async fn main() {
    // there is a valid "metric_tag_configuration" in the system
    let metric_tag_configuration_data_id =
        std::env::var("METRIC_TAG_CONFIGURATION_DATA_ID").unwrap();
    let body = MetricTagConfigurationUpdateRequest::new(
        MetricTagConfigurationUpdateData::new(
            metric_tag_configuration_data_id.clone(),
            MetricTagConfigurationType::MANAGE_TAGS,
        )
        .attributes(MetricTagConfigurationUpdateAttributes::new().tags(vec!["app".to_string()])),
    );
    let configuration = datadog::Configuration::new();
    let api = MetricsAPI::with_config(configuration);
    let resp = api
        .update_tag_configuration(metric_tag_configuration_data_id.clone(), body)
        .await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" cargo run
/**
 * Update a tag configuration returns "OK" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
const apiInstance = new v2.MetricsApi(configuration);

// there is a valid "metric_tag_configuration" in the system
const METRIC_TAG_CONFIGURATION_DATA_ID = process.env
  .METRIC_TAG_CONFIGURATION_DATA_ID as string;

const params: v2.MetricsApiUpdateTagConfigurationRequest = {
  body: {
    data: {
      type: "manage_tags",
      id: METRIC_TAG_CONFIGURATION_DATA_ID,
      attributes: {
        tags: ["app"],
      },
    },
  },
  metricName: METRIC_TAG_CONFIGURATION_DATA_ID,
};

apiInstance
  .updateTagConfiguration(params)
  .then((data: v2.MetricTagConfigurationResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

Instructions

First install the library and its dependencies and then save the example to example.ts and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" tsc "example.ts"