How does Datadog determine the Agent hostname?
This page is not yet available in Spanish. We are working on its translation.
If you have any questions or feedback about our current translation project,
feel free to reach out to us!Potential host names
The Datadog Agent collects potential host names from many different sources. Run the Agent’s status subcommand to see all names the Agent is detecting.
...
Hostnames
=========
hostname: my.special.hostname
agent-hostname: my.special.hostname
ec2-hostname: ip-192-0-0-1.internal
instance-id: i-deadbeef
socket-hostname: myhost
socket-fqdn: myhost.mydomain
...
From these names, a canonical name is chosen for the host. The Agent uses this name to identify itself to Datadog. The other names are submitted as well, but only as candidates for aliasing.
The canonical hostname is chosen according to the following rules. The first match is selected.
- agent-hostname: A hostname explicitly set in the Agent configuration file if it does not start with ip- or domu.
- hostname (
hostname -f on Linux): If the DNS hostname is not an EC2 default, for example: ip-192-0-0-1. - instance-id: If the Agent can reach the EC2 metadata endpoint from the host.
- hostname: Fall back on the DNS hostname even if it is an EC2 default.
If the name is recognized as a common non-unique name (for example, localhost.localdomain), the current rule fails and passes through to the next.
See Hostname detection logic for details on how the Agent determines the hostname.
AWS hosts
When pulling information on your AWS hosts from the Datadog API, the following attributes display based on availability:
| Attribute | Description |
|---|
aws_id | The instance id, fallback on host if no instance id |
aws_name | The cloud providername tag |
display_name | The canonical hostname (value of host identifier) |
Host aliases
A single host running in EC2 might have an instance ID (i-abcd1234), a generic hostname provided by EC2 based on the host’s IP address (ip-192-0-0-1), and a meaningful hostname provided by an internal DNS server or a config-managed hosts file (myhost.mydomain). Datadog creates aliases for host names when there are multiple uniquely identifiable names for a single host.
The names collected by the Agent (detailed above) are added as aliases for the chosen canonical name.
See the list of all hosts in your account from the Infrastructure List. The aliases associated with each host are available in the inspect panel, which is accessed by clicking the Inspect button while hovering over a host row:
Note: These aliases are not available for searching or filtering. They are available only in the inspect panel mentioned above.
Agent versions
There are differences in hostname resolution between Agent v5 and Agent v6.
Linux and macOS
When upgrading from Agent v5 to Agent v6, there might be a difference in the hostname reported by your Agent. To resolve the system hostname Agent v5 uses the hostname -f command while Agent v6 uses the Golang API os.Hostname(). On upgrades, the Agent hostname could change from a Fully-Qualified Domain Name (FQDN) to a short hostname, for example:
sub.domain.tld –> sub
Note: Starting from Agent v6.3, the hostname_fqdn configuration option was introduced that allows Agent v6 to have the same behavior as Agent v5. This flag is disabled by default on version 6.3+. See the example datadog.yaml for enabling this option.
Determine if you’re affected
Starting with v6.3.0, the Agent logs the warning below if you’re affected by the change:
DEPRECATION NOTICE: The agent resolved your hostname as <HOSTNAME>. However in a future version, it will be resolved as <FQDN> by default. To enable the future behavior, please enable the `hostname_fqdn` flag in the configuration.
You are not affected if any of the following are true:
- The Agent runs in GCE.
- The hostname is set the Agent’s main configuration file or through the
DD_HOSTNAME environment variable. - The Agent runs in a container with access to the Docker or Kubernetes API.
- The hostname output of
cat /proc/sys/kernel/hostname and hostname -f are the same.
Recommended action
If you’re affected by this change, Datadog recommends taking the following action when you upgrade your Agent:
- Upgrading from Agent v5 to Agent v < 6.3: Hardcode your hostname in the Agent’s main configuration file.
- Upgrading from Agent v5 to Agent >= v6.3: Enable the
hostname_fqdn option in the Agent’s main configuration file. This ensures that you keep the same hostname. - Upgrading from Agent v5 to Agent v6 (a future version which uses the fqdn by default): you don’t need to take any action.
- If you want to ensure the current default behavior of Agent v6 is preserved when you upgrade the Agent in the future, set
hostname_fqdn to false. That said, Datadog recommends you switch hostname_fqdn to true whenever possible.
Windows
On Agent v5, the Windows Agent reported the unqualified hostname by default. To maintain backward compatibility, this behavior is preserved with Agent v6. The new flag hostname_fqdn remains disabled by default on Windows, and will remain disabled by default on future v6 versions.
The Windows Agent honors the configuration flag starting with v6.5. Setting hostname_fqdn to true results in the Windows Agent reporting the fully qualified hostname.
Recommended action
By default, the recommended action is to do nothing. This preserves the existing behavior, especially if upgrading from Agent v5.
If you want to have Windows hosts specifically report fully qualified host names, then add hostname_fqdn set to true in your Agent’s main configuration file.
GCE
Only affects Agents running on GCE
By default, Agent v6 uses the instance’s hostname provided by GCE. This matches the behavior of Agent v5.5.1+ if gce_updated_hostname is set to true in datadog.conf.
If you’re upgrading from Agent v5 with gce_updated_hostname unset or set to false, and the hostname of the Agent is not hardcoded in datadog.conf/datadog.yaml, the reported hostname on Datadog changes from the GCE instance name to the full GCE instance hostname (which includes the GCE project id).
