Adding Custom Host Attributes to Dynatrace OneAgent via DT_HOST_ATTRIBUTES

Why Custom Host Attributes Matter

Dynatrace hosts are the first‑level entities that collect metrics, traces and logs. When you have dozens or hundreds of hosts, tagging them with meaningful key/value pairs—such as environment=prod or team=backend—lets you filter dashboards, create alerting rules and slice data by business units. These tags are called custom host attributes and are added to the host entity during OneAgent startup.

How OneAgent Reads DT_HOST_ATTRIBUTES

OneAgent reads a single environment variable named DT_HOST_ATTRIBUTES at process launch. The variable contains a comma‑separated list of key=value pairs. The format is strict: no spaces around commas unless the value itself contains a space. Example:

DT_HOST_ATTRIBUTES="environment=prod,team=backend"

During startup, OneAgent parses this string, validates each key against a list of reserved names, and attaches the resulting map to the host entity. The attributes then appear under Host → Properties → Custom attributes in the UI and can be queried via the /api/v2/entities endpoint.

Setting the Environment Variable: A Shell Example

Below is a minimal shell script that demonstrates how to set the variable and start OneAgent on a Linux host. Adjust the path to your OneAgent binary as needed.

#!/usr/bin/env bash
# 1. Define custom attributes
export DT_HOST_ATTRIBUTES="environment=prod,team=backend"

# 2. Start or restart the OneAgent service
#   Option A: Direct binary (for manual runs)
# ./oneagent.sh start

#   Option B: Systemd service (recommended)
# systemctl restart oneagent

# 3. Verify the agent is running
systemctl status oneagent | grep "Active:"

Permission notes: The script must run as the user that owns the OneAgent process (commonly root or a dedicated dynatrace user). If you use systemd, the DT_HOST_ATTRIBUTES variable should be defined in the service unit file under Environment= or in a drop‑in snippet.

Restarting OneAgent to Apply Changes

OneAgent reads DT_HOST_ATTRIBUTES only at startup. Simply updating the variable in a running shell will not propagate new attributes. After changing the value, you must restart the agent:

• For a manual binary: ./oneagent.sh restart
• For systemd: systemctl restart oneagent

Check that the restart succeeded with systemctl status oneagent or by inspecting the agent logs under /opt/dynatrace/oneagent/logs/oneagent.log for a line that says “Custom host attributes set”.

Verifying the Attributes in the UI and API

After the restart, confirm the attributes appear in the Dynatrace UI:

1. Navigate to Hosts → All hosts.
2. Select a host that was just restarted.
3. Open the Properties panel and scroll to Custom attributes. You should see environment=prod and team=backend.

Alternatively, query the API:

curl -sS -H "Authorization: Api-Token YOUR_TOKEN" \
  "https://YOUR_ENVIRONMENT.live.dynatrace.com/api/v2/entities?entitySelector=type(HOST)&fields=properties"

Look for the properties object in the JSON response; it should contain the keys you defined. If the attributes are missing, double‑check the restart and the variable syntax.

Common Pitfalls and Limitations

• Reserved names: Keys like dt.entity.host, memory or cpu are reserved and will be ignored or cause conflicts. Stick to custom, meaningful names.
• Length limit: The entire DT_HOST_ATTRIBUTES string is capped at roughly 8 KB. Exceeding this silently truncates the list, so keep the number of attributes and the length of values moderate.
• Spaces and commas: The parser treats commas as separators; spaces are allowed only inside a value if you quote the entire string. For example, region="us east" should be written as region=us east (no quotes) or region="us east" (quotes inside the string).
• Dynamic changes: OneAgent does not support hot‑reloading of attributes. Any change requires a full restart, which may trigger a brief monitoring gap.
• Environment‑specific overrides: If you deploy the same host to multiple Dynatrace environments, you must set the variable separately for each environment’s OneAgent instance.

Best Practices

• Define a consistent naming convention (e.g., environment, team, region) and document it in your team’s runbook.
• Use systemd drop‑in files for production deployments to avoid accidental changes in user shells.
• Automate verification in CI/CD pipelines: after a deployment, run the API query and assert the presence of expected attributes.
• Keep the attribute list lean; only include tags that are used for filtering or alerting to stay within the size limit.
• Periodically audit host attributes via the API to ensure no stale or conflicting keys remain.

Conclusion

Custom host attributes, when added via the DT_HOST_ATTRIBUTES environment variable, give you fine‑grained control over host classification in Dynatrace. By following the steps above—setting the variable, restarting OneAgent, and verifying in the UI or API—you can reliably tag hosts and leverage those tags for dashboards, alerts, and segmentation. Remember the reserved names, length limits, and the need for a restart, and you’ll avoid the most common mistakes.