How does Datadog determine the Agent hostname?
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.
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:
- 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.
When pulling information on your AWS hosts from the Datadog API, the following attributes display based on availability:
|The instance id, fallback on host if no instance id|
|The cloud |
|The canonical hostname (value of host identifier)|
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:
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:
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.
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
false. That said, Datadog recommends you switch
true whenever possible.
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.
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.
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
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.yaml, the reported hostname on Datadog changes from the GCE instance
name to the full GCE instance
hostname (which includes the GCE project id).