docs: APM integration documentation #6287

bmorelli25 · 2021-10-04T23:09:29Z

Summary

Moves all APM Server Reference docs to /docs/legacy/*. Retains a temporary index.asciidoc in /docs/ to keep the build working until broken links are addressed
Moves all APM Guide docs to /docs/legacy/guide/*. Retains a temporary index.asciidoc in /docs/guide/ to keep the build working until broken links are addressed
Creates a new entry point (integrations-index.asciidoc) for the APM User Guide documentation.
Copies relevant APM Overview content to the new book (almost all content)

Build it

gh pr checkout 6287
$GIT_HOME/docs/build_docs --doc $GIT_HOME/apm-server/docs/integrations-index.asciidoc --chunk 2 --open

To do after this PR is merged

Fix old redirects broken in ab092ac
Fix fields.asciidoc script which was manually overwritten in ab092ac
Undo/fix b9adaef
Undo 9b50edd
Undo 832718b & f0336ee (temp include for https://github.com/elastic/observability-docs/blame/master/docs/en/observability/instrument-apps.asciidoc#L18)
Fix ~100 broken cross-doc links: Stop building APM Server and Overview books docs#2239 (comment).

Related issues and PRs

Stop building APM Server and Overview books docs#2239

…ration-docs

apmmachine · 2021-10-04T23:14:28Z

💚 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: 2021-10-14T19:37:36.359+0000
Duration: 41 min 39 sec
Commit: 8901e28

Test stats 🧪

Test	Results
Failed	0
Passed	6273
Skipped	18
Total	6291

🤖 GitHub comments

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

/test : Re-trigger the build.
/hey-apm : Run the hey-apm benchmark.
/package : Generate and publish the docker images.

…ration-docs

bmorelli25 · 2021-10-05T22:58:58Z

Chunk level is changing which means a number of links need to be fixed before this PR can be merged:

edit: removed because fixed

simitt

@bmorelli25 I took an initial look. I have a couple of remarks already but can also hold off for now until you ping me to take a closer look.

bmorelli25 · 2021-10-06T15:55:12Z

Hey @simitt — sure, any comments/suggestions are appreciated. The goal of this PR so far was to see if it was even possible to combine the APM Overview and APM Server into one book and get it to pass to elasticsearch-ci/docs ci. And that test is finally green.

The next steps, as I see them, are to:

Do a little more clean up, then merge this PR
Point all inbound APM links to the new APM book (not the Overview or Server Reference)
Stop building the master and 7.x versions of the Overview and Reference
Add new and old documentation to the new APM book

bmorelli25 · 2021-10-06T16:17:48Z

~~I think it's worth pointing out too that the TOC you see if you build this PR is not at all related to what the final layout of this content will be. I just needed headings to fill things out.~~

edit: removed temp TOC headings

…ration-docs

simitt · 2021-10-13T06:54:15Z

Are you planning on duplicating information that stays valid with the new managment model? (For example explanation around distributed tracing, transaction sampling, OpenTracing bridges, etc.)?

bmorelli25 · 2021-10-13T15:56:26Z

Are you planning on duplicating information that stays valid with the new managment model? (For example explanation around distributed tracing, transaction sampling, OpenTracing bridges, etc.)?

Yes. Duplication is unfortunate, but it's the only thing that made sense to me for content that is relevant to both the old way and the new way of doing things:

Option 1: Have one file that's "included" in both books for content that's relevant to both use cases -- It's unfortunately not possible to keep one file as the source of truth and include it in both the deprecated APM Overview and the new APM Guide. That's because page IDs must be unique in a book.
Option 2: Move content that's relevant to both use cases to the new book -- Considering the APM standalone/binary users' point of view, it wouldn't be a good experience for them to go to the deprecated book and not see the content that used to exist there. There'd be no way of knowing that the distributed tracing, sampling, etc., docs in the APM Guide apply to their use case as well
Option 3: Duplicate content that's relevant to both use cases -- This increases the complexity of updating shared content, but IMO provides the best user experience for both APM use cases.

…ration-docs

simitt

I'm good with merging this in as is and then adding additional content (such as for configuring the apm Integration).

The comments I left can be handled in a follow up.

simitt · 2021-10-15T11:49:26Z

docs/apm-components.asciidoc

+
+Elastic APM consists of four components: *APM agents*, *Elastic Agent*, *Elasticsearch*, and *Kibana*.
+
+image::./images/apm-architecture.png[Architecture of Elastic APM]


Another viable scenario will be to host an elastic-agent with an apm integration alongside a user's app, and then have these remote agents enroll via the centrally hosted elastic-agent.

Elastic APM consists of four components: APM agents, Elastic Agent, Elasticsearch, and Kibana.

Technically that is correct, but I think the interesting part for users would be the APM Integration, rather than the Elastic Agent. Could we generally talk about the APM Integration, and then in the concrete setup section, and in the more detailled paragraph below introduce the Elastic Agent to run the Integration?

simitt · 2021-10-15T12:25:24Z

docs/data-model.asciidoc

+These are known as events, and can be `spans`, `transactions`, `errors`, or `metrics`.
+
+* <<data-model-spans>>
+* <<data-model-transactions>>


Maybe we could aready de-emphasize the the difference between spans and transactions a bit. They are written to the same data stream now, so maybe let's focus on traces and then a bit less prominent mention the difference between spans and transactions.

simitt · 2021-10-15T12:28:08Z

docs/apm-data-security.asciidoc

+
+[source,console]
+----
+GET _ingest/pipeline/apm


We'll have a set of pipelines per datastreams, so this will need to be changed a bit.

bmorelli25 · 2021-10-15T20:08:43Z

Great feedback, @simitt. I'll address in a future PR.

See elastic#6287

* fix apmpackage changelog * update to go1.17.1 * make update-beats * Update go.mod to 1.17 * go mod tidy * go mod download all * Makefile: move fields.asciidoc to docs/legacy * Manual tweaks to fields.asciidoc See #6287 * Stop generating fields.asciidoc We won't be updating libbeat fields.yml anymore, so no need to keep regenerating fields.asciidoc. Co-authored-by: Andrew Wilkins <[email protected]>

# Conflicts: # docs/guide/index.asciidoc

* docs: APM integration documentation (#6287) # Conflicts: # docs/guide/index.asciidoc * Update docs/guide/apm-breaking-changes.asciidoc

* fix apmpackage changelog * update to go1.17.1 * make update-beats * Update go.mod to 1.17 * go mod tidy * go mod download all * Makefile: move fields.asciidoc to docs/legacy * Manual tweaks to fields.asciidoc See elastic/apm-server#6287 * Stop generating fields.asciidoc We won't be updating libbeat fields.yml anymore, so no need to keep regenerating fields.asciidoc. Co-authored-by: Andrew Wilkins <[email protected]>

docs: get it building

ab092ac

mergify bot added the backport-skip Skip notification from the automated backport with mergify label Oct 4, 2021

elastic deleted a comment from mergify bot Oct 4, 2021

Merge branch 'master' of github.com:elastic/apm-server into new-integ…

48c3b69

…ration-docs

bmorelli25 added 4 commits October 4, 2021 16:27

docs: move deprecated content to legacy directory

0e1bc75

docs: one more missing legacy link

eea081a

docs: things to undo later

b9adaef

docs: move guide to legacy

fef113b

bmorelli25 mentioned this pull request Oct 5, 2021

[Request] Create APM integration documentation elastic/observability-docs#1073

Closed

25 tasks

bmorelli25 added 6 commits October 5, 2021 14:21

docs: add temp breaking changes

9b50edd

docs: more fixes

cf9b614

docs: add temp file

832718b

Merge branch 'master' of github.com:elastic/apm-server into new-integ…

0fb7069

…ration-docs

docs: add temp tag

f0336ee

docs: ugh so many fixes

a3c4b30

bmorelli25 added 2 commits October 5, 2021 16:10

docs: fix api-key and secret-token links

3e9107f

docs: fix more links

487321b

bmorelli25 mentioned this pull request Oct 6, 2021

docs: remove link to APM Server elastic/kibana#114038

Merged

docs: more fixes

3cc9571

simitt reviewed Oct 6, 2021

View reviewed changes

Merge branch 'master' into new-integration-docs

17abfa5

bmorelli25 marked this pull request as ready for review October 6, 2021 18:28

bmorelli25 requested a review from simitt October 6, 2021 18:28

bmorelli25 added 2 commits October 12, 2021 14:11

Merge branch 'master' of github.com:elastic/apm-server into new-integ…

037e86e

…ration-docs

docs: finishing touches

2d10734

elastic deleted a comment from mergify bot Oct 12, 2021

bmorelli25 mentioned this pull request Oct 13, 2021

Add APM Guide elastic/docs#2246

Merged

bmorelli25 added 2 commits October 13, 2021 08:58

Merge branch 'master' into new-integration-docs

6463006

docs: start to add content from apm overview

e2dec08

ollyhowell assigned bmorelli25 Oct 14, 2021

bmorelli25 added 2 commits October 14, 2021 11:02

Merge branch 'master' of github.com:elastic/apm-server into new-integ…

1434848

…ration-docs

docs: finish duplicating apm overview

8901e28

elastic deleted a comment from mergify bot Oct 14, 2021

hgmauri approved these changes Oct 14, 2021

View reviewed changes

simitt approved these changes Oct 15, 2021

View reviewed changes

bmorelli25 merged commit 74832cc into elastic:master Oct 15, 2021

bmorelli25 deleted the new-integration-docs branch October 15, 2021 20:09

axw added a commit to stuartnelson3/apm-server that referenced this pull request Oct 16, 2021

Manual tweaks to fields.asciidoc

33fe078

See elastic#6287

axw mentioned this pull request Oct 16, 2021

make update #6318

Merged

bmorelli25 added a commit to bmorelli25/apm-server that referenced this pull request Oct 18, 2021

docs: APM integration documentation (elastic#6287)

b8e9be8

# Conflicts: # docs/guide/index.asciidoc

bmorelli25 mentioned this pull request Oct 18, 2021

[7.x] docs: APM integration documentation (#6287) #6376

Merged

bmorelli25 added a commit that referenced this pull request Oct 18, 2021

[7.x] docs: APM integration documentation (#6287) (#6376)

aa96ad1

* docs: APM integration documentation (#6287) # Conflicts: # docs/guide/index.asciidoc * Update docs/guide/apm-breaking-changes.asciidoc

v1v mentioned this pull request Nov 23, 2021

update beats: fix new file location #6700

Merged

bmorelli25 mentioned this pull request Nov 24, 2021

docs: Add "deprecating soon" notices #6708

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: APM integration documentation #6287

docs: APM integration documentation #6287

bmorelli25 commented Oct 4, 2021 •

edited

Loading

apmmachine commented Oct 4, 2021 •

edited

Loading

Build stats

Test stats 🧪

bmorelli25 commented Oct 5, 2021 •

edited

Loading

simitt left a comment

bmorelli25 commented Oct 6, 2021

bmorelli25 commented Oct 6, 2021 •

edited

Loading

simitt commented Oct 13, 2021

bmorelli25 commented Oct 13, 2021

simitt left a comment

simitt Oct 15, 2021

simitt Oct 15, 2021

simitt Oct 15, 2021

bmorelli25 commented Oct 15, 2021


		Elastic APM consists of four components: APM agents, Elastic Agent, Elasticsearch, and Kibana.

		image::./images/apm-architecture.png[Architecture of Elastic APM]

docs: APM integration documentation #6287

docs: APM integration documentation #6287

Conversation

bmorelli25 commented Oct 4, 2021 • edited Loading

Summary

Build it

To do after this PR is merged

Related issues and PRs

apmmachine commented Oct 4, 2021 • edited Loading

💚 Build Succeeded

Build stats

Test stats 🧪

🤖 GitHub comments

bmorelli25 commented Oct 5, 2021 • edited Loading

simitt left a comment

Choose a reason for hiding this comment

bmorelli25 commented Oct 6, 2021

bmorelli25 commented Oct 6, 2021 • edited Loading

simitt commented Oct 13, 2021

bmorelli25 commented Oct 13, 2021

simitt left a comment

Choose a reason for hiding this comment

simitt Oct 15, 2021

Choose a reason for hiding this comment

simitt Oct 15, 2021

Choose a reason for hiding this comment

simitt Oct 15, 2021

Choose a reason for hiding this comment

bmorelli25 commented Oct 15, 2021

bmorelli25 commented Oct 4, 2021 •

edited

Loading

apmmachine commented Oct 4, 2021 •

edited

Loading

bmorelli25 commented Oct 5, 2021 •

edited

Loading

bmorelli25 commented Oct 6, 2021 •

edited

Loading