diff --git a/docs/breaking-changes.asciidoc b/docs/breaking-changes.asciidoc new file mode 100644 index 00000000000..a807c2ef4c2 --- /dev/null +++ b/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 <> 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 \ No newline at end of file diff --git a/docs/guide/apm-breaking-changes.asciidoc b/docs/guide/apm-breaking-changes.asciidoc new file mode 100644 index 00000000000..515b5dd23f5 --- /dev/null +++ b/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. + +* <> + +Also see <>. + +[[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" +------------------------------------------------------------ \ No newline at end of file diff --git a/docs/guide/apm-release-notes.asciidoc b/docs/guide/apm-release-notes.asciidoc index 7cff27dfac1..dac2b631b9e 100644 --- a/docs/guide/apm-release-notes.asciidoc +++ b/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]] +=== 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 <>. +* Elastic APM agents support the W3C Trace Context. +All agents now have <>. +* <> 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 <>. [float] ===== New features diff --git a/docs/guide/index.asciidoc b/docs/guide/index.asciidoc index 7ce6c54c619..9d5d8115063 100644 --- a/docs/guide/index.asciidoc +++ b/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[] \ No newline at end of file diff --git a/docs/guide/opentracing.asciidoc b/docs/guide/opentracing.asciidoc new file mode 100644 index 00000000000..a00265d8618 --- /dev/null +++ b/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 <> and <> 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] \ No newline at end of file diff --git a/docs/release-notes.asciidoc b/docs/release-notes.asciidoc index b81a7a56ce1..9d65205fd45 100644 --- a/docs/release-notes.asciidoc +++ b/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. * <> * <> diff --git a/docs/upgrading.asciidoc b/docs/upgrading.asciidoc index 04187d761e6..f42c4bcab88 100644 --- a/docs/upgrading.asciidoc +++ b/docs/upgrading.asciidoc @@ -6,50 +6,26 @@ However, check out the <> section for except Before upgrading: -* Review the <> and the <> -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 <> and <> +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 <> -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 <> 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 <> 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[] \ No newline at end of file