docs: improve docs around bundlers/transpilers, methods of starting the agent #2837

trentm · 2022-07-22T00:09:28Z

Closes: #1967

review notes

Here are some highlights of what changes this PR makes to the docs:

A re-write of the 'starting-the-agent' doc page to:
- Discuss all the ways to require/import and start the agent.
- Discuss all the confusing gotchas with different tech. There are subtle diffs between them.
Update supported-technologies doc page:
- Add the latest node release schedule svg (we had an ancient one). Also add a nuance to the "Node.js versions" section stating that we still do test with 8.6 and will only drop node version support in a major.
- Add an ESM section describing the current limitation, and how to configure compilers/bundlers to emit CommonJS module code.
Remove the "es-modules.html" page, which was incomplete and misleading. It has a redirect page to the relevant new content mentioned above.
Add a "Get started with TypeScript" doc, and an "./examples/typescript/" using the APM agent.
Add an "./examples/esbuild/" using the APM agent. (Doing similar for Webpack would perhaps be helpful, but I haven't added one here.)
Ensure 'npm run test:babel' fails if it doesn't use import apm from 'elastic-apm-node/start' to start the agent before other imports.

Our docs on ESM usage with Babel state that you need to use 'elastic-apm-node/start' to instrument properly. Our test case should do so too.

…dd ES Module support limitation note (will have to clarify the somewhat confusing es-modules.html content)

This is experimental. I'm not sure if there are side-effects. See #1967 (comment)

…the Bundlers gotchas section

…ck usage

Adding this with*out* extension would be problematic. Currently without an "exports" a "foo.mjs" can `import 'elastic-apm-node/start.js'` (requires the .js) and can `import 'elastic-apm-node/lib/config.js'` et al. That's fine. No need to lock it down. If we *really* want the extension*less* access names, then we need to add "exports"... which locks it down, which *could* be breaking. So... let's not. I think we should bias to including the extension as ESM becomes more popular.

apmmachine · 2022-07-22T00:30:21Z

💚 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: 2022-07-29T16:49:54.056+0000
Duration: 21 min 12 sec

Test stats 🧪

Test	Results
Failed	0
Passed	257308
Skipped	0
Total	257308

🤖 GitHub comments

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

/test : Re-trigger the build.
run module tests for <modules> : Run TAV tests for one or more modules, where <modules> can be either a comma separated list of modules (e.g. memcached,redis) or the string literal ALL to test all modules
run benchmark tests : Run the benchmark test only.
run elasticsearch-ci/docs : Re-trigger the docs validation. (use unformatted text in the comment!)

… and reference to the updated sdtarting-the-agent docs and the ES Modules section in supported-technologies. Also add the start-option-separate-init-module start option.

bmorelli25

This is looking really good! Here are some nitpicks, questions, and ideas for you to consider.

docs/set-up.asciidoc

bmorelli25 · 2022-07-28T20:15:49Z

docs/set-up.asciidoc

+// Application main code goes here.
+----
+
+When authoring code using CommonJS (i.e. using `require(...)`), this method is rarely used. However, when using a tool (such as Babel or esbuild) to translate/transpile from code using ES modules (i.e. `import ...` statements) to code using CommonJS, this start method is necessary to ensure that the APM agent is _started before other imports in the same file_. See <<start-esm-imports>> below for details.


The second sentence is very long (and has multiple parentheticals). Can we break it up? What about something like this?

This method is rarely used when authoring code using CommonJS (i.e. using require(...)).
However, this method is necessary if you use a tool like Babel or esbuild to translate/transpile from code using ES modules (i.e. using import ... statements) to code using CommonJS. This start method ensures that the APM agent is started before other imports in the same file. See <> below for details.

Also, what do you mean when you say "rarely used"? Is there a use case for this method and CommonJS that we should explain?

Also, what do you mean when you say "rarely used"?

There isn't a use case for this beyond saving a couple keystrokes over require('elastic-apm-node').start() at the cost of not having a way to pass options to that .start() call.

@bmorelli25 How about I just drop the reference to CommonJS usage completely? There is no harm if a require-using programmer uses this form. So something like this:

This start method exists for those that use a tool like Babel or esbuild to translate/transpile from code using ES modules (as in the following example) to code using CommonJS. This start method ensures that the APM agent is started before other imports in the same file. See ... below for details.

docs/set-up.asciidoc

docs/typescript.asciidoc

docs/set-up.asciidoc

docs/agent-api.asciidoc

docs/troubleshooting.asciidoc

docs/set-up.asciidoc

Co-authored-by: Brandon Morelli <brandon.morelli@elastic.co>

astorm

Approving. Overall it says true things and gives us a better place to point folks working with TypeScript and other compiled languages. I didn't go full tech review on all the examples but what's there seems good. Approving presuming the more written word advice/feedback from @bmorelli25 in incorporated/resolved.

docs/configuration.asciidoc

astorm · 2022-07-28T20:56:33Z

docs/redirects.asciidoc

@@ -41,4 +41,12 @@ This endpoint has moved. Please see <<transaction-add-labels>>.
 [role="exclude",id="get-started"]


TIL: we have a deleted pages page.

Yeah! They're perfect for this use case.

astorm · 2022-07-28T21:49:18Z

docs/set-up.asciidoc

@@ -1,7 +1,7 @@
 [[set-up]]


TIL: we have a doc named set-up.asciidoc and a doc named setup.asciidoc.

Yah, it drives me crazy. :) And an <<advanced-setup>> anchor that is labelled "Configuration", but a separate <<configuration>> anchor that is labelled "Configuration options". Neither of these are in the "Set up the Agent" section.

Co-authored-by: Brandon Morelli <brandon.morelli@elastic.co>

docs/set-up.asciidoc

trentm added 11 commits July 7, 2022 17:25

ensure 'npm run test:babel' fails if not using 'elastic-apm-node/start'

ab89fce

Our docs on ESM usage with Babel state that you need to use 'elastic-apm-node/start' to instrument properly. Our test case should do so too.

Merge branch 'main' into trentm/docs-bundlers-ts-etc

d441fae

update supported tech doc page: latest node release schedule image; a…

e7a3ee7

…dd ES Module support limitation note (will have to clarify the somewhat confusing es-modules.html content)

Add "exports" so pure ESM can import 'elastic-apm-node/start' without.

9f741a5

This is experimental. I'm not sure if there are side-effects. See #1967 (comment)

a start at improved 'Starting the agent' docs; I still have to write …

2b0f892

…the Bundlers gotchas section

a section on Bundlers gotchas, incl 'externals' config info for webpa…

412e404

…ck usage

esbuild externals usage docs and example

9023c1e

more tweaks

b1ac9a1

tweaks, not sure about 'exports' addition for this PR

bb4587a

fix 'make check'

87b2157

trentm self-assigned this Jul 22, 2022

github-actions bot added the agent-nodejs Make available for APM Agents project planning. label Jul 22, 2022

elastic-apm-tech added this to In Progress in APM-Agents (OLD) Jul 22, 2022

replace es-modules.html page with a new 'Get started with TypeScript'…

de96baf

… and reference to the updated sdtarting-the-agent docs and the ES Modules section in supported-technologies. Also add the start-option-separate-init-module start option.

trentm mentioned this pull request Jul 26, 2022

log correlation + webpack may not work #2844

Open

trentm added 3 commits July 26, 2022 14:24

update ESM section

ebbdbd4

tweak

e49f497

tweaks and asciidoc syntax fixes

855df00

trentm marked this pull request as ready for review July 26, 2022 22:27

trentm requested review from bmorelli25 and astorm July 26, 2022 22:27

bmorelli25 reviewed Jul 28, 2022

View reviewed changes

trentm and others added 4 commits July 28, 2022 15:14

grammar

78d8fde

Co-authored-by: Brandon Morelli <brandon.morelli@elastic.co>

consistently code-format node

1a371c7

Co-authored-by: Brandon Morelli <brandon.morelli@elastic.co>

capitalization

d67d660

Co-authored-by: Brandon Morelli <brandon.morelli@elastic.co>

capitalization

60bb3a7

Co-authored-by: Brandon Morelli <brandon.morelli@elastic.co>

astorm approved these changes Jul 28, 2022

View reviewed changes

emdash FTW

4f12d50

Co-authored-by: Brandon Morelli <brandon.morelli@elastic.co>

trentm and others added 3 commits July 28, 2022 16:37

caps

5a7360e

Co-authored-by: Brandon Morelli <brandon.morelli@elastic.co>

phrasing

515709d

Co-authored-by: Brandon Morelli <brandon.morelli@elastic.co>

improvements mostly as Brandon suggested

c9fb5c3

trentm requested a review from bmorelli25 July 29, 2022 00:33

bmorelli25 reviewed Jul 29, 2022

View reviewed changes

docs/set-up.asciidoc Outdated Show resolved Hide resolved

bmorelli25 reviewed Jul 29, 2022

View reviewed changes

docs/set-up.asciidoc Show resolved Hide resolved

bmorelli25 approved these changes Jul 29, 2022

View reviewed changes

trentm added 3 commits July 29, 2022 09:46

I put my thang down, flip it and reverse it

e76ab76

.start() consistency

d410b09

s/function/method/ for consistency

0e305c1

trentm merged commit 90c3709 into main Jul 29, 2022

APM-Agents (OLD) automation moved this from In Progress to Done Jul 29, 2022

trentm deleted the trentm/docs-bundlers-ts-etc branch July 29, 2022 20:16

This was referenced Jul 29, 2022

Express with Webpack not sending Transactions #1962

Closed

http & https module instrumentation breaks "stripe" #2524

Closed

Not working with apollo-server-lambda (Apollo GraphQL) #2832

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: improve docs around bundlers/transpilers, methods of starting the agent #2837

docs: improve docs around bundlers/transpilers, methods of starting the agent #2837

trentm commented Jul 22, 2022 •

edited

apmmachine commented Jul 22, 2022 •

edited

Build stats

Test stats 🧪

bmorelli25 left a comment

bmorelli25 Jul 28, 2022

trentm Jul 28, 2022

astorm left a comment

astorm Jul 28, 2022

bmorelli25 Jul 29, 2022

astorm Jul 28, 2022

trentm Jul 29, 2022 •

edited

		@@ -41,4 +41,12 @@ This endpoint has moved. Please see <<transaction-add-labels>>.
		[role="exclude",id="get-started"]

docs: improve docs around bundlers/transpilers, methods of starting the agent #2837

docs: improve docs around bundlers/transpilers, methods of starting the agent #2837

Conversation

trentm commented Jul 22, 2022 • edited

review notes

apmmachine commented Jul 22, 2022 • edited

💚 Build Succeeded

Build stats

Test stats 🧪

🤖 GitHub comments

bmorelli25 left a comment

Choose a reason for hiding this comment

bmorelli25 Jul 28, 2022

Choose a reason for hiding this comment

trentm Jul 28, 2022

Choose a reason for hiding this comment

astorm left a comment

Choose a reason for hiding this comment

astorm Jul 28, 2022

Choose a reason for hiding this comment

bmorelli25 Jul 29, 2022

Choose a reason for hiding this comment

astorm Jul 28, 2022

Choose a reason for hiding this comment

trentm Jul 29, 2022 • edited

Choose a reason for hiding this comment

trentm commented Jul 22, 2022 •

edited

apmmachine commented Jul 22, 2022 •

edited

trentm Jul 29, 2022 •

edited