---
title: Agent-Side Filtering for Custom Metrics
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: Docs > Metrics > Metrics Guides > Agent-Side Filtering for Custom Metrics
---

# Agent-Side Filtering for Custom Metrics

{% callout %}
##### Join the Preview!

Agent-Side Filtering for Custom Metrics is in Preview. If you're interested in this feature, complete this form.

[Request Access](https://www.datadoghq.com/product-preview/agent-side-filtering-for-custom/)
{% /callout %}

## Overview{% #overview %}

Agent-side filtering enables you to filter out unused or unwanted custom metrics (both from DogStatsD and Agent integrations) directly at the Datadog Agent, before sending them to Datadog. This can significantly reduce both indexed and ingested custom metric volume.

Filtering is performed at the Agent level but centrally managed through the Datadog UI, giving teams full visibility and control. You can create, update, and manage filtering policies in Datadog, streamlining metric governance while maintaining transparency.

Creating and updating filtering policies requires the [`metric_tags_write`](https://docs.datadoghq.com/account_management/rbac/permissions/#metrics) RBAC permission. All users can view filtering policies.

## Prerequisites{% #prerequisites %}

- Upgrade to Datadog Agent v7.67.0 or higher.
  - Using v7.70.0 or higher is recommended to filter DogStastD metrics.
  - Using v7.74.0 or higher is required for Agent Integration metrics.
- With [`org_management`](https://docs.datadoghq.com/account_management/rbac/permissions/#access-management) permissions, enable [Remote Configuration](https://app.datadoghq.com/organization-settings/remote-config) for your organization.
- With [`api_keys_write`](https://docs.datadoghq.com/account_management/rbac/permissions#api-and-application-keys) permissions, enable the [Remote Configuration capability on the API keys](https://app.datadoghq.com/organization-settings/api-keys) used by your Agents. After enabling Remote Configuration on an API key, restart your Agents for the change to take effect.

{% image
   source="https://docs.dd-static.net/images/agent/remote_config/RC_Key_updated.b0e2299082792781d28ea9a3c1e88950.png?auto=format"
   alt="API Key properties with Remote Configuration capability Enable button." /%}

## Create a metric filtering policy{% #create-a-metric-filtering-policy %}

You can create a metric filtering policy from the [Metrics Settings page](https://app.datadoghq.com/metric/settings/policies) or the [Metrics Summary page](https://app.datadoghq.com/metric/summary).

Metric filtering policies are applied to all Agents v7.67.0+ (v7.74.0+ for Agent Integration metrics) with Remote Configuration enabled. Older Agent versions, or Agents with Remote Configuration disabled, do not apply filtering policies.

Policy updates are deployed to Agents in 1-2 minutes.

### From the Metrics Settings page{% #from-the-metrics-settings-page %}

1. Click **+ Create Policy**.
1. Click **Filter metrics**.
1. Provide a description for the new policy.
1. Select the metrics to filter from the **Metrics to Filter** dropdown, or click **Upload CSV**.
   - If you choose to upload a CSV, select the file and click **Open**. You can use multiple CSVs to create the policy.
1. When you're satisfied with the list of metrics to filter, click **Save and Filter**.

### From the Metrics Summary page{% #from-the-metrics-summary-page %}

Create a metric filtering policy from the Metrics Summary page using any of the following methods:

{% tab title="From a metric query" %}

1. Enter a metric query in the search bar.
1. Click the three vertical dots button on the right-hand side of the screen.
1. Click **Filter metrics**.
1. In the **Choose policy** dropdown, click **New Policy**. Provide a description for the policy.
1. Review the **Metrics to Filter**. Click `X` on the right side of any row to remove a metric from the list, or click `+ Include More Metrics` to add metrics to the list.
1. Click **Save and Filter**.

{% video
   url="https://docs.dd-static.net/images/metrics/guide/agent_filtering_for_custom_metrics/create_policy_from_metric_query.mp4" /%}

{% /tab %}

{% tab title="From the policy editor" %}

1. Click the three vertical dots button on the right-hand side of the screen.
1. Click **Filter metrics**.
1. In the **Choose policy** dropdown, click **New Policy**. Provide a description for the policy.
1. Enter a metric query in the **Metrics to Filter** field, or select metrics individually from the dropdown. Click `X` on the right side of any row to remove a metric from the list.
1. Click **Save and Filter**.

{% video
   url="https://docs.dd-static.net/images/metrics/guide/agent_filtering_for_custom_metrics/create_policy_with_policy_editor.mp4" /%}

{% /tab %}

{% tab title="From CSV upload" %}

1. Click the three vertical dots button on the right-hand side of the screen.
1. Click **Filter metrics**.
1. In the **Choose policy** dropdown, click **New Policy**. Provide a description for the policy.
1. Click **Upload CSV** to the right of the **Metrics to Filter** field.
1. Select the CSV file, and click **Open**.
1. Review the metrics listed. Click `X` on the right side of any row to remove a metric from the list. If needed, upload additional CSV files, or add metrics through the **Metrics to Filter** field.
1. Click **Save and Filter**.

{% video
   url="https://docs.dd-static.net/images/metrics/guide/agent_filtering_for_custom_metrics/create_policy_with_csv_upload.mp4" /%}

{% /tab %}

## Edit a metric filtering policy{% #edit-a-metric-filtering-policy %}

You can edit a metric filtering policy from the [Metrics Settings page](https://docs.datadoghq.com/account_management/rbac/permissions/#metrics) or the [Metrics Summary page](https://docs.datadoghq.com/account_management/rbac/permissions/#access-management).

### From the Metrics Settings page{% #from-the-metrics-settings-page-1 %}

1. Click the policy to edit.
1. Click **Edit**.
1. Select the metrics to filter from the **Metrics to Filter** dropdown, or click **Upload CSV**.
   - If you choose to upload a CSV, select the file and click **Open**.
1. Click **Save and Filter**.

{% video
   url="https://docs.dd-static.net/images/metrics/guide/agent_filtering_for_custom_metrics/edit_policy_from_metrics_settings.mp4" /%}

### From the Metrics Summary page{% #from-the-metrics-summary-page-1 %}

Edit a metric filtering policy from the Metrics Summary page using any of the following methods:

{% tab title="From a metric query" %}

1. Enter a metric query in the search bar.
1. Click the three vertical dots button on the right-hand side of the screen.
1. Click **Filter metrics**.
1. In the **Choose policy** dropdown, select the policy to edit.
1. Review the **Metrics to Filter** and **Existing metrics in policy** lists. Click `X` on the right side of any row to remove a metric from the list, or click `+ Include More Metrics` to add metrics to the list.
1. Click **Save and Filter**.

{% video
   url="https://docs.dd-static.net/images/metrics/guide/agent_filtering_for_custom_metrics/edit_policy_with_metric_query.mp4" /%}

{% /tab %}

{% tab title="From the policy editor" %}

1. Click the three vertical dots button on the right-hand side of the screen.
1. Click **Filter metrics**.
1. In the **Choose policy** dropdown, select the policy to edit.
1. Select metrics individually from the **Metrics to Filter** dropdown. Click `X` on the right side of any row to remove a metric from the list.
1. Click **Save and Filter**.

{% /tab %}

{% tab title="From CSV upload" %}

1. Click the three vertical dots button on the right-hand side of the screen.
1. Click **Filter metrics**.
1. In the **Choose policy** dropdown, select the policy to edit.
1. Click **Upload CSV** to the right of the **Metrics to Filter** field.
1. Select the CSV file, and click **Open**.
1. Review the **Metrics to Filter** and **Existing metrics in policy** lists. Click `X` on the right side of any row to remove a metric from the list, or click `+ Include More Metrics` to add metrics to the list.
1. Click **Save and Filter**.

{% /tab %}

## View all policies and filtered metrics{% #view-all-policies-and-filtered-metrics %}

You can view all your policies and filtered metrics from the [Metrics Settings page](https://docs.datadoghq.com/account_management/rbac/permissions/#metrics).

**Click on the [settings button](https://docs.datadoghq.com/account_management/rbac/permissions/#metrics)**:

{% image
   source="https://docs.dd-static.net/images/metrics/guide/agent_filtering_for_custom_metrics/settings_from_summary.71c89900bafb3cc813476cc4ffe96aa2.png?auto=format"
   alt="The settings button on the metric summary page" /%}

**Click on Metrics in the navigation bar** and go straight to settings:

{% image
   source="https://docs.dd-static.net/images/metrics/guide/agent_filtering_for_custom_metrics/settings_from_nav.e11f3113ee7af91fae9e4be6a98ade9f.png?auto=format"
   alt="The settings option from the expanded Metrics panel in Datadog" /%}

### View all policies{% #view-all-policies %}

Select the **Policies** tab from the sidebar to see a list of all your policies. If you don't see the sidebar, click the **Show Sidebar** button .

Click on any metric filtering policy to open its detail view for edits or deletion.

### View all filtered metrics{% #view-all-filtered-metrics %}

Select the **Filtered Metrics** tab from the sidebar to see a list of all your filtered. If you don't see the sidebar, click the **Show Sidebar** button .

Click on a filtered metric's attached policies in the **ATTACHED POLICIES** column for edits or deletion.

## Delete policies{% #delete-policies %}

You can delete metric filtering policies from the [Metrics Settings page](https://docs.datadoghq.com/account_management/rbac/permissions/#metrics).

1. Click on the metric filtering policy to delete.
1. Select **Delete** in the top-right corner of the page.

{% image
   source="https://docs.dd-static.net/images/metrics/guide/agent_filtering_for_custom_metrics/delete_policy.1035bdd2cd5ef2a80d8e052f05b69ceb.png?auto=format"
   alt="The delete policy button on a metric filtering policy detail view" /%}

## Manage metric filtering policies through the API{% #manage-metric-filtering-policies-through-the-api %}

{% alert level="danger" %}
These endpoints are subject to change while Agent-side filtering for custom metrics is in Preview.
{% /alert %}

These endpoints require a valid Datadog API key and application key. See [Getting started](https://docs.datadoghq.com/api/latest/#getting-started) in the API Reference for more information.

### Create a filtered metric policy{% #create-a-filtered-metric-policy %}

The base URL for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site/) is: 

Substitute `<BASE_URL>` in the example below with the base URL.

**POST** `<BASE_URL>/api/unstable/remote_config/products/metric_control/filtered_metrics/policies`

#### Example body{% #example-body %}

```json
{
  "data": {
    "type": "filtered_metrics",
    "attributes": {
      "policy_name": "my policy",
      "metric_names": [
        "metric.name.one",
        "metric.name.two"
      ]
    }
  }
}
```

### Update a filtered metric policy (partial update){% #update-a-filtered-metric-policy-partial-update %}

The base URL for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site/) is: 

Substitute `<BASE_URL>` in the example below with the base URL.

**PATCH** `<BASE_URL>/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}`

#### Example body{% #example-body-1 %}

```json
{
  "data": {
    "type": "filtered_metrics",
    "attributes": {
      "policy_name": "my policy",
      "metrics_to_add": [
        "metric.name.three",
        "metric.name.four"
      ],
      "metrics_to_remove": [
        "metric.name.five",
        "metric.name.six"
      ]
    }
  }
}
```

### Update a filtered metric policy (full replace){% #update-a-filtered-metric-policy-full-replace %}

The base URL for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site/) is: 

Substitute `<BASE_URL>` in the example below with the base URL.

**PUT** `<BASE_URL>/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}`

#### Example body{% #example-body-2 %}

```json
{
  "data": {
    "type": "filtered_metrics",
    "attributes": {
      "policy_name": "my policy",
      "metric_names": [
        "metric.name.seven",
        "metric.name.eight"
      ]
    }
  }
}
```

### Delete a policy{% #delete-a-policy %}

The base URL for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site/) is: 

Substitute `<BASE_URL>` in the example below with the base URL.

**DELETE** `<BASE_URL>/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}`

### Get a filtered metric policy{% #get-a-filtered-metric-policy %}

The base URL for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site/) is: 

Substitute `<BASE_URL>` in the example below with the base URL.

**GET** `<BASE_URL>/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}`

#### Example response body{% #example-response-body %}

```json
{
  "data": [
    {
      "type": "filtered_metrics",
      "id": "metric.name.one",
      "attributes": {
        "updated_timestamp": 1745954352
      }
    },
    {
      "type": "filtered_metrics",
      "id": "metric.name.two"
      "attributes": {
        "updated_timestamp": 1745954389
      }
    }
    // ... up to ~10,000 entries
  ],
  "links": {
    "self": "/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}?page[offset]=200&page[limit]=100",
    "next": "/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}?page[offset]=300&page[limit]=100",
    "prev": "/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}?page[offset]=100&page[limit]=100",
    "first": "/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}?page[offset]=0&page[limit]=100",
    "last": "/api/unstable/remote_config/products/metric_control/filtered_metrics/policies/{policy-id}?page[offset]=9900&page[limit]=100"
  },
  "meta": {
    "agent_coverage_percent": 100,
    "agents_with_latest_policy_count": 4,
    "deployment_failure": {
        "failed_agent_count": 0,
        "failure_message": ""
    },
    "deployment_status": "Deployed to all Agents",
    "deployment_strategy": "all",
    "policy_name": "test_policy_1",
    "total": 7,
    "total_agent_count": 4,
    "updated_by": "user@datadoghq.com",
    "updated_timestamp": 1758912365
  }
}
```

### List filtered metric policies{% #list-filtered-metric-policies %}

The base URL for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site/) is: 

Substitute `<BASE_URL>` in the example below with the base URL.

**GET** `<BASE_URL>/api/unstable/remote_config/products/metric_control/filtered_metrics/policies`

#### Example response body{% #example-response-body-1 %}

```json
{
    "data": [
        {
            "id": "06b-fab-47e",
            "type": "filtered_metrics",
            "attributes": {
                "count": 85,
                "deployment_status": "Deployed to all Agents",
                "deployment_strategy": "all",
                "policy_name": "policy one",
                "updated_by": "user@datadoghq.com",
                "updated_timestamp": 1758547485,
                "version": 4            
            }
        },
        {
            "id": "07b-201-47e",
            "type": "filtered_metrics",
            "attributes": {
                "count": 8,
                "deployment_status": "Deployed to all Agents",
                "deployment_strategy": "all",
                "policy_name": "policy two",
                "updated_by": "user@datadoghq.com",
                "updated_timestamp": 1758547212,
                "version": 1
            }
        }
    ]
}
```

## Preview limitations{% #preview-limitations %}

This initial preview release includes the following limitations:

- A maximum of 10,000 metric names can be filtered out.
- Resource usage impact on the Agent is limited to up to 10MB of memory (RSS), and no increase to CPU usage.
- Only custom metrics received from either DogStatsD or Agent integrations are supported.

## Further reading{% #further-reading %}

- [Learn more about Custom Metrics](https://docs.datadoghq.com/metrics/custom_metrics/)
- [Custom Metrics Billing](https://docs.datadoghq.com/account_management/billing/custom_metrics/?tab=countrate)
- [Metrics without Limits™](https://docs.datadoghq.com/metrics/metrics-without-limits/)
- [Metrics Volume Management](https://docs.datadoghq.com/metrics/volume/)
- [Best practices for end-to-end custom metrics governance](https://www.datadoghq.com/blog/custom-metrics-governance/)