docs: backport elastic#1940

docs/breaking-changes.asciidoc

@@ -0,0 +1,33 @@
+[[breaking-changes]]
+=== Breaking Changes
+APM Server is built on top of {beats-ref}/index.html[libbeat].
+As such, any breaking change in libbeat is also considered to be a breaking change in APM Server.
+
+[float]
+==== HEAD
+
+[float]
+==== 6.7
+* There are no breaking changes in APM Server.
+
+[float]
+==== 6.6
+* There are no breaking changes in APM Server.
+
+[float]
+==== 6.5
+* There are no breaking changes in APM Server.
+* Advanced users may find the <<upgrading-to-65,upgrading to 6.5 guide>> useful.
+
+[float]
+==== 6.4
+* Indexing the `onboarding` document in it's own index by default.
+
+[float]
+==== 6.3
+* Indexing events in separate indices by default.
+* {beats-ref}/breaking-changes-6.3.html[Breaking changes in libbeat]
+
+[float]
+==== 6.2
+* APM Server GA

docs/guide/apm-breaking-changes.asciidoc

@@ -0,0 +1,50 @@
+[[apm-breaking-changes]]
+== Breaking changes
+
+This section discusses the changes that you need to be aware of when migrating your application from one version of APM to another.
+
+* <<breaking-6.4.0, APM version 6.4.0>>
+
+Also see <<apm-release-notes>>.
+
+[[breaking-6.4.0]]
+=== Breaking changes in 6.4.0
+
+We previously split APM data into separate indices (transaction, span, error, etc.).
+In 6.4 APM Kibana UI starts to leverage those separate indices for queries.
+
+In case you only update Kibana but run an older version of APM Server you will not be able to see any APM data by default.
+To fix this, use the {kibana-ref}/apm-settings-kb.html[Kibana APM settings] to specify the location of the APM index:
+["source","sh"]
+------------------------------------------------------------
+apm_oss.errorIndices: apm-*
+apm_oss.spanIndices: apm-*
+apm_oss.transactionIndices: apm-*
+apm_oss.onboardingIndices: apm-*
+------------------------------------------------------------
+
+In case you are upgrading APM Server from an older version, you might need to refresh your APM index pattern for certain APM UI features to work.
+Also ensure to add the new config options in `apm-server.yml` in case you keep your existing configuration file:
+["source","sh"]
+------------------------------------------------------------
+output.elasticsearch:
+  indices:
+    - index: "apm-%{[observer.version]}-sourcemap"
+      when.contains:
+        processor.event: "sourcemap"
+    - index: "apm-%{[observer.version]}-error-%{+yyyy.MM.dd}"
+      when.contains:
+        processor.event: "error"
+    - index: "apm-%{[observer.version]}-transaction-%{+yyyy.MM.dd}"
+      when.contains:
+        processor.event: "transaction"
+    - index: "apm-%{[observer.version]}-span-%{+yyyy.MM.dd}"
+      when.contains:
+        processor.event: "span"
+    - index: "apm-%{[observer.version]}-metric-%{+yyyy.MM.dd}"
+      when.contains:
+        processor.event: "metric"
+    - index: "apm-%{[observer.version]}-onboarding-%{+yyyy.MM.dd}"
+      when.contains:
+        processor.event: "onboarding"
+------------------------------------------------------------

docs/guide/apm-release-notes.asciidoc

@@ -1,14 +1,41 @@
-[[kibana]]
 [[apm-release-notes]]
-== Release notes
+== Release highlights
+
+This section summarizes the most important APM changes in each release.
+
+For a full list of changes, see the
+{apm-server-ref-v}/release-notes.html[APM Server Release Notes] or the
+{kibana-ref}/release-notes.html[Kibana Release Notes].
+
+* <<release-notes-6.7.0>>
+* <<release-notes-6.6.0>>
+* <<release-notes-6.5.0>>
+* <<release-notes-6.4.1>>
+* <<release-notes-6.4.0>>
+
+[[release-notes-6.7.0]]
+=== APM version 6.7.0
+
+No significant changes.
+
+[[release-notes-6.6.0]]
+=== APM version 6.6.0
 
 [float]
-==== APM version 6.5.0
+==== New features
+
+* Elastic APM agents now automatically record certain <<metrics,infrastructure and application metrics>>.
+* Elastic APM agents support the W3C Trace Context.
+All agents now have <<opentracing,OpenTracing compatible bridges>>.
+* <<distributed-tracing,Distributed tracing>> is generally available.
+
+[[release-notes-6.5.0]]
+=== APM version 6.5.0
 
 [float]
-===== New features
+==== New features
 
-Elastic APM now enables {apm-get-started-ref}/distributed-tracing.html[distributed tracing].
+Elastic APM now enables {apm-overview-ref-v}/distributed-tracing.html[distributed tracing].
 
 *APM Server*
 
@@ -29,8 +56,8 @@ Elastic APM now enables {apm-get-started-ref}/distributed-tracing.html[distribut
 * Python switched to contextvars instead of thread locals for context tracking in Python 3.7
 * Node added support for Restify Framework, dropped support for Node.js 4 and 9
 
-[float]
-==== APM version 6.4.1
+[[release-notes-6.4.1]]
+=== APM version 6.4.1
 
 [float]
 ===== Bug Fixes
@@ -40,50 +67,13 @@ To fix this, the APM Kibana UI now falls back to use `apm-*` as default indices
 Users can still leverage separate indices for queries by overriding the default values described in {kibana-ref}/apm-settings-kb.html[Kibana APM settings].
 
 
-[float]
-==== APM version 6.4.0
+[[release-notes-6.4.0]]
+=== APM version 6.4.0
 
 [float]
 ===== Breaking changes
 
-We previously split APM data into separate indices (transaction, span, error, etc.).
-In 6.4 APM Kibana UI starts to leverage those separate indices for queries.
-
-In case you only update Kibana but run an older version of APM Server you will not be able to see any APM data by default.
-To fix this, use the {kibana-ref}/apm-settings-kb.html[Kibana APM settings] to specify the location of the APM index:
-["source","sh"]
-------------------------------------------------------------
-apm_oss.errorIndices: apm-*
-apm_oss.spanIndices: apm-*
-apm_oss.transactionIndices: apm-*
-apm_oss.onboardingIndices: apm-*
-------------------------------------------------------------
-
-In case you are upgrading APM Server from an older version, you might need to refresh your APM index pattern for certain APM UI features to work.
-Also ensure to add the new config options in `apm-server.yml` in case you keep your existing configuration file:
-["source","sh"]
-------------------------------------------------------------
-output.elasticsearch:
-  indices:
-    - index: "apm-%{[beat.version]}-sourcemap"
-      when.contains:
-        processor.event: "sourcemap"
-    - index: "apm-%{[beat.version]}-error-%{+yyyy.MM.dd}"
-      when.contains:
-        processor.event: "error"
-    - index: "apm-%{[beat.version]}-transaction-%{+yyyy.MM.dd}"
-      when.contains:
-        processor.event: "transaction"
-    - index: "apm-%{[beat.version]}-span-%{+yyyy.MM.dd}"
-      when.contains:
-        processor.event: "span"
-    - index: "apm-%{[beat.version]}-metric-%{+yyyy.MM.dd}"
-      when.contains:
-        processor.event: "metric"
-    - index: "apm-%{[beat.version]}-onboarding-%{+yyyy.MM.dd}"
-      when.contains:
-        processor.event: "onboarding"
-------------------------------------------------------------
+See <<breaking-6.4.0>>.
 
 [float]
 ===== New features

docs/guide/index.asciidoc

@@ -19,6 +19,10 @@ include::./apm-data-model.asciidoc[]
 
 include::./distributed-tracing.asciidoc[]
 
+include::./opentracing.asciidoc[]
+
 include::./agent-server-compatibility.asciidoc[]
 
+include::./apm-breaking-changes.asciidoc[]
+
 include::./apm-release-notes.asciidoc[]

docs/guide/opentracing.asciidoc

@@ -0,0 +1,19 @@
+[[opentracing]]
+== OpenTracing bridge
+
+All Elastic APM agents have https://opentracing.io/[OpenTracing] compatible bridges.
+
+The OpenTracing bridge allows you to create Elastic APM <<transactions,transactions>> and <<transaction-spans,spans>> using the OpenTracing API.
+This means you can reuse your existing OpenTracing instrumentation to quickly and easily begin using Elastic APM.
+
+[float]
+=== Agent specific details
+
+Not all features of the OpenTracing API are supported. In addition, there are some Elastic APM specific tags you should be aware of. Please see the relevant Agent documentation for more detailed information:
+
+* {apm-go-ref}/opentracing.html[Go agent]
+* {apm-java-ref}/opentracing-bridge.html[Java agent]
+* {apm-node-ref}/opentracing.html[Node.js agent]
+* {apm-py-ref}/opentracing-bridge.html[Python agent]
+* {apm-ruby-ref}/opentracing.html[Ruby agent]
+* {apm-rum-ref}/opentracing.html[JavaScript Real User Monitoring (RUM) agent]

docs/release-notes.asciidoc

@@ -8,8 +8,7 @@
 [partintro]
 
 --
-This following section summarizes the changes in each release.
-
+This following sections summarizes the changes in each release.
 
 * <<release-notes-6.7>>
 * <<release-notes-6.6>>

docs/upgrading.asciidoc

@@ -6,50 +6,26 @@ However, check out the <<breaking-changes, breaking changes>> section for except
 
 Before upgrading:
 
-* Review the <<release-notes,release notes>> and the <<breaking-changes, breaking changes>> 
-for changes between your current version and the one you are upgrading to.
-* Check the {stack-ref}/index.html[Elastic Stack Installation and Upgrade Guide] for guidance on how to upgrade your 
- Elastic Stack. 
- For a more tailored upgrade guide, try out the {upgrade_guide}[Interactive Upgrade Guide].
+* Review the APM Server <<release-notes,release notes>> and <<breaking-changes, breaking changes>> 
+for changes between your current APM Server version and the one you are upgrading to.
+* Visit the general APM {apm-overview-ref-v}/apm-release-notes.html[release highlights] and {apm-overview-ref-v}/apm-breaking-changes.html[breaking changes] for highlights and important changes.
+* Check the {stack-ref}/index.html[Elastic Stack Installation and Upgrade Guide] for guidance on how to upgrade your Elastic Stack. 
 
-When ready to actually upgrade your APM Server between minor versions, 
+When you're ready to upgrade your APM Server between minor versions, 
 simply install the new release.
 
-Ensure the configuration file `apm-server.yml` is configured properly again according to your needs.
-Be aware of newly added configuration options and their default settings.
-Also check out the documentation for <<configuring-howto-apm-server, configuration>>
-to read more about available configuration options.
+You'll want to take a look at the `apm-server.yml` configuration file after installing a new release.
+There may be newly added configuration options, and you'll want to be aware of their default settings.
+See <<configuring-howto-apm-server,Configuring APM Server>> for more information on available configuration options.
 
-If you set up index patterns and dashboards manually by running `./apm-server setup`, rerun
-the command to update the index pattern and the dashboards.
+If you set up index patterns and dashboards manually by running `./apm-server setup`,
+rerun the command to update the index pattern and the dashboards.
 
 When everything is properly configured and updated, start the APM server.
 
 When you start the APM server after upgrading, it creates new indices that use the current version,
 and applies the correct template automatically.
 
-[[breaking-changes]]
-=== Breaking Changes
-APM Server is built on top of {beats-ref}/index.html[libbeat].
-As such, any breaking change in libbeat is also considered to be a breaking change in APM Server.
-
-[float]
-==== HEAD 
-* There are no breaking changes in APM Server.
-* Advanced users may find the <<upgrading-to-65,upgrading to 6.5 guide>> useful.
-* https://www.elastic.co/guide/en/beats/libbeat/master/breaking-changes.html[Breaking changes in libbeat]
-
-[float]
-==== 6.4
-* Indexing the `onboarding` document in it's own index by default.
-
-[float]
-==== 6.3
-* Indexing events in separate indices by default.
-* https://www.elastic.co/guide/en/beats/libbeat/current/breaking-changes-6.3.html[Breaking changes in libbeat]
-
-[float]
-==== 6.2
-* APM Server GA
+include::./breaking-changes.asciidoc[]
 
 include::./upgrading-to-65.asciidoc[]