From eeba0984eac22cd711117c45b7f3dd4928e542a9 Mon Sep 17 00:00:00 2001 From: Brandon Morelli Date: Wed, 15 Jul 2020 10:50:23 -0700 Subject: [PATCH] docs: Instrumentation configuration (#19765) --- auditbeat/docs/configuring-howto.asciidoc | 3 + filebeat/docs/configuring-howto.asciidoc | 3 + heartbeat/docs/configuring-howto.asciidoc | 3 + journalbeat/docs/configuring-howto.asciidoc | 3 + libbeat/docs/shared-instrumentation.asciidoc | 91 +++++++++++++++++++ metricbeat/docs/configuring-howto.asciidoc | 3 + packetbeat/docs/configuring-howto.asciidoc | 3 + winlogbeat/docs/configuring-howto.asciidoc | 3 + .../docs/configuring-howto.asciidoc | 4 + 9 files changed, 116 insertions(+) create mode 100644 libbeat/docs/shared-instrumentation.asciidoc diff --git a/auditbeat/docs/configuring-howto.asciidoc b/auditbeat/docs/configuring-howto.asciidoc index f52e7abb0d6..745c58c7997 100644 --- a/auditbeat/docs/configuring-howto.asciidoc +++ b/auditbeat/docs/configuring-howto.asciidoc @@ -24,6 +24,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> * <> +* <> * <<{beatname_lc}-reference-yml>> After changing configuration settings, you need to restart {beatname_uc} to @@ -57,4 +58,6 @@ include::{libbeat-dir}/http-endpoint.asciidoc[] include::{libbeat-dir}/regexp.asciidoc[] +include::{libbeat-dir}/shared-instrumentation.asciidoc[] + include::{libbeat-dir}/reference-yml.asciidoc[] diff --git a/filebeat/docs/configuring-howto.asciidoc b/filebeat/docs/configuring-howto.asciidoc index 89a8f4b4f2d..ec70fe23942 100644 --- a/filebeat/docs/configuring-howto.asciidoc +++ b/filebeat/docs/configuring-howto.asciidoc @@ -27,6 +27,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> * <> +* <> * <<{beatname_lc}-reference-yml>> -- @@ -65,4 +66,6 @@ include::{libbeat-dir}/http-endpoint.asciidoc[] include::{libbeat-dir}/regexp.asciidoc[] +include::{libbeat-dir}/shared-instrumentation.asciidoc[] + include::{libbeat-dir}/reference-yml.asciidoc[] diff --git a/heartbeat/docs/configuring-howto.asciidoc b/heartbeat/docs/configuring-howto.asciidoc index 11b1bfcbcfd..f562b8a42c1 100644 --- a/heartbeat/docs/configuring-howto.asciidoc +++ b/heartbeat/docs/configuring-howto.asciidoc @@ -23,6 +23,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> * <> +* <> * <<{beatname_lc}-reference-yml>> -- @@ -59,4 +60,6 @@ include::{libbeat-dir}/http-endpoint.asciidoc[] include::{libbeat-dir}/regexp.asciidoc[] +include::{libbeat-dir}/shared-instrumentation.asciidoc[] + include::{libbeat-dir}/reference-yml.asciidoc[] diff --git a/journalbeat/docs/configuring-howto.asciidoc b/journalbeat/docs/configuring-howto.asciidoc index c813fa2d151..93083ac4ccc 100644 --- a/journalbeat/docs/configuring-howto.asciidoc +++ b/journalbeat/docs/configuring-howto.asciidoc @@ -21,6 +21,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> * <> +* <> * <<{beatname_lc}-reference-yml>> -- @@ -49,4 +50,6 @@ include::{libbeat-dir}/http-endpoint.asciidoc[] include::{libbeat-dir}/regexp.asciidoc[] +include::{libbeat-dir}/shared-instrumentation.asciidoc[] + include::{libbeat-dir}/reference-yml.asciidoc[] diff --git a/libbeat/docs/shared-instrumentation.asciidoc b/libbeat/docs/shared-instrumentation.asciidoc new file mode 100644 index 00000000000..9b3d72bfd67 --- /dev/null +++ b/libbeat/docs/shared-instrumentation.asciidoc @@ -0,0 +1,91 @@ +[[configuration-instrumentation]] +== Configure APM instrumentation + +++++ +Instrumentation +++++ + +Libbeat uses the Elastic APM Go Agent to instrument its publishing pipeline. +Currently, only the Elasticsearch output is instrumented. +To gain insight into the performance of {beatname_uc}, you can enable this instrumentation and send trace data to APM Server. + +Example configuration with instrumentation enabled: + +["source","yaml"] +---- +instrumentation: + enabled: true + environment: production + hosts: + - "http://localhost:8200" + api_key: L5ER6FEvjkmlfalBealQ3f3fLqf03fazfOV +---- + +[float] +=== Configuration options + +You can specify the following options in the `instrumentation` section of the +{beatname_lc}.yml+ config file: + +[float] +==== `enabled` + +Set to `true` to enable instrumentation of {beatname_uc}. +Defaults to `false`. + +[float] +==== `environment` + +Set the environment in which {beatname_uc} is running, for example, `staging`, `production`, `dev`, etc. +Environments can be filtered in the {kibana-ref}/xpack-apm.html[APM app]. + +[float] +==== `hosts` + +The {apm-server-ref-v}/getting-started-apm-server.html[APM Server] hosts to report instrumentation data to. +Defaults to `http://localhost:8200`. + +[float] +==== `api_key` + +{apm-server-ref-v}/api-key.html[API key] used to secure communication with the APM Server(s). +If `api_key` is set then `secret_token` will be ignored. + +[float] +==== `secret_token` + +{apm-server-ref-v}/secret-token.html[Secret token] used to secure communication with the APM Server(s). + +[float] +==== `profiling.cpu.enabled` + +Set to `true` to enable CPU profiling, where profile samples are recorded as events. + +This feature is experimental. + +[float] +==== `profiling.cpu.interval` + +Configure the CPU profiling interval. Defaults to `60s`. + +This feature is experimental. + +[float] +==== `profiling.cpu.duration` + +Configure the CPU profiling duration. Defaults to `10s`. + +This feature is experimental. + +[float] +==== `profiling.heap.enabled` + +Set to `true` to enable heap profiling. + +This feature is experimental. + +[float] +==== `profiling.heap.interval` + +Configure the heap profiling interval. Defaults to `60s`. + +This feature is experimental. diff --git a/metricbeat/docs/configuring-howto.asciidoc b/metricbeat/docs/configuring-howto.asciidoc index d379bb9e8f9..60f8928df53 100644 --- a/metricbeat/docs/configuring-howto.asciidoc +++ b/metricbeat/docs/configuring-howto.asciidoc @@ -25,6 +25,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> * <> +* <> * <<{beatname_lc}-reference-yml>> -- @@ -61,4 +62,6 @@ include::{libbeat-dir}/http-endpoint.asciidoc[] include::{libbeat-dir}/regexp.asciidoc[] +include::{libbeat-dir}/shared-instrumentation.asciidoc[] + include::{libbeat-dir}/reference-yml.asciidoc[] diff --git a/packetbeat/docs/configuring-howto.asciidoc b/packetbeat/docs/configuring-howto.asciidoc index 1975d3c7dcb..cc9e3c9a926 100644 --- a/packetbeat/docs/configuring-howto.asciidoc +++ b/packetbeat/docs/configuring-howto.asciidoc @@ -25,6 +25,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> * <> +* <> * <<{beatname_lc}-reference-yml>> -- @@ -51,4 +52,6 @@ include::{libbeat-dir}/loggingconfig.asciidoc[] include::{libbeat-dir}/http-endpoint.asciidoc[] +include::{libbeat-dir}/shared-instrumentation.asciidoc[] + include::{libbeat-dir}/reference-yml.asciidoc[] diff --git a/winlogbeat/docs/configuring-howto.asciidoc b/winlogbeat/docs/configuring-howto.asciidoc index d0447dc3099..5c1c6086ace 100644 --- a/winlogbeat/docs/configuring-howto.asciidoc +++ b/winlogbeat/docs/configuring-howto.asciidoc @@ -22,6 +22,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> * <> +* <> * <<{beatname_lc}-reference-yml>> -- @@ -48,4 +49,6 @@ include::{libbeat-dir}/loggingconfig.asciidoc[] include::{libbeat-dir}/http-endpoint.asciidoc[] +include::{libbeat-dir}/shared-instrumentation.asciidoc[] + include::{libbeat-dir}/reference-yml.asciidoc[] diff --git a/x-pack/functionbeat/docs/configuring-howto.asciidoc b/x-pack/functionbeat/docs/configuring-howto.asciidoc index ff0525cecb0..192cb79fea3 100644 --- a/x-pack/functionbeat/docs/configuring-howto.asciidoc +++ b/x-pack/functionbeat/docs/configuring-howto.asciidoc @@ -21,6 +21,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[] * <> * <> * <> +* <> * <<{beatname_lc}-reference-yml>> -- @@ -57,5 +58,8 @@ include::{libbeat-dir}/loggingconfig.asciidoc[] [role="xpack"] include::{libbeat-dir}/regexp.asciidoc[] +[role="xpack"] +include::{libbeat-dir}/shared-instrumentation.asciidoc[] + [role="xpack"] include::{libbeat-dir}/reference-yml.asciidoc[]