docs: add v2 upgrade guide (elastic#631)

docs/upgrade-to-v2.asciidoc

@@ -0,0 +1,94 @@
+[[upgrade-to-v2]]
+
+ifdef::env-github[]
+NOTE: For the best reading experience,
+please view this documentation at https://www.elastic.co/guide/en/apm/agent/nodejs/current/upgrade-to-v2.html[elastic.co]
+endif::[]
+
+=== Upgrade to v2.x
+
+The following is a guide on upgrading your Node.js agent from version 1.x to version 2.x.
+
+[[v2-overview]]
+==== Overview
+
+Version 2.0.0 of the Node.js agent requires version 6.5 of the APM Server or higher and makes use of the new HTTP intake API.
+
+The new agent supports Node.js 6, 8, and 10+.
+
+The format of the error ID's have changed from a UUID4 to a hex formatted random 128 bit number.
+Likewise,
+the format of the transaction ID's have changed from a UUID4 to a hex formatted random 64 bit number.
+
+[[v2-config-options]]
+==== Config options
+
+[[v2-configuration-order]]
+===== Configuration order
+
+The Node.js agent can be configured using a combination of inline config options,
+environment variables,
+and a config file.
+Many config options also have default values.
+The order in which all these are applied have changed in 2.0.0.
+
+In 1.x the order in which config options overruled each other was (higher overwrite lower):
+
+- Inline options given to <<apm-start,`.start()`>>
+- <<agent-configuration-file,Agent config file>>
+- Environment variables
+- Default values
+
+The new order in 2.0.0 is as follows (higher overwrite lower):
+
+- Environment variables
+- Inline options given to <<apm-start,`.start()`>>
+- <<agent-configuration-file,Agent config file>>
+- Default values
+
+[[v2-changed-units]]
+===== Changed units
+
+In 1.x,
+the config option <<aborted-error-threshold,`abortedErrorThreshold`>> expected a millisecond value.
+In 2.0.0 the default time unit is seconds.
+If you'd like to keep using milliseconds,
+you need to specify the unit,
+e.g: `1500ms`.
+
+In 1.x,
+all boolean config options could be configured using the strings `on`,
+`yes`,
+`1` etc to mean `true` with similar values representing `false`.
+In 2.0.0 this has been restricted,
+and only the strings `true` and `false` will be interpreted as the boolean equivalent.
+
+[[v2-removed-config-options]]
+===== Removed config options
+
+The following config options have been removed in version 2.0.0:
+
+|=======================================================================
+|Name |Note
+|`flushInterval` |Use <<api-request-time,`apiRequestTime`>> instead. Note that this option has a slightly different meaning as the intake API has changed.
+|`maxQueueSize` |Use <<api-request-size,`apiRequestSize`>> instead. Note that this option has a slightly different meaning as the intake API has changed.
+|=======================================================================
+
+[[v2-agent-api]]
+==== Agent API
+
+The <<apm-add-filter,`agent.addFilter()`>> callback is called with a different payload in 2.0.0 (see docs for details).
+
+[NOTE]
+====
+While the `addFilter()` function is still called for all types of data sent to the APM Server,
+three new filter functions have been added in 2.0.0 as well:
+<<apm-add-error-filter,`agent.addErrorFilter()`>>,
+<<apm-add-transaction-filter,`agent.addTransactionFilter()`>>,
+and <<apm-add-span-filter,`agent.addSpanFilter()`>>,
+called only for errors,
+transactions,
+and spans respectively.
+====
+
+The previously undocumented method `span.offsetTime()` has been removed in 2.0.0.

docs/upgrading.asciidoc

@@ -10,5 +10,8 @@ endif::[]
 The following upgrade guides are available:
 
 * <<upgrade-to-v1,Upgrade to v1.x>> - Follow this guide to upgrade from version 0.x to version 1.x of the Elastic APM Node.js agent
+* <<upgrade-to-v2,Upgrade to v2.x>> - Follow this guide to upgrade from version 1.x to version 2.x of the Elastic APM Node.js agent
 
 include::./upgrade-to-v1.asciidoc[Upgrade to v1.x]
+
+include::./upgrade-to-v2.asciidoc[Upgrade to v2.x]