Improve fields view in Docs

[ruflin]

The current view of fields in our Beats docs is not very intuitive / readable. It should be improved. This issue is to discuss and track improvements.

Discussion started in #9269

@dedemorton FYI

[webmat]

Tagging with ecs even if not ECS-related directly. The migration to ECS is going to introduce so many aliases that this will be important to fix in time for 7.0.

[dedemorton]

@karenzone Let's collaborate on this together. We can't do much about the formatting (our css needs an overhaul, IMO), but we can work with what we've got.

Just to clarify, Karen and I will come up with a recommendation for layout. We'll probably need help implementing script changes.

[dedemorton]

As part of this effort, I would also like to clean up the content in the field docs and make sure the titles are unique for each section. Right now, we see what look like duplicate TOC entries whenever we have fields added by both a module and a processor (see below). Many of the field descriptions are either incomplete or need a good edit (hopefully we'll be able to leverage the ECS edits here).

[dedemorton]

I've created a proposal that has my "first pass" at a design for this content. Not sure if it's feasible or whether it will work in all situations, but it's a stake in the ground. The prototype has some stuff I was just trying out. Everything is up for discussion: #9519 (The asciidoc for my prototype is hand coded, not generated.)

[dedemorton]

Should we keep this open or close it? We did make some improvements, but I suspect we'll want to revisit this as part of a larger redesign related to integrations (or whatever we're calling the project now).

[ruflin]

The modules on the Beats side will stay around for a while and still be used. We definitively need to have this discussion for the new view but there we potentially have less limitations on asciidoc, at least inside Kibana. I would separate the two discussions and keep this open. I would hope that we can also align the view of ECS and this one here whatever we come up with.

[jsoriano]

I think we should revisit this. A related discussion appeared here #18802 (comment). In some modules there are some descriptions of fields added manually, what is not very maintainable. And the automatically generated docs seem mostly empty in the module discussed there: https://www.elastic.co/guide/en/beats/metricbeat/7.7/exported-fields-googlecloud.html

[elasticmachine]

Pinging @elastic/integrations (Team:Integrations)

[kaiyan-sheng]

+1 @jsoriano! Thanks for pointing to this issue. Two things I see here:

• When using light weight module, we tend to use dynamic mapping for fields, such as aws.*.metrics.*.*, googlecloud.stackdriver.*.*.*.* and azure.monitor.metrics.*.*. This makes the exported fields documentation not very useful for users if they want to see exactly what are the metrics these modules can collect. Maybe we should consider adding static mapping for each available metric on top of the dynamic mapping.

• exported fields section link is under Fields section in each metricset. But the link takes us to a full list of fields for the module. For example, as a user, if I click exported fields in compute metricset under googlecloud module, I would expect to see descriptions for all fields under/only under compute metricset. But this link actually take me to all fields under googlecloud module.

[ruflin]

@hbharding I would like to also get you involved here as we will need to show this nicely in the Ingest Manager too.

[botelastic]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.