--- title: Set Primary Tags to Scope description: >- Learn how to set primary tags to scope and filter APM data across different environments, services, and versions for better organization. breadcrumbs: Docs > APM > Tracing Guides > Set Primary Tags to Scope --- # Set Primary Tags to Scope ## Definition{% #definition %} There are several dimensions available to scope an entire Datadog APM application. These include aggregate statistics (such as requests/second, latency, error rate, Apdex score) and visible [traces](https://docs.datadoghq.com/tracing/glossary.md#trace). These dimensions are set up through primary tags that allow you to get an even finer view of your application's behavior. Use cases for primary tags include environment, availability zone, datacenter, etc. Primary tags must follow a different set of rules from those of conventional [Datadog tags](https://docs.datadoghq.com/getting_started/tagging.md). ## Setup{% #setup %} ### Environment{% #environment %} The default and mandatory primary tag is the environment your traces are collected from. Its tag key is `env`, and its default value for un-tagged data is `env:none`. #### Tracer environment{% #tracer-environment %} Datadog recommends having the tracer set `env`. It also allows for greater flexibility because the definition of `env` lives within the actual runtime of the service. If `DD_ENV` is exposed to your service's process, the tracer will use it automatically. See [Unified Service Tagging](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md) to learn about setting `DD_ENV` and other standard service environment variables. You may also manually set `env` as a global tag for the tracer in code. See [assigning tags in APM](https://docs.datadoghq.com/getting_started/tagging/assigning_tags.md#traces) for more information. #### Agent environment{% #agent-environment %} The `env` tag can be set in your Agent configuration. **Do not set different `env` tags on the Tracer and Agent. This may cause duplicate tagging on [trace metrics](https://docs.datadoghq.com/tracing/metrics/metrics_namespace.md).** Options: 1. Top-level Agent configuration: ```yaml env: ... ``` **Containerized environments**: The Agent also supports configuration of the top-level `env` through the environment variable `DD_ENV`. 1. Agent host tag: ```yaml tags: env: ... ``` **Containerized environments**: The Agent also supports configuration of top-level `tags` through the environment variable `DD_TAGS`. #### Data by environment{% #data-by-environment %} Environments appear at the top of APM pages. Use the `env` dropdown to scope the data displayed on the current page. ## Add additional primary tags in Datadog{% #add-additional-primary-tags-in-datadog %} If you need to aggregate your trace metrics across additional dimensions, Datadog recommends setting up additional primary tags in addition to the mandatory primary tag `env:`. Once configured, a second dropdown is available in the **Software Catalog Performance** tab. Go to the [APM Settings](https://app.datadoghq.com/apm/settings) page to define, change, or remove your primary tags. **Note**: - Only organization administrators have access to this page. - Changes may take up to two hours to be reflected in the UI. - The tracer always adds `resource`, `name`, and `service` tags to spans. Datadog recommends never adding these as host level tags to avoid confusion. - The additional primary tags support up to 100 unique values per tag. See [APM data volume guidelines](https://docs.datadoghq.com/tracing/troubleshooting.md#data-volume-guidelines) for details. - Additional primary tags can be host or container tags. Span-level tags added by the tracer cannot be used as primary tags. If you change a previously set primary tag, be aware of the following: - Historical APM data aggregated by the previously set tag is no longer accessible. - Any APM monitors scoped to the previous tag display a status of *No Data*. ## Container-based additional primary tags{% #container-based-additional-primary-tags %} You can index your trace metrics based on the tags derived from Docker containers and Kubernetes pod metadata on Linux-based platforms. Container-based primary tags are available in Datadog Agent versions 7.35.0 and later. To enable container-based primary tags, install Agent version 7.35.0 or later, update the CID stats setting as described below, and restart the Agent. The procedure for enabling depends on how you installed the Agent: {% tab title="Helm" %} Using the Datadog Helm chart version 2.26.2 or later, add the following to your values file: ```yaml #... datadog: #... env: - name: DD_APM_FEATURES value: 'enable_cid_stats' ``` {% /tab %} {% tab title="Kubernetes (without Helm)" %} Use the following environment variable in the Agent DaemonSet. If you are running a container per Agent process, add the following environment variable to all containers. Otherwise, add it to the Agent container. ```yaml # (...) env: # (...) - name: DD_APM_FEATURES value: 'enable_cid_stats' ``` {% /tab %} {% tab title="Docker Compose" %} Add the following to your [docker-compose.yml](https://docs.datadoghq.com/agent/guide/compose-and-the-datadog-agent.md) file: ```yaml services: #... datadog: #... environment: - DD_APM_FEATURES: 'enable_cid_stats' ``` {% /tab %} {% tab title="Environment variables" %} If you configure the Agent with environment variables, as is common with Docker and ECS installations, pass the following environment variable to the trace Agent after upgrading the Docker image. ``` DD_APM_FEATURES=enable_cid_stats ``` {% /tab %} Restart the Agent. Go to the [APM Settings](https://app.datadoghq.com/apm/settings) page and select the additional primary tag you want to use. It can take up to two hours for changes to this setting to take effect. Now you can filter your services in the [Software Catalog](https://app.datadoghq.com/services) by the tag being sent by your containerized services. Trace metrics used by Dashboards and Monitors can also be aggregated by the container primary tag. **Note**: Primary tag values should not contain capital letters or special characters (aside from underscores, minuses, colons, periods, and slashes). If they do, some features may not work properly. ### Custom labels as tags{% #custom-labels-as-tags %} If you haven't already, you may also configure the Agent to send container or Pod labels as custom tags for your traces with [Assigning Tags](https://docs.datadoghq.com/getting_started/tagging/assigning_tags.md). ## View data by primary tag{% #view-data-by-primary-tag %} Primary tags appear at the top of APM pages. Use these selectors to filter the data displayed on the current page. To view all data independent of a primary tag, choose `:*` from the dropdown. {% image source="https://docs.dd-static.net/images/tracing/guide/setting_primary_tags/second-primary-tag-dropdown.70bf3f6c7a70917c8e551a63982a5eb5.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/guide/setting_primary_tags/second-primary-tag-dropdown.70bf3f6c7a70917c8e551a63982a5eb5.png?auto=format&fit=max&w=850&dpr=2 2x" alt="The dropdown menu showing options for selecting a scope with the second primary tag" /%} ## Further Reading{% #further-reading %} - [Connect your Logs and Traces together](https://docs.datadoghq.com/tracing/other_telemetry/connect_logs_and_traces.md) - [Instrument manually your application to create traces.](https://docs.datadoghq.com/tracing/manual_instrumentation.md) - [Implement Opentracing across your applications.](https://docs.datadoghq.com/tracing/opentracing.md) - [Explore your services, resources, and traces](https://docs.datadoghq.com/tracing/glossary.md)