Initial docs for agent OTel mode

[kilfoyle]

This adds an initial set of public docs, marked as Technical Preview, for running Elastic Agent in OTel mode. The info is based off of the Elastic Distribution for OTel Collector readme, some of the official OTel docs, and off of Michal's very nice demo from the Ingest Team all hands.

Preview pages:

• Run Elastic Agent as an OTel Collector
• Elastic Agent OTel configuration
• Elastic Agent OTel components
• elastic-agent otel command

Closes: #1086

[github-actions]

A documentation preview will be available soon.

• 🔨 Buildkite builds
• 📚 HTML diff
• 📙 Preview page

Request a new doc build by commenting

• Rebuild this PR: run docs-build
• Rebuild this PR and all Elastic docs: run docs-build rebuild

_{run docs-build is much faster than run docs-build rebuild. A rebuild should only be needed in rare situations.}

_{If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here.}

[strawgate]

Looking really great! Added some thoughts

[andrzej-stencel]

Thank you @kilfoyle for putting this together 🙏 This is a great start. Added a couple small comments. One thing that I think is important is to list the components that are included in the distro, but I suppose this can be done in a follow-up PR as well.

[ycombinator]

One thing that I think is important is to list the components that are included in the distro, but I suppose this can be done in a follow-up PR as well.

Related to this note: the README at https://github.com/elastic/elastic-agent/blob/main/internal/pkg/otel/README.md is auto-generated any time new components are added. Ideally we could have some automation that mirrors the contents of that file in the public (web site) docs. @kilfoyle do you think this is possible?

In any case, ++ to setting up such automation in follow up PRs.

[kilfoyle]

I pushed some changes. More to come...
And I'll respond to comments very soon too. Thanks for the excellent feedback!

[kilfoyle]

@strawgate, @andrzej-stencel @michalpristas @ycombinator
The docs are updated based on the feedback (thank you!) and the preview links are in the description.

One challenge is going to be keeping the Elastic Agent OTel configuration and the Elastic Agent OTel components pages up to date. As the sample configuration and the bundled components change, I'd ask folks to please either tag me on the code PRs so I know about it, or feel free to just push an update to these docs.

Alternatively, we could just have links in the docs to the sample config file and the readme so that they can be the single sources of truth, but I think it's helpful to customers to include the content in the docs. Please let me know if you have preferences.

[kilfoyle]

@ycombinator

Related to this note: the README at https://github.com/elastic/elastic-agent/blob/main/internal/pkg/otel/README.md is auto-generated any time new components are added. Ideally we could have some automation that mirrors the contents of that file in the public (web site) docs. @kilfoyle do you think this is possible?

I would love to mirror both the readme and the sample otel config file in the docs. As far as I know we don't have any instance of doing this sort of thing currently. I'll look into it, but it may have to wait until the planned next docs system comes to fruition. Also, a challenge is that pulling content from other repos creates a dependency for the already very fragile docs build and the various CI checks that incorporate it. Breaking the docs CI blocks a lot of PRs, unfortunately.

[mergify]

This pull request is now in conflict. Could you fix it @kilfoyle? 🙏
To fixup this pull request, you can check out it locally. See documentation: https://help.github.com/articles/checking-out-pull-requests-locally/

git fetch <remote-repo>
git checkout -b 1086/initial-otel-docs <remote-repo>/1086/initial-otel-docs
git merge <remote-repo>/main
git push <remote-repo> 1086/initial-otel-docs

[strawgate]

Do we have a plan to finish this?

[kilfoyle]

Do we have a plan to finish this?

@strawgate Yes! I'm sorry that this got left behind. The hold-up is that I found out that @mdbirnstiehl from the Observability docs team separately has been pushing very comprehensive docs for the Elastic Agent OTel collector into the new elastic/opentelemetry repo (Mike's PR), and based on recent discussion with the Observability Team, I gather that that location, rather than the Fleet & Agent public docs, is the preferred location for us to document the agent OTel collector.

@mlunadia Please let me know if I've misunderstood anything from that discussion.

Below are the pages that I had planned to add to the public Fleet & Agent docs via this PR. I'd appreciate any thoughts about whether these should still be added. If they shouldn't be added, I can instead add links to Mike's docs in the opentelemetry repo.

Run Elastic Agent as an OTel Collector
Elastic Agent OTel configuration
Elastic Agent OTel components
elastic-agent otel command

If it's okay to add these I'll get them refreshed and merged asap.

[strawgate]

I think we still want to have the sub command and flags documented here even if there is more comprehensive onboarding documentation available elsewhere.

Will review the O11y docs as well

[kilfoyle]

Just to keep things tidy and not lose the changes here, I've opened a fresh PR that updates the Fleet & Agent guide with just the otel subcommand and flags, and a short introduction that links out to full docs in the elastic/opentelemetry repo.

I'll close this one soon. Please see instead: Add docs for agent 'otel' mode

[kilfoyle]

Closing in favour of this much reduced version: #1250