docs: APM integration documentation (#6287)

docs/apm-breaking.asciidoc

@@ -0,0 +1,151 @@
+:issue: https://github.com/elastic/apm-server/issues/
+:pull: https://github.com/elastic/apm-server/pull/
+
+[[apm-breaking]]
+== Breaking Changes
+
+// todo: integration APM Server release notes
+// (which might mean removing this entirely, or more likely, adding this content to headings in those notes)
+// fix all broken links once a new attribute is added
+
+[float]
+[[breaking-changes-7.15]]
+=== 7.15
+
+The following breaking changes were introduced in 7.15:
+
+- `network.connection_type` is now `network.connection.type` {pull}5671[5671]
+- `transaction.page` and `error.page` no longer recorded {pull}5872[5872]
+- experimental:["This breaking change applies to the experimental tail-based sampling feature."] `apm-server.sampling.tail` now requires `apm-server.data_streams.enabled` {pull}5952[5952]
+- beta:["This breaking change applies to the beta APM integration."] The `traces-sampled-*` data stream is now `traces-apm.sampled-*` {pull}5952[5952]
+
+[float]
+[[breaking-changes-7.14]]
+=== 7.14
+There are no breaking changes in APM Server.
+
+[float]
+[[breaking-changes-7.13]]
+=== 7.13
+There are no breaking changes in APM Server.
+
+[float]
+[[breaking-changes-7.12]]
+=== 7.12
+
+There are three breaking changes to be aware of;
+these changes only impact users ingesting data with
+// {apm-server-ref-v}/jaeger.html[Jaeger clients].
+
+* Leading 0s are no longer removed from Jaeger client trace/span ids.
++
+--
+This change ensures distributed tracing continues to work across platforms by creating
+consistent, full trace/span IDs from Jaeger clients, Elastic APM agents,
+and OpenTelemetry SDKs.
+--
+
+* Jaeger spans will now have a type of "app" where they previously were "custom".
++
+--
+If the Jaeger span type is not inferred, it will now be "app".
+This aligns with the OpenTelemetry Collector exporter
+and improves the functionality of the _time spent by span type_ charts in the APM app.
+--
+
+* Jaeger spans may now have a more accurate outcome of "unknown".
++
+--
+Previously, a "success" outcome was assumed when a span didn't fail.
+The new default assigns "unknown", and only sets an outcome of "success" or "failure" when
+the outcome is explicitly known.
+This change aligns with Elastic APM agents and the OpenTelemetry Collector exporter.
+--
+
+[float]
+[[breaking-changes-7.11]]
+=== 7.11
+There are no breaking changes in APM Server.
+
+[float]
+[[breaking-changes-7.10]]
+=== 7.10
+There are no breaking changes in APM Server.
+
+[float]
+[[breaking-changes-7.9]]
+=== 7.9
+There are no breaking changes in APM Server.
+
+[float]
+[[breaking-changes-7.8]]
+=== 7.8
+There are no breaking changes in APM Server.
+
+[float]
+[[breaking-changes-7.7]]
+=== 7.7
+There are no breaking changes in APM Server.
+However, a previously hardcoded feature is now configurable.
+// Failing to follow these <<upgrading-to-77,upgrade steps>> will result in increased span metadata ingestion when upgrading to version 7.7.
+
+[float]
+[[breaking-changes-7.6]]
+=== 7.6
+There are no breaking changes in APM Server.
+
+[float]
+[[breaking-changes-7.5]]
+=== 7.5
+The following breaking changes have been introduced in 7.5:
+
+* Introduced dedicated `apm-server.ilm.setup.*` flags.
+This means you can now customize ILM behavior from within the APM Server configuration.
+As a side effect, `setup.template.*` settings will be ignored for ILM related templates per event type.
+// See {apm-server-ref}/ilm.html#ilm-setup[set up ILM] for more information.
+
+* By default, ILM policies will not longer be versioned.
+All event types will switch to the new default policy: rollover after 30 days or when reaching a size 50gb.
+// See {apm-server-ref}/ilm.html[default policy] for more information.
+
+* To make use of all the new features introduced in 7.5,
+you must ensure you are using version 7.5+ of APM Server and version 7.5+ of Kibana.
+
+[float]
+[[breaking-changes-7.0]]
+=== 7.0
+The following breaking changes have been introduced in 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.0.0.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.0.0.html#breaking-ecs[More information and changed fields].
+// * {beats-ref}/breaking-changes-7.0.html[Breaking changes in libbeat]
+
+[float]
+[[breaking-changes-6.5]]
+=== 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]
+[[breaking-changes-6.4]]
+=== 6.4
+The following breaking changes have been introduced in 6.4:
+
+* Indexing the `onboarding` document in it's own index by default.
+
+[float]
+[[breaking-changes-6.3]]
+=== 6.3
+The following breaking changes have been introduced in 6.3:
+
+* Indexing events in separate indices by default.
+// * {beats-ref-63}/breaking-changes-6.3.html[Breaking changes in libbeat]
+
+[float]
+[[breaking-changes-6.2]]
+=== 6.2
+
+APM Server is now GA (generally available).

docs/apm-components.asciidoc

@@ -0,0 +1,64 @@
+[[apm-components]]
+=== Components and documentation
+
+Elastic APM consists of four components: *APM agents*, *Elastic Agent*, *Elasticsearch*, and *Kibana*.
+
+image::./images/apm-architecture.png[Architecture of Elastic APM]
+
+[float]
+==== APM Agents
+
+APM agents are open source libraries written in the same language as your service.
+You may only need one, or you might use all of them.
+You install them into your service as you would install any other library.
+They instrument your code and collect performance data and errors at runtime.
+This data is buffered for a short period and sent on to APM Server.
+
+Each agent has its own documentation:
+
+* {apm-go-ref-v}/introduction.html[Go agent]
+* {apm-ios-ref-v}/intro.html[iOS agent]
+* {apm-java-ref-v}/intro.html[Java agent]
+* {apm-dotnet-ref-v}/intro.html[.NET agent]
+* {apm-node-ref-v}/intro.html[Node.js agent]
+* {apm-php-ref-v}/intro.html[PHP agent]
+* {apm-py-ref-v}/getting-started.html[Python agent]
+* {apm-ruby-ref-v}/introduction.html[Ruby agent]
+* {apm-rum-ref-v}/intro.html[JavaScript Real User Monitoring (RUM) agent]
+
+[float]
+==== Elastic Agent
+
+Elastic Agent is a single, unified way to add monitoring for logs, metrics, traces, and other types of data to each host.
+A single agent makes it easier and faster to deploy monitoring across your infrastructure.
+The agent’s single, unified policy makes it easier to add integrations for new data sources.
+
+The APM integration within Elastic Agent receives performance data from your APM agents,
+validates and processes it, and then transforms the data into {es} documents.
+Removing this logic from APM agents help keeps them light, prevents certain security risks,
+and improves compatibility across the Elastic Stack.
+
+[float]
+==== Elasticsearch
+
+{ref}/index.html[Elasticsearch] is a highly scalable free and open full-text search and analytics engine.
+It allows you to store, search, and analyze large volumes of data quickly and in near real time.
+Elasticsearch is used to store APM performance metrics and make use of its aggregations.
+
+[float]
+==== Kibana APM app
+
+{kibana-ref}/index.html[Kibana] is a free and open analytics and visualization platform designed to work with Elasticsearch.
+You use Kibana to search, view, and interact with data stored in Elasticsearch.
+
+Since application performance monitoring is all about visualizing data and detecting bottlenecks,
+it's crucial you understand how to use the {kibana-ref}/xpack-apm.html[APM app] in Kibana.
+The following sections will help you get started:
+
+* {apm-app-ref}/apm-ui.html[Set up]
+* {apm-app-ref}/apm-getting-started.html[Get started]
+* {apm-app-ref}/apm-how-to.html[How-to guides]
+
+APM also has built-in integrations with Machine learning. To learn more about this feature,
+or the anomaly detection feature that's built on top of it,
+refer to {kibana-ref}/machine-learning-integration.html[Machine learning integration].