Type to search.

Add Host metadata

Serverless

Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud.

Availability

  • Generally available

    This functionality is generally available and ready for production usage.

Serverless interfaces and procedures might differ from classic Elastic Stack deployments.

Stack

The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats.

Availability

  • Generally available

    This functionality is generally available and ready for production usage.

Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments.

This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

Tip

Inputs that collect logs and metrics use this processor by default, so you do not need to configure it explicitly.

The add_host_metadata processor annotates each event with relevant metadata from the host machine.

Note

If you are using Elastic Agent to monitor external system, use the add_observer_metadata processor instead of add_host_metadata.

Example

YAML 
- add_host_metadata:
    cache.ttl: 5m
    geo:
      name: nyc-dc1-rack1
      location: 40.7128, -74.0060
      continent_name: North America
      country_iso_code: US
      region_name: New York
      region_iso_code: NY
      city_name: New York

The fields added to the event look like this:

JSON 
{
   "host":{
      "architecture":"x86_64",
      "name":"example-host",
      "id":"",
      "os":{
         "family":"darwin",
         "type":"macos",
         "build":"16G1212",
         "platform":"darwin",
         "version":"10.12.6",
         "kernel":"16.7.0",
         "name":"Mac OS X"
      },
      "ip": ["192.168.0.1", "10.0.0.1"],
      "mac": ["00:25:96:12:34:56", "72:00:06:ff:79:f1"],
      "geo": {
          "continent_name": "North America",
          "country_iso_code": "US",
          "region_name": "New York",
          "region_iso_code": "NY",
          "city_name": "New York",
          "name": "nyc-dc1-rack1",
          "location": "40.7128, -74.0060"
        }
   }
}

Configuration settings

Note

Elastic Agent processors execute before ingest pipelines, which means that they process the raw event data rather than the final event sent to Elasticsearch. For related limitations, refer to What are some limitations of using processors?

Important

If host.* fields already exist in the event, they are overwritten by default unless you set replace_fields to true in the processor configuration.

Name Required Default Description
netinfo.enabled No true Whether to include IP addresses and MAC addresses as fields host.ip and host.mac.
cache.ttl No 5m Sets the cache expiration time for the internal cache used by the processor. Negative values disable caching altogether.
geo.name No User-definable token to be used for identifying a discrete location. Frequently a data center, rack, or similar.
geo.location No Longitude and latitude in comma-separated format.
geo.continent_name No Name of the continent.
geo.country_name No Name of the country.
geo.region_name No Name of the region.
geo.city_name No Name of the city.
geo.country_iso_code No ISO country code.
geo.region_iso_code No ISO region code.
replace_fields No true Whether to replace existing host fields in the event. If true (default), the processor always runs and overwrites any existing host.* fields with metadata from add_host_metadata. If false, the processor only adds metadata when no host.* fields exist in the event or when only host.name is present. If other host fields exist, the processor is skipped entirely.