search

elastic / ecs

Elastic Common Schema
https://www.elastic.co/what-is/ecs
Apache License 2.0
1.01k stars 418 forks source link

agent.name documentation might be wrong. #1915

Open philippkahr opened 2 years ago

philippkahr commented 2 years ago

Description of the issue:

The documentation https://www.elastic.co/guide/en/ecs/current/ecs-agent.html says:

Custom name of the agent. This is a name that can be given to an agent. This can be helpful if for example two Filebeat instances are running on the same host but a human readable separation is needed on which Filebeat instance data is coming from. If no name is given, the name is often left empty.

Agent.name can of course be anything that it want to be. Shouldn't we mention that our Beats and Elastic Agent per default use the Hostname as a value? Because the last line If no name is given, the name is often left empty is irritating.

ebeahan commented 2 years ago

Because the last line If no name is given, the name is often left empty is irritating.

I agree this sentence is unnecessary.

Shouldn't we mention that our Beats and Elastic Agent per default use the Hostname as a value?

I vote against adding a mention for two reasons:

  1. Users should query/alert/filter using host.* or observer.* fields for host name values and not agent.*. ECS intentionally avoided defining an agent.hostname field. Beats/Agents default to use the hostname, but other sources, like APM, use different conventions.
  2. To avoid stating Beats/Agent defaults in ECS. The Beats or Agents docs best describe their defaults and config options and are more likely up-to-date should defaults change.
philippkahr commented 2 years ago

Makes sense to me!

Users should query/alert/filter using host. or observer. fields for host name values and not agent.*. ECS https://github.com/elastic/ecs/issues/178#issuecomment-512586064defining an agent.hostname field. Beats/Agents default to use the hostname, but other sources, like APM, use different conventions.

Maybe we should have a blog post that explains what fields someone should use starting with 8.x?

ebeahan commented 2 years ago

Removed the unneeded sentence in #1919.

ebeahan commented 2 years ago

Maybe we should have a blog post that explains what fields someone should use starting with 8.x?

The team has been adding more content to the docs to capture recommended conventions and patterns, but, yes, a blog post would be another way to share.