Fix alias field generation in docs

[ruflin]

Alias fields documented in the fields list were not correct. The reason is that path was used in our generation of the docs for a different puprose. This one was renamed and reporting of path was added for field alias.

[ruflin]

@dedemorton This is a fix for the aliases but I think we need a bigger overhaul on how we represent / show fields. @karenzone Perhaps if we figure it out for ECS, we can also use it here.

[webmat]

I find this literal output of path: a bit dry. I understand that this is the terminology used inside ElasticSearch.

But I think we could output something a bit more human friendly here:

*`beat.name`*::
+
--
type: alias

alias to: agent.type

[ruflin]

changed, PR will be updated in a minute.

[dedemorton]

@ruflin I agree. The headings in particular are not very helpful and the repetition of headings looks odd. The structure looks especially bad when the descriptions in the source yml are cryptic. It works a bit better when the descriptions are more complete. I think we should come up with a good design for the reference content and work back from there. @karenzone Let's work on this together.

[webmat]

Yeah the context is that all of these field being aliased are now replaced by more canonical fields. Most of them are ECS fields, but not necessarily.

So there's a few things we can do, in addition to my simple suggestion above, if we think it's worth it:

• We could have a functional asciidoc link that lets the user navigate to the new canonical definition
• We could pull the definition of the new field (in example above, get agent.type definition), and add it to this old field (in example above, output definition to deprecated field beat.name), in addition to mentioning that it's now an alias.
• Instead of copying the field's doc to the old field, we could output a deprecation warning and say that "This field is going away in 8.0. In the meantime, this alias ensures visualizations and aggregations based on this field will continue working, but please update them to the new field."
  • Note that most module fields are moving in this fashion, and that some of the generic Beats fields are moving as well. So perhaps we can have a full explanation in one place, and a much shorter text in each of these aliases, which may well end up being 100+ aliases.

One final note, the presence of an alias does not absolutely mean that this is a migration for 7.0, or caused by ECS. So perhaps all of these suggestions above need to be triggered by an additional field in the yml files. Such field migrations can keep happening in 8.0 and later, and we may want to be able to differentiate them.

[dedemorton]

I don't like the idea of an asciidoc link because I don't want to force users to go to a different page to find a field description. I think the 3rd option is best because it helps users understand why we've created the aliases. At any rate, we should pull in the description of ECS fields from a single source of truth and use those descriptions wherever we describe the fields. I hope that we can make the descriptions generic enough so that they make sense wherever the description might show up.

[ruflin]

This PR is here to fix the current bug. As mentioned in my initial comment, we need to have a broader discussion but this should not hold back this PR.

@dedemorton What is the best place we can continue this discussion?

[webmat]

I'm good with splitting off the perfect representation of aliases to later. This PR addresses some foundational stuff.

Perhaps open a GH issue specifically about the visual representation of aliases, and port the discussion there?

[ruflin]

Issue opened here: #9288

@webmat Could you approve the PR so I can merge it? It will conflict with many other (ecs) PR's :-)

[webmat]

Yes, LGTM