Update APM Quick start and new management modes

[bmorelli25]

Summary

This PR separates our getting started content into two sections:

• Quick start with Elastic Cloud—super quick and easy, few decision points
• Get started (self-managed)—longer but more in-depth

The self-managed get started page includes all new content that explains the difference between using the APM Server binary, and using a Fleet-managed APM Server. Specifically, we call out pros/cons, supported outputs, required components, and the configuration method. There is also a decision tree to help users decide which options is right for them.

Questions for reviewers

• Does this separation make sense?
• Is the distinction between APM Server binary | Fleet-managed clear enough?
• What is missing?

[ghost]

💚 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-05-22T18:28:19.900+0000

• Duration: 6 min 47 sec

🤖 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 and publish the docker images.

• /test windows : Build & tests on Windows.

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

[mergify]

This pull request does not have a backport label. Could you fix it @bmorelli25? 🙏
To fixup this pull request, you need to add the backport labels for the needed
branches, such as:

• backport-7.x is the label to automatically backport to the 7.x branch.
• backport-7./d is the label to automatically backport to the 7./d branch. /d is the digit

NOTE: backport-skip has been added to this pull request.

[simitt]

@bmorelli25 please ping me when this is ready for another round of review

[axw]

Looks good overall. Should we be saying something like "Elastic Agent-managed", rather than "Fleet-managed"? Elastic Agent itself may be in standalone or Fleet mode. Given that we've added support for source maps and agent config in standalone mode, should we generalise a bit here?

[bmorelli25]

Looks good overall. Should we be saying something like "Elastic Agent-managed", rather than "Fleet-managed"? Elastic Agent itself may be in standalone or Fleet mode. Given that we've added support for source maps and agent config in standalone mode, should we generalise a bit here?

@axw For phase one of our documentation redesign, we decided to level-up the APM Server binary and present two main and equally recommended options for running APM Server: the APM Server binary and Fleet-managed APM Server.

Running Elastic Agent standalone (in any capacity) is still an "advanced" use-case with incomplete and less mature documentation. The Elastic Agent team is having active discussions about making standalone easier to use and prioritizing filling our documentation gaps on that topic. As they move in that direction, we will as well. So we'll eventually document three methods of installing/running/etc APM Server.

[simitt]

@elasticmachine, run elasticsearch-ci/docs

[simitt]

Is it intended that docs are still placed under the legacy header?

[ghost]

📚 Go benchmark report

Diff with the main branch

goos: linux
goarch: amd64
pkg: github.com/elastic/apm-server/internal/agentcfg
cpu: 12th Gen Intel(R) Core(TM) i5-12500
                                  │ build/main/bench.out │              bench.out              │
                                  │        sec/op        │    sec/op     vs base               │
FetchAndAdd/FetchFromCache-12                41.13n ± 4%    47.32n ± 3%  +15.05% (p=0.002 n=6)
FetchAndAdd/FetchAndAddToCache-12            91.99n ± 1%   101.65n ± 4%  +10.51% (p=0.002 n=6)
geomean                                      61.51n         69.36n       +12.75%

                                  │ build/main/bench.out │             bench.out              │
                                  │         B/op         │    B/op     vs base                │
geomean                                                ²               +0.00%               ²
¹ all samples are equal
² summaries must be >0 to compute geomean

                                  │ build/main/bench.out │             bench.out              │
                                  │      allocs/op       │ allocs/op   vs base                │
geomean                                                ²               +0.00%               ²
¹ all samples are equal
² summaries must be >0 to compute geomean

pkg: github.com/elastic/apm-server/internal/beater/request
                                             │ build/main/bench.out │              bench.out              │
                                             │        sec/op        │    sec/op     vs base               │
ContextResetContentEncoding/empty-12                   116.5n ±  1%   131.1n ±  1%  +12.53% (p=0.002 n=6)
ContextResetContentEncoding/uncompressed-12            140.0n ±  1%   157.0n ±  1%  +12.14% (p=0.002 n=6)
geomean                                                930.8n         896.5n         -3.69%

                                             │ build/main/bench.out │              bench.out               │
                                             │         B/op         │     B/op      vs base                │
geomean                                                           ²                 +0.00%               ²
¹ all samples are equal
² summaries must be >0 to compute geomean

                                             │ build/main/bench.out │             bench.out              │
                                             │      allocs/op       │ allocs/op   vs base                │
geomean                                                           ²               +0.00%               ²
¹ all samples are equal
² summaries must be >0 to compute geomean

pkg: github.com/elastic/apm-server/internal/publish
             │ build/main/bench.out │            bench.out             │
             │        sec/op        │   sec/op    vs base              │
Publisher-12             1.004 ± 0%   1.003 ± 0%  -0.07% (p=0.015 n=6)

             │ build/main/bench.out │           bench.out            │
             │         B/op         │     B/op       vs base         │

             │ build/main/bench.out │           bench.out           │
             │      allocs/op       │  allocs/op    vs base         │

pkg: github.com/elastic/apm-server/x-pack/apm-server/aggregation/spanmetrics
                 │ build/main/bench.out │          bench.out           │
                 │        sec/op        │   sec/op     vs base         │

                 │ build/main/bench.out │            bench.out            │
                 │         B/op         │     B/op      vs base           │
¹ all samples are equal

                 │ build/main/bench.out │           bench.out           │
                 │      allocs/op       │ allocs/op   vs base           │
¹ all samples are equal

pkg: github.com/elastic/apm-server/x-pack/apm-server/aggregation/txmetrics
                        │ build/main/bench.out │          bench.out           │
                        │        sec/op        │   sec/op     vs base         │

                        │ build/main/bench.out │           bench.out           │
                        │         B/op         │    B/op     vs base           │
¹ all samples are equal

                        │ build/main/bench.out │           bench.out           │
                        │      allocs/op       │ allocs/op   vs base           │
¹ all samples are equal

pkg: github.com/elastic/apm-server/x-pack/apm-server/sampling
               │ build/main/bench.out │             bench.out              │
               │        sec/op        │    sec/op     vs base              │
geomean                  610.3n         602.7n        -1.24%

               │ build/main/bench.out │              bench.out               │
               │         B/op         │     B/op      vs base                │
geomean                             ²                 +0.05%               ²
¹ all samples are equal
² summaries must be >0 to compute geomean

               │ build/main/bench.out │             bench.out              │
               │      allocs/op       │ allocs/op   vs base                │
geomean                             ²               +0.00%               ²
¹ all samples are equal
² summaries must be >0 to compute geomean

pkg: github.com/elastic/apm-server/x-pack/apm-server/sampling/eventstorage
                                            │ build/main/bench.out │               bench.out               │
                                            │        sec/op        │    sec/op      vs base                │
WriteTransaction/json_codec-12                       4.223µ ±  16%   15.509µ ± 17%  +267.28% (p=0.002 n=6)
WriteTransaction/json_codec_big_tx-12                4.979µ ±   4%   12.228µ ± 39%  +145.61% (p=0.002 n=6)
ReadEvents/json_codec/0_events-12                    309.9n ±   7%    344.4n ± 10%   +11.12% (p=0.002 n=6)
ReadEvents/json_codec/10_events-12                   199.5µ ±  24%    139.1µ ± 38%   -30.28% (p=0.015 n=6)
ReadEvents/json_codec_big_tx/0_events-12             320.1n ±   8%    351.4n ±  8%    +9.78% (p=0.026 n=6)
ReadEvents/json_codec_big_tx/1_events-12             11.72µ ±  11%    12.59µ ±  2%    +7.39% (p=0.015 n=6)
ReadEvents/json_codec_big_tx/10_events-12            185.1µ ±  42%    133.9µ ± 72%   -27.70% (p=0.041 n=6)
ReadEvents/json_codec_big_tx/100_events-12           1.031m ±   2%    1.010m ±  2%    -2.04% (p=0.041 n=6)
ReadEvents/json_codec_big_tx/1000_events-12          9.464m ±   5%    9.216m ±  2%    -2.62% (p=0.015 n=6)
ReadEvents/nop_codec/0_events-12                     303.8n ±   3%    341.1n ±  5%   +12.26% (p=0.002 n=6)
ReadEvents/nop_codec/100_events-12                   149.0µ ±   5%    140.8µ ± 12%    -5.51% (p=0.026 n=6)
ReadEvents/nop_codec_big_tx/0_events-12              302.3n ±  10%    352.6n ±  9%   +16.64% (p=0.004 n=6)
ReadEvents/nop_codec_big_tx/1_events-12              1.948µ ±   8%    2.114µ ±  9%    +8.52% (p=0.041 n=6)
IsTraceSampled/sampled-12                            70.67n ±   4%    78.52n ±  4%   +11.12% (p=0.002 n=6)
IsTraceSampled/unsampled-12                          72.59n ±   3%    79.31n ±  0%    +9.24% (p=0.002 n=6)
IsTraceSampled/unknown-12                            375.3n ±   3%    416.8n ±  2%   +11.04% (p=0.002 n=6)
geomean                                              29.13µ           31.85µ          +9.31%

                                            │ build/main/bench.out │               bench.out                │
                                            │         B/op         │      B/op       vs base                │
WriteTransaction/json_codec-12                       2.928Ki ±  0%    2.929Ki ±  0%  +0.05% (p=0.041 n=6)
WriteTransaction/json_codec_big_tx-12                3.686Ki ±  0%    3.688Ki ±  0%  +0.05% (p=0.013 n=6)
ReadEvents/json_codec/10_events-12                   81.36Ki ±  0%    81.35Ki ±  0%  -0.01% (p=0.043 n=6)
ReadEvents/json_codec/1000_events-12                 3.338Mi ±  1%    3.308Mi ±  1%  -0.93% (p=0.019 n=6)
ReadEvents/nop_codec_big_tx/100_events-12            244.7Ki ±  0%    244.5Ki ±  0%  -0.06% (p=0.024 n=6)
ReadEvents/nop_codec_big_tx/399_events-12            877.9Ki ±  0%    876.5Ki ±  0%  -0.16% (p=0.022 n=6)
geomean                                              31.35Ki          31.44Ki        +0.26%
¹ all samples are equal

                                            │ build/main/bench.out │              bench.out              │
                                            │      allocs/op       │  allocs/op   vs base                │
geomean                                                 144.7         144.7       -0.00%
¹ all samples are equal

report generated with https://pkg.go.dev/golang.org/x/perf/cmd/benchstat

[mergify]

This pull request is now in conflicts. Could you fix it @bmorelli25? 🙏
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 upstream
git checkout -b ft-new-apm-start upstream/ft-new-apm-start
git merge upstream/main
git push upstream ft-new-apm-start

[simitt]

Looks good, just left a couple of smaller comments.

[simitt]

Step 2 mentions to write down the apm-server url as it is needed afterwards, no mentioning of the secret-token. But here the secret token is required. Either we describe to enable api-key auth and make it part of this instructions, or we add the secret-token in Step 2.

[bmorelli25]

This content lives in the observability-docs repo. I've opened elastic/observability-docs#2964 to add the secret token to step two.