forked from elastic/apm-server
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[Docs] 7.0 Breaking changes, Release highlights, Migration assistant,…
… ECS changes (elastic#1940)
- Loading branch information
1 parent
d5c8f0b
commit c36249e
Showing
11 changed files
with
316 additions
and
132 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| [[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] | ||
| ==== 7.0 | ||
| * Removed deprecated Intake v1 API endpoints. | ||
| Upgrade agents to a version that supports APM Server >= 6.5. | ||
| {apm-overview-ref-v}/breaking-7.7.0-beta1.html#breaking-remove-v1[More information]. | ||
| * Moved fields in Elasticsearch to be compliant with the Elastic Common Schema (ECS). | ||
| {apm-overview-ref-v}/breaking-7.7.0-beta1.html#breaking-ecs[More information and changed fields]. | ||
| * {beats-ref}/breaking-changes-7.0.html[Breaking changes in libbeat] | ||
|
|
||
| [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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,10 +1,6 @@ | ||
| The contextual data describes the environment in which an event is recorded. | ||
| It includes the `service`, the `system` where the service runs, and the `process`. | ||
|
|
||
| It can also contain information about the authenticated `user`. | ||
|
|
||
| An event's context can also include information about an authenticated `user`, a request leading to it, or a response. | ||
| For instance, HTTP requests context have `url`, `cookies`, `body`, `headers`, etc. | ||
|
|
||
| The agents provide some settings for users to capture customized information. This data is stored as not-indexed in a `custom` object. | ||
| Searchable information is stored as `tags` instead. | ||
| * Data about the environment in which the event is recorded: | ||
| ** Service - environment, framework, language, etc. | ||
| ** Host - architecture, hostname, IP, etc. | ||
| ** Process - args, PID, PPID, etc. | ||
| ** URL - full, domain, port, query, etc. | ||
| ** User - (if supplied) email, ID, username, etc. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| [frame="topbot",options="header"] | ||
| |====================== | ||
| |Old Field|New Field | ||
| |`beat.hostname` |`observer.hostname` | ||
| |`beat.name` |`observer.type` | ||
| |`beat.version` |`observer.version` | ||
| |`context.custom` |`error.custom` | ||
| |`context.db.instance` |`span.db.instance` | ||
| |`context.db.statement` |`span.db.statement` | ||
| |`context.db.type` |`span.db.type` | ||
| |`context.db.user` |`span.db.user.name` | ||
| |`context.http.method` |`span.http.method` | ||
| |`context.http.status_code` |`span.http.response.status_code` | ||
| |`context.http.url` |`span.http.url.original` | ||
| |`context.process.argv` |`process.args` | ||
| |`context.process.pid` |`process.pid` | ||
| |`context.process.ppid` |`process.ppid` | ||
| |`context.process.title` |`process.title` | ||
| |`context.request.body` |`http.request.body.original` | ||
| |`context.request.cookies` |`http.request.cookies` | ||
| |`context.request.env` |`http.request.env` | ||
| |`context.request.headers` |`http.request.headers` | ||
| |`context.request.http_version` |`http.version` | ||
| |`context.request.method` |`http.request.method` | ||
| |`context.request.socket` |`http.request.socket` | ||
| |`context.request.url.full` |`url.full` | ||
| |`context.request.url.hash` |`url.fragment` | ||
| |`context.request.url.hostname` |`url.domain` | ||
| |`context.request.url.pathname` |`url.path` | ||
| |`context.request.url.port` |`url.port` | ||
| |`context.request.url.protocol` |`url.scheme` | ||
| |`context.request.url.raw` |`url.original` | ||
| |`context.request.url.search` |`url.query` | ||
| |`context.response.finished` |`http.response.finished` | ||
| |`context.response.headers.content-type` |`http.response.headers.content-type` | ||
| |`context.response.headers_sent` |`http.response.headers_sent` | ||
| |`context.response.status_code` |`http.response.status_code` | ||
| |`context.service.agent.name` |`agent.name` | ||
| |`context.service.agent.version` |`agent.version` | ||
| |`context.service.environment` |`service.environment` | ||
| |`context.service.framework.name` |`service.framework.name` | ||
| |`context.service.framework.version` |`service.framework.version` | ||
| |`context.service.language.name` |`service.language.name` | ||
| |`context.service.language.version` |`service.language.version` | ||
| |`context.service.name` |`service.name` | ||
| |`context.service.runtime.name` |`service.runtime.name` | ||
| |`context.service.runtime.version` |`service.runtime.version` | ||
| |`context.service.version` |`service.version` | ||
| |`context.system.architecture` |`host.architecture` | ||
| |`context.system.hostname` |`host.hostname` | ||
| |`context.system.ip` |`host.ip` | ||
| |`context.system.platform` |`host.os.platform` | ||
| |`context.tags` |`labels` | ||
| |`context.user.email` |`user.email` | ||
| |`context.user.id` |`user.id` | ||
| |`context.user.ip` |`client.ip` | ||
| |`context.user.user-agent` |`user_agent.original` | ||
| |`context.user.username` |`user.name` | ||
| |`listening` |`observer.listening` | ||
| |====================== | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,84 @@ | ||
| [[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-7.7.0-beta1, APM version 7.7.0-beta1>> | ||
| * <<breaking-6.4.0, APM version 6.4.0>> | ||
|
|
||
| Also see <<apm-release-notes>>. | ||
|
|
||
| [[breaking-7.7.0-beta1]] | ||
| === Breaking changes in 7.7.0-beta1 | ||
|
|
||
| APM Server:: | ||
| + | ||
| [[breaking-remove-v1]] | ||
| **Removed deprecated Intake v1 API endpoints.** Before upgrading APM Server, ensure all APM agents are upgraded to a version that supports APM Server >= 6.5. View the <<agent-server-compatibility, agent/server compatibility matrix>> to determine if your agent versions are compatible. | ||
| + | ||
| [[breaking-ecs]] | ||
| **Moved fields in Elasticsearch to be compliant with the Elastic Common Schema (ECS).** | ||
| APM has aligned with the field names defined in the | ||
| https://github.com/elastic/ecs[Elastic Common Schema (ECS)]. | ||
| Utilizing this common schema will allow for easier data correlation within Elasticsearch. | ||
| + | ||
| See the <<ecs-compliance,ECS field changes>> table for full details on which fields have changed. | ||
|
|
||
| APM UI:: | ||
| + | ||
| [[breaking-new-endpoints]] | ||
| **Moved to new data endpoints.**+ | ||
| When you upgrade to 7.x, | ||
| data in indices created prior to 7.0 will not automatically appear in the APM UI. | ||
| We offer a Kibana Migration Assistant (in the Kibana Management section) to help you migrate your data. | ||
| The migration assistant will reindex your older data in the new ECS format. | ||
| Be aware that this is a beta release. | ||
| This script is **not** meant to be run on production data at this stage. | ||
|
|
||
| [float] | ||
| [[ecs-compliance]] | ||
| ==== Elastic Common Schema field changes | ||
|
|
||
| include::../field-name-changes.asciidoc[] | ||
|
|
||
| [[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" | ||
| ------------------------------------------------------------ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.