Doc: Elastic Agent standalone documentation can use improvements

[ppf2]

Some users are having trouble following documentation to set up standalone Elastic agents.

For example:

• https://www.elastic.co/guide/en/fleet/current/elastic-agent-configuration.html

  • This page and its subsections have no mention of what to do with modules or where the module documentation is located

  • In the section below, users are looking for the minimum required set of settings to configure for the agent to be operational

    The following sections describe some settings you might need to configure to run an Elastic Agent standalone. For a full reference example, refer to the elastic-agent.reference.yml file.

• https://www.elastic.co/guide/en/fleet/master/beats-agent-comparison.html#supported-configurations: Under supported configurations > modules, it simply links to filebeat modules which suggests that all other beats (metricbeat) modules are not supported

• If we do not intend to duplicate the modules documentation in Elastic Agent guide, let's make sure to add all appropriate cross links to the documentation in all the supported modules

[elasticmachine]

Pinging @elastic/agent (Team:Agent)

[elasticmachine]

Pinging @elastic/obs-docs (Team:Docs)

[ppf2]

Additional feedback from our users:

What default options can be set in the inputs section of the elastic-agent.reference.yml?

Here is a specific example:

The default elastic-agent.yml and elastic-agent.reference.yml has an inputs section that includes some defaults for system/metrics. In that section is the following for the CPU metricset:

      - metricset: cpu

        # Dataset name must conform to the naming conventions for Elasticsearch indices, cannot contain dashes (-), and cannot exceed 100 bytes

        data_stream.dataset: system.cpu

If we look specifically at the CPU metricset we get when exporting the config from Fleet we get the following:

      - id: system/metrics-system.cpu-65f74497-9f44-4223-aa23-9e56369415db

        data_stream:

          dataset: system.cpu

          type: metrics

        period: 1m

        cpu.metrics:

          - percentages

          - normalized_percentages

        metricsets:

          - cpu

We do not currently see any documentation that explains the additional options we see when exporting a config from fleet, such as period, data_stream.type, and cpu.metrics.

Since we have some familiarity with metricbeat, we can figure out that if we go to https://www.elastic.co/guide/en/beats/metricbeat/current/metricbeat-metricset-system-cpu.html and look at the options that we might be able to define those in the elastic-agent.yml config in our cpu metricset section, but it’s still a guess if you don’t already know it’s possible. We only know it’s possible because we currently have access to fleet.

Other basic options like changing the period do not appear to be documented. Seems like https://www.elastic.co/guide/en/fleet/current/elastic-agent-input-configuration.html would be a good place for elastic to expand and show the basic options that can be applied to each metricset, and then possibly the individual metricbeat module pages, like the one we linked above for CPU could be expanded with a section for use with elastic-agent.

We think the reference file could also be improved by just providing the options with some comments. For example:

inputs:

  - type: system/metrics

    data_stream.namespace: default

    use_output: default

    streams:

      - metricset: cpu

        data_stream.dataset: system.cpu

        # period at which metrics will be collected and sent

        # period: 10s

        # Option to control what CPU metrics are reported.

        # The value is a list and three metric types are supported - percentages, normalized_percentages, and ticks.

        # The default value is cpu.metrics: [percentages].

        # cpu.metrics: [percentages]

...

And then obviously doing this for each system metric at least of the default ones currently in the config with a link to documentation on where to find additional settings for the various metricsets within a module.

[lucabelluccini]

Feedback:

• There is no list of supported inputs
• There are few examples around with logfile input (where is documented) and system/metrics input. Still, the https://www.elastic.co/guide/en/fleet/current/beats-agent-comparison.html#supported-inputs-beats-and-agent states they're supported.