---
isPrivate: true
title: How does Datadog determine the Agent hostname?
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: Docs > Agent > Agent FAQ > How does Datadog determine the Agent hostname?
---

# How does Datadog determine the Agent hostname?

## Potential host names{% #potential-host-names %}

The Datadog Agent collects potential host names from many different sources. Run the Agent's [status subcommand](https://docs.datadoghq.com/agent/configuration/agent-commands/#agent-status-and-information) to see all names the Agent is detecting.

```text
...
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.

1. **agent-hostname**: A hostname explicitly set in the [Agent configuration file](https://docs.datadoghq.com/agent/configuration/agent-configuration-files/#agent-main-configuration-file) if it does not start with ip- or domu.
1. **hostname** (`hostname -f` on Linux): If the DNS hostname is not an EC2 default, for example: `ip-192-0-0-1`.
1. **instance-id**: If the Agent can reach the EC2 metadata endpoint from the host.
1. **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](https://github.com/DataDog/datadog-agent/tree/main/pkg/util/hostname) for details on how the Agent determines the hostname.

### AWS hosts{% #aws-hosts %}

When pulling information on your AWS hosts from the [Datadog API](https://docs.datadoghq.com/api/v1/hosts/), 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{% #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](https://app.datadoghq.com/infrastructure). 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:

{% image
   source="https://datadog-docs.imgix.net/images/agent/faq/host_aliases.9eeeec6a774e6d1a2c928d06a1d669d9.png?auto=format"
   alt="Host aliases" /%}

**Note**: These aliases are not available for searching or filtering. They are available only in the inspect panel mentioned above.

## Agent versions{% #agent-versions %}

There are differences in hostname resolution between Agent v5 and Agent v6.

{% tab title="Agent v6 & v7" %}
### Linux and macOS{% #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](https://github.com/DataDog/datadog-agent/blob/master/pkg/config/config_template.yaml) for enabling this option.

#### Determine if you're affected{% #determine-if-youre-affected %}

Starting with v6.3.0, the Agent logs the warning below if you're affected by the change:

```text
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](https://docs.datadoghq.com/agent/configuration/agent-configuration-files/#agent-main-configuration-file) 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{% #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](https://docs.datadoghq.com/agent/configuration/agent-configuration-files/#agent-main-configuration-file) file.
- **Upgrading from Agent v5 to Agent >= v6.3**: Enable the `hostname_fqdn` option in the [Agent's main configuration](https://docs.datadoghq.com/agent/configuration/agent-configuration-files/#agent-main-configuration-file) 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{% #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{% #recommended-action-1 %}

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](https://docs.datadoghq.com/agent/configuration/agent-configuration-files/#agent-main-configuration-file).

### GCE{% #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).
{% /tab %}

{% tab title="Agent v5" %}

{% image
   source="https://datadog-docs.imgix.net/images/agent/faq/agent_hostname.8ce0fd9a14a551701c1d04bfd0daddb0.jpeg?auto=format"
   alt="Agent hostname scheme" /%}

{% /tab %}