diff --git a/docs/apm-breaking.asciidoc b/docs/apm-breaking.asciidoc index 020986b019d..933edc5d043 100644 --- a/docs/apm-breaking.asciidoc +++ b/docs/apm-breaking.asciidoc @@ -8,6 +8,12 @@ // (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 +// These tagged regions are required for the stack-docs repo includes +// tag::notable-v8-breaking-changes[] +// end::notable-v8-breaking-changes[] +// tag::716-bc[] +// end::716-bc[] + [float] [[breaking-changes-7.15]] === 7.15 diff --git a/docs/apm-distributed-tracing.asciidoc b/docs/apm-distributed-tracing.asciidoc index 937094c54b4..19fb3c64e58 100644 --- a/docs/apm-distributed-tracing.asciidoc +++ b/docs/apm-distributed-tracing.asciidoc @@ -103,7 +103,7 @@ with each agent's API. Sending services must add the `traceparent` header to outgoing requests. -- -include::./tab-widgets/distributed-trace-send-widget.asciidoc[] +include::./shared/distributed-trace-send/distributed-trace-send-widget.asciidoc[] -- [float] @@ -114,7 +114,7 @@ Receiving services must parse the incoming `traceparent` header, and start a new transaction or span as a child of the received context. -- -include::./tab-widgets/distributed-trace-receive-widget.asciidoc[] +include::./shared/distributed-trace-receive/distributed-trace-receive-widget.asciidoc[] -- [float] diff --git a/docs/apm-package/apm-input-settings.asciidoc b/docs/apm-input-settings.asciidoc similarity index 52% rename from docs/apm-package/apm-input-settings.asciidoc rename to docs/apm-input-settings.asciidoc index 81b89dafe2e..e12f49d4bc2 100644 --- a/docs/apm-package/apm-input-settings.asciidoc +++ b/docs/apm-input-settings.asciidoc @@ -22,7 +22,7 @@ OPTIONAL INFO AND EXAMPLE [id="input-{input-type}-host-setting"] `host` -| (string) Defines the host and port the server is listening on. +| (text) Defines the host and port the server is listening on. Use `unix:/path/to.sock` to listen on a unix domain socket. *Default:* `localhost:8200` @@ -30,17 +30,73 @@ Use `unix:/path/to.sock` to listen on a unix domain socket. // ============================================================================= -// tag::secret_token-setting[] +// tag::url-setting[] | -[id="input-{input-type}-secret_token-setting"] -`secret_token` +[id="input-{input-type}-url-setting"] +`URL` -| (string) Authorization token for sending APM data. -The same token must also be set in each APM agent. -This token is not used for RUM endpoints. +| The unchangeable, publicly reachable server URL for deployments on Elastic Cloud or ECK. +// end::url-setting[] -*Default:* No secret token set -// end::secret_token-setting[] +// ============================================================================= + +// tag::max_header_bytes-setting[] +| +[id="input-{input-type}-max_header_bytes-setting"] +`max_header_bytes` + +| (int) Maximum permitted size of a request's header accepted by the server to be processed (in Bytes). + +*Default:* `1048576` Bytes +// end::max_header_bytes-setting[] + +// ============================================================================= + +// tag::idle_timeout-setting[] +| +[id="input-{input-type}-idle_timeout-setting"] +`idle_timeout` + +| (text) Maximum amount of time to wait for the next incoming request before underlying connection is closed. + +*Default:* `45s` (45 seconds) +// end::idle_timeout-setting[] + +// ============================================================================= + +// tag::read_timeout-setting[] +| +[id="input-{input-type}-read_timeout-setting"] +`read_timeout` + +| (text) Maximum permitted duration for reading an entire request. + +*Default:* `3600s` (3600 seconds) +// end::read_timeout-setting[] + +// ============================================================================= + +// tag::shutdown_timeout-setting[] +| +[id="input-{input-type}-shutdown_timeout-setting"] +`shutdown_timeout` + +| (text) Maximum duration in seconds before releasing resources when shutting down the server. + +*Default:* `30s` (30 seconds) +// end::shutdown_timeout-setting[] + +// ============================================================================= + +// tag::write_timeout-setting[] +| +[id="input-{input-type}-write_timeout-setting"] +`write_timeout` + +| (text) Maximum permitted duration for writing a response. + +*Default:* `30s` (30 seconds) +// end::write_timeout-setting[] // ============================================================================= @@ -56,14 +112,26 @@ This token is not used for RUM endpoints. // ============================================================================= -// tag::default_service_environment-setting[] +// tag::max_connections-setting[] | -[id="input-{input-type}-default_service_environment-setting"] -`default_service_environment` +[id="input-{input-type}-max_connections-setting"] +`max_connections` -| (string) The default service environment for events without a defined service environment. +| (int) Maximum number of TCP connections to accept simultaneously. `0` means unlimited. -// end::default_service_environment-setting[] +*Default:* `0` (unlimited) +// end::max_connections-setting[] + +// ============================================================================= + +// tag::response_headers-setting[] +| +[id="input-{input-type}-response_headers-setting"] +`response_headers` + +| (text) Custom HTTP headers to add to HTTP responses. Useful for security policy compliance. + +// end::response_headers-setting[] // ============================================================================= @@ -80,6 +148,32 @@ If true, APM Server captures the IP of the instrumented service and its User Age // ============================================================================= +// tag::default_service_environment-setting[] +| +[id="input-{input-type}-default_service_environment-setting"] +`default_service_environment` + +| (text) The default service environment for events without a defined service environment. + +*Default:* none + +// end::default_service_environment-setting[] + +// ============================================================================= + +// tag::golang_xpvar-setting[] +| +[id="input-{input-type}-golang_xpvar-setting"] +`golang_xpvar` + +| (bool) When set to `true`, the server exposes https://golang.org/pkg/expvar/[Golang expvar] under `/debug/vars`. + +*Default:* `false` + +// end::golang_xpvar-setting[] + +// ============================================================================= + // tag::enable_rum-setting[] | [id="input-{input-type}-enable_rum-setting"] @@ -97,7 +191,7 @@ If true, APM Server captures the IP of the instrumented service and its User Age [id="input-{input-type}-rum_allow_origins-setting"] `rum_allow_origins` -| (string) A list of permitted origins for RUM support. +| (text) A list of permitted origins for RUM support. User-agents send an Origin header that will be validated against this list. This is done automatically by modern browsers as part of the https://www.w3.org/TR/cors/[CORS specification]. An origin is made of a protocol scheme, host and port, without the URL path. @@ -112,7 +206,7 @@ An origin is made of a protocol scheme, host and port, without the URL path. [id="input-{input-type}-rum_allow_headers-setting"] `rum_allow_headers` -| (string) By default, HTTP requests made from the RUM agent to the APM integration are limited in the HTTP headers they are allowed to have. +| (text) By default, HTTP requests made from the RUM agent to the APM integration are limited in the HTTP headers they are allowed to have. If any other headers are added, the request will be rejected by the browser due to Cross-Origin Resource Sharing (CORS) restrictions. If you need to add extra headers to these requests, use this configuration to allow additional headers. @@ -128,74 +222,111 @@ Configured values are appended to the default list and used as the value for the [id="input-{input-type}-rum_response_headers-setting"] `rum_response_headers` -| (yaml) Custom HTTP headers to add to RUM responses. For example, for security policy compliance. +| (text) Custom HTTP headers to add to RUM responses. For example, for security policy compliance. +*Default:* none // end::rum_response_headers-setting[] // ============================================================================= -// tag::anonymous_enabled-setting[] +// tag::rum_library_frame_pattern-setting[] | -[id="input-{input-type}-anonymous_enabled-setting"] -`anonymous_enabled` +[id="input-{input-type}-rum_library_frame_pattern-setting"] +`rum_library_frame_pattern` -| (bool) Enable or disable anonymous authentication. +| (text) RegExp to be matched against a stacktrace frame's `file_name` and `abs_path` attributes. +If the RegExp matches, the stacktrace frame is considered to be a library frame. +When source mapping is applied, the `error.culprit` is set to reflect the _function_ and the _filename_ +of the first non-library frame. +This aims to provide an entry point for identifying issues. -*Default:* `true` (enabled) -// end::anonymous_enabled-setting[] +*Default:* `"node_modules\|bower_components\|~"` +// end::rum_library_frame_pattern-setting[] // ============================================================================= -// tag::anonymous_allow_agent-setting[] +// tag::rum_exclude_from_grouping-setting[] | -[id="input-{input-type}-anonymous_allow_agent-setting"] -`anonymous_allow_agent` +[id="input-{input-type}-rum_exclude_from_grouping-setting"] +`rum_exclude_from_grouping` -| (array) A list of permitted APM agent names for anonymous authentication. -Names in this list must match the agent's `agent.name`. +| (text) RegExp to be matched against a stacktrace frame's `file_name`. +If the RegExp matches, the stacktrace frame is excluded from being used for calculating error groups. -*Default:* `[rum-js, js-base, iOS/swift]` (only RUM and iOS/Swift agent events are accepted) -// end::anonymous_allow_agent-setting[] +*Default:* `"^/webpack"` (excludes stacktrace frames that have a filename starting with `/webpack`) +// end::rum_exclude_from_grouping-setting[] // ============================================================================= -// tag::anonymous_allow_service-setting[] +// tag::tls_enabled-setting[] | -[id="input-{input-type}-anonymous_allow_service-setting"] -`anonymous_allow_service` +[id="input-{input-type}-tls_enabled-setting"] +`tls_enabled` -| (array) A list of permitted service names for anonymous authentication. -Names in this list must match the agent's `service.name`. -This can be used to limit the number of service-specific indices or data streams created. +| (bool) Enable TLS. -*Default:* Not set (any service name is accepted) -// end::anonymous_allow_service-setting[] +*Default:* `false` +// end::tls_enabled-setting[] // ============================================================================= -// tag::anonymous_rate_limit_event_limit-setting[] +// tag::tls_certificate-setting[] | -[id="input-{input-type}-anonymous_rate_limit_event_limit-setting"] -`anonymous_rate_limit_event_limit` +[id="input-{input-type}-tls_certificate-setting"] +`tls_certificate` -| (int) The maximum amount of events allowed to be sent to the APM Server anonymous auth endpoint per IP per second. +| (text) The path to the file containing the certificate for server authentication. Required when TLS is enabled. -*Default:* `10` -// end::anonymous_rate_limit_event_limit-setting[] +*Default:* none +// end::tls_certificate-setting[] // ============================================================================= -// tag::anonymous_rate_limit_ip_limit-setting[] +// tag::tls_key-setting[] | -[id="input-{input-type}-anonymous_rate_limit_ip_limit-setting"] -`anonymous_rate_limit_ip_limit` +[id="input-{input-type}-tls_key-setting"] +`tls_key` -| (int) The number of unique IP addresses to track in an LRU cache. -IP addresses in the cache will be rate limited according to the `anonymous_rate_limit_event_limit` setting. -Consider increasing this default if your application has many concurrent clients. +| (text) The path to the file containing the Server certificate key. Required when TLS is enabled. -*Default:* `10000` -// end::anonymous_rate_limit_ip_limit-setting[] +*Default:* none +// end::tls_key-setting[] + +// ============================================================================= + +// tag::tls_supported_protocols-setting[] +| +[id="input-{input-type}-tls_supported_protocols-setting"] +`tls_supported_protocols` + +| (array) A list of allowed TLS protocol versions. + +*Default:* `["TLSv1.0", "TLSv1.1", "TLSv1.2"]` +// end::tls_supported_protocols-setting[] + +// ============================================================================= + +// tag::tls_cipher_suites-setting[] +| +[id="input-{input-type}-tls_cipher_suites-setting"] +`tls_cipher_suites` + +| (text) The list of cipher suites to use. The first entry has the highest priority. +If this option is omitted, the Go crypto library’s https://golang.org/pkg/crypto/tls/[default suites] are used (recommended). +Note that TLS 1.3 cipher suites are not individually configurable in Go, so they are not included in this list. +// end::tls_cipher_suites-setting[] + +// ============================================================================= + +// tag::tls_curve_types-setting[] +| +[id="input-{input-type}-tls_curve_types-setting"] +`tls_curve_types` + +| (text) The list of curve types for ECDHE (Elliptic Curve Diffie-Hellman ephemeral key exchange). + +*Default:* none +// end::tls_curve_types-setting[] // ============================================================================= @@ -225,23 +356,81 @@ The minimum value for this setting should be the number of API keys configured i // ============================================================================= -// tag::sourcemap_api_key-setting[] +// tag::secret_token-setting[] | -[id="input-{input-type}-sourcemap_api_key-setting"] -`sourcemap_api_key` +[id="input-{input-type}-secret_token-setting"] +`secret_token` + +| (text) Authorization token for sending APM data. +The same token must also be set in each APM agent. +This token is not used for RUM endpoints. -| (string) RUM API key for sourcemaps. Formatted as `:`. -// end::sourcemap_api_key-setting[] +*Default:* No secret token set +// end::secret_token-setting[] // ============================================================================= -// tag::kibana_api_key-setting[] +// tag::anonymous_enabled-setting[] | -[id="input-{input-type}-kibana_api_key-setting"] -`kibana_api_key` +[id="input-{input-type}-anonymous_enabled-setting"] +`anonymous_enabled` -| (string) API Key for APM central configuration feature. Formatted as `:`. +| (bool) Enable or disable anonymous authentication. + +*Default:* `true` (enabled) +// end::anonymous_enabled-setting[] + +// ============================================================================= + +// tag::anonymous_allow_agent-setting[] +| +[id="input-{input-type}-anonymous_allow_agent-setting"] +`anonymous_allow_agent` -// end::kibana_api_key-setting[] +| (array) A list of permitted APM agent names for anonymous authentication. +Names in this list must match the agent's `agent.name`. + +*Default:* `[rum-js, js-base, iOS/swift]` (only RUM and iOS/Swift agent events are accepted) +// end::anonymous_allow_agent-setting[] + +// ============================================================================= + +// tag::anonymous_allow_service-setting[] +| +[id="input-{input-type}-anonymous_allow_service-setting"] +`anonymous_allow_service` + +| (array) A list of permitted service names for anonymous authentication. +Names in this list must match the agent's `service.name`. +This can be used to limit the number of service-specific indices or data streams created. + +*Default:* Not set (any service name is accepted) +// end::anonymous_allow_service-setting[] + +// ============================================================================= + +// tag::anonymous_rate_limit_ip_limit-setting[] +| +[id="input-{input-type}-anonymous_rate_limit_ip_limit-setting"] +`anonymous_rate_limit_ip_limit` + +| (int) The number of unique IP addresses to track in an LRU cache. +IP addresses in the cache will be rate limited according to the `anonymous_rate_limit_event_limit` setting. +Consider increasing this default if your application has many concurrent clients. + +*Default:* `10000` +// end::anonymous_rate_limit_ip_limit-setting[] + +// ============================================================================= + +// tag::anonymous_rate_limit_event_limit-setting[] +| +[id="input-{input-type}-anonymous_rate_limit_event_limit-setting"] +`anonymous_rate_limit_event_limit` + +| (int) The maximum amount of events allowed to be sent to the APM Server anonymous auth endpoint per IP per second. + +*Default:* `10` +// end::anonymous_rate_limit_event_limit-setting[] // ============================================================================= diff --git a/docs/apm-package/apm-integration.asciidoc b/docs/apm-package/apm-integration.asciidoc index 471a4e9b86a..3feba1fa088 100644 --- a/docs/apm-package/apm-integration.asciidoc +++ b/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 -* <> * <> * {fleet-guide}/fleet-overview.html[Fleet overview] include::./data-streams.asciidoc[] -include::./input-apm.asciidoc[] - include::./configure.asciidoc[] \ No newline at end of file diff --git a/docs/apm-quick-start.asciidoc b/docs/apm-quick-start.asciidoc new file mode 100644 index 00000000000..817a7c0b66c --- /dev/null +++ b/docs/apm-quick-start.asciidoc @@ -0,0 +1,16 @@ +[[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 + + +// Used in the obs-docs repo +// tag::apm-agent[] +// end::apm-agent[] diff --git a/docs/apm-tune-elasticsearch.asciidoc b/docs/apm-tune-elasticsearch.asciidoc new file mode 100644 index 00000000000..5d42654fa05 --- /dev/null +++ b/docs/apm-tune-elasticsearch.asciidoc @@ -0,0 +1,22 @@ +[[apm-tune-elasticsearch]] +=== Tune {es} for data ingestion + +++++ +Tune {es} +++++ + +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 diff --git a/docs/data-streams.asciidoc b/docs/data-streams.asciidoc new file mode 100644 index 00000000000..0db0c1449b8 --- /dev/null +++ b/docs/data-streams.asciidoc @@ -0,0 +1,4 @@ +[[apm-data-streams]] +== Data streams + +// to do: fill with content. placeholder for external links for now diff --git a/docs/how-to.asciidoc b/docs/how-to.asciidoc new file mode 100644 index 00000000000..428d086cf5c --- /dev/null +++ b/docs/how-to.asciidoc @@ -0,0 +1,23 @@ +[[how-to-guides]] +== How-to guides + +Learn how to perform common APM configuration and management tasks. + +* <> +* <> +* <> +* <> +* <> +* <> + +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[] diff --git a/docs/ilm-how-to.asciidoc b/docs/ilm-how-to.asciidoc new file mode 100644 index 00000000000..4cd67352e5e --- /dev/null +++ b/docs/ilm-how-to.asciidoc @@ -0,0 +1,18 @@ +[[ilm-how-to]] +=== Index lifecycle management (ILM) + +// todo: add more context and an example + +++++ +Customize index lifecycle management +++++ + +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. diff --git a/docs/ingest-pipelines.asciidoc b/docs/ingest-pipelines.asciidoc new file mode 100644 index 00000000000..2376ed4be76 --- /dev/null +++ b/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 <> 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 \ No newline at end of file diff --git a/docs/apm-package/input-apm.asciidoc b/docs/input-apm.asciidoc similarity index 50% rename from docs/apm-package/input-apm.asciidoc rename to docs/input-apm.asciidoc index d1e47cd58cb..b9199cac92c 100644 --- a/docs/apm-package/input-apm.asciidoc +++ b/docs/input-apm.asciidoc @@ -7,21 +7,10 @@ Input settings ++++ -beta::[] - -To edit the APM integration input settings, open {kib} and select: -**Integrations** > **Elastic APM** > **Add Elastic APM**. -Expand the carrot to view all settings. - -A limited number of settings are currently supported. - -[NOTE] -==== -Templates, pipelines, index lifecycle management, etc., cannot be configured -with APM Server or Fleet, and must instead be configured with {kib} or {es}. -<>. -// Configuration via the `apm-server.yml` file is no longer supported. -==== +To edit the APM integration input settings, open {kib}, select **Add data**, +and search for and select "Elastic APM". +If the integration is already installed, under the polices tab, select **Actions** > **Edit integration**. +If the integration has not been installed, select **Add Elastic APM**. [float] [[apm-input-general-settings]] @@ -31,26 +20,17 @@ with APM Server or Fleet, and must instead be configured with {kib} or {es}. |=== include::./apm-input-settings.asciidoc[tag=host-setting] -include::./apm-input-settings.asciidoc[tag=secret_token-setting] +include::./apm-input-settings.asciidoc[tag=url-setting] +include::./apm-input-settings.asciidoc[tag=max_header_bytes-setting] +include::./apm-input-settings.asciidoc[tag=idle_timeout-setting] +include::./apm-input-settings.asciidoc[tag=read_timeout-setting] +include::./apm-input-settings.asciidoc[tag=shutdown_timeout-setting] include::./apm-input-settings.asciidoc[tag=max_event_bytes-setting] -include::./apm-input-settings.asciidoc[tag=default_service_environment-setting] +include::./apm-input-settings.asciidoc[tag=max_connections-setting] +include::./apm-input-settings.asciidoc[tag=response_headers-setting] include::./apm-input-settings.asciidoc[tag=capture_personal_data-setting] - -|=== - -[float] -[[apm-input-anon-auth-settings]] -=== Anonymous authentication settings - -[cols="2*Integrate with Jaeger +++++ + +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 <> with APM Agent central configuration, or <> in each Jaeger client. + +See the https://www.jaegertracing.io/docs/1.27/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: + +* <> +* <> +* <> + +IMPORTANT: There are <> 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: + +* <> +* <> + +[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.27/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]. diff --git a/docs/legacy/guide/distributed-tracing.asciidoc b/docs/legacy/guide/distributed-tracing.asciidoc index cb0e5cd40f2..ce3e03d6e37 100644 --- a/docs/legacy/guide/distributed-tracing.asciidoc +++ b/docs/legacy/guide/distributed-tracing.asciidoc @@ -96,7 +96,7 @@ with each agent's API. Sending services must add the `traceparent` header to outgoing requests. -- -include::../../tab-widgets/distributed-trace-send-widget.asciidoc[] +include::../../shared/distributed-trace-send/distributed-trace-send-widget.asciidoc[] -- [float] @@ -106,7 +106,7 @@ Receiving services must parse the incoming `traceparent` header, and start a new transaction or span as a child of the received context. -- -include::../../tab-widgets/distributed-trace-receive-widget.asciidoc[] +include::../../shared/distributed-trace-receive/distributed-trace-receive-widget.asciidoc[] -- [float] diff --git a/docs/legacy/guide/install-and-run.asciidoc b/docs/legacy/guide/install-and-run.asciidoc index 2ba72da2311..d1965c4a39e 100644 --- a/docs/legacy/guide/install-and-run.asciidoc +++ b/docs/legacy/guide/install-and-run.asciidoc @@ -12,7 +12,7 @@ This guide describes how to get started quickly with Elastic APM. You’ll learn [[before-installation]] === Step 1: Spin up the Elastic Stack -include::../../tab-widgets/spin-up-stack-widget.asciidoc[] +include::../tab-widgets/spin-up-stack-widget.asciidoc[] [float] [[agents]] @@ -42,7 +42,7 @@ Select your service's language for installation instructions: // end::apm-agent[] -- -include::../../tab-widgets/install-agents-widget.asciidoc[] +include::../tab-widgets/install-agents-widget.asciidoc[] -- TIP: Check the {apm-overview-ref-v}/agent-server-compatibility.html[Agent/Server compatibility matrix] to ensure you're using agents that are compatible with your version of {es}. @@ -63,11 +63,11 @@ environment names, sampling rates, instrumentations, metrics, and more. Broadly speaking, there are two ways to configure APM agents: // end::configure-agents[] -include::../../tab-widgets/configure-agent-widget.asciidoc[] +include::../tab-widgets/configure-agent-widget.asciidoc[] *Configure APM Server* -include::../../tab-widgets/configure-server-widget.asciidoc[] +include::../tab-widgets/configure-server-widget.asciidoc[] [float] [[visualize-kibana]] @@ -82,7 +82,7 @@ To open the APM app: . Lauch {kib}: + -- -include::../../tab-widgets/open-kibana-widget.asciidoc[] +include::../../shared/open-kibana/open-kibana-widget.asciidoc[] -- . In the side navigation, under *Observability*, select *APM*. diff --git a/docs/legacy/guide/opentelemetry-elastic.asciidoc b/docs/legacy/guide/opentelemetry-elastic.asciidoc index f1950b988e1..328ffb10bd6 100644 --- a/docs/legacy/guide/opentelemetry-elastic.asciidoc +++ b/docs/legacy/guide/opentelemetry-elastic.asciidoc @@ -160,7 +160,7 @@ Use *Discover* to validate that metrics are successfully reported to {kib}. . Launch {kib}: + -- -include::../../tab-widgets/open-kibana-widget.asciidoc[] +include::../../shared/open-kibana/open-kibana-widget.asciidoc[] -- . Open the main menu, then click *Discover*. diff --git a/docs/legacy/jaeger-support.asciidoc b/docs/legacy/jaeger-support.asciidoc index 8b2588ba07d..f7b89d300e2 100644 --- a/docs/legacy/jaeger-support.asciidoc +++ b/docs/legacy/jaeger-support.asciidoc @@ -25,7 +25,7 @@ IMPORTANT: There are <> to this integration. APM Server serves Jaeger gRPC over the same <> as the Elastic APM agent protocol. -include::../tab-widgets/jaeger-widget.asciidoc[] +include::./tab-widgets/jaeger-widget.asciidoc[] [float] [[jaeger-configure-sampling]] @@ -48,7 +48,7 @@ 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. -include::../tab-widgets/jaeger-sampling-widget.asciidoc[] +include::./tab-widgets/jaeger-sampling-widget.asciidoc[] [float] [[jaeger-configure-sampling-local]] diff --git a/docs/legacy/tab-widgets/configure-agent-widget.asciidoc b/docs/legacy/tab-widgets/configure-agent-widget.asciidoc new file mode 100644 index 00000000000..0936b939643 --- /dev/null +++ b/docs/legacy/tab-widgets/configure-agent-widget.asciidoc @@ -0,0 +1,40 @@ +++++ +
+
+ + +
+
+++++ + +include::configure-agent.asciidoc[tag=central-config] + +++++ +
+ +
+++++ \ No newline at end of file diff --git a/docs/tab-widgets/configure-agent.asciidoc b/docs/legacy/tab-widgets/configure-agent.asciidoc similarity index 100% rename from docs/tab-widgets/configure-agent.asciidoc rename to docs/legacy/tab-widgets/configure-agent.asciidoc diff --git a/docs/legacy/tab-widgets/configure-server-widget.asciidoc b/docs/legacy/tab-widgets/configure-server-widget.asciidoc new file mode 100644 index 00000000000..bcbfdf2d9c5 --- /dev/null +++ b/docs/legacy/tab-widgets/configure-server-widget.asciidoc @@ -0,0 +1,40 @@ +++++ +
+
+ + +
+
+++++ + +include::configure-server.asciidoc[tag=ess] + +++++ +
+ +
+++++ \ No newline at end of file diff --git a/docs/tab-widgets/configure-server.asciidoc b/docs/legacy/tab-widgets/configure-server.asciidoc similarity index 100% rename from docs/tab-widgets/configure-server.asciidoc rename to docs/legacy/tab-widgets/configure-server.asciidoc diff --git a/docs/legacy/tab-widgets/install-agents-widget.asciidoc b/docs/legacy/tab-widgets/install-agents-widget.asciidoc new file mode 100644 index 00000000000..9a165850c0e --- /dev/null +++ b/docs/legacy/tab-widgets/install-agents-widget.asciidoc @@ -0,0 +1,168 @@ +// The Java agent defaults to visible. +// Change with `aria-selected="false"` and `hidden=""` +++++ +
+
+ + + + + + + + + +
+ + +
+++++ + +include::install-agents.asciidoc[tag=java] + +++++ +
+ + + + + + +
+++++ \ No newline at end of file diff --git a/docs/tab-widgets/install-agents.asciidoc b/docs/legacy/tab-widgets/install-agents.asciidoc similarity index 100% rename from docs/tab-widgets/install-agents.asciidoc rename to docs/legacy/tab-widgets/install-agents.asciidoc diff --git a/docs/tab-widgets/jaeger-sampling-widget.asciidoc b/docs/legacy/tab-widgets/jaeger-sampling-widget.asciidoc similarity index 100% rename from docs/tab-widgets/jaeger-sampling-widget.asciidoc rename to docs/legacy/tab-widgets/jaeger-sampling-widget.asciidoc diff --git a/docs/tab-widgets/jaeger-sampling.asciidoc b/docs/legacy/tab-widgets/jaeger-sampling.asciidoc similarity index 100% rename from docs/tab-widgets/jaeger-sampling.asciidoc rename to docs/legacy/tab-widgets/jaeger-sampling.asciidoc diff --git a/docs/tab-widgets/jaeger-widget.asciidoc b/docs/legacy/tab-widgets/jaeger-widget.asciidoc similarity index 100% rename from docs/tab-widgets/jaeger-widget.asciidoc rename to docs/legacy/tab-widgets/jaeger-widget.asciidoc diff --git a/docs/tab-widgets/jaeger.asciidoc b/docs/legacy/tab-widgets/jaeger.asciidoc similarity index 100% rename from docs/tab-widgets/jaeger.asciidoc rename to docs/legacy/tab-widgets/jaeger.asciidoc diff --git a/docs/tab-widgets/spin-up-stack-widget.asciidoc b/docs/legacy/tab-widgets/spin-up-stack-widget.asciidoc similarity index 100% rename from docs/tab-widgets/spin-up-stack-widget.asciidoc rename to docs/legacy/tab-widgets/spin-up-stack-widget.asciidoc diff --git a/docs/tab-widgets/spin-up-stack.asciidoc b/docs/legacy/tab-widgets/spin-up-stack.asciidoc similarity index 100% rename from docs/tab-widgets/spin-up-stack.asciidoc rename to docs/legacy/tab-widgets/spin-up-stack.asciidoc diff --git a/docs/manage-storage.asciidoc b/docs/manage-storage.asciidoc new file mode 100644 index 00000000000..d08b31b85d5 --- /dev/null +++ b/docs/manage-storage.asciidoc @@ -0,0 +1,214 @@ +[[manage-storage]] +=== Manage storage + +* <> +* <> +* <> +* <> +* <> + +[float] +[[storage-guide]] +=== Storage and sizing guide + +APM processing and storage costs are largely dominated by transactions, spans, and stack frames. + +* <> describe an event captured by an Elastic APM agent instrumenting a service. +They are the highest level of work being measuring within a service. +* <> belong to transactions. They measure from the start to end of an activity, +and contain information about a specific code path that has been executed. +* *Stack frames* belong to spans. Stack frames represent a function call on the call stack, +and include attributes like function name, file name and path, line number, etc. +Stack frames can heavily influence the size of a span. + +[float] +==== Typical transactions + +Due to the high variability of APM data, it's difficult to classify a transaction as typical. +Regardless, this guide will attempt to classify Transactions as _Small_, _Medium_, or _Large_, +and make recommendations based on those classifications. + +The size of a transaction depends on the language, agent settings, and what services the agent instruments. +For instance, an agent auto-instrumenting a service with a popular tech stack +(web framework, database, caching library, etc.) is more likely to generate bigger transactions. + +In addition, all agents support manual instrumentation. +How little or much you use these APIs will also impact what a typical transaction looks like. + +If your sampling rate is very small, transactions will be the dominate storage cost. + +Here's a speculative reference: + +[options="header"] +|======================================================================= +|Transaction size |Number of Spans |Number of stack frames +|_Small_ |5-10 |5-10 +|_Medium_ |15-20 |15-20 +|_Large_ |30-40 |30-40 +|======================================================================= + +There will always be transaction outliers with hundreds of spans or stack frames, but those are very rare. +Small transactions are the most common. + +[float] +==== Typical storage + +Consider the following typical storage reference. +These numbers do not account for Elasticsearch compression. + +* 1 unsampled transaction is **~1 Kb** +* 1 span with 10 stack frames is **~4 Kb** +* 1 span with 50 stack frames is **~20 Kb** +* 1 transaction with 10 spans, each with 10 stack frames is **~50 Kb** +* 1 transaction with 25 spans, each with 25 spans is **250-300 Kb** +* 100 transactions with 10 spans, each with 10 stack frames, sampled at 90% is **600 Kb** + +APM data compresses quite well, so the storage cost in Elasticsearch will be considerably less: + +* Indexing 100 unsampled transactions per second for 1 hour results in 360,000 documents. These documents use around **50 Mb** of disk space. +* Indexing 10 transactions per second for 1 hour, each transaction with 10 spans, each span with 10 stack frames, results in 396,000 documents. These documents use around **200 Mb** of disk space. +* Indexing 25 transactions per second for 1 hour, each transaction with 25 spans, each span with 25 stack frames, results in 2,340,000 documents. These documents use around **1.2 Gb** of disk space. + +NOTE: These examples were indexing the same data over and over with minimal variation. Because of that, the compression ratios observed of 80-90% are somewhat optimistic. + +[float] +[[processing-and-performance]] +=== Processing and performance + +APM Server performance depends on a number of factors: memory and CPU available, +network latency, transaction sizes, workload patterns, +agent and server settings, versions, and protocol. + +Let's look at a simple example that makes the following assumptions: + +* The load is generated in the same region as where APM Server and Elasticsearch are deployed. +* We're using the default settings in cloud. +* A small number of agents are reporting. + +This leaves us with relevant variables like payload and instance sizes. +See the table below for approximations. +As a reminder, events are +<> and +<>. + +[options="header"] +|======================================================================= +|Transaction/Instance |512Mb Instance |2Gb Instance |8Gb Instance +|Small transactions + +_5 spans with 5 stack frames each_ |600 events/second |1200 events/second |4800 events/second +|Medium transactions + +_15 spans with 15 stack frames each_ |300 events/second |600 events/second |2400 events/second +|Large transactions + +_30 spans with 30 stack frames each_ |150 events/second |300 events/second |1400 events/second +|======================================================================= + +In other words, a 512 Mb instance can process \~3 Mbs per second, +while an 8 Gb instance can process ~20 Mbs per second. + +APM Server is CPU bound, so it scales better from 2 Gb to 8 Gb than it does from 512 Mb to 2 Gb. +This is because larger instance types in Elastic Cloud come with much more computing power. + +Don't forget that the APM Server is stateless. +Several instances running do not need to know about each other. +This means that with a properly sized Elasticsearch instance, APM Server scales out linearly. + +NOTE: RUM deserves special consideration. The RUM agent runs in browsers, and there can be many thousands reporting to an APM Server with very variable network latency. + +[float] +[[reduce-apm-storage]] +=== Reduce storage + +The amount of storage for APM data depends on several factors: +the number of services you are instrumenting, how much traffic the services see, agent and server settings, +and the length of time you store your data. + +[float] +==== Reduce the sample rate + +The transaction sample rate directly influences the number of documents (more precisely, spans) to be indexed. +It is the easiest way to reduce storage. + +The transaction sample rate is a configuration setting of each agent. +Reducing it does not affect the collection of metrics such as _Transactions per second_. + +[float] +==== Reduce collected stacktrace information + +Elastic APM agents collect `stacktrace` information under certain circumstances. +This can be very helpful in identifying issues in your code, +but it also comes with an overhead at collection time and increases the storage usage. + +Stacktrace collection settings are managed in each agent. + +[float] +==== Delete data + +You might want to only keep data for a defined time period. +This might mean deleting old documents periodically, +deleting data collected for specific services or customers, +or deleting specific indices. + +Depending on your use case, +you can delete data periodically with <>, +{curator-ref-current}[Curator], the {ref}/docs-delete-by-query.html[Delete By Query API], +or in the {kibana-ref}/managing-indices.html[Kibana Index Management UI]. + +[float] +[[delete-data-with-ilm]] +===== Delete data with ILM + +Index Lifecycle management (ILM) enables you to automate how you want to manage your indices over time. +You can base actions on factors such as shard size and performance requirements. +See <> to learn more. + +[float] +[[delete-data-in-kibana]] +===== Delete data via Kibana Index Management UI + +Select the indices you want to delete, and click **Manage indices** to see the available actions. +Then click **delete indices**. + +[float] +[[manage-indices-in-kibana]] +=== Manage Indices via Kibana + +Kibana's {ref}/index-mgmt.html[index management] allows you to manage your cluster's +indices, data streams, index templates, and much more. + +[float] +[[update-data]] +=== Update existing data + +You might want to update documents that are already indexed. +For example, if you your service name was set incorrectly. + +To do this, you can use the {ref}/docs-update-by-query.html[Update By Query API]. + +[float] +==== Rename a service + +To rename a service, send the following request: + +["source","sh"] +------------------------------------------------------------ +POST *-apm-*/_update_by_query?expand_wildcards=all +{ + "query": { + "term": { + "service.name": { + "value": "current-service-name" + } + } + }, + "script": { + "source": "ctx._source.service.name = 'new-service-name'", + "lang": "painless" + } +} +------------------------------------------------------------ +// CONSOLE + +TIP: Remember to also change the service name in the {apm-agents-ref}/index.html[APM agent configuration]. diff --git a/docs/open-telemetry.asciidoc b/docs/open-telemetry.asciidoc index 8ef147e4ce2..4f5b3ee86e0 100644 --- a/docs/open-telemetry.asciidoc +++ b/docs/open-telemetry.asciidoc @@ -163,7 +163,7 @@ Use *Discover* to validate that metrics are successfully reported to {kib}. . Launch {kib}: + -- -include::./tab-widgets/open-kibana-widget.asciidoc[] +include::./shared/open-kibana/open-kibana-widget.asciidoc[] -- . Open the main menu, then click *Discover*. diff --git a/docs/tab-widgets/distributed-trace-receive-widget.asciidoc b/docs/shared/distributed-trace-receive/distributed-trace-receive-widget.asciidoc similarity index 100% rename from docs/tab-widgets/distributed-trace-receive-widget.asciidoc rename to docs/shared/distributed-trace-receive/distributed-trace-receive-widget.asciidoc diff --git a/docs/tab-widgets/distributed-trace-receive.asciidoc b/docs/shared/distributed-trace-receive/distributed-trace-receive.asciidoc similarity index 100% rename from docs/tab-widgets/distributed-trace-receive.asciidoc rename to docs/shared/distributed-trace-receive/distributed-trace-receive.asciidoc diff --git a/docs/tab-widgets/distributed-trace-send-widget.asciidoc b/docs/shared/distributed-trace-send/distributed-trace-send-widget.asciidoc similarity index 100% rename from docs/tab-widgets/distributed-trace-send-widget.asciidoc rename to docs/shared/distributed-trace-send/distributed-trace-send-widget.asciidoc diff --git a/docs/tab-widgets/distributed-trace-send.asciidoc b/docs/shared/distributed-trace-send/distributed-trace-send.asciidoc similarity index 100% rename from docs/tab-widgets/distributed-trace-send.asciidoc rename to docs/shared/distributed-trace-send/distributed-trace-send.asciidoc diff --git a/docs/shared/jaeger/jaeger-widget.asciidoc b/docs/shared/jaeger/jaeger-widget.asciidoc new file mode 100644 index 00000000000..5902738ca38 --- /dev/null +++ b/docs/shared/jaeger/jaeger-widget.asciidoc @@ -0,0 +1,40 @@ +++++ +
+
+ + +
+
+++++ + +include::jaeger.asciidoc[tag=ess] + +++++ +
+ +
+++++ \ No newline at end of file diff --git a/docs/shared/jaeger/jaeger.asciidoc b/docs/shared/jaeger/jaeger.asciidoc new file mode 100644 index 00000000000..9502729e1d9 --- /dev/null +++ b/docs/shared/jaeger/jaeger.asciidoc @@ -0,0 +1,64 @@ +// tag::ess[] +. Log into {ess-console}[Elastic Cloud] and select your deployment. +In {kib}, select **Add data**, then search for and select "Elastic APM". +If the integration is already installed, under the polices tab, select **Actions** > **Edit integration**. +If the integration has not been installed, select **Add Elastic APM**. +Copy the URL. If you're using Agent authorization, copy the Secret token as well. + +. Configure the APM Integration as a collector for your Jaeger agents. ++ +As of this writing, the Jaeger agent binary offers the following CLI flags, +which can be used to enable TLS, output to {ecloud}, and set the APM Integration secret token: ++ +[source,terminal] +---- +--reporter.grpc.tls.enabled=true +--reporter.grpc.host-port= +--agent.tags="elastic-apm-auth=Bearer " +---- + +TIP: For the equivalent environment variables, +change all letters to upper-case and replace punctuation with underscores (`_`). +See the https://www.jaegertracing.io/docs/1.27/cli/[Jaeger CLI flags documentation] for more information. + +// end::ess[] + +// tag::self-managed[] +. Configure the APM Integration as a collector for your Jaeger agents. +In {kib}, select **Add data**, then search for and select "Elastic APM". +If the integration is already installed, under the polices tab, select **Actions** > **Edit integration**. +If the integration has not been installed, select **Add Elastic APM**. +Copy the Host. If you're using Agent authorization, copy the Secret token as well. ++ +As of this writing, the Jaeger agent binary offers the `--reporter.grpc.host-port` CLI flag. +Use this to define the host and port that the APM Integration is listening on: ++ +[source,terminal] +---- +--reporter.grpc.host-port= +---- + +. (Optional) Enable encryption ++ +When TLS is enabled for the APM Integration, Jaeger agents must also enable TLS communication: ++ +[source,terminal] +---- +--reporter.grpc.tls.enabled=true +---- + +. (Optional) Enable token-based authorization ++ +A secret token or API key can be used to ensure only authorized Jaeger agents can send data to the APM Integration. +When enabled, use an agent level tag to authorize Jaeger agent communication with the APM Server: ++ +[source,terminal] +---- +--agent.tags="elastic-apm-auth=Bearer " +---- + +TIP: For the equivalent environment variables, +change all letters to upper-case and replace punctuation with underscores (`_`). +See the https://www.jaegertracing.io/docs/1.27/cli/[Jaeger CLI flags documentation] for more information. + +// end::self-managed[] diff --git a/docs/tab-widgets/open-kibana-widget.asciidoc b/docs/shared/open-kibana/open-kibana-widget.asciidoc similarity index 100% rename from docs/tab-widgets/open-kibana-widget.asciidoc rename to docs/shared/open-kibana/open-kibana-widget.asciidoc diff --git a/docs/tab-widgets/open-kibana.asciidoc b/docs/shared/open-kibana/open-kibana.asciidoc similarity index 100% rename from docs/tab-widgets/open-kibana.asciidoc rename to docs/shared/open-kibana/open-kibana.asciidoc diff --git a/docs/source-map-how-to.asciidoc b/docs/source-map-how-to.asciidoc new file mode 100644 index 00000000000..ad118449b22 --- /dev/null +++ b/docs/source-map-how-to.asciidoc @@ -0,0 +1,181 @@ +[[source-map-how-to]] +=== Create and upload source maps (RUM) + +Minifying JavaScript bundles in production is a common practice; +it can greatly improve the load time and network latency of your applications. +The problem with minifying code is that it can be hard to debug. + +For best results, uploading source maps should become a part of your deployment procedure, +and not something you only do when you see unhelpful errors. +That's because uploading source maps after errors happen won't make old errors magically readable — +errors must occur again for source mapping to occur. + +Here's an example of an exception stack trace in the APM app when using minified code. +As you can see, it's not very helpful. + +[role="screenshot"] +image::images/source-map-before.png[APM app without source mapping] + +With a source map, minified files are mapped back to the original source code, +allowing you to maintain the speed advantage of minified code, +without losing the ability to quickly and easily debug your application. +Here's the same example as before, but with a source map uploaded and applied: + +[role="screenshot"] +image::images/source-map-after.png[APM app with source mapping] + +Follow the steps below to enable source mapping your error stack traces in the APM app: + +* <> +* <> +* <> + +[float] +[[source-map-rum-initialize]] +=== Initialize the RUM Agent + +First, set the service name and version of your application when initializing the RUM Agent. +The `serviceVersion` you choose might be the `version` from your `package.json`. For example: + +[source,js] +---- +import { init as initApm } from '@elastic/apm-rum' +const serviceVersion = require("./package.json").version + +const apm = initApm({ + serviceName: 'myService', + serviceVersion: serviceVersion +}) +---- + +Or, `serviceVersion` could be a git commit reference. For example: + +[source,js] +---- +const git = require('git-rev-sync') +const serviceVersion = git.short() +---- + +It can also be any other unique string that indicates a specific version of your application. +APM Server uses the `serviceVersion` to match the correct source map file to each stack trace. + +[float] +[role="child_attributes"] +[[source-map-rum-generate]] +=== Generate a source map + +To be compatible with Elastic APM, source maps must follow the +https://sourcemaps.info/spec.html[source map revision 3 proposal spec]. + +Source maps can be generated and configured in many different ways. +For example, if you're using parcel, they are generated by default. +If you are using webpack, some configuration may need to be done to generate a source map: + +[source,js] +---- +const webpack = require('webpack') +const serviceVersion = require("./package.json").version <1> +const TerserPlugin = require('terser-webpack-plugin'); +module.exports = { + entry: 'app.js', + output: { + filename: 'app.min.js', + path: './dist' + }, + devtool: 'source-map', + plugins: [ + new webpack.DefinePlugin({'serviceVersion': JSON.stringify(serviceVersion)}), + new TerserPlugin({ + sourceMap: true + }) + ] +} +---- +<1> If you're using a different method of defining `serviceVersion`, you can set it here. + +[float] +[[source-map-rum-upload]] +=== Upload the source map to Kibana + +Kibana exposes a {kibana-ref}/rum-sourcemap-api.html[source map endpoint] for uploading source maps. +Source maps can be uploaded as a string, or as a file upload. +Before uploading a source map, ensure that RUM support is enabled in the APM integration + +Let's look at two different ways to upload a source map: curl and a custom application. +Each example includes the four fields necessary for APM Server to later map minified code to its source: + +* `service_name` - Should match the `serviceName` from step one +* `service_version` - Should match the `serviceVersion` from step one +* `bundle_filepath` - The absolute path of the final bundle as used in the web application +* `sourcemap` - The location of the source map. +If you have multiple source maps, you'll need to upload each individually. + +[float] +[[source-map-curl]] +==== Upload via curl + +Here’s an example curl request that uploads the source map file created in the previous step. +This request uses an API key for authentication. + +[source,console] +---- +SERVICEVERSION=`node -e "console.log(require('./package.json').version);"` && \ <1> +curl -X POST "http://localhost:5601/api/apm/sourcemaps" \ +-H 'Content-Type: multipart/form-data' \ +-H 'kbn-xsrf: true' \ +-H 'Authorization: ApiKey ${YOUR_API_KEY}' \ <2> +-F 'service_name="foo"' \ +-F 'service_version="$SERVICEVERSION"' \ +-F 'bundle_filepath="/test/e2e/general-usecase/bundle.js.map"' \ +-F 'sourcemap="@./dist/app.min.js.map"' +---- +<1> This example uses the version from `package.json` +<2> The API key used here needs to have appropriate {kibana-ref}/rum-sourcemap-api.html[privileges] + +[float] +[[source-map-custom-app]] +==== Upload via a custom app + +To ensure uploading source maps become a part of your deployment process, +consider automating the process with a custom application. +Here’s an example Node.js application that uploads the source map file created in the previous step: + +[source,js] +---- +console.log('Uploading sourcemaps!') +var request = require('request') +var filepath = './dist/app.min.js.map' +var formData = { + headers: { + Content-Type: 'multipart/form-data', + kbn-xsrf: 'true', + Authorization: 'ApiKey ${YOUR_API_KEY}' + }, + service_name: 'service-name’, + service_version: require("./package.json").version, // Or use 'git-rev-sync' for git commit hash + bundle_filepath: 'http://localhost/app.min.js', + sourcemap: fs.createReadStream(filepath) +} +request.post({url: 'http://localhost:5601/api/apm/sourcemaps',formData: formData}, function (err, resp, body) { + if (err) { + console.log('Error while uploading sourcemaps!', err) + } else { + console.log('Sourcemaps uploaded!') + } +}) +---- + +// todo: add links when they exist + +// [float] +// [[source-map-done]] +// === Next steps + +// That's it! The source map has been uploaded to Elasticsearch, +// and any new exception stack traces should now be correctly mapped to your source code. + +// More information: + +// * <> +// * <>. +// * <>. diff --git a/docs/tab-widgets/configure-agent-widget.asciidoc b/docs/tab-widgets/configure-agent-widget.asciidoc index 0936b939643..af8e0cb5230 100644 --- a/docs/tab-widgets/configure-agent-widget.asciidoc +++ b/docs/tab-widgets/configure-agent-widget.asciidoc @@ -1,40 +1 @@ -++++ -
-
- - -
-
-++++ - -include::configure-agent.asciidoc[tag=central-config] - -++++ -
- -
-++++ \ No newline at end of file +// delete after PR in obs-docs repo \ No newline at end of file diff --git a/docs/tab-widgets/configure-server-widget.asciidoc b/docs/tab-widgets/configure-server-widget.asciidoc index bcbfdf2d9c5..af8e0cb5230 100644 --- a/docs/tab-widgets/configure-server-widget.asciidoc +++ b/docs/tab-widgets/configure-server-widget.asciidoc @@ -1,40 +1 @@ -++++ -
-
- - -
-
-++++ - -include::configure-server.asciidoc[tag=ess] - -++++ -
- -
-++++ \ No newline at end of file +// delete after PR in obs-docs repo \ No newline at end of file diff --git a/docs/tab-widgets/install-agents-widget.asciidoc b/docs/tab-widgets/install-agents-widget.asciidoc index 9a165850c0e..af8e0cb5230 100644 --- a/docs/tab-widgets/install-agents-widget.asciidoc +++ b/docs/tab-widgets/install-agents-widget.asciidoc @@ -1,168 +1 @@ -// The Java agent defaults to visible. -// Change with `aria-selected="false"` and `hidden=""` -++++ -
-
- - - - - - - - - -
- - -
-++++ - -include::install-agents.asciidoc[tag=java] - -++++ -
- - - - - - -
-++++ \ No newline at end of file +// delete after PR in obs-docs repo \ No newline at end of file diff --git a/docs/upgrade.asciidoc b/docs/upgrade.asciidoc new file mode 100644 index 00000000000..57d693be936 --- /dev/null +++ b/docs/upgrade.asciidoc @@ -0,0 +1,4 @@ +[[upgrade]] +== Upgrade + +// placeholder \ No newline at end of file