Add content to APM User guide

docs/apm-package/apm-integration.asciidoc

@@ -108,13 +108,9 @@ In the future, we may align with Elastic Stack versioning.
 [[apm-integration-learn-more]]
 === Learn more
 
-// to do: update these links
-* <<input-apm>>
 * <<apm-integration-data-streams>>
 * {fleet-guide}/fleet-overview.html[Fleet overview]
 
 include::./data-streams.asciidoc[]
 
-include::./input-apm.asciidoc[]
-
 include::./configure.asciidoc[]

docs/apm-quick-start.asciidoc

@@ -0,0 +1,11 @@
+[[apm-quick-start]]
+== Quick start
+
+// to do: Include quick start file from obs-docs repo
+
+// Considerations:
+
+// * Point to EA APT/YUM
+// * Point to EA for running on Docker
+// * Point to EA for directory layout
+// * Point to EA for systemd

docs/apm-tune-elasticsearch.asciidoc

@@ -0,0 +1,22 @@
+[[apm-tune-elasticsearch]]
+=== Tune {es} for data ingestion
+
+++++
+<titleabbrev>Tune {es}</titleabbrev>
+++++
+
+The {es} Reference provides insight on tuning {es}.
+
+{ref}/tune-for-indexing-speed.html[Tune for indexing speed] provides information on:
+
+* Refresh interval
+* Disabling swapping
+* Optimizing filesystem cache
+* Considerations regarding faster hardware
+* Setting the indexing buffer size
+
+{ref}/tune-for-disk-usage.html[Tune for disk usage] provides information on:
+
+* Disabling unneeded features
+* Shard size
+* Shrink index

docs/data-streams.asciidoc

@@ -0,0 +1,4 @@
+[[apm-data-streams]]
+== Data streams
+
+// to do: fill with content. placeholder for external links for now

docs/how-to.asciidoc

@@ -0,0 +1,23 @@
+[[how-to-guides]]
+== How-to guides
+
+Learn how to perform common APM configuration and management tasks.
+
+* <<source-map-how-to>>
+* <<ilm-how-to>>
+* <<jaeger-integration>>
+* <<ingest-pipelines>>
+* <<manage-storage>>
+* <<apm-tune-elasticsearch>>
+
+include::./source-map-how-to.asciidoc[]
+
+include::./ilm-how-to.asciidoc[]
+
+include::./jaeger-integration.asciidoc[]
+
+include::./ingest-pipelines.asciidoc[]
+
+include::./manage-storage.asciidoc[]
+
+include::./apm-tune-elasticsearch.asciidoc[]

docs/ilm-how-to.asciidoc

@@ -0,0 +1,18 @@
+[[ilm-how-to]]
+=== Index lifecycle management (ILM)
+
+// todo: add more context and an example
+
+++++
+<titleabbrev>Customize index lifecycle management</titleabbrev>
+++++
+
+The index lifecycle management (ILM) feature in {es} allows you to automate the
+lifecycle of your APM Server indices as they grow and age.
+ILM is enabled by default, and a default policy is applied to all APM indices.
+
+To view and edit these index lifecycle policies in {kib},
+select *Stack Management* / *Index Lifecycle Management*.
+Search for `apm`.
+
+See {ref}/getting-started-index-lifecycle-management.html[manage the index lifecycle] for more information.

docs/ingest-pipelines.asciidoc

@@ -0,0 +1,21 @@
+[[ingest-pipelines]]
+=== Parse data using ingest pipelines
+
+The APM integration loads default ingest node pipelines into {es}.
+These pipelines preprocess and enrich APM documents before indexing them.
+For example, a pipeline might define one processor that removes a field, and another that renames a field.
+
+Pipelines can be used to ensure data security by removing or obfuscating sensitive information.
+See <<apm-data-security,data security>> for an example.
+
+[float]
+[[view-edit-default-pipelines]]
+=== View or edit a default pipeline
+
+To view or edit a default pipelines in {kib},
+select *Stack Management* / *Index Node Pipelines*.
+Search for `apm`.
+
+See {ref}/ingest.html[ingest node pipelines] for more information.
+
+// to do: add more information including an example

docs/integrations-index.asciidoc

@@ -7,22 +7,32 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 [[apm-user-guide]]
 = APM User Guide
 
+IMPORTANT: You are looking at preliminary documentation for a future release. For current documentation, see the
+https://www.elastic.co/guide/en/apm/get-started/current/index.html[APM Overview] or
+https://www.elastic.co/guide/en/apm/server/current/index.html[APM Server Reference].
+
 include::apm-overview.asciidoc[]
 
 include::apm-components.asciidoc[]
 
-== Quick start
-
-Include quick start file from obs-docs repo
+include::apm-quick-start.asciidoc[]
 
 include::data-model.asciidoc[]
 
 include::features.asciidoc[]
 
+include::how-to.asciidoc[]
+
+include::input-apm.asciidoc[]
+
+include::data-streams.asciidoc[]
+
 include::troubleshoot-apm.asciidoc[]
 
 include::apm-breaking.asciidoc[]
 
+include::upgrade.asciidoc[]
+
 // This includes the legacy APM Overview
 include::legacy/guide/index.asciidoc[]
 

docs/jaeger-integration.asciidoc

@@ -0,0 +1,112 @@
+[[jaeger-integration]]
+=== Jaeger integration
+
+++++
+<titleabbrev>Integrate with Jaeger</titleabbrev>
+++++
+
+Elastic APM integrates with https://www.jaegertracing.io/[Jaeger], an open-source, distributed tracing system.
+This integration allows users with an existing Jaeger setup to switch from the default Jaeger backend,
+to the Elastic Stack.
+Best of all, no instrumentation changes are needed in your application code.
+
+[float]
+[[jaeger-architecture]]
+=== Supported architecture
+
+Jaeger architecture supports different data formats and transport protocols
+that define how data can be sent to a collector. Elastic APM, as a Jaeger collector,
+supports communication with *Jaeger agents* via gRPC.
+
+* The APM integration serves Jaeger gRPC over the same host and port as the Elastic APM agent protocol.
+
+* The APM integration gRPC endpoint supports TLS. If SSL is configured,
+SSL settings will automatically be applied to the APM integration's Jaeger gRPC endpoint.
+
+* The gRPC endpoint supports probabilistic sampling.
+Sampling decisions can be configured <<configure-sampling-central-jaeger,centrally>> with APM Agent central configuration, or <<configure-sampling-local-jaeger,locally>> in each Jaeger client.
+
+See the https://www.jaegertracing.io/docs/1.22/architecture[Jaeger docs]
+for more information on Jaeger architecture.
+
+[float]
+[[get-started-jaeger]]
+=== Get started
+
+Connect your preexisting Jaeger setup to Elastic APM in three steps:
+
+* <<configure-agent-client-jaeger>>
+* <<configure-sampling-jaeger>>
+* <<configure-start-jaeger>>
+
+IMPORTANT: There are <<caveats-jaeger,caveats>> to this integration.
+
+[float]
+[[configure-agent-client-jaeger]]
+==== Configure Jaeger agents
+
+The APM integration serves Jaeger gRPC over the same host and port as the Elastic APM agent protocol.
+
+include::./shared/jaeger/jaeger-widget.asciidoc[]
+
+[float]
+[[configure-sampling-jaeger]]
+==== Configure Sampling
+
+The APM integration supports probabilistic sampling, which can be used to reduce the amount of data that your agents collect and send.
+Probabilistic sampling makes a random sampling decision based on the configured sampling value.
+For example, a value of `.2` means that 20% of traces will be sampled.
+
+There are two different ways to configure the sampling rate of your Jaeger agents:
+
+* <<jaeger-configure-sampling-central,APM Agent central configuration (default)>>
+* <<jaeger-configure-sampling-local,Local sampling in each Jaeger client>>
+
+[float]
+[[configure-sampling-central-jaeger]]
+===== APM Agent central configuration (default)
+
+Central sampling, with APM Agent central configuration,
+allows Jaeger clients to poll APM Server for the sampling rate.
+This means sample rates can be configured on the fly, on a per-service and per-environment basis.
+See {kibana-ref}/agent-configuration.html[Central configuration] to learn more.
+
+[float]
+[[configure-sampling-local-jaeger]]
+===== Local sampling in each Jaeger client
+
+If you don't have access to the APM app,
+you'll need to change the Jaeger client's `sampler.type` and `sampler.param`.
+This enables you to set the sampling configuration locally in each Jaeger client.
+See the official https://www.jaegertracing.io/docs/1.22/sampling/[Jaeger sampling documentation]
+for more information.
+
+[float]
+[[configure-start-jaeger]]
+==== Start sending data
+
+That's it! Data sent from Jaeger clients to the APM Server can now be viewed in the APM app.
+
+[float]
+[[caveats-jaeger]]
+=== Caveats
+
+There are some limitations and differences between Elastic APM and Jaeger that you should be aware of.
+
+*Jaeger integration limitations:*
+
+* Because Jaeger has its own trace context header, and does not currently support W3C trace context headers,
+it is not possible to mix and match the use of Elastic's APM agents and Jaeger's clients.
+* Elastic APM only supports probabilistic sampling.
+
+*Differences between APM Agents and Jaeger Clients:*
+
+* Jaeger clients only sends trace data.
+APM agents support a larger number of features, like
+multiple types of metrics, and application breakdown charts.
+When using Jaeger, features like this will not be available in the APM app.
+* Elastic APM's {apm-overview-ref-v}/apm-data-model.html[data model] is different than Jaegers.
+For Jaeger trace data to work with Elastic's data model, we rely on spans being tagged with the appropriate
+https://github.com/opentracing/specification/blob/master/semantic_conventions.md[`span.kind`].
+** Server Jaeger spans are mapped to Elastic APM {apm-overview-ref-v}/transactions.html[transactions].
+** Client Jaeger spans are mapped to Elastic APM {apm-overview-ref-v}/transaction-spans.html[spans] -- unless the span is the root, in which case it is mapped to an Elastic APM {apm-overview-ref-v}/transactions.html[transaction].