From 9acdf39d4571fc3ba4b1ace2f30b988fc16a02d4 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 2 Oct 2019 13:37:56 -0700 Subject: [PATCH 01/11] docs: initial improvements --- docs/configuration.asciidoc | 6 +-- docs/custom-spans.asciidoc | 2 +- docs/custom-stack.asciidoc | 36 +++++++------- docs/custom-transactions.asciidoc | 2 +- docs/express.asciidoc | 26 +++++------ docs/fastify.asciidoc | 24 +++++----- docs/hapi.asciidoc | 24 +++++----- docs/index.asciidoc | 31 ++++-------- docs/intro.asciidoc | 24 ---------- docs/koa.asciidoc | 24 +++++----- docs/lambda.asciidoc | 18 +++---- docs/opentracing.asciidoc | 8 ++-- docs/redirects.asciidoc | 5 ++ docs/restify.asciidoc | 24 +++++----- docs/set-up.asciidoc | 70 ++++++++++++++++++++++++++++ docs/setup.asciidoc | 39 +++------------- docs/source-maps.asciidoc | 2 +- docs/supported-technologies.asciidoc | 2 +- 18 files changed, 186 insertions(+), 181 deletions(-) create mode 100644 docs/set-up.asciidoc diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc index 0a34d35e43..f2f0e5834d 100644 --- a/docs/configuration.asciidoc +++ b/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]] diff --git a/docs/custom-spans.asciidoc b/docs/custom-spans.asciidoc index f5dfc934d2..4fdc4f4491 100644 --- a/docs/custom-spans.asciidoc +++ b/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, diff --git a/docs/custom-stack.asciidoc b/docs/custom-stack.asciidoc index c8169067c1..1570fa1ddf 100644 --- a/docs/custom-stack.asciidoc +++ b/docs/custom-stack.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-stack.html[elastic.co] endif::[] -== Get started with a custom Node.js stack +=== APM 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. @@ -13,19 +13,15 @@ and there are various ways you can tweak it to fit your needs. If you are using either Express, hapi, Koa, Restify, Fastify, or AWS Lambda we recommend that you read these articles instead: -* <> -* <> -* <> -* <> -* <> -* <> +// This pulls in the "web-frameworks-list" from set-up.asciidoc +include::set-up.asciidoc[tag=web-frameworks-list] For a custom Node.js app, follow the guide below to get started. For more advanced topics, check out the <>. [float] [[custom-stack-installation]] -=== Installation +==== Installation Add the `elastic-apm-node` module as a dependency to your application: @@ -36,7 +32,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,7 +60,7 @@ The agent will now monitor the performance of your application and record any un [float] [[custom-stack-advanced-configuration]] -==== Advanced configuration +===== Advanced configuration In the above example we initialize the agent by calling the <> function. This function takes an optional options object used to configure the agent. @@ -90,14 +86,14 @@ See all possible ways to configure the agent <> * <> [float] [[custom-stack-performance-monitoring]] -=== Performance monitoring +==== Performance monitoring Elastic APM automatically measures the performance of your application. It records spans for database queries, @@ -116,7 +112,7 @@ See the <> for details. [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,7 +165,7 @@ 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". @@ -185,7 +181,7 @@ please follow the <>. [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, @@ -208,7 +204,7 @@ see <>. [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,7 +236,7 @@ app.use(function (err, req, res, next) { [float] [[custom-stack-filter-sensitive-information]] -=== 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. @@ -257,7 +253,7 @@ use one of the <> functions [float] [[custom-stack-add-your-own-data]] -=== 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. @@ -273,13 +269,13 @@ use one of the functions below: [float] [[custom-stack-compatibility]] -=== Compatibility +==== Compatibility See the <> for details. [float] [[custom-stack-troubleshooting]] -=== Troubleshooting +==== Troubleshooting If you can't get the Node.js agent to work as expected, please follow the <>. diff --git a/docs/custom-transactions.asciidoc b/docs/custom-transactions.asciidoc index 7370307a48..b5aba01a34 100644 --- a/docs/custom-transactions.asciidoc +++ b/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, diff --git a/docs/express.asciidoc b/docs/express.asciidoc index 830744ef8d..afe77cc327 100644 --- a/docs/express.asciidoc +++ b/docs/express.asciidoc @@ -5,16 +5,16 @@ NOTE: For the best reading experience, please view this documentation at https://www.elastic.co/guide/en/apm/agent/nodejs/current/express.html[elastic.co] endif::[] -== Get started with Express +=== APM with Express Getting Elastic APM set up for your Express app is easy, and there are various ways you can tweak it to fit your needs. Follow the guide below to get started, and for more advanced topics, -check out the <>. +check out the <>. [float] [[express-installation]] -=== Installation +==== Installation Add the `elastic-apm-node` module as a dependency to your application: @@ -25,7 +25,7 @@ npm install elastic-apm-node --save [float] [[express-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 `express`, `http`, etc. @@ -61,7 +61,7 @@ The agent will now monitor the performance of your Express application and recor [float] [[express-advanced-configuration]] -==== Advanced configuration +===== Advanced configuration In the above example we initialize the agent by calling the <> function. This function takes an optional options object used to configure the agent. @@ -87,14 +87,14 @@ See all possible ways to configure the agent <> * <> [float] [[express-performance-monitoring]] -=== Performance monitoring +==== Performance monitoring Elastic APM automatically measures the performance of your Express application. It records spans for database queries, @@ -113,7 +113,7 @@ See the <> for details. [float] [[express-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". @@ -128,7 +128,7 @@ please follow the <>. [float] [[express-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, @@ -151,7 +151,7 @@ see <>. [float] [[express-filter-sensitive-information]] -=== 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. @@ -168,7 +168,7 @@ use one of the <> functions [float] [[express-add-your-own-data]] -=== 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. @@ -184,13 +184,13 @@ use one of the functions below: [float] [[express-compatibility]] -=== Compatibility +==== Compatibility See the <> for details. [float] [[express-troubleshooting]] -=== Troubleshooting +==== Troubleshooting If you can't get the Node.js agent to work as expected, please follow the <>. diff --git a/docs/fastify.asciidoc b/docs/fastify.asciidoc index 46627effc3..576647ee9d 100644 --- a/docs/fastify.asciidoc +++ b/docs/fastify.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/fastify.html[elastic.co] endif::[] -== Get started with Fastify +=== APM with Fastify Getting Elastic APM set up for your Fastify app is easy, and there are various ways you can tweak it to fit your needs. @@ -15,7 +15,7 @@ check out the <>. [float] [[fastify-installation]] -=== Installation +==== Installation Add the `elastic-apm-node` module as a dependency to your application: @@ -26,7 +26,7 @@ npm install elastic-apm-node --save [float] [[fastify-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 `fastify`, `http`, etc. @@ -70,7 +70,7 @@ The agent will now monitor the performance of your Fastify application and recor [float] [[fastify-advanced-configuration]] -==== Advanced configuration +===== Advanced configuration In the above example we initialize the agent by calling the <> function. This function takes an optional options object used to configure the agent. @@ -96,14 +96,14 @@ See all possible ways to configure the agent <> * <> [float] [[fastify-performance-monitoring]] -=== Performance monitoring +==== Performance monitoring Elastic APM automatically measures the performance of your Fastify application. It records spans for database queries, @@ -122,7 +122,7 @@ See the <> for details. [float] [[fastify-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". @@ -137,7 +137,7 @@ please follow the <>. [float] [[fastify-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, @@ -160,7 +160,7 @@ see <>. [float] [[fastify-filter-sensitive-information]] -=== 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. @@ -177,7 +177,7 @@ use one of the <> functions [float] [[fastify-add-your-own-data]] -=== 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. @@ -193,13 +193,13 @@ use one of the functions below: [float] [[fastify-compatibility]] -=== Compatibility +==== Compatibility See the <> for details. [float] [[fastify-troubleshooting]] -=== Troubleshooting +==== Troubleshooting If you can't get the Node.js agent to work as expected, please follow the <>. diff --git a/docs/hapi.asciidoc b/docs/hapi.asciidoc index 7c03d072a1..0c4fb73864 100644 --- a/docs/hapi.asciidoc +++ b/docs/hapi.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/hapi.html[elastic.co] endif::[] -== Get started with hapi +=== APM with hapi Getting Elastic APM set up for your hapi app is easy, and there are various ways you can tweak it to fit your needs. @@ -14,7 +14,7 @@ check out the <>. [float] [[hapi-installation]] -=== Installation +==== Installation Add the `elastic-apm-node` module as a dependency to your application: @@ -25,7 +25,7 @@ npm install elastic-apm-node --save [float] [[hapi-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 `hapi`, `http`, etc. @@ -72,7 +72,7 @@ The agent will now monitor the performance of your hapi application and record a [float] [[hapi-advanced-configuration]] -==== Advanced configuration +===== Advanced configuration In the above example we initialize the agent by calling the <> function. This function takes an optional options object used to configure the agent. @@ -98,14 +98,14 @@ See all possible ways to configure the agent <> * <> [float] [[hapi-performance-monitoring]] -=== Performance monitoring +==== Performance monitoring Elastic APM automatically measures the performance of your hapi application. It records spans for database queries, @@ -124,7 +124,7 @@ See the <> for details. [float] [[hapi-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". @@ -139,7 +139,7 @@ please follow the <>. [float] [[hapi-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, @@ -162,7 +162,7 @@ see <>. [float] [[hapi-filter-sensitive-information]] -=== 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. @@ -179,7 +179,7 @@ use one of the <> functions [float] [[hapi-add-your-own-data]] -=== 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. @@ -195,13 +195,13 @@ use one of the functions below: [float] [[hapi-compatibility]] -=== Compatibility +==== Compatibility See the <> for details. [float] [[hapi-troubleshooting]] -=== Troubleshooting +==== Troubleshooting If you can't get the Node.js agent to work as expected, please follow the <>. diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 4c97160f2f..c35a979f33 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -1,5 +1,4 @@ -:branch: current -:server-branch: 6.5 +include::{asciidoc-dir}/../../shared/versions/stack/current.asciidoc[] include::{asciidoc-dir}/../../shared/attributes.asciidoc[] :type-string: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type[] @@ -22,42 +21,28 @@ endif::[] include::./intro.asciidoc[] -include::./express.asciidoc[] +include::./set-up.asciidoc[] -include::./hapi.asciidoc[] - -include::./koa.asciidoc[] - -include::./restify.asciidoc[] - -include::./fastify.asciidoc[] - -include::./lambda.asciidoc[] - -include::./custom-stack.asciidoc[] +include::./supported-technologies.asciidoc[] include::./setup.asciidoc[] include::./api.asciidoc[] -include::./custom-transactions.asciidoc[] - -include::./custom-spans.asciidoc[] - include::./metrics.asciidoc[] -include::./performance-tuning.asciidoc[] +include::./opentracing.asciidoc[] + +// Log correlation include will go here include::./source-maps.asciidoc[] -include::./opentracing.asciidoc[] +include::./performance-tuning.asciidoc[] -include::./supported-technologies.asciidoc[] +include::./troubleshooting.asciidoc[] include::./upgrading.asciidoc[] -include::./troubleshooting.asciidoc[] - include::./release-notes.asciidoc[] include::./redirects.asciidoc[] diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc index 2aa2b58b3e..9e1824ddaf 100644 --- a/docs/intro.asciidoc +++ b/docs/intro.asciidoc @@ -7,8 +7,6 @@ endif::[] == Introduction -Welcome to the APM Node.js Agent documentation. - The Elastic APM Node.js Agent sends performance metrics and errors to the APM Server. It has built-in support for the most popular frameworks and routers, as well as a simple API which allows you to instrument any application. @@ -21,25 +19,3 @@ APM Agents work in conjunction with the {apm-server-ref-v}/index.html[APM Server {ref}/index.html[Elasticsearch], and {kibana-ref}/index.html[Kibana]. Please view the {apm-overview-ref-v}/index.html[APM Overview] for details on how these components work together. - -[float] -[[get-started]] -=== Get started - -To get you off the ground, we've prepared guides for the most popular web frameworks: - -* <> -* <> -* <> -* <> -* <> - -Alternatively, you should check out our guide for <>. -To get an overview of which components of your application we instrument automatically, -use the <> page. - -Other useful documentation includes: - -- <> -- <> -- <> diff --git a/docs/koa.asciidoc b/docs/koa.asciidoc index 8595d59347..b62124215f 100644 --- a/docs/koa.asciidoc +++ b/docs/koa.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/koa.html[elastic.co] endif::[] -== Get started with Koa +=== APM with Koa Getting Elastic APM set up for your Koa app is easy, and there are various ways you can tweak it to fit your needs. @@ -22,7 +22,7 @@ In the meantime, you can <> function. This function takes an optional options object used to configure the agent. @@ -100,14 +100,14 @@ See all possible ways to configure the agent <> * <> [float] [[koa-performance-monitoring]] -=== Performance monitoring +==== Performance monitoring Elastic APM automatically measures the performance of your Koa application. It records spans for database queries, @@ -126,7 +126,7 @@ See the <> for details. [float] [[koa-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". @@ -141,7 +141,7 @@ please follow the <>. [float] [[koa-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, @@ -164,7 +164,7 @@ see <>. [float] [[koa-filter-sensitive-information]] -=== 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. @@ -181,7 +181,7 @@ use one of the <> functions [float] [[koa-add-your-own-data]] -=== 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. @@ -197,13 +197,13 @@ use one of the functions below: [float] [[koa-compatibility]] -=== Compatibility +==== Compatibility See the <> for details. [float] [[koa-troubleshooting]] -=== Troubleshooting +==== Troubleshooting If you can't get the Node.js agent to work as expected, please follow the <>. diff --git a/docs/lambda.asciidoc b/docs/lambda.asciidoc index b377b6f327..03dca2c758 100644 --- a/docs/lambda.asciidoc +++ b/docs/lambda.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/lambda.html[elastic.co] endif::[] -== Get started with Lambda +=== APM with Lambda Getting Elastic APM set up for your lambda functions is easy, and there are various ways you can tweak it to fit your needs. @@ -14,7 +14,7 @@ check out the <>. [float] [[lambda-installation]] -=== Installation +==== Installation Add the `elastic-apm-node` module as a dependency to your application: @@ -25,7 +25,7 @@ npm install elastic-apm-node --save [float] [[lambda-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`, etc. @@ -55,14 +55,14 @@ The agent will now monitor the performance of your lambda function. [float] [[lambda-full-documentation]] -==== Full documentation +===== Full documentation * <> * <> [float] [[lambda-performance-monitoring]] -=== Performance monitoring +==== Performance monitoring Elastic APM automatically measures the performance of everything within your lambda function executions. It records traces for database queries, @@ -77,7 +77,7 @@ see the <>. [float] [[lambda-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, @@ -100,7 +100,7 @@ see <>. [float] [[lambda-filter-sensitive-information]] -=== 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. @@ -117,7 +117,7 @@ use one of the <> functions [float] [[lambda-add-your-own-data]] -=== Add your own data +==== Add your own data The Node.js agent will keep track of the active lambda function execution 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 execution resulted in a particular error or which lambda functions are slow. @@ -133,7 +133,7 @@ use one of the two functions below: [float] [[lambda-troubleshooting]] -=== Troubleshooting +==== Troubleshooting If you can't get the Node.js agent to work as expected, please follow the <>. diff --git a/docs/opentracing.asciidoc b/docs/opentracing.asciidoc index 43662c4ece..4ffbafacdb 100644 --- a/docs/opentracing.asciidoc +++ b/docs/opentracing.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/opentracing.html[elastic.co] endif::[] -== OpenTracing support +== OpenTracing API The Elastic APM OpenTracing bridge allows creating Elastic APM transactions and spans, using the https://opentracing-javascript.surge.sh/[OpenTracing API]. @@ -120,11 +120,11 @@ The following tags only have special meaning on the span if the underlying Elast E.g. If the tag value is `200`, the transaction result will be set to `HTTP 2xx` (defaults to `success`) - `user.id` - sets the user id, - appears in the "User" tab in the transaction details in the Elastic APM UI + appears in the "User" tab in the transaction details in the Elastic APM app - `user.email` - sets the user email, - appears in the "User" tab in the transaction details in the Elastic APM UI + appears in the "User" tab in the transaction details in the Elastic APM app - `user.username` - sets the user name, - appears in the "User" tab in the transaction details in the Elastic APM UI + appears in the "User" tab in the transaction details in the Elastic APM app [float] [[ot-caveats]] diff --git a/docs/redirects.asciidoc b/docs/redirects.asciidoc index b365c235e2..d94b2f4ae8 100644 --- a/docs/redirects.asciidoc +++ b/docs/redirects.asciidoc @@ -37,3 +37,8 @@ This endpoint has moved. Please see <>. === `transaction.addTags({ [name]: value })` This endpoint has moved. Please see <>. + +[role="exclude",id="get-started"] +=== Get started + +This page has moved. Please see <>. \ No newline at end of file diff --git a/docs/restify.asciidoc b/docs/restify.asciidoc index 8a531a6ea1..a8649871a5 100644 --- a/docs/restify.asciidoc +++ b/docs/restify.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/restify.html[elastic.co] endif::[] -== Get started with Restify +=== APM with Restify Getting Elastic APM set up for your Restify app is easy, and there are various ways you can tweak it to fit your needs. @@ -14,7 +14,7 @@ check out the <>. [float] [[restify-installation]] -=== Installation +==== Installation Add the `elastic-apm-node` module as a dependency to your application: @@ -25,7 +25,7 @@ npm install elastic-apm-node --save [float] [[restify-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 `restify`, `http`, etc. @@ -64,7 +64,7 @@ The agent will now monitor the performance of your Restify application and recor [float] [[restify-advanced-configuration]] -==== Advanced configuration +===== Advanced configuration In the above example we initialize the agent by calling the <> function. This function takes an optional options object used to configure the agent. @@ -90,14 +90,14 @@ See all possible ways to configure the agent <> * <> [float] [[restify-performance-monitoring]] -=== Performance monitoring +==== Performance monitoring Elastic APM automatically measures the performance of your Restify application. It records spans for database queries, @@ -116,7 +116,7 @@ See the <> for details. [float] [[restify-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". @@ -131,7 +131,7 @@ please follow the <>. [float] [[restify-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, @@ -154,7 +154,7 @@ see <>. [float] [[restify-filter-sensitive-information]] -=== 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. @@ -171,7 +171,7 @@ use one of the <> functions [float] [[restify-add-your-own-data]] -=== 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. @@ -187,13 +187,13 @@ use one of the functions below: [float] [[restify-compatibility]] -=== Compatibility +==== Compatibility See the <> for details. [float] [[restify-troubleshooting]] -=== Troubleshooting +==== Troubleshooting If you can't get the Node.js agent to work as expected, please follow the <>. diff --git a/docs/set-up.asciidoc b/docs/set-up.asciidoc new file mode 100644 index 0000000000..15fcc78bbb --- /dev/null +++ b/docs/set-up.asciidoc @@ -0,0 +1,70 @@ +[[set-up]] +== Set up the Agent + +To get you off the ground, we've prepared guides for setting up the Agent with a few different popular web frameworks: + +// This tagged region is used throughout the documentation to link to the framework guides +// Updates made here will be applied elsewhere as well. +// tag::web-frameworks-list[] +* <> +* <> +* <> +* <> +* <> +* <> +// end::web-frameworks-list[] + +Alternatively, you can <>. +To see an overview of which components of your application we instrument automatically, +use the <> page. + +Other useful documentation includes: + +* <> +* <> +* <> +* <> + +include::./express.asciidoc[] + +include::./hapi.asciidoc[] + +include::./koa.asciidoc[] + +include::./restify.asciidoc[] + +include::./fastify.asciidoc[] + +include::./lambda.asciidoc[] + +include::./custom-stack.asciidoc[] + +[[starting-the-agent]] +=== Starting the agent + +IMPORTANT: The Elastic APM agent for Node.js needs to be started as the first thing in your application - *before any other module is required/imported*. +This means that you should probably require and start it in your applications main file (usually `index.js`, `server.js`, or `app.js`). + +There are two ways to start the Elastic APM agent for Node.js: + +* Require the `elastic-apm-node` module and call the <> function on the returned agent: ++ +[source,js] +---- +var apm = require('elastic-apm-node').start({ + // add configuration options here +}) +---- +* Require the `elastic-apm-node/start` script: ++ +[source,js] +---- +var apm = require('elastic-apm-node/start') +---- ++ +If using this approach, +you can't configure the agent by passing in an options object, +but instead have to rely on <>. + +NOTE: If you are using Babel, you need to use the `elastic-apm-node/start` approach. +<>. \ No newline at end of file diff --git a/docs/setup.asciidoc b/docs/setup.asciidoc index 9455db659b..598d4201d6 100644 --- a/docs/setup.asciidoc +++ b/docs/setup.asciidoc @@ -5,47 +5,16 @@ NOTE: For the best reading experience, please view this documentation at https://www.elastic.co/guide/en/apm/agent/nodejs/current/advanced-setup.html[elastic.co] endif::[] -== Setup and Configuration +== Configuration -The following pages will help you set up and configure your APM Agent. +The following pages will help you configure your APM Agent. -* <> * <> ** <> ** <> * <> * <> -[[starting-the-agent]] -=== Starting the agent - -IMPORTANT: The Elastic APM agent for Node.js needs to be started as the first thing in your application - *before any other module is required/imported*. -This means that you should probably require and start it in your applications main file (usually `index.js`, `server.js`, or `app.js`). - -There are two ways to start the Elastic APM agent for Node.js: - -* Require the `elastic-apm-node` module and call the <> function on the returned agent: -+ -[source,js] ----- -var apm = require('elastic-apm-node').start({ - // add configuration options here -}) ----- -* Require the `elastic-apm-node/start` script: -+ -[source,js] ----- -var apm = require('elastic-apm-node/start') ----- -+ -If using this approach, -you can't configure the agent by passing in an options object, -but instead have to rely on <>. - -NOTE: If you are using Babel, you need to use the `elastic-apm-node/start` approach. -<>. - [[configuring-the-agent]] === Configuring the agent @@ -141,3 +110,7 @@ import * as apm from 'elastic-apm-node/start' ---- include::./configuration.asciidoc[] + +include::./custom-transactions.asciidoc[] + +include::./custom-spans.asciidoc[] diff --git a/docs/source-maps.asciidoc b/docs/source-maps.asciidoc index 920a1e72fe..940afe05aa 100644 --- a/docs/source-maps.asciidoc +++ b/docs/source-maps.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/source-maps.html[elastic.co] endif::[] -== Source Map Support +== Source map support The Elastic APM Node.js agent supports source maps by default. If you transpile your source code and supply a source map, diff --git a/docs/supported-technologies.asciidoc b/docs/supported-technologies.asciidoc index 911f909186..3edc65603a 100644 --- a/docs/supported-technologies.asciidoc +++ b/docs/supported-technologies.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/supported-technologies.html[elastic.co] endif::[] -== Supported Technologies +== Supported technologies Support for the Elastic APM Node.js agent follows the support schedule of Node.js itself to the end-of-life period of each version after its maintenance term. Versions of Node.js past their end-of-life date are not supported. From 87667e517b0d22054f15b7369dd5cfb74166b010 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 2 Oct 2019 13:51:18 -0700 Subject: [PATCH 02/11] docs: add how does the agent work section --- docs/intro.asciidoc | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc index 9e1824ddaf..50f619e3ff 100644 --- a/docs/intro.asciidoc +++ b/docs/intro.asciidoc @@ -11,6 +11,21 @@ The Elastic APM Node.js Agent sends performance metrics and errors to the APM Se It has built-in support for the most popular frameworks and routers, as well as a simple API which allows you to instrument any application. +[float] +[[how-it-works]] +=== How does the Agent work? + +The agent auto-instruments <> and records interesting events, +like HTTP requests and database queries. To do this, it ?? +This means that for the supported technologies, there are no code changes required. + +The Agent automatically ... to measure their duration and metadata (like the DB statement), +as well as HTTP related information (like the URL, parameters, and headers). + +These events, called Transactions and Spans, are sent to the APM Server. +The APM Server converts them to a format suitable for Elasticsearch, and sends them to an Elasticsearch cluster. +You can then use the APM app in Kibana to gain insight into latency issues and error culprits within your application. + [float] [[additional-components]] === Additional Components From cb53aff8c93054378e2f2c5f11e9ee9fb123ff11 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 2 Oct 2019 14:54:20 -0700 Subject: [PATCH 03/11] docs: add log correlation --- docs/agent-api.asciidoc | 7 ++++++- docs/index.asciidoc | 2 +- docs/log-correlation.asciidoc | 22 ++++++++++++++++++++++ 3 files changed, 29 insertions(+), 2 deletions(-) create mode 100644 docs/log-correlation.asciidoc diff --git a/docs/agent-api.asciidoc b/docs/agent-api.asciidoc index 526998bd2b..970d9d9779 100644 --- a/docs/agent-api.asciidoc +++ b/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[] diff --git a/docs/index.asciidoc b/docs/index.asciidoc index c35a979f33..88e748b17c 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -33,7 +33,7 @@ include::./metrics.asciidoc[] include::./opentracing.asciidoc[] -// Log correlation include will go here +include::./log-correlation.asciidoc[] include::./source-maps.asciidoc[] diff --git a/docs/log-correlation.asciidoc b/docs/log-correlation.asciidoc new file mode 100644 index 0000000000..40ab8c0d8b --- /dev/null +++ b/docs/log-correlation.asciidoc @@ -0,0 +1,22 @@ +[[log-correlation]] +== Log correlation + +In order to correlate logs from your app with transactions captured by the +Elastic APM Node.js Agent, your logs must contain one or more of the following identifiers: + +* `transaction.id` +* `trace.id` +* `span.id` + +The Node.js Agent provides the `apm.currentTraceIds` method to help with this task. + +:leveloffset: -1 +include::agent-api.asciidoc[tag=currentTraceIds] +:leveloffset: +1 + +Using your favorite logging framework, you'd then need to inject this information into your logs. + +When your logs contain the appropriate identifiers, the final step is to ingest them into the same +Elasticsearch instance that contains your APM data. See +{apm-overview-ref-v}/observability-integrations.html#_ingest_your_logs_into_elasticsearch[Ingest your logs into Elasticsearch] +for more information. From 575068a62012c6795b88d35131d02ea6f71a94ef Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 2 Oct 2019 15:01:14 -0700 Subject: [PATCH 04/11] docs: update docs/intro.asciidoc Co-Authored-By: Stephen Belanger --- docs/intro.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc index 50f619e3ff..557dd3fee0 100644 --- a/docs/intro.asciidoc +++ b/docs/intro.asciidoc @@ -19,7 +19,7 @@ The agent auto-instruments <> and like HTTP requests and database queries. To do this, it ?? This means that for the supported technologies, there are no code changes required. -The Agent automatically ... to measure their duration and metadata (like the DB statement), +The Agent automatically links module function calls to callback calls to measure their duration and metadata (like the DB statement), as well as HTTP related information (like the URL, parameters, and headers). These events, called Transactions and Spans, are sent to the APM Server. From c979334ba8c3e1796f9677913acf933bd7228e0f Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 2 Oct 2019 15:01:18 -0700 Subject: [PATCH 05/11] docs: update docs/intro.asciidoc Co-Authored-By: Stephen Belanger --- docs/intro.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc index 557dd3fee0..d4b6b7dcc6 100644 --- a/docs/intro.asciidoc +++ b/docs/intro.asciidoc @@ -16,7 +16,7 @@ as well as a simple API which allows you to instrument any application. === How does the Agent work? The agent auto-instruments <> and records interesting events, -like HTTP requests and database queries. To do this, it ?? +like HTTP requests and database queries. To do this, it patches modules as they are loaded to capture when module functions and callbacks are called. Additionally, there are some cases where a module will be patched to allow tracing context to be propagated through the asynchronous continuation. This means that for the supported technologies, there are no code changes required. The Agent automatically links module function calls to callback calls to measure their duration and metadata (like the DB statement), From 155b6c417a76ad6fe85c0881b9a5656cba9e0fce Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 2 Oct 2019 15:10:06 -0700 Subject: [PATCH 06/11] docs: fix formatting of table --- docs/supported-technologies.asciidoc | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/supported-technologies.asciidoc b/docs/supported-technologies.asciidoc index 3edc65603a..1c608cc80b 100644 --- a/docs/supported-technologies.asciidoc +++ b/docs/supported-technologies.asciidoc @@ -37,15 +37,16 @@ These are the frameworks that we officially support: [options="header"] |======================================================================= -|Framework |Version |Note -|<> |^4.0.0 | -|<> |>=9.0.0 <19.0.0 | -|<> |>=17.9.0 <19.0.0 | -|<> via koa-router or @koa/router |>=5.2.0 <9.0.0 |Koa doesn't have a built in router, -so we can't support Koa directly since we rely on router information for full support. -We currently support the most popular Koa router called https://github.com/alexmingoia/koa-router[koa-router] -|<> |>=5.2.0 | -|<> |>=0.27.0 | +|Framework |Version +|<> |^4.0.0 +|<> |>=9.0.0 <19.0.0 +|<> |>=17.9.0 <19.0.0 +|<> via koa-router or @koa/router |>=5.2.0 <9.0.0 +2+|Koa doesn't have a built in router, so we can't support Koa directly since we rely on +router information for full support. We currently support the most popular Koa router called +https://github.com/alexmingoia/koa-router[koa-router]. +|<> |>=5.2.0 +|<> |>=0.27.0 |======================================================================= [float] From 9cd431d37051dc3b1f64555665cf82d1344be15d Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Thu, 3 Oct 2019 11:12:30 -0700 Subject: [PATCH 07/11] docs: remove duplication part 1 --- docs/express.asciidoc | 99 +++---------------------- docs/fastify.asciidoc | 99 +++---------------------- docs/hapi.asciidoc | 99 +++---------------------- docs/koa.asciidoc | 99 +++---------------------- docs/lambda.asciidoc | 37 ++-------- docs/restify.asciidoc | 99 +++---------------------- docs/shared-set-up.asciidoc | 139 ++++++++++++++++++++++++++++++++++++ 7 files changed, 194 insertions(+), 477 deletions(-) create mode 100644 docs/shared-set-up.asciidoc diff --git a/docs/express.asciidoc b/docs/express.asciidoc index afe77cc327..a059512f10 100644 --- a/docs/express.asciidoc +++ b/docs/express.asciidoc @@ -1,3 +1,5 @@ +:framework: Express + [[express]] ifdef::env-github[] @@ -63,27 +65,7 @@ The agent will now monitor the performance of your Express application and recor [[express-advanced-configuration]] ===== Advanced configuration -In the above example we initialize the agent by calling the <> 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= -ELASTIC_APM_SECRET_TOKEN= -ELASTIC_APM_SERVER_URL= ----- - -And then just start the agent like so: - -[source,js] ----- -// Start the agent before any thing else in your app -const apm = require('elastic-apm-node').start() ----- - -See all possible ways to configure the agent <>. +include::./shared-set-up.asciidoc[tag=advanced-configuration] [float] [[express-full-documentation]] @@ -96,101 +78,40 @@ See all possible ways to configure the agent <>. -To instrument other events, -you can use custom spans. -For information about custom spans, -see the <>. - -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 <> for details. +include::./shared-set-up.asciidoc[tag=performance-monitoring] [float] [[express-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 agent detected an incoming HTTP request to your application, -but didn't know which route in your Express app the HTTP request matched. - -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. -If you see this or can't get any meaningful metrics to show up, -please follow the <>. +include::./shared-set-up.asciidoc[tag=unknown-roots] [float] [[express-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 <>. +include::./shared-set-up.asciidoc[tag=error-logging] [float] [[express-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. - -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 <> config option -* By default, the Node.js agent will filter certain HTTP headers known to contain sensitive information. -To disable this, -use the <> config option -* To apply custom filters, -use one of the <> functions +include::./shared-set-up.asciidoc[tag=filter-sensitive-info] [float] [[express-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: - -* <> - Call this to enrich collected performance data and errors with information about the user/client -* <> - 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) -* <> - 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] [[express-compatibility]] ==== Compatibility -See the <> for details. +include::./shared-set-up.asciidoc[tag=compatibility-link] [float] [[express-troubleshooting]] ==== Troubleshooting -If you can't get the Node.js agent to work as expected, -please follow the <>. +include::./shared-set-up.asciidoc[tag=troubleshooting-link] diff --git a/docs/fastify.asciidoc b/docs/fastify.asciidoc index 576647ee9d..4b1e71a8b3 100644 --- a/docs/fastify.asciidoc +++ b/docs/fastify.asciidoc @@ -1,3 +1,5 @@ +:framework: Fastify + [[fastify]] ifdef::env-github[] @@ -72,27 +74,7 @@ The agent will now monitor the performance of your Fastify application and recor [[fastify-advanced-configuration]] ===== Advanced configuration -In the above example we initialize the agent by calling the <> 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= -ELASTIC_APM_SECRET_TOKEN= -ELASTIC_APM_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() ----- - -See all possible ways to configure the agent <>. +include::./shared-set-up.asciidoc[tag=advanced-configuration] [float] [[fastify-full-documentation]] @@ -105,101 +87,40 @@ See all possible ways to configure the agent <>. -To instrument other events, -you can use custom spans. -For information about custom spans, -see the <>. - -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 <> for details. +include::./shared-set-up.asciidoc[tag=performance-monitoring] [float] [[fastify-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 agent detected an incoming HTTP request to your application, -but didn't know which route in your Fastify app the HTTP request matched. - -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. -If you see this or can't get any meaningful metrics to show up, -please follow the <>. +include::./shared-set-up.asciidoc[tag=unknown-roots] [float] [[fastify-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 <>. +include::./shared-set-up.asciidoc[tag=error-logging] [float] [[fastify-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. - -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 <> config option -* By default, the Node.js agent will filter certain HTTP headers known to contain sensitive information. -To disable this, -use the <> config option -* To apply custom filters, -use one of the <> functions +include::./shared-set-up.asciidoc[tag=filter-sensitive-info] [float] [[fastify-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: - -* <> - Call this to enrich collected performance data and errors with information about the user/client -* <> - 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) -* <> - 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] [[fastify-compatibility]] ==== Compatibility -See the <> for details. +include::./shared-set-up.asciidoc[tag=compatibility-link] [float] [[fastify-troubleshooting]] ==== Troubleshooting -If you can't get the Node.js agent to work as expected, -please follow the <>. +include::./shared-set-up.asciidoc[tag=troubleshooting-link] diff --git a/docs/hapi.asciidoc b/docs/hapi.asciidoc index 0c4fb73864..196c57456f 100644 --- a/docs/hapi.asciidoc +++ b/docs/hapi.asciidoc @@ -1,3 +1,5 @@ +:framework: hapi + [[hapi]] ifdef::env-github[] @@ -74,27 +76,7 @@ The agent will now monitor the performance of your hapi application and record a [[hapi-advanced-configuration]] ===== Advanced configuration -In the above example we initialize the agent by calling the <> 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= -ELASTIC_APM_SECRET_TOKEN= -ELASTIC_APM_SERVER_URL= ----- - -And then just start the agent like so: - -[source,js] ----- -// Start the agent before any thing else in your app -const apm = require('elastic-apm-node').start() ----- - -See all possible ways to configure the agent <>. +include::./shared-set-up.asciidoc[tag=advanced-configuration] [float] [[hapi-full-documentation]] @@ -107,101 +89,40 @@ See all possible ways to configure the agent <>. -To instrument other events, -you can use custom spans. -For information about custom spans, -see the <>. - -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 <> for details. +include::./shared-set-up.asciidoc[tag=performance-monitoring] [float] [[hapi-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 agent detected an incoming HTTP request to your application, -but didn't know which route in your hapi app the HTTP request matched. - -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. -If you see this or can't get any meaningful metrics to show up, -please follow the <>. +include::./shared-set-up.asciidoc[tag=unknown-roots] [float] [[hapi-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 <>. +include::./shared-set-up.asciidoc[tag=error-logging] [float] [[hapi-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. - -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 <> config option -* By default, the Node.js agent will filter certain HTTP headers known to contain sensitive information. -To disable this, -use the <> config option -* To apply custom filters, -use one of the <> functions +include::./shared-set-up.asciidoc[tag=filter-sensitive-info] [float] [[hapi-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: - -* <> - Call this to enrich collected performance data and errors with information about the user/client -* <> - 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) -* <> - 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] [[hapi-compatibility]] ==== Compatibility -See the <> for details. +include::./shared-set-up.asciidoc[tag=compatibility-link] [float] [[hapi-troubleshooting]] ==== Troubleshooting -If you can't get the Node.js agent to work as expected, -please follow the <>. +include::./shared-set-up.asciidoc[tag=troubleshooting-link] diff --git a/docs/koa.asciidoc b/docs/koa.asciidoc index b62124215f..06d499d7bd 100644 --- a/docs/koa.asciidoc +++ b/docs/koa.asciidoc @@ -1,3 +1,5 @@ +:framework: Koa + [[koa]] ifdef::env-github[] @@ -76,27 +78,7 @@ The agent will now monitor the performance of your Koa application and record an [[koa-advanced-configuration]] ===== Advanced configuration -In the above example we initialize the agent by calling the <> 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= -ELASTIC_APM_SECRET_TOKEN= -ELASTIC_APM_SERVER_URL= ----- - -And then just start the agent like so: - -[source,js] ----- -// Start the agent before any thing else in your app -const apm = require('elastic-apm-node').start() ----- - -See all possible ways to configure the agent <>. +include::./shared-set-up.asciidoc[tag=advanced-configuration] [float] [[koa-full-documentation]] @@ -109,101 +91,40 @@ See all possible ways to configure the agent <>. -To instrument other events, -you can use custom spans. -For information about custom spans, -see the <>. - -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 <> for details. +include::./shared-set-up.asciidoc[tag=performance-monitoring] [float] [[koa-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 agent detected an incoming HTTP request to your application, -but didn't know which route in your Koa app the HTTP request matched. - -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. -If you see this or can't get any meaningful metrics to show up, -please follow the <>. +include::./shared-set-up.asciidoc[tag=unknown-roots] [float] [[koa-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 <>. +include::./shared-set-up.asciidoc[tag=error-logging] [float] [[koa-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. - -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 <> config option -* By default, the Node.js agent will filter certain HTTP headers known to contain sensitive information. -To disable this, -use the <> config option -* To apply custom filters, -use one of the <> functions +include::./shared-set-up.asciidoc[tag=filter-sensitive-info] [float] [[koa-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: - -* <> - Call this to enrich collected performance data and errors with information about the user/client -* <> - 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) -* <> - 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] [[koa-compatibility]] ==== Compatibility -See the <> for details. +include::./shared-set-up.asciidoc[tag=compatibility-link] [float] [[koa-troubleshooting]] ==== Troubleshooting -If you can't get the Node.js agent to work as expected, -please follow the <>. +include::./shared-set-up.asciidoc[tag=troubleshooting-link] diff --git a/docs/lambda.asciidoc b/docs/lambda.asciidoc index 03dca2c758..dfbc5a1a76 100644 --- a/docs/lambda.asciidoc +++ b/docs/lambda.asciidoc @@ -1,3 +1,5 @@ +:framework: lambda + [[lambda]] ifdef::env-github[] @@ -79,41 +81,13 @@ see the <>. [[lambda-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 <>. +include::./shared-set-up.asciidoc[tag=error-logging] [float] [[lambda-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. - -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 <> config option -* By default, the Node.js agent will filter certain HTTP headers known to contain sensitive information. -To disable this, -use the <> config option -* To apply custom filters, -use one of the <> functions +include::./shared-set-up.asciidoc[tag=filter-sensitive-info] [float] [[lambda-add-your-own-data]] @@ -135,5 +109,4 @@ use one of the two functions below: [[lambda-troubleshooting]] ==== Troubleshooting -If you can't get the Node.js agent to work as expected, -please follow the <>. +include::./shared-set-up.asciidoc[tag=troubleshooting-link] diff --git a/docs/restify.asciidoc b/docs/restify.asciidoc index a8649871a5..9c29e229c6 100644 --- a/docs/restify.asciidoc +++ b/docs/restify.asciidoc @@ -1,3 +1,5 @@ +:framework: Restify + [[restify]] ifdef::env-github[] @@ -66,27 +68,7 @@ The agent will now monitor the performance of your Restify application and recor [[restify-advanced-configuration]] ===== Advanced configuration -In the above example we initialize the agent by calling the <> 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= -ELASTIC_APM_SECRET_TOKEN= -ELASTIC_APM_SERVER_URL= ----- - -And then just start the agent like so: - -[source,js] ----- -// Start the agent before any thing else in your app -const apm = require('elastic-apm-node').start() ----- - -See all possible ways to configure the agent <>. +include::./shared-set-up.asciidoc[tag=advanced-configuration] [float] [[restify-full-documentation]] @@ -99,101 +81,40 @@ See all possible ways to configure the agent <>. -To instrument other events, -you can use custom spans. -For information about custom spans, -see the <>. - -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 <> for details. +include::./shared-set-up.asciidoc[tag=performance-monitoring] [float] [[restify-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 agent detected an incoming HTTP request to your application, -but didn't know which route in your Restify app the HTTP request matched. - -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. -If you see this or can't get any meaningful metrics to show up, -please follow the <>. +include::./shared-set-up.asciidoc[tag=unknown-roots] [float] [[restify-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 <>. +include::./shared-set-up.asciidoc[tag=error-logging] [float] [[restify-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. - -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 <> config option -* By default, the Node.js agent will filter certain HTTP headers known to contain sensitive information. -To disable this, -use the <> config option -* To apply custom filters, -use one of the <> functions +include::./shared-set-up.asciidoc[tag=filter-sensitive-info] [float] [[restify-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: - -* <> - Call this to enrich collected performance data and errors with information about the user/client -* <> - 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) -* <> - 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] [[restify-compatibility]] ==== Compatibility -See the <> for details. +include::./shared-set-up.asciidoc[tag=compatibility-link] [float] [[restify-troubleshooting]] ==== Troubleshooting -If you can't get the Node.js agent to work as expected, -please follow the <>. +include::./shared-set-up.asciidoc[tag=troubleshooting-link] diff --git a/docs/shared-set-up.asciidoc b/docs/shared-set-up.asciidoc new file mode 100644 index 0000000000..451a7e0b3c --- /dev/null +++ b/docs/shared-set-up.asciidoc @@ -0,0 +1,139 @@ +// Content in this file is shared across the Node.js documentation. +// Ensure any changes made here are relevant to all areas where the documentation is included. +// You can search for the tag name to determine where the content is used. +// ----------------------------------------------------------------- + +// Advanced configuration +// tag::advanced-configuration[] +In the above example we initialize the agent by calling the <> 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= +ELASTIC_APM_SECRET_TOKEN= +ELASTIC_APM_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() +---- + +See all possible ways to configure the agent <>. +// end::advanced-configuration[] + +// ----------------------------------------------------------------- + +// Performance monitoring +// tag::performance-monitoring[] +Elastic APM automatically measures the performance of your {framework} application. +It records spans for database queries, +external HTTP requests, +and other slow operations that happen during requests to your {framework} app. + +By default, the agent will instrument <>. +To instrument other events, +you can use custom spans. +For information about custom spans, +see the <>. + +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 <> for details. +// end::performance-monitoring[] + +// ----------------------------------------------------------------- + +// Unknown roots +// tag::unknown-roots[] +When viewing the performance metrics of your application in Elastic APM, +you might see some transactions named "unknown route". +This indicates that the agent detected an incoming HTTP request to your application, +but didn't know which route in your {framework} app the HTTP request matched. + +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. +If you see this or can't get any meaningful metrics to show up, +please follow the <>. +// end::unknown-roots[] + +// ----------------------------------------------------------------- + +// Error logging +// tag::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 <>. +// end::error-logging[] + +// ----------------------------------------------------------------- + +// Filter sensitive information +// tag::filter-sensitive-info[] +By default, the Node.js agent will filter common sensitive information before sending errors and metrics to the Elastic APM server. + +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 <> config option +* By default, the Node.js agent will filter certain HTTP headers known to contain sensitive information. +To disable this, +use the <> config option +* To apply custom filters, +use one of the <> functions +//end::filter-sensitive-info[] + +// ----------------------------------------------------------------- + +// Add your own data +// tag::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: + +* <> - Call this to enrich collected performance data and errors with information about the user/client +* <> - 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) +* <> - 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) +//end::add-your-own-data[] + +// ----------------------------------------------------------------- + +// Compatibility +// tag::compatibility-link[] +See <> for details. +// end::compatibility-link[] + +// ----------------------------------------------------------------- + +// Troubleshooting +// tag::troubleshooting-link[] +If you can't get the Node.js agent to work as expected, +please follow the <>. +// end::troubleshooting-link[] \ No newline at end of file From d84d67e27eb87317e81a07a56b260f8d0d33de44 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Thu, 3 Oct 2019 12:09:50 -0700 Subject: [PATCH 08/11] docs: duplication part 2 --- docs/custom-stack.asciidoc | 109 ++++-------------------------------- docs/hapi.asciidoc | 5 +- docs/koa.asciidoc | 5 +- docs/restify.asciidoc | 5 +- docs/shared-set-up.asciidoc | 9 +++ 5 files changed, 24 insertions(+), 109 deletions(-) diff --git a/docs/custom-stack.asciidoc b/docs/custom-stack.asciidoc index 1570fa1ddf..210895be07 100644 --- a/docs/custom-stack.asciidoc +++ b/docs/custom-stack.asciidoc @@ -1,3 +1,5 @@ +:framework: custom Node.js + [[custom-stack]] ifdef::env-github[] @@ -7,18 +9,13 @@ endif::[] === APM 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: -// This pulls in the "web-frameworks-list" from set-up.asciidoc include::set-up.asciidoc[tag=web-frameworks-list] -For a custom Node.js app, follow the guide below to get started. -For more advanced topics, check out the <>. - [float] [[custom-stack-installation]] ==== Installation @@ -62,27 +59,7 @@ The agent will now monitor the performance of your application and record any un [[custom-stack-advanced-configuration]] ===== Advanced configuration -In the above example we initialize the agent by calling the <> 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= -ELASTIC_APM_SECRET_TOKEN= -ELASTIC_APM_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() ----- - -See all possible ways to configure the agent <>. +include::./shared-set-up.asciidoc[tag=advanced-configuration] [float] [[custom-stack-full-documentation]] @@ -95,20 +72,7 @@ See all possible ways to configure the agent <>. -To instrument other events, -you can use custom spans. -For information about custom spans, -see the <>. - -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 <> for details. +include::./shared-set-up.asciidoc[tag=performance-monitoring] [float] [[custom-stack-route-naming]] @@ -167,40 +131,13 @@ http.createServer(function (req, res) { [[custom-stack-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 <>. -If you still can't get any meaningful metrics to show up, -please follow the <>. +include::./shared-set-up.asciidoc[tag=unknown-roots] [float] [[custom-stack-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 <>. +include::./shared-set-up.asciidoc[tag=error-logging] [float] [[custom-stack-middleware-error-handler]] @@ -238,44 +175,22 @@ app.use(function (err, req, res, next) { [[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. - -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 <> config option -* By default the Node.js agent will filter certain HTTP headers known to contain sensitive information. -To disable this, -use the <> config option -* To apply custom filters, -use one of the <> 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: - -* <> - Call this to enrich collected performance data and errors with information about the user/client -* <> - 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) -* <> - 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 -See the <> for details. +include::./shared-set-up.asciidoc[tag=compatibility-link] [float] [[custom-stack-troubleshooting]] ==== Troubleshooting -If you can't get the Node.js agent to work as expected, -please follow the <>. +include::./shared-set-up.asciidoc[tag=troubleshooting-link] diff --git a/docs/hapi.asciidoc b/docs/hapi.asciidoc index 196c57456f..b2604b8074 100644 --- a/docs/hapi.asciidoc +++ b/docs/hapi.asciidoc @@ -9,10 +9,7 @@ endif::[] === APM with hapi -Getting Elastic APM set up for your hapi app is easy, -and there are various ways you can tweak it to fit your needs. -Follow the guide below to get started, and for more advanced topics, -check out the <>. +include::./shared-set-up.asciidoc[tag=introduction] [float] [[hapi-installation]] diff --git a/docs/koa.asciidoc b/docs/koa.asciidoc index 06d499d7bd..c73c19c05c 100644 --- a/docs/koa.asciidoc +++ b/docs/koa.asciidoc @@ -9,10 +9,7 @@ endif::[] === APM with Koa -Getting Elastic APM set up for your Koa app is easy, -and there are various ways you can tweak it to fit your needs. -Follow the guide below to get started, and for more advanced topics, -check out the <>. +include::./shared-set-up.asciidoc[tag=introduction] Koa doesn't have a built-in router, so we can't support Koa directly since we rely on router information for full support. diff --git a/docs/restify.asciidoc b/docs/restify.asciidoc index 9c29e229c6..451bed6b12 100644 --- a/docs/restify.asciidoc +++ b/docs/restify.asciidoc @@ -9,10 +9,7 @@ endif::[] === APM with Restify -Getting Elastic APM set up for your Restify app is easy, -and there are various ways you can tweak it to fit your needs. -Follow the guide below to get started, and for more advanced topics, -check out the <>. +include::./shared-set-up.asciidoc[tag=introduction] [float] [[restify-installation]] diff --git a/docs/shared-set-up.asciidoc b/docs/shared-set-up.asciidoc index 451a7e0b3c..dcde1dae63 100644 --- a/docs/shared-set-up.asciidoc +++ b/docs/shared-set-up.asciidoc @@ -3,6 +3,15 @@ // You can search for the tag name to determine where the content is used. // ----------------------------------------------------------------- +// tag::introduction[] +Getting Elastic APM set up for your {framework} app is easy, +and there are various ways you can tweak it to fit your needs. +Follow the guide below to get started, and for more advanced topics, +check out the <>. +// end::introduction[] + +// ----------------------------------------------------------------- + // Advanced configuration // tag::advanced-configuration[] In the above example we initialize the agent by calling the <> function. From ba6d24e6c3cfc83bf3c15c92d418e7563f3880a7 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Thu, 3 Oct 2019 12:11:32 -0700 Subject: [PATCH 09/11] docs: get started --- docs/custom-stack.asciidoc | 2 +- docs/express.asciidoc | 2 +- docs/fastify.asciidoc | 2 +- docs/hapi.asciidoc | 2 +- docs/koa.asciidoc | 2 +- docs/lambda.asciidoc | 2 +- docs/restify.asciidoc | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/custom-stack.asciidoc b/docs/custom-stack.asciidoc index 210895be07..67f14f6543 100644 --- a/docs/custom-stack.asciidoc +++ b/docs/custom-stack.asciidoc @@ -7,7 +7,7 @@ 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::[] -=== APM with a custom Node.js stack +=== Get started with a custom Node.js stack include::./shared-set-up.asciidoc[tag=introduction] diff --git a/docs/express.asciidoc b/docs/express.asciidoc index a059512f10..caf9466c76 100644 --- a/docs/express.asciidoc +++ b/docs/express.asciidoc @@ -7,7 +7,7 @@ NOTE: For the best reading experience, please view this documentation at https://www.elastic.co/guide/en/apm/agent/nodejs/current/express.html[elastic.co] endif::[] -=== APM with Express +=== Get started with Express Getting Elastic APM set up for your Express app is easy, and there are various ways you can tweak it to fit your needs. diff --git a/docs/fastify.asciidoc b/docs/fastify.asciidoc index 4b1e71a8b3..cf9e4b00f9 100644 --- a/docs/fastify.asciidoc +++ b/docs/fastify.asciidoc @@ -7,7 +7,7 @@ NOTE: For the best reading experience, please view this documentation at https://www.elastic.co/guide/en/apm/agent/nodejs/current/fastify.html[elastic.co] endif::[] -=== APM with Fastify +=== Get started with Fastify Getting Elastic APM set up for your Fastify app is easy, and there are various ways you can tweak it to fit your needs. diff --git a/docs/hapi.asciidoc b/docs/hapi.asciidoc index b2604b8074..e236518ee1 100644 --- a/docs/hapi.asciidoc +++ b/docs/hapi.asciidoc @@ -7,7 +7,7 @@ NOTE: For the best reading experience, please view this documentation at https://www.elastic.co/guide/en/apm/agent/nodejs/current/hapi.html[elastic.co] endif::[] -=== APM with hapi +=== Get started with hapi include::./shared-set-up.asciidoc[tag=introduction] diff --git a/docs/koa.asciidoc b/docs/koa.asciidoc index c73c19c05c..7779435b5e 100644 --- a/docs/koa.asciidoc +++ b/docs/koa.asciidoc @@ -7,7 +7,7 @@ NOTE: For the best reading experience, please view this documentation at https://www.elastic.co/guide/en/apm/agent/nodejs/current/koa.html[elastic.co] endif::[] -=== APM with Koa +=== Get started with Koa include::./shared-set-up.asciidoc[tag=introduction] diff --git a/docs/lambda.asciidoc b/docs/lambda.asciidoc index dfbc5a1a76..4a05e873b9 100644 --- a/docs/lambda.asciidoc +++ b/docs/lambda.asciidoc @@ -7,7 +7,7 @@ NOTE: For the best reading experience, please view this documentation at https://www.elastic.co/guide/en/apm/agent/nodejs/current/lambda.html[elastic.co] endif::[] -=== APM with Lambda +=== Get started with Lambda Getting Elastic APM set up for your lambda functions is easy, and there are various ways you can tweak it to fit your needs. diff --git a/docs/restify.asciidoc b/docs/restify.asciidoc index 451bed6b12..d5d5065f46 100644 --- a/docs/restify.asciidoc +++ b/docs/restify.asciidoc @@ -7,7 +7,7 @@ NOTE: For the best reading experience, please view this documentation at https://www.elastic.co/guide/en/apm/agent/nodejs/current/restify.html[elastic.co] endif::[] -=== APM with Restify +=== Get started with Restify include::./shared-set-up.asciidoc[tag=introduction] From a9a5be6597bb9131eb14dba5d9b70c124c2e2324 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Mon, 7 Oct 2019 10:36:35 -0700 Subject: [PATCH 10/11] docs: add link to APM Agent config --- docs/configuration.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc index f2f0e5834d..217da7b56b 100644 --- a/docs/configuration.asciidoc +++ b/docs/configuration.asciidoc @@ -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 {apm-overview-ref-v}/agent-configuration.html[APM Agent configuration]. [[async-hooks]] ==== `asyncHooks` From aee9d6437ffd5c2126ef196fdd673789826b45ea Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Mon, 7 Oct 2019 18:56:13 -0700 Subject: [PATCH 11/11] docs: fix doc build --- docs/configuration.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc index 217da7b56b..710ca6fce1 100644 --- a/docs/configuration.asciidoc +++ b/docs/configuration.asciidoc @@ -146,7 +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 {apm-overview-ref-v}/agent-configuration.html[APM Agent configuration]. +More information is available in {kibana-ref}/agent-configuration.html[APM Agent configuration]. [[async-hooks]] ==== `asyncHooks`