From feff77ababbd9ae0f03898762c4f86d6b90e0c9f Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Fri, 15 Oct 2021 14:12:02 -0700 Subject: [PATCH 01/19] docs: add sourcemap upload guide --- docs/how-to.asciidoc | 26 +++++ docs/source-map-how-to.asciidoc | 185 ++++++++++++++++++++++++++++++++ 2 files changed, 211 insertions(+) create mode 100644 docs/how-to.asciidoc create mode 100644 docs/source-map-how-to.asciidoc diff --git a/docs/how-to.asciidoc b/docs/how-to.asciidoc new file mode 100644 index 0000000000..3969a2ef93 --- /dev/null +++ b/docs/how-to.asciidoc @@ -0,0 +1,26 @@ +[[how-to-guides]] += How-to guides + +Learn how to perform common APM configuration and management tasks. + +// * <> +// * <> +// * <> +// * <<{beatname_lc}-template>> +// * <> +// * <> +// * <> + +// include::./sourcemaps.asciidoc[] + +// include::./ilm.asciidoc[] + +// include::./jaeger-support.asciidoc[] + +// include::{libbeat-dir}/howto/load-index-templates.asciidoc[] + +// include::./storage-management.asciidoc[] + +// include::./configuring-ingest.asciidoc[] + +// include::./data-ingestion.asciidoc[] diff --git a/docs/source-map-how-to.asciidoc b/docs/source-map-how-to.asciidoc new file mode 100644 index 0000000000..623339c892 --- /dev/null +++ b/docs/source-map-how-to.asciidoc @@ -0,0 +1,185 @@ +[[source-map-how-to]] +== How to apply source maps to error stack traces when using minified bundles + +++++ +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: + +// * <> +// * <>. +// * <>. From a41b639f5d3d389147ed918f0cb63c64a909acc8 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Fri, 15 Oct 2021 14:26:27 -0700 Subject: [PATCH 02/19] docs: add placeholder ILM topic --- docs/how-to.asciidoc | 8 ++++---- docs/ilm-how-to.asciidoc | 18 ++++++++++++++++++ 2 files changed, 22 insertions(+), 4 deletions(-) create mode 100644 docs/ilm-how-to.asciidoc diff --git a/docs/how-to.asciidoc b/docs/how-to.asciidoc index 3969a2ef93..84755ee8ad 100644 --- a/docs/how-to.asciidoc +++ b/docs/how-to.asciidoc @@ -3,17 +3,17 @@ Learn how to perform common APM configuration and management tasks. -// * <> -// * <> +* <> +* <> // * <> // * <<{beatname_lc}-template>> // * <> // * <> // * <> -// include::./sourcemaps.asciidoc[] +include::./source-map-how-to.asciidoc[] -// include::./ilm.asciidoc[] +include::./ilm-how-to.asciidoc[] // include::./jaeger-support.asciidoc[] diff --git a/docs/ilm-how-to.asciidoc b/docs/ilm-how-to.asciidoc new file mode 100644 index 0000000000..4cd67352e5 --- /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. From b704a80f09611b8e8ca6b498b3d53022301f3787 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Fri, 15 Oct 2021 15:41:26 -0700 Subject: [PATCH 03/19] docs: add manage storage --- docs/how-to.asciidoc | 6 +- docs/integrations-index.asciidoc | 2 + docs/manage-storage.asciidoc | 280 +++++++++++++++++++++++++++++++ docs/source-map-how-to.asciidoc | 2 +- 4 files changed, 286 insertions(+), 4 deletions(-) create mode 100644 docs/manage-storage.asciidoc diff --git a/docs/how-to.asciidoc b/docs/how-to.asciidoc index 84755ee8ad..53ee2d1f6f 100644 --- a/docs/how-to.asciidoc +++ b/docs/how-to.asciidoc @@ -1,5 +1,5 @@ [[how-to-guides]] -= How-to guides +== How-to guides Learn how to perform common APM configuration and management tasks. @@ -7,7 +7,7 @@ Learn how to perform common APM configuration and management tasks. * <> // * <> // * <<{beatname_lc}-template>> -// * <> +* <> // * <> // * <> @@ -19,7 +19,7 @@ include::./ilm-how-to.asciidoc[] // include::{libbeat-dir}/howto/load-index-templates.asciidoc[] -// include::./storage-management.asciidoc[] +include::./manage-storage.asciidoc[] // include::./configuring-ingest.asciidoc[] diff --git a/docs/integrations-index.asciidoc b/docs/integrations-index.asciidoc index 2b7a46e143..7fb8769638 100644 --- a/docs/integrations-index.asciidoc +++ b/docs/integrations-index.asciidoc @@ -19,6 +19,8 @@ include::data-model.asciidoc[] include::features.asciidoc[] +include::how-to.asciidoc[] + include::troubleshoot-apm.asciidoc[] include::apm-breaking.asciidoc[] diff --git a/docs/manage-storage.asciidoc b/docs/manage-storage.asciidoc new file mode 100644 index 0000000000..299318bae5 --- /dev/null +++ b/docs/manage-storage.asciidoc @@ -0,0 +1,280 @@ +[[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-with-curator]] +===== Delete data periodically + +To delete data periodically you can use {curator-ref-current}[Curator] and set up a cron job to run it. + +By default, APM indices have the pattern `apm-%{[observer.version]}-{type}-%{+yyyy.MM.dd}`. +With the curator command line interface you can, for instance, see all your existing indices: + +["source","sh",subs="attributes"] +------------------------------------------------------------ +curator_cli --host localhost show_indices --filter_list '[{"filtertype":"pattern","kind":"prefix","value":"apm-"}]' + +apm-{version}-error-{sample_date_0} +apm-{version}-error-{sample_date_1} +apm-{version}-error-{sample_date_2} +apm-{version}-sourcemap +apm-{version}-span-{sample_date_0} +apm-{version}-span-{sample_date_1} +apm-{version}-span-{sample_date_2} +apm-{version}-transaction-{sample_date_0} +apm-{version}-transaction-{sample_date_1} +apm-{version}-transaction-{sample_date_2} +------------------------------------------------------------ + +And then delete any span indices older than 1 day: + +["source","sh",subs="attributes"] +------------------------------------------------------------ +curator_cli --host localhost delete_indices --filter_list '[{"filtertype":"pattern","kind":"prefix","value":"apm-{version}-span-"}, {"filtertype":"age","source":"name","timestring":"%Y.%m.%d","unit":"days","unit_count":1,"direction":"older"}]' + +INFO Deleting selected indices: [apm-{version}-span-{sample_date_0}, apm-{version}-span-{sample_date_1}] +INFO ---deleting index apm-{version}-span-{sample_date_0} +INFO ---deleting index apm-{version}-span-{sample_date_1} +INFO "delete_indices" action completed. +------------------------------------------------------------ + +[float] +[[delete-data-query]] +===== Delete data matching a query + +You can delete documents matching a specific query. +For example, all documents with a given `context.service.name` use the following request: + +["source","sh"] +------------------------------------------------------------ +POST /apm-*/_delete_by_query +{ + "query": { + "bool": { + "must": [ + { + "term": { + "context.service.name": { + "value": "old-service-name" + } + } + } + ] + } + } +} +------------------------------------------------------------ + +See {ref}/docs-delete-by-query.html[delete by query] for further information on this topic. + +[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 {kibana-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 +{ + "query": { + "term": { + "context.service.name": { + "value": "old-service-name" + } + } + }, + "script": { + "source": "ctx._source.context.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/source-map-how-to.asciidoc b/docs/source-map-how-to.asciidoc index 623339c892..4940a2d4ed 100644 --- a/docs/source-map-how-to.asciidoc +++ b/docs/source-map-how-to.asciidoc @@ -1,5 +1,5 @@ [[source-map-how-to]] -== How to apply source maps to error stack traces when using minified bundles +=== How to apply source maps to error stack traces when using minified bundles ++++ Create and upload source maps (RUM) From 21e5625bdeffd34cb9fd1f9b804c8ce50df4ee94 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Mon, 18 Oct 2021 14:23:36 -0700 Subject: [PATCH 04/19] docs: add pipeline and es tuning docs --- docs/apm-tune-elasticsearch.asciidoc | 22 ++++++++++++++++++++++ docs/how-to.asciidoc | 10 +++++----- docs/ingest-pipelines.asciidoc | 21 +++++++++++++++++++++ docs/integrations-index.asciidoc | 4 ++++ docs/manage-storage.asciidoc | 2 +- 5 files changed, 53 insertions(+), 6 deletions(-) create mode 100644 docs/apm-tune-elasticsearch.asciidoc create mode 100644 docs/ingest-pipelines.asciidoc diff --git a/docs/apm-tune-elasticsearch.asciidoc b/docs/apm-tune-elasticsearch.asciidoc new file mode 100644 index 0000000000..5d42654fa0 --- /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/how-to.asciidoc b/docs/how-to.asciidoc index 53ee2d1f6f..1cbd88e9d7 100644 --- a/docs/how-to.asciidoc +++ b/docs/how-to.asciidoc @@ -7,9 +7,9 @@ Learn how to perform common APM configuration and management tasks. * <> // * <> // * <<{beatname_lc}-template>> +* <> * <> -// * <> -// * <> +* <> include::./source-map-how-to.asciidoc[] @@ -19,8 +19,8 @@ include::./ilm-how-to.asciidoc[] // include::{libbeat-dir}/howto/load-index-templates.asciidoc[] -include::./manage-storage.asciidoc[] +include::./ingest-pipelines.asciidoc[] -// include::./configuring-ingest.asciidoc[] +include::./manage-storage.asciidoc[] -// include::./data-ingestion.asciidoc[] +include::./apm-tune-elasticsearch.asciidoc[] diff --git a/docs/ingest-pipelines.asciidoc b/docs/ingest-pipelines.asciidoc new file mode 100644 index 0000000000..2376ed4be7 --- /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/integrations-index.asciidoc b/docs/integrations-index.asciidoc index 7fb8769638..fa634717c6 100644 --- a/docs/integrations-index.asciidoc +++ b/docs/integrations-index.asciidoc @@ -7,6 +7,10 @@ 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[] diff --git a/docs/manage-storage.asciidoc b/docs/manage-storage.asciidoc index 299318bae5..832c2b6dfa 100644 --- a/docs/manage-storage.asciidoc +++ b/docs/manage-storage.asciidoc @@ -162,7 +162,7 @@ or in the {kibana-ref}/managing-indices.html[Kibana Index Management UI]. 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. +See <> to learn more. [float] [[delete-data-with-curator]] From b07054eadb17bb4cbd56ea6c21ca369c9bc4f987 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Mon, 18 Oct 2021 16:10:51 -0700 Subject: [PATCH 05/19] docs: add jaeger --- docs/how-to.asciidoc | 7 +- docs/jaeger-integration.asciidoc | 112 ++++++++++++++++++++++ docs/shared/jaeger/jaeger-widget.asciidoc | 40 ++++++++ docs/shared/jaeger/jaeger.asciidoc | 59 ++++++++++++ 4 files changed, 213 insertions(+), 5 deletions(-) create mode 100644 docs/jaeger-integration.asciidoc create mode 100644 docs/shared/jaeger/jaeger-widget.asciidoc create mode 100644 docs/shared/jaeger/jaeger.asciidoc diff --git a/docs/how-to.asciidoc b/docs/how-to.asciidoc index 1cbd88e9d7..428d086cf5 100644 --- a/docs/how-to.asciidoc +++ b/docs/how-to.asciidoc @@ -5,8 +5,7 @@ Learn how to perform common APM configuration and management tasks. * <> * <> -// * <> -// * <<{beatname_lc}-template>> +* <> * <> * <> * <> @@ -15,9 +14,7 @@ include::./source-map-how-to.asciidoc[] include::./ilm-how-to.asciidoc[] -// include::./jaeger-support.asciidoc[] - -// include::{libbeat-dir}/howto/load-index-templates.asciidoc[] +include::./jaeger-integration.asciidoc[] include::./ingest-pipelines.asciidoc[] diff --git a/docs/jaeger-integration.asciidoc b/docs/jaeger-integration.asciidoc new file mode 100644 index 0000000000..1a4bb15fd7 --- /dev/null +++ b/docs/jaeger-integration.asciidoc @@ -0,0 +1,112 @@ +[[jaeger-integration]] +== Jaeger integration + +++++ +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.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: + +* <> +* <> +* <> + +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::../tab-widgets/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] +[[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]. diff --git a/docs/shared/jaeger/jaeger-widget.asciidoc b/docs/shared/jaeger/jaeger-widget.asciidoc new file mode 100644 index 0000000000..5902738ca3 --- /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 0000000000..6161acc855 --- /dev/null +++ b/docs/shared/jaeger/jaeger.asciidoc @@ -0,0 +1,59 @@ +// tag::ess[] +. Log into {ess-console}[Elastic Cloud] and select your deployment. +Open {kib} and navigate to: +**Integrations** > **Elastic APM** > **Add Elastic APM**. +Copy the host and secret token; you'll need these in the next step. + +. 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.22/cli/[Jaeger CLI flags documentation] for more information. + +// end::ess[] + +// tag::self-managed[] +. Configure the APM Integration as a collector for your Jaeger agents. ++ +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.22/cli/[Jaeger CLI flags documentation] for more information. + +// end::self-managed[] From 3b3f229092e63d6ccef6d45bacebae06faca383b Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Mon, 18 Oct 2021 16:29:12 -0700 Subject: [PATCH 06/19] docs: fixes --- docs/apm-package/apm-integration.asciidoc | 4 ---- docs/apm-quick-start.asciidoc | 11 +++++++++++ docs/integrations-index.asciidoc | 6 +++--- docs/jaeger-integration.asciidoc | 6 +++--- 4 files changed, 17 insertions(+), 10 deletions(-) create mode 100644 docs/apm-quick-start.asciidoc diff --git a/docs/apm-package/apm-integration.asciidoc b/docs/apm-package/apm-integration.asciidoc index b5db27a6fb..31aa8aae71 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 0000000000..e6cae77df0 --- /dev/null +++ b/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 diff --git a/docs/integrations-index.asciidoc b/docs/integrations-index.asciidoc index fa634717c6..9acb27378c 100644 --- a/docs/integrations-index.asciidoc +++ b/docs/integrations-index.asciidoc @@ -15,9 +15,7 @@ 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[] @@ -25,6 +23,8 @@ include::features.asciidoc[] include::how-to.asciidoc[] +include::input-apm.asciidoc[] + include::troubleshoot-apm.asciidoc[] include::apm-breaking.asciidoc[] diff --git a/docs/jaeger-integration.asciidoc b/docs/jaeger-integration.asciidoc index 1a4bb15fd7..d6c8b77b26 100644 --- a/docs/jaeger-integration.asciidoc +++ b/docs/jaeger-integration.asciidoc @@ -1,5 +1,5 @@ [[jaeger-integration]] -== Jaeger integration +=== Jaeger integration ++++ Integrate with Jaeger @@ -47,7 +47,7 @@ IMPORTANT: There are <> to this integration. The APM integration serves Jaeger gRPC over the same host and port as the Elastic APM agent protocol. -include::../tab-widgets/jaeger-widget.asciidoc[] +include::./shared/jaeger/jaeger-widget.asciidoc[] [float] [[configure-sampling-jaeger]] @@ -63,7 +63,7 @@ There are two different ways to configure the sampling rate of your Jaeger agent * <> [float] -[[sampling-central-jaeger]] +[[configure-sampling-central-jaeger]] ===== APM Agent central configuration (default) Central sampling, with APM Agent central configuration, From 5517e092d806a162c6a38eb94bd3a82d31466d4c Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Mon, 18 Oct 2021 16:29:21 -0700 Subject: [PATCH 07/19] docs: move input settings --- docs/{apm-package => }/apm-input-settings.asciidoc | 0 docs/{apm-package => }/input-apm.asciidoc | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename docs/{apm-package => }/apm-input-settings.asciidoc (100%) rename docs/{apm-package => }/input-apm.asciidoc (100%) diff --git a/docs/apm-package/apm-input-settings.asciidoc b/docs/apm-input-settings.asciidoc similarity index 100% rename from docs/apm-package/apm-input-settings.asciidoc rename to docs/apm-input-settings.asciidoc diff --git a/docs/apm-package/input-apm.asciidoc b/docs/input-apm.asciidoc similarity index 100% rename from docs/apm-package/input-apm.asciidoc rename to docs/input-apm.asciidoc From a1999e33405ba2e028efda09db8dc3c8bf2f821a Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Mon, 18 Oct 2021 16:56:59 -0700 Subject: [PATCH 08/19] docs: fix doc build --- docs/manage-storage.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/manage-storage.asciidoc b/docs/manage-storage.asciidoc index 832c2b6dfa..4e3f6e32bd 100644 --- a/docs/manage-storage.asciidoc +++ b/docs/manage-storage.asciidoc @@ -241,7 +241,7 @@ Then click **delete indices**. [[manage-indices-in-kibana]] === Manage Indices via Kibana -Kibana's {kibana-ref}/index-mgmt.html[index management] allows you to manage your cluster's +Kibana's {ref}/index-mgmt.html[index management] allows you to manage your cluster's indices, data streams, index templates, and much more. [float] From 6d74877655f58000916aa9e60453d90380ac254c Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Mon, 18 Oct 2021 17:58:15 -0700 Subject: [PATCH 09/19] docs: add upgrade page for broken links --- docs/integrations-index.asciidoc | 2 ++ docs/upgrade.asciidoc | 4 ++++ 2 files changed, 6 insertions(+) create mode 100644 docs/upgrade.asciidoc diff --git a/docs/integrations-index.asciidoc b/docs/integrations-index.asciidoc index 9acb27378c..39d0fc361e 100644 --- a/docs/integrations-index.asciidoc +++ b/docs/integrations-index.asciidoc @@ -29,6 +29,8 @@ include::troubleshoot-apm.asciidoc[] include::apm-breaking.asciidoc[] +include::upgrade.asciidoc[] + // This includes the legacy APM Overview include::legacy/guide/index.asciidoc[] diff --git a/docs/upgrade.asciidoc b/docs/upgrade.asciidoc new file mode 100644 index 0000000000..57d693be93 --- /dev/null +++ b/docs/upgrade.asciidoc @@ -0,0 +1,4 @@ +[[upgrade]] +== Upgrade + +// placeholder \ No newline at end of file From f83246e304a3ae3d2166ac583af9caa651aa34a0 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 20 Oct 2021 11:43:50 -0700 Subject: [PATCH 10/19] docs: clean it up --- docs/data-streams.asciidoc | 4 +++ docs/integrations-index.asciidoc | 2 ++ docs/manage-storage.asciidoc | 49 ++++---------------------------- 3 files changed, 12 insertions(+), 43 deletions(-) create mode 100644 docs/data-streams.asciidoc diff --git a/docs/data-streams.asciidoc b/docs/data-streams.asciidoc new file mode 100644 index 0000000000..0db0c1449b --- /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/integrations-index.asciidoc b/docs/integrations-index.asciidoc index 39d0fc361e..e5a8fa419f 100644 --- a/docs/integrations-index.asciidoc +++ b/docs/integrations-index.asciidoc @@ -25,6 +25,8 @@ include::how-to.asciidoc[] include::input-apm.asciidoc[] +include::data-streams.asciidoc[] + include::troubleshoot-apm.asciidoc[] include::apm-breaking.asciidoc[] diff --git a/docs/manage-storage.asciidoc b/docs/manage-storage.asciidoc index 4e3f6e32bd..d8eb0457aa 100644 --- a/docs/manage-storage.asciidoc +++ b/docs/manage-storage.asciidoc @@ -164,43 +164,6 @@ Index Lifecycle management (ILM) enables you to automate how you want to manage You can base actions on factors such as shard size and performance requirements. See <> to learn more. -[float] -[[delete-data-with-curator]] -===== Delete data periodically - -To delete data periodically you can use {curator-ref-current}[Curator] and set up a cron job to run it. - -By default, APM indices have the pattern `apm-%{[observer.version]}-{type}-%{+yyyy.MM.dd}`. -With the curator command line interface you can, for instance, see all your existing indices: - -["source","sh",subs="attributes"] ------------------------------------------------------------- -curator_cli --host localhost show_indices --filter_list '[{"filtertype":"pattern","kind":"prefix","value":"apm-"}]' - -apm-{version}-error-{sample_date_0} -apm-{version}-error-{sample_date_1} -apm-{version}-error-{sample_date_2} -apm-{version}-sourcemap -apm-{version}-span-{sample_date_0} -apm-{version}-span-{sample_date_1} -apm-{version}-span-{sample_date_2} -apm-{version}-transaction-{sample_date_0} -apm-{version}-transaction-{sample_date_1} -apm-{version}-transaction-{sample_date_2} ------------------------------------------------------------- - -And then delete any span indices older than 1 day: - -["source","sh",subs="attributes"] ------------------------------------------------------------- -curator_cli --host localhost delete_indices --filter_list '[{"filtertype":"pattern","kind":"prefix","value":"apm-{version}-span-"}, {"filtertype":"age","source":"name","timestring":"%Y.%m.%d","unit":"days","unit_count":1,"direction":"older"}]' - -INFO Deleting selected indices: [apm-{version}-span-{sample_date_0}, apm-{version}-span-{sample_date_1}] -INFO ---deleting index apm-{version}-span-{sample_date_0} -INFO ---deleting index apm-{version}-span-{sample_date_1} -INFO "delete_indices" action completed. ------------------------------------------------------------- - [float] [[delete-data-query]] ===== Delete data matching a query @@ -210,14 +173,14 @@ For example, all documents with a given `context.service.name` use the following ["source","sh"] ------------------------------------------------------------ -POST /apm-*/_delete_by_query +POST /*-apm-*/_delete_by_query { "query": { "bool": { "must": [ { "term": { - "context.service.name": { + "service.name": { "value": "old-service-name" } } @@ -260,17 +223,17 @@ To rename a service, send the following request: ["source","sh"] ------------------------------------------------------------ -POST /apm-*/_update_by_query +POST *-apm-*/_update_by_query { "query": { "term": { - "context.service.name": { - "value": "old-service-name" + "service.name": { + "value": "current-service-name" } } }, "script": { - "source": "ctx._source.context.service.name = 'new-service-name'", + "source": "ctx._source.service.name = 'new-service-name'", "lang": "painless" } } From b1d4b78d26339e6623178ea4d145add51bea451d Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 20 Oct 2021 12:00:46 -0700 Subject: [PATCH 11/19] docs: update more jaeger --- docs/jaeger-integration.asciidoc | 4 ++-- docs/shared/jaeger/jaeger.asciidoc | 17 +++++++++++------ 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/jaeger-integration.asciidoc b/docs/jaeger-integration.asciidoc index d6c8b77b26..ec23679959 100644 --- a/docs/jaeger-integration.asciidoc +++ b/docs/jaeger-integration.asciidoc @@ -26,7 +26,7 @@ SSL settings will automatically be applied to the APM integration's Jaeger gRPC * 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.22/architecture[Jaeger docs] +See the https://www.jaegertracing.io/docs/1.27/architecture[Jaeger docs] for more information on Jaeger architecture. [float] @@ -78,7 +78,7 @@ See {kibana-ref}/agent-configuration.html[Central configuration] to learn more. 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] +See the official https://www.jaegertracing.io/docs/1.27/sampling/[Jaeger sampling documentation] for more information. [float] diff --git a/docs/shared/jaeger/jaeger.asciidoc b/docs/shared/jaeger/jaeger.asciidoc index 6161acc855..8bdda6f51f 100644 --- a/docs/shared/jaeger/jaeger.asciidoc +++ b/docs/shared/jaeger/jaeger.asciidoc @@ -1,8 +1,9 @@ // tag::ess[] . Log into {ess-console}[Elastic Cloud] and select your deployment. -Open {kib} and navigate to: -**Integrations** > **Elastic APM** > **Add Elastic APM**. -Copy the host and secret token; you'll need these in the next step. +Open {kib} and navigate to: **Fleet** > **Agent polices**. +Select the policy that has the Elastic APM Integration installed, +then select **Actions** > **Edit Integraiton**. +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. + @@ -12,18 +13,22 @@ which can be used to enable TLS, output to {ecloud}, and set the APM Integration [source,terminal] ---- --reporter.grpc.tls.enabled=true ---reporter.grpc.host-port= +--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.22/cli/[Jaeger CLI flags documentation] for more information. +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. +Open {kib} and navigate to: **Fleet** > **Agent polices**. +Select the policy that has the Elastic APM Integration installed, +then select **Actions** > **Edit Integraiton**. +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: @@ -54,6 +59,6 @@ When enabled, use an agent level tag to authorize Jaeger agent communication wit 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.22/cli/[Jaeger CLI flags documentation] for more information. +See the https://www.jaegertracing.io/docs/1.27/cli/[Jaeger CLI flags documentation] for more information. // end::self-managed[] From be00f221a7be617b634fa76728bd739332c4ed71 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Mon, 25 Oct 2021 14:52:35 -0700 Subject: [PATCH 12/19] docs: update input settings for 7.16 --- docs/apm-input-settings.asciidoc | 313 +++++++++++++++++++++++++------ docs/input-apm.asciidoc | 76 ++++---- 2 files changed, 288 insertions(+), 101 deletions(-) diff --git a/docs/apm-input-settings.asciidoc b/docs/apm-input-settings.asciidoc index 81b89dafe2..e12f49d4bc 100644 --- a/docs/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/input-apm.asciidoc b/docs/input-apm.asciidoc index d1e47cd58c..0b5624cd66 100644 --- a/docs/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* Date: Mon, 25 Oct 2021 14:54:57 -0700 Subject: [PATCH 13/19] docs: update config instructions --- docs/input-apm.asciidoc | 2 +- docs/shared/jaeger/jaeger.asciidoc | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/input-apm.asciidoc b/docs/input-apm.asciidoc index 0b5624cd66..b9199cac92 100644 --- a/docs/input-apm.asciidoc +++ b/docs/input-apm.asciidoc @@ -7,7 +7,7 @@ Input settings ++++ -To edit the APM integration input settings, open {kib}, select `Add data`, +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**. diff --git a/docs/shared/jaeger/jaeger.asciidoc b/docs/shared/jaeger/jaeger.asciidoc index 8bdda6f51f..9502729e1d 100644 --- a/docs/shared/jaeger/jaeger.asciidoc +++ b/docs/shared/jaeger/jaeger.asciidoc @@ -1,8 +1,8 @@ // tag::ess[] . Log into {ess-console}[Elastic Cloud] and select your deployment. -Open {kib} and navigate to: **Fleet** > **Agent polices**. -Select the policy that has the Elastic APM Integration installed, -then select **Actions** > **Edit Integraiton**. +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. @@ -25,9 +25,9 @@ See the https://www.jaegertracing.io/docs/1.27/cli/[Jaeger CLI flags documentati // tag::self-managed[] . Configure the APM Integration as a collector for your Jaeger agents. -Open {kib} and navigate to: **Fleet** > **Agent polices**. -Select the policy that has the Elastic APM Integration installed, -then select **Actions** > **Edit Integraiton**. +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. From aae58d80f578530155df991a0fd539fcd18eab14 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 27 Oct 2021 13:37:53 -0700 Subject: [PATCH 14/19] docs: fix merge conflict --- docs/integrations-index.asciidoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/integrations-index.asciidoc b/docs/integrations-index.asciidoc index c650300c0c..2cc3364dff 100644 --- a/docs/integrations-index.asciidoc +++ b/docs/integrations-index.asciidoc @@ -42,6 +42,8 @@ include::apm-breaking.asciidoc[] include::upgrade.asciidoc[] +include::release-notes.asciidoc[leveloffset=+1] + // This includes the legacy APM Overview include::legacy/guide/index.asciidoc[] From 31b51fcc8381cb4e574defaca076fb288d3a889a Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 27 Oct 2021 15:36:17 -0700 Subject: [PATCH 15/19] docs: move legacy tab widgets to legacy folder --- docs/apm-distributed-tracing.asciidoc | 4 ++-- docs/legacy/guide/distributed-tracing.asciidoc | 4 ++-- docs/legacy/guide/install-and-run.asciidoc | 10 +++++----- docs/legacy/guide/opentelemetry-elastic.asciidoc | 2 +- docs/legacy/jaeger-support.asciidoc | 4 ++-- .../tab-widgets/configure-agent-widget.asciidoc | 0 docs/{ => legacy}/tab-widgets/configure-agent.asciidoc | 0 .../tab-widgets/configure-server-widget.asciidoc | 0 .../{ => legacy}/tab-widgets/configure-server.asciidoc | 0 .../tab-widgets/install-agents-widget.asciidoc | 0 docs/{ => legacy}/tab-widgets/install-agents.asciidoc | 0 .../tab-widgets/jaeger-sampling-widget.asciidoc | 0 docs/{ => legacy}/tab-widgets/jaeger-sampling.asciidoc | 0 docs/{ => legacy}/tab-widgets/jaeger-widget.asciidoc | 0 docs/{ => legacy}/tab-widgets/jaeger.asciidoc | 0 .../tab-widgets/spin-up-stack-widget.asciidoc | 0 docs/{ => legacy}/tab-widgets/spin-up-stack.asciidoc | 0 docs/open-telemetry.asciidoc | 2 +- .../distributed-trace-receive-widget.asciidoc | 0 .../distributed-trace-receive.asciidoc | 0 .../distributed-trace-send-widget.asciidoc | 0 .../distributed-trace-send.asciidoc | 0 .../open-kibana}/open-kibana-widget.asciidoc | 0 .../open-kibana}/open-kibana.asciidoc | 0 24 files changed, 13 insertions(+), 13 deletions(-) rename docs/{ => legacy}/tab-widgets/configure-agent-widget.asciidoc (100%) rename docs/{ => legacy}/tab-widgets/configure-agent.asciidoc (100%) rename docs/{ => legacy}/tab-widgets/configure-server-widget.asciidoc (100%) rename docs/{ => legacy}/tab-widgets/configure-server.asciidoc (100%) rename docs/{ => legacy}/tab-widgets/install-agents-widget.asciidoc (100%) rename docs/{ => legacy}/tab-widgets/install-agents.asciidoc (100%) rename docs/{ => legacy}/tab-widgets/jaeger-sampling-widget.asciidoc (100%) rename docs/{ => legacy}/tab-widgets/jaeger-sampling.asciidoc (100%) rename docs/{ => legacy}/tab-widgets/jaeger-widget.asciidoc (100%) rename docs/{ => legacy}/tab-widgets/jaeger.asciidoc (100%) rename docs/{ => legacy}/tab-widgets/spin-up-stack-widget.asciidoc (100%) rename docs/{ => legacy}/tab-widgets/spin-up-stack.asciidoc (100%) rename docs/{tab-widgets => shared/distributed-trace-receive}/distributed-trace-receive-widget.asciidoc (100%) rename docs/{tab-widgets => shared/distributed-trace-receive}/distributed-trace-receive.asciidoc (100%) rename docs/{tab-widgets => shared/distributed-trace-send}/distributed-trace-send-widget.asciidoc (100%) rename docs/{tab-widgets => shared/distributed-trace-send}/distributed-trace-send.asciidoc (100%) rename docs/{tab-widgets => shared/open-kibana}/open-kibana-widget.asciidoc (100%) rename docs/{tab-widgets => shared/open-kibana}/open-kibana.asciidoc (100%) diff --git a/docs/apm-distributed-tracing.asciidoc b/docs/apm-distributed-tracing.asciidoc index 937094c54b..19fb3c64e5 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/legacy/guide/distributed-tracing.asciidoc b/docs/legacy/guide/distributed-tracing.asciidoc index cb0e5cd40f..ce3e03d6e3 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 2ba72da231..d1965c4a39 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 f1950b988e..328ffb10bd 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 8b2588ba07..f7b89d300e 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/tab-widgets/configure-agent-widget.asciidoc b/docs/legacy/tab-widgets/configure-agent-widget.asciidoc similarity index 100% rename from docs/tab-widgets/configure-agent-widget.asciidoc rename to docs/legacy/tab-widgets/configure-agent-widget.asciidoc 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/tab-widgets/configure-server-widget.asciidoc b/docs/legacy/tab-widgets/configure-server-widget.asciidoc similarity index 100% rename from docs/tab-widgets/configure-server-widget.asciidoc rename to docs/legacy/tab-widgets/configure-server-widget.asciidoc 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/tab-widgets/install-agents-widget.asciidoc b/docs/legacy/tab-widgets/install-agents-widget.asciidoc similarity index 100% rename from docs/tab-widgets/install-agents-widget.asciidoc rename to docs/legacy/tab-widgets/install-agents-widget.asciidoc 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/open-telemetry.asciidoc b/docs/open-telemetry.asciidoc index 8ef147e4ce..4f5b3ee86e 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/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 From 4283eef4f419ec2b3342d00fe4cd36fd78a09f70 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 27 Oct 2021 15:40:25 -0700 Subject: [PATCH 16/19] docs: fix cross-doc includes --- docs/apm-quick-start.asciidoc | 5 +++++ docs/tab-widgets/configure-agent-widget.asciidoc | 1 + docs/tab-widgets/configure-server-widget.asciidoc | 1 + docs/tab-widgets/install-agent-widget.asciidoc | 1 + 4 files changed, 8 insertions(+) create mode 100644 docs/tab-widgets/configure-agent-widget.asciidoc create mode 100644 docs/tab-widgets/configure-server-widget.asciidoc create mode 100644 docs/tab-widgets/install-agent-widget.asciidoc diff --git a/docs/apm-quick-start.asciidoc b/docs/apm-quick-start.asciidoc index e6cae77df0..817a7c0b66 100644 --- a/docs/apm-quick-start.asciidoc +++ b/docs/apm-quick-start.asciidoc @@ -9,3 +9,8 @@ // * 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/tab-widgets/configure-agent-widget.asciidoc b/docs/tab-widgets/configure-agent-widget.asciidoc new file mode 100644 index 0000000000..af8e0cb523 --- /dev/null +++ b/docs/tab-widgets/configure-agent-widget.asciidoc @@ -0,0 +1 @@ +// 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 new file mode 100644 index 0000000000..af8e0cb523 --- /dev/null +++ b/docs/tab-widgets/configure-server-widget.asciidoc @@ -0,0 +1 @@ +// delete after PR in obs-docs repo \ No newline at end of file diff --git a/docs/tab-widgets/install-agent-widget.asciidoc b/docs/tab-widgets/install-agent-widget.asciidoc new file mode 100644 index 0000000000..af8e0cb523 --- /dev/null +++ b/docs/tab-widgets/install-agent-widget.asciidoc @@ -0,0 +1 @@ +// delete after PR in obs-docs repo \ No newline at end of file From e210291fe9d2922005f739248dcf47562f909818 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 27 Oct 2021 15:53:29 -0700 Subject: [PATCH 17/19] forgot the 's' --- ...stall-agent-widget.asciidoc => install-agents-widget.asciidoc} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/tab-widgets/{install-agent-widget.asciidoc => install-agents-widget.asciidoc} (100%) diff --git a/docs/tab-widgets/install-agent-widget.asciidoc b/docs/tab-widgets/install-agents-widget.asciidoc similarity index 100% rename from docs/tab-widgets/install-agent-widget.asciidoc rename to docs/tab-widgets/install-agents-widget.asciidoc From e752a59fe947d5f5e38b99942e8ea4b77dee604d Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 27 Oct 2021 16:04:49 -0700 Subject: [PATCH 18/19] docs: fix cross-doc includes --- docs/apm-breaking.asciidoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/apm-breaking.asciidoc b/docs/apm-breaking.asciidoc index 020986b019..933edc5d04 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 From a9f7eb342c9660de03b0b0eca6186e318ce098b3 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Fri, 29 Oct 2021 12:56:36 -0700 Subject: [PATCH 19/19] docs: feedback --- docs/manage-storage.asciidoc | 31 +------------------------------ docs/source-map-how-to.asciidoc | 6 +----- 2 files changed, 2 insertions(+), 35 deletions(-) diff --git a/docs/manage-storage.asciidoc b/docs/manage-storage.asciidoc index d8eb0457aa..d08b31b85d 100644 --- a/docs/manage-storage.asciidoc +++ b/docs/manage-storage.asciidoc @@ -164,35 +164,6 @@ Index Lifecycle management (ILM) enables you to automate how you want to manage You can base actions on factors such as shard size and performance requirements. See <> to learn more. -[float] -[[delete-data-query]] -===== Delete data matching a query - -You can delete documents matching a specific query. -For example, all documents with a given `context.service.name` use the following request: - -["source","sh"] ------------------------------------------------------------- -POST /*-apm-*/_delete_by_query -{ - "query": { - "bool": { - "must": [ - { - "term": { - "service.name": { - "value": "old-service-name" - } - } - } - ] - } - } -} ------------------------------------------------------------- - -See {ref}/docs-delete-by-query.html[delete by query] for further information on this topic. - [float] [[delete-data-in-kibana]] ===== Delete data via Kibana Index Management UI @@ -223,7 +194,7 @@ To rename a service, send the following request: ["source","sh"] ------------------------------------------------------------ -POST *-apm-*/_update_by_query +POST *-apm-*/_update_by_query?expand_wildcards=all { "query": { "term": { diff --git a/docs/source-map-how-to.asciidoc b/docs/source-map-how-to.asciidoc index 4940a2d4ed..ad118449b2 100644 --- a/docs/source-map-how-to.asciidoc +++ b/docs/source-map-how-to.asciidoc @@ -1,9 +1,5 @@ [[source-map-how-to]] -=== How to apply source maps to error stack traces when using minified bundles - -++++ -Create and upload source maps (RUM) -++++ +=== 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.