Getting Started with Tags
Overview
Tags are a way of adding dimensions to Datadog telemetries so they can be filtered, aggregated, and compared in Datadog visualizations. Using tags enables you to observe aggregate performance across several hosts and (optionally) narrow the set further based on specific elements. In summary, tagging is a method to observe aggregate data points.
Tagging binds different data types in Datadog, allowing for correlation and call to action between metrics, traces, and logs. This is accomplished with reserved tag keys.
| Tag Key | Allows for |
|---|
host | Correlation between metrics, traces, processes, and logs. |
device | Segregation of metrics, traces, processes, and logs by device or disk. |
source | Span filtering and automated pipeline creation for Log Management. |
service | Scoping of application specific data across metrics, traces, and logs. |
env | Scoping of application specific data across metrics, traces, and logs. |
version | Scoping of application specific data across metrics, traces, and logs. |
Datadog recommends looking at containers, VMs, and cloud infrastructure at the service level in aggregate. For example, look at CPU usage across a collection of hosts that represents a service, rather than CPU usage for server A or server B separately.
Because containers and cloud environments regularly churn through hosts, using tags is important to aggregate your metrics.
Below are Datadog’s tagging requirements:
Tags must start with a letter and after that may contain the characters listed below:
- Alphanumerics
- Underscores
- Minuses
- Colons
- Periods
- Slashes
Other special characters are converted to underscores.
Tags can be up to 200 characters long and support Unicode letters (which includes most character sets, including languages such as Japanese).
Tags are converted to lowercase. Therefore, CamelCase tags are not recommended. Authentication (crawler) based integrations convert camel case tags to underscores, for example TestTag –> test_tag.
A tag can be in the format value or <KEY>:<VALUE>. Commonly used tag keys are env, instance, and name. The key always precedes the first colon of the global tag definition, for example:
| Tag | Key | Value |
|---|
env:staging:east | env | staging:east |
env_staging:east | env_staging | east |
Tags should not originate from unbounded sources, such as epoch timestamps, user IDs, or request IDs. Doing so may infinitely increase the number of metrics for your organization and impact your billing.
Limitations (such as downcasing) only apply to metric tags, not log attributes or span tags.
Tagging methods
Tags may be assigned using any (or all) of the following methods.
| Method | Assign tags |
|---|
| Configuration Files | Manually in your main Agent or integration configuration files. |
| UI | In the Datadog site. |
| API | When using Datadog’s API. |
| DogStatsD | When submitting metrics with DogStatsD. |
For more information, see Assigning Tags.
Unified service tagging
As a best practice, Datadog recommends using unified service tagging when assigning tags. Unified service tagging ties Datadog telemetry together through the use of three standard tags: env, service, and version. To learn how to configure your environment with unified tagging, see Unified Service Tagging.
Usage
After you have assigned tags at the host and integration level, start using them to filter and group your metrics, traces, and logs. Tags are used in the following areas of your Datadog platform.
| Area | Use Tags to |
|---|
| Events | Filter the event stream. |
| Dashboards | Filter and group metrics on graphs. |
| Infrastructure | Filter and group on the host map, infrastructure list, live containers, and live processes views. |
| Monitors | Manage monitors, create monitors, or manage downtime. |
| Metrics | Filter and group with the Metric Explorer. |
| Integrations | Optionally limit metrics for AWS, Google Cloud, and Azure. |
| APM | Filter services, traces, and profiles, or navigate to other areas with the Service Map. |
| RUM & Session Replay | Filter event search, analytics, patterns, replays, and issues with the RUM Explorer. |
| Synthetic Monitoring & Continuous Testing | Filter and group Synthetic tests or tests running in CI pipelines with the Synthetic Monitoring & Testing Results Explorer. |
| Notebooks | Filter and group metrics on graphs. |
| Logs | Filter logs search, analytics, patterns, live tail, and pipelines. |
| SLOs | Search for SLOs, grouped metric-based SLOs, and grouped monitor-based SLOs. |
| Developers | Pull information or setup different areas in the UI with the API. |
| Billing | Report on Datadog usage by choosing up to three tags, for example: env, team, and account_id. |
| CI Visibility | Filter and group test runs or pipeline executions with the CI Visibility Explorer. |
For more information, see Using Tags.
Further Reading
Additional helpful documentation, links, and articles:
