docs: documentation restructure (#1428)

docs/agent-api.asciidoc

@@ -754,7 +754,11 @@ apm.clearPatches(['timers'])
 
 [small]#Added in: v2.17.0#
 
-Produces an object containing `trace.id` and either `transaction.id` or `span.id` when a current transaction or span is available.
+// This content is reused in log-correlation.asciidoc
+// Ensure any updates here also make sense there
+// tag::currentTraceIds[]
+
+`apm.currentTraceIds` produces an object containing `trace.id` and either `transaction.id` or `span.id` when a current transaction or span is available.
 When no transaction or span is available it will return an empty object.
 This enables log correlation to APM traces with structured loggers.
 
@@ -782,3 +786,4 @@ This enables log correlation to APM traces with text-only loggers.
 // or ...
 "trace.id=abc123 span.id=abc123"
 ----
+// end::currentTraceIds[]

docs/configuration.asciidoc

@@ -105,11 +105,11 @@ The environment name is automatically logged along with all errors and transacti
 If you want to overwrite this,
 use this option.
 
-Environments allow you to easily filter data on a global level in the APM UI.
+Environments allow you to easily filter data on a global level in the APM app.
 It's important to be consistent when naming environments across agents.
-See {kibana-ref}/filters.html#environment-selector[environment selector] in the Kibana UI for more information.
+See {kibana-ref}/filters.html#environment-selector[environment selector] in the APM app for more information.
 
-NOTE: This feature is fully supported in the APM UI in Kibana versions >= 7.2.
+NOTE: This feature is fully supported in the APM app in Kibana versions >= 7.2.
 You must use the query bar to filter for a specific environment in versions prior to 7.2.
 
 [[instrument]]
@@ -146,6 +146,7 @@ Activate APM Agent Configuration via Kibana.
 If set to `true`, the client will poll the APM Server regularly for new agent configuration.
 
 NOTE: This feature requires APM Server v7.3 or later and that the APM Server is configured with `kibana.enabled: true`.
+More information is available in {kibana-ref}/agent-configuration.html[APM Agent configuration].
 
 [[async-hooks]]
 ==== `asyncHooks`

docs/custom-spans.asciidoc

@@ -5,7 +5,7 @@ NOTE: For the best reading experience,
 please view this documentation at https://www.elastic.co/guide/en/apm/agent/nodejs/current/custom-spans.html[elastic.co]
 endif::[]
 
-== Custom Spans
+=== Custom spans
 
 This is an example of how to use custom spans.
 For general information about the Elastic APM Node.js Span API,

docs/custom-stack.asciidoc

@@ -1,31 +1,24 @@
+:framework: custom Node.js
+
 [[custom-stack]]
 
 ifdef::env-github[]
 NOTE: For the best reading experience,
 please view this documentation at https://www.elastic.co/guide/en/apm/agent/nodejs/current/custom-stack.html[elastic.co]
 endif::[]
 
-== Get started with a custom Node.js stack
+=== Get started with a custom Node.js stack
 
-Getting Elastic APM set up for your Node.js app is easy,
-and there are various ways you can tweak it to fit your needs.
+include::./shared-set-up.asciidoc[tag=introduction]
 
-If you are using either Express, hapi, Koa, Restify, Fastify, or AWS Lambda
+If you are using Express, hapi, Koa, Restify, Fastify, or AWS Lambda,
 we recommend that you read these articles instead:
 
-* <<express,Get started with Express>>
-* <<hapi,Get started with hapi>>
-* <<koa,Get started with Koa>>
-* <<restify,Get started with Restify>>
-* <<fastify,Get started with Fastify>>
-* <<lambda,Get started with Lambda>>
-
-For a custom Node.js app, follow the guide below to get started.
-For more advanced topics, check out the <<api,API Reference>>.
+include::set-up.asciidoc[tag=web-frameworks-list]
 
 [float]
 [[custom-stack-installation]]
-=== Installation
+==== Installation
 
 Add the `elastic-apm-node` module as a dependency to your application:
 
@@ -36,7 +29,7 @@ npm install elastic-apm-node --save
 
 [float]
 [[custom-stack-initialization]]
-=== Initialization
+==== Initialization
 
 It's important that the agent is started before you require *any* other modules in your Node.js application - i.e. before `http` and before your router etc.
 
@@ -64,59 +57,26 @@ The agent will now monitor the performance of your application and record any un
 
 [float]
 [[custom-stack-advanced-configuration]]
-==== Advanced configuration
-
-In the above example we initialize the agent by calling the <<apm-start,`start()`>> function.
-This function takes an optional options object used to configure the agent.
-Any option not supplied via the options object can instead be configured using environment variables.
-So if you prefer, you can set the same configuration options using environment variables:
-
-[source,bash]
-----
-ELASTIC_APM_SERVICE_NAME=<service name>
-ELASTIC_APM_SECRET_TOKEN=<token>
-ELASTIC_APM_SERVER_URL=<server url>
-----
-
-And then just start the agent like so:
-
-[source,js]
-----
-// Start the agent before any thing else in your app
-var apm = require('elastic-apm-node').start()
-----
+===== Advanced configuration
 
-See all possible ways to configure the agent <<configuring-the-agent,in the API documentation>>.
+include::./shared-set-up.asciidoc[tag=advanced-configuration]
 
 [float]
 [[custom-stack-full-documentation]]
-==== Full documentation
+===== Full documentation
 
 * <<advanced-setup,Setup and Configuration>>
 * <<api,API Reference>>
 
 [float]
 [[custom-stack-performance-monitoring]]
-=== Performance monitoring
+==== Performance monitoring
 
-Elastic APM automatically measures the performance of your application.
-It records spans for database queries,
-external HTTP requests,
-and other slow operations that happen during requests to your app.
-
-By default, the agent will instrument <<supported-technologies,the most common modules>>.
-To instrument other events,
-you can use custom spans.
-For information about custom spans,
-see the <<custom-spans,Custom Spans section>>.
-
-Spans are grouped in transactions - by default one for each incoming HTTP request.
-But it's possible to create custom transactions not associated with an HTTP request.
-See the <<custom-transactions,Custom Transactions section>> for details.
+include::./shared-set-up.asciidoc[tag=performance-monitoring]
 
 [float]
 [[custom-stack-route-naming]]
-==== Route naming
+===== Route naming
 
 The Node.js agent tracks incoming HTTP requests to your application in what are called "transactions".
 All transactions with the same name are grouped together automatically.
@@ -169,46 +129,19 @@ http.createServer(function (req, res) {
 
 [float]
 [[custom-stack-unknown-routes]]
-==== Unknown routes
+===== Unknown routes
 
-When viewing the performance metrics of your application in Elastic APM,
-you might see some transactions named "unknown route".
-This indicates that the Elastic APM Node.js agent detected an incoming HTTP request to your application,
-but didn't know what to name it.
-
-This might simply be 404 requests,
-which by definition don't match any route,
-or it might be a symptom that the agent wasn't installed correctly.
-Make sure we either support your router or that you <<custom-stack-route-naming,manually name your routes>>.
-If you still can't get any meaningful metrics to show up,
-please follow the <<troubleshooting,Troubleshooting Guide>>.
+include::./shared-set-up.asciidoc[tag=unknown-roots]
 
 [float]
 [[custom-stack-error-logging]]
-=== Error logging
+==== Error logging
 
-By default the Node.js agent will watch for uncaught exceptions and send them to Elastic APM automatically.
-But in most cases errors are not thrown but returned via a callback,
-caught by a promise,
-or simply manually created.
-Those errors will not automatically be sent to Elastic APM.
-To manually send an error to Elastic APM,
-simply call `apm.captureError()` with the error:
-
-[source,js]
-----
-var err = new Error('Ups, something broke!')
-
-apm.captureError(err)
-----
-
-For advanced logging of errors,
-including adding extra metadata to the error,
-see <<apm-capture-error,the API documentation>>.
+include::./shared-set-up.asciidoc[tag=error-logging]
 
 [float]
 [[custom-stack-middleware-error-handler]]
-==== Middleware error handler
+===== Middleware error handler
 
 If you use the https://www.npmjs.com/package/connect[connect] module and an error is either thrown synchronously inside one of the middleware functions or is passed as the first argument to the middleware `next()` function,
 it will be passed to the https://www.npmjs.com/package/connect#error-middleware[Connect error handler].
@@ -240,46 +173,24 @@ app.use(function (err, req, res, next) {
 
 [float]
 [[custom-stack-filter-sensitive-information]]
-=== Filter sensitive information
-
-By default, the Node.js agent will filter common sensitive information before sending errors and metrics to the Elastic APM server.
+==== Filter sensitive information
 
-It's possible for you to tweak these defaults or remove any information you don't want to send to Elastic APM:
-
-* By default the Node.js agent will not log the body of HTTP requests.
-To enable this,
-use the <<capture-body,`captureBody`>> config option
-* By default the Node.js agent will filter certain HTTP headers known to contain sensitive information.
-To disable this,
-use the <<filter-http-headers,`filterHttpHeaders`>> config option
-* To apply custom filters,
-use one of the <<apm-add-filter,filtering>> functions
+include::./shared-set-up.asciidoc[tag=filter-sensitive-info]
 
 [float]
 [[custom-stack-add-your-own-data]]
-=== Add your own data
-
-The Node.js agent will keep track of the active HTTP request and will link it to errors and recorded transaction metrics when they are sent to the Elastic APM server.
-This allows you to see details about which request resulted in a particular error or which requests cause a certain HTTP endpoint to be slow.
-
-But in many cases,
-information about the HTTP request itself isn't enough.
-To add even more metadata to errors and transactions,
-use one of the functions below:
+==== Add your own data
 
-* <<apm-set-user-context,`apm.setUserContext()`>> - Call this to enrich collected performance data and errors with information about the user/client
-* <<apm-set-custom-context,`apm.setCustomContext()`>> - Call this to enrich collected performance data and errors with any information that you think will help you debug performance issues and errors (this data is only stored, but not indexed in Elasticsearch)
-* <<apm-set-label,`apm.setLabel()`>> - Call this to enrich collected performance data and errors with simple key/value strings that you think will help you debug performance issues and errors (labels are indexed in Elasticsearch)
+include::./shared-set-up.asciidoc[tag=add-your-own-data]
 
 [float]
 [[custom-stack-compatibility]]
-=== Compatibility
+==== Compatibility
 
-See the <<supported-technologies,Supported technologies section>> for details.
+include::./shared-set-up.asciidoc[tag=compatibility-link]
 
 [float]
 [[custom-stack-troubleshooting]]
-=== Troubleshooting
+==== Troubleshooting
 
-If you can't get the Node.js agent to work as expected,
-please follow the <<troubleshooting,Troubleshooting Guide>>.
+include::./shared-set-up.asciidoc[tag=troubleshooting-link]

docs/custom-transactions.asciidoc

@@ -5,7 +5,7 @@ NOTE: For the best reading experience,
 please view this documentation at https://www.elastic.co/guide/en/apm/agent/nodejs/current/custom-transactions.html[elastic.co]
 endif::[]
 
-== Custom Transactions
+=== Custom transactions
 
 This is an example of how to use custom transactions.
 For general information about the Elastic APM Node.js Transaction API,