Documenting metrics messages in Beats logs

[ycombinator]

What does this PR do?

This PR documents the metrics that are periodically emitted by Beats in their logs.

Why is it important?

To understand what the metrics mean and how they could be used for troubleshooting.

[mergify]

This pull request does not have a backport label.
If this is a bug or security fix, could you label this PR @ycombinator? 🙏.
For such, you'll need to label your PR with:

• The upcoming major version of the Elastic Stack
• The upcoming minor version of the Elastic Stack (if you're not pushing a breaking change)

To fixup this pull request, you need to add the backport labels for the needed
branches, such as:

• backport-v8./d.0 is the label to automatically backport to the 8./d branch. /d is the digit

[elasticmachine]

💚 Build Succeeded

the below badges are clickable and redirect to their specific view in the CI or DOCS

Expand to view the summary

Build stats

• Start Time: 2023-07-31T23:40:02.663+0000

• Duration: 9 min 16 sec

❕ Flaky test report

No test was executed to be analysed.

🤖 GitHub comments

Expand to view the GitHub comments

To re-run your PR in the CI, just comment with:

• /test : Re-trigger the build.

• /package : Generate the packages and run the E2E tests.

• /beats-tester : Run the installation tests with beats-tester.

• run elasticsearch-ci/docs : Re-trigger the docs validation. (use unformatted text in the comment!)

[elasticmachine]

Pinging @elastic/elastic-agent (Team:Elastic-Agent)

[kilfoyle]

@ycombinator Thanks for opening this!
A couple of questions:

1. Would it be okay with you if I commit directly to your branch? To get this showing up in the docs I'd add an include statement to the troubleshooting.asciidoc source file for each beat, basically copying how the debug docs page is set up.
2. Does this look okay to you as a place in the table of contents for the new page to go (using Functionbeat as an example)?

[ycombinator]

Would it be okay with you if I commit directly to your branch?

Yes, please! There are a number of things that will need fixing / improving in this PR and I'd be grateful if you could help with that by directly pushing commits to my branch. I'll add some PR comments in the areas I'd like your help.

Does this look okay to you as a place in the table of contents for the new page to go (using Functionbeat as an example)?

Yes, I think that's fine, although if you think we should shorten that tile so it fits better with the rest of its sibling nav items, feel free to make the necessary edits.

Thanks!

[ycombinator]

Just curious: what does this line do?

[kilfoyle]

I think it doesn't do anything, and rather it's just a leftover from when we had to identified X-pack content. I left it in when I copied the content over from the other docs page just because I'm not 100% sure it's not used anymore.

[kilfoyle]

Sounds good @ycombinator
I've reworked the structure slightly so that:

• The new page now shows up in all of the Beats docs.
• The format and location of metrics-in-logs.asciidoc and the files that embed it completely matches that of the "Debug" page, debugging.asciidoc.
• The sections that you mention are specific to Filebeat will show up only in the Filebeat docs (that's accomplished by wrapping the sections in ifeval::["{beatname_lc}"=="filebeat"] and endif::[] tags).
• The full page title is still Understand metrics in {beatname} logs, but in the table of contents the name is shortened to Understand logged metrics. Let me know if the shortened version doesn't really work.

I'll still have some suggestions for the wording so I'll add those probably later in the day tomorrow.

[kilfoyle]

Here's a preview showing Filebeat versus non-Filebeat:

• Understand metrics in Filebeat logs
• Understand metrics in Functionbeat logs

[faec]

This looks great thank you for writing this up!

[cmacknz]

@lucabelluccini FYI this is likely helpful for support.

[ycombinator]

@lucabelluccini FYI this is likely helpful for support.

The published version is at https://www.elastic.co/guide/en/beats/filebeat/master/understand-filebeat-logs.html

[lucabelluccini]

Lovely @ycombinator ! Thank you for the notification @cmacknz