Service naming
- Latest Dynatrace
- Explanation
- 4-min read
In Dynatrace, service names come from your telemetry. The source depends on the detection model: Service Detection v2 services are named from attributes on your spans, while Service Detection v1 services are named from what OneAgent detects on the process. This page explains where service names come from and how to set a service's name yourself.
How services get their names
Dynatrace uses two detection models, and the naming experience differs between them. Knowing which one named a service tells you whether you need to do anything at all.
Service Detection v2
Service Detection v2 names services from the OpenTelemetry resource attributes already on your spans, so you get readable names without any configuration:
- On Kubernetes, services are named from
k8s.workload.name. A workload calledcheckoutappears as thecheckoutservice. - For services that report an OpenTelemetry
service.name, that value becomes the service name directly.
These names follow OpenTelemetry conventions, so your naming approach is the same whether your data comes from OneAgent, the OpenTelemetry SDK, or both. SDv2 services are meaningful by default and rarely need any naming configuration. For the full list of attributes Dynatrace uses, see the built-in service detection rules.
Service Detection v1
Service Detection v1 is the classic detection model for OneAgent-instrumented processes, used for technologies that don't yet report OpenTelemetry resource attributes. It names a service from the technology and properties it detects on the process, such as the web container, framework, or context root, rather than from a service.name attribute.
Because SDv1 derives the name from what it detects, this is the model where naming a service yourself makes the biggest difference. Setting service.name gives an SDv1 service the label you want and carries that name onto its telemetry, as described next.
Service name templates for SDv2
For SDv2, you configure service names via service detection rules that use service name templates. A template combines static text with resource attribute placeholders to define how each service is named.
Template syntax
Wrap attribute placeholders in curly braces:
{attribute.name}
You can mix static text and multiple placeholders:
{dt.kubernetes.workload.name} - {dt.kubernetes.cluster.name}
If a placeholder attribute is absent on a span, it resolves to an empty string. There is currently no autocomplete for attribute names in the Dynatrace web UI, so validate your attribute names against the span data before configuring a service detection rule.
Supported attributes
For service name templates, use stable, low-cardinality, non-sensitive resource attributes or custom attributes present on the span. Below are some common examples:
| Attribute | Example value |
|---|---|
|
|
|
|
|
|
|
|
|
|
For the full list of attributes, see Customize service detection in Service Detection v2.
Configure a service name template
To configure a service name template
-
Go to
Settings > Process and contextualize > Services > Service detection (under Service detection v2). -
Open an existing service detection rule or create a new one.
-
In the Service name template field, enter your template string, for example:
{dt.kubernetes.workload.name} - {k8s.namespace.name} -
In the Matching condition, set a scope condition to control which workloads the rule applies to, for example,
dt.host_group.id == "NOMAD-nonprod14". -
Select Save changes or Create.
-
Verify the resulting service names in
Services.
Primary Grail fields and primary Grail tags are not recommended in service name templates.
Primary Grail fields and tags are available as dimensions on all service signals. You can use them as columns and filters in Services and dashboards without embedding them in the service names. The recommended approach is to keep the service name clean and use primary Grail tags as dimensions. For details, see Add context with tags, not names.
Set a service name with OTEL_SERVICE_NAME
Setting a name yourself is most useful for Service Detection v1 services, since Service Detection v2 already derives meaningful names. To choose a service's name, set the OTEL_SERVICE_NAME environment variable on the application process:
OTEL_SERVICE_NAME=my-checkout-service
This works with OneAgent. You don't need the OpenTelemetry SDK or the OpenTelemetry Span Sensor enabled.
If you want to set other resource attributes at the same time, use OTEL_RESOURCE_ATTRIBUTES instead:
OTEL_RESOURCE_ATTRIBUTES=service.name=my-checkout-service
How the value appears depends on how the service is detected:
- Services detected by Service Detection v2 use
service.nameas the service name directly. - Services detected by Service Detection v1 show the name as
service.name (detected name), and the value is also set asdt.service.nameon the service's spans and metrics.
Add context with tags, not names
When you want to tell similar services apart by environment, region, team, or application, keep the service name clean and put that context on the data as dimensions you can filter and sort by.
Instead of a name like checkout [prod, us-east, team-payments], keep checkout and filter the service list by k8s.namespace.name, region, or primary_tags.team. The information is the same, but it's structured and queryable.
- Primary Grail fields cover infrastructure context such as Kubernetes cluster and namespace, host group, and cloud account. Dynatrace enriches them on every signal automatically.
- Primary Grail tags promote your own attributes, such as team, application, or cost center, into the same set of dimensions.
In Services, use the new Explorer (Early Access) view to filter and sort your services by primary Grail fields and tags. For details, see New Explorer view.
Rename services with OpenPipeline rules Coming soon
A single OpenPipeline processing rule sets dt.service.name based on any span attribute—cluster name, namespace, deployment name, or a custom attribute—and applies the result atomically to the service entity, its metrics, and its spans.
set dt.service.name = "checkout" where k8s.deployment.name matches "^checkout-.*"
Use stable, low-cardinality attributes for dt.service.name, as high-cardinality values (such as IP address or user ID) cause metric explosion and increased storage costs. Moreover, avoid attributes that carry sensitive information, as service names are stored permanently across entities, metrics, and spans.
OpenPipeline processing rules support pattern matching, conditional logic, and fallback chains. One configuration point is used for service entity, metrics, and spans.
To add a dt.service.name processor to your spans pipeline
-
Go to
Settings > Process and contextualize > OpenPipeline > Spans. -
Go to the Pipelines tab, and open the pipeline that processes the spans you want to rename.
-
In the Processing stage, select (Add Processing) > DQL.
-
Enter a name for the processor, for example,
Rename $host:8080. -
Enter a Matching condition to scope which spans the rule applies to, for example,
matchesValue(dt.service.name, "*host:8080*") AND isNotNull(k8s.workload.name) AND isNotNull(server.address). -
In the DQL processor definition field, enter the renaming rule:
fieldsRemove dt.service.name| fieldsAdd dt.service.name = concat(k8s.workload.name, " ", server.address) -
Select Save.
After saving, allow a few minutes for new spans to be processed. Verify the updated service names in the Explorer (Early Access) view in Services.
Don't use primary Grail fields and primary Grail tags as part of the dt.service.name value.
Primary Grail fields and tags are available as queryable dimensions on all service signals and work better as filters and columns than as part of the service name. Keep the service name clean, and use primary Grail tags as dimensions. For details, see Add context with tags, not names.
Good to know
- Names flow with your telemetry. Because the service name is part of the telemetry, the same name appears across spans, metrics, logs, dashboards, SLOs, and alerts.
- New names apply going forward. A name you set with
service.nameappears on telemetry sent after you set it. Existing metrics and spans keep the name they were recorded with. - One service per process in Service Detection v2.
service.nameis a process-level attribute. With Service Detection v2, one process maps to one service, so each service carries its own name. With Service Detection v1, a process that hosts more than one service shares a singleservice.nameacross them.