docs: Instrumentation configuration (#19765) (#19953)

elastic · Jul 21, 2020 · 69b6a3a · 69b6a3a
1 parent 4d0fcea
commit 69b6a3a
Show file tree

Hide file tree

Showing 9 changed files with 116 additions and 0 deletions.
diff --git a/auditbeat/docs/configuring-howto.asciidoc b/auditbeat/docs/configuring-howto.asciidoc
@@ -24,6 +24,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[]
 * <<configuration-logging>>
 * <<http-endpoint>>
 * <<regexp-support>>
+* <<configuration-instrumentation>>
 * <<{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
@@ -27,6 +27,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[]
 * <<configuration-logging>>
 * <<http-endpoint>>
 * <<regexp-support>>
+* <<configuration-instrumentation>>
 * <<{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
@@ -23,6 +23,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[]
 * <<configuration-logging>>
 * <<http-endpoint>>
 * <<regexp-support>>
+* <<configuration-instrumentation>>
 * <<{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
@@ -21,6 +21,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[]
 * <<configuration-logging>>
 * <<http-endpoint>>
 * <<regexp-support>>
+* <<configuration-instrumentation>>
 * <<{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
@@ -0,0 +1,91 @@
+[[configuration-instrumentation]]
+== Configure APM instrumentation
+
+++++
+<titleabbrev>Instrumentation</titleabbrev>
+++++
+
+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
@@ -25,6 +25,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[]
 * <<configuration-logging>>
 * <<http-endpoint>>
 * <<regexp-support>>
+* <<configuration-instrumentation>>
 * <<{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
@@ -25,6 +25,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[]
 * <<configuring-internal-queue>>
 * <<configuration-logging>>
 * <<http-endpoint>>
+* <<configuration-instrumentation>>
 * <<{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
@@ -22,6 +22,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[]
 * <<configuring-internal-queue>>
 * <<configuration-logging>>
 * <<http-endpoint>>
+* <<configuration-instrumentation>>
 * <<{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
@@ -21,6 +21,7 @@ include::{libbeat-dir}/shared/configuring-intro.asciidoc[]
 * <<configuring-internal-queue>>
 * <<configuration-logging>>
 * <<regexp-support>>
+* <<configuration-instrumentation>>
 * <<{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[]