From f39c31a46336f3b4210c70ebe81d8897f138ae4b Mon Sep 17 00:00:00 2001 From: Florian Lehner Date: Fri, 18 Oct 2024 12:07:13 +0200 Subject: [PATCH 1/4] profiling: add documentation for the config file Signed-off-by: Florian Lehner --- docs/en/observability/index.asciidoc | 1 + .../profiling-advanced-configuration.asciidoc | 17 +++++++++++ .../profiling-config-file.asciidoc | 30 +++++++++++++++++++ docs/en/observability/profiling-envs.asciidoc | 3 +- 4 files changed, 50 insertions(+), 1 deletion(-) create mode 100644 docs/en/observability/profiling-config-file.asciidoc diff --git a/docs/en/observability/index.asciidoc b/docs/en/observability/index.asciidoc index 0061ab6808..8a54f68fc2 100644 --- a/docs/en/observability/index.asciidoc +++ b/docs/en/observability/index.asciidoc @@ -145,6 +145,7 @@ include::profiling-add-symbols.asciidoc[leveloffset=+4] include::profiling-use-a-proxy.asciidoc[leveloffset=+4] include::profiling-no-kernel-version-check.asciidoc[leveloffset=+4] include::profiling-envs.asciidoc[leveloffset=+4] +include::profiling-config-file.asciidoc[leveloffset=+4] include::profiling-upgrade.asciidoc[leveloffset=+3] diff --git a/docs/en/observability/profiling-advanced-configuration.asciidoc b/docs/en/observability/profiling-advanced-configuration.asciidoc index 1cbf9562e3..5bf584eb7c 100644 --- a/docs/en/observability/profiling-advanced-configuration.asciidoc +++ b/docs/en/observability/profiling-advanced-configuration.asciidoc @@ -10,3 +10,20 @@ See the following sections for more information: * <>: Configure the Universal Profiling Agent to bypass the kernel version compatibility check. * <>: Configure the Universal Profiling Agent using the environment. +WARNING: Command line arguments to the Universal Profiling Agent have precedence over environment variables. And environment varaibles have precedence over configuration files. + +The Universal Profiling Agent accepts the following CLI arguments: + +[options="header"] +|================================== +| CLI argument | Type | Example | Description +| `-v` | `bool` | `-v` | Run the Universal Profiling Agent in verbose mode. +| `-no-kernel-version-check` | `bool` | `-no-kernel-version-check` | Disable the kernel version check. See <> for more details. +| `-tags` | `string` | `-tags='cloud_region:us-central1;env:staging'` | Set specific tags. See <> for more details. +| `-project-id` | `uint` | `-project-id 73` | Splits profiling data into logical groups that you control. You can assign any non-zero, unsigned integer <= 4095. +| `-secret-token` | `string` | `-secret-token=abc123` | Set the secret token for the communication with the Universal Profiling Collector to `abc123`. +| `-collection-agent` | `string` | `-collection-agent=example.com:443` | Set the destination for reporting profiling information to `example.com:443`. +| `-probabilistic-interval` | `duration` | `-probabilistic-interval=2m30s`| Set the probabilistic interval to `2m30s`. See <> for more details. +| `-probabilistic-threshold` | `uint` | `-probabilistic-threshold=50` | Set the probabilistic threshold to `50`. See <> for more details. +| `-config` | `string` | `-config=/opt/Elastic/universal-profiling/pf-host-agent.conf` | Set the path for the configuration file of the Universal Profiling Agent. See <> for more details. +|================================== \ No newline at end of file diff --git a/docs/en/observability/profiling-config-file.asciidoc b/docs/en/observability/profiling-config-file.asciidoc new file mode 100644 index 0000000000..e6372c7b5b --- /dev/null +++ b/docs/en/observability/profiling-config-file.asciidoc @@ -0,0 +1,30 @@ +[[profiling-config-file]] += Configuration file of the Universal Profiling Agent + +The Universal Profiling Agent can be configured using a configuration file. The path to the configuration file can be specified by the CLI argument `-config`. +By default `/etc/Elastic/universal-profiling/pf-host-agent.conf` is looked up as location for the configuration file. + +The expected format of the configuration file is a plaintext file, where each line holds one argument. + +Example: +[source] +---- +project-id: 73 +secret-token: abc123 +collection-agent: example.com:443 +---- + +WARNING: Command line arguments to the Universal Profiling Agent have precedence over environment variables. And environment varaibles have precedence over configuration files. + +[options="header"] +|================================== +| Config file argument | Type | Example | Description +| `verbose` | `bool` | `verbose: true` | Run the Universal Profiling Agent in verbose mode. +| `no-kernel-version-check` | `bool` | `no-kernel-version-check: true` | Disable the kernel version check. See <> for more details. +| `tags` | `string` | `tags: 'cloud_region:us-central1;env:staging'` | Set specific tags. See <> for more details. +| `project-id` | `uint` | `project-id: 73` | Splits profiling data into logical groups that you control. You can assign any non-zero, unsigned integer <= 4095. +| `secret-token` | `string` | `secret-token: abc123` | Set the secret token for the communication with the Universal Profiling Collector to `abc123`. +| `collection-agent` | `string` | `collection-agent: example.com:443` | Set the destination for reporting profiling information to `example.com:443`. +| `probabilistic-interval` | `duration` | `probabilistic-interval: 2m30s`| Set the probabilistic interval to `2m30s`. See <> for more details. +| `probabilistic-threshold` | `uint` | `probabilistic-threshold: 50` | Set the probabilistic threshold to `50`. See <> for more details. +|================================== \ No newline at end of file diff --git a/docs/en/observability/profiling-envs.asciidoc b/docs/en/observability/profiling-envs.asciidoc index eba9f1bcb5..0f2eb94c5d 100644 --- a/docs/en/observability/profiling-envs.asciidoc +++ b/docs/en/observability/profiling-envs.asciidoc @@ -3,7 +3,7 @@ The Universal Profiling Agent can be configured with environment variables. -WARNING: Command line arguments to the Universal Profiling Agent have precedence over environment variables. +WARNING: Command line arguments to the Universal Profiling Agent have precedence over environment variables. And environment varaibles have precedence over configuration files. [options="header"] |================================== @@ -16,4 +16,5 @@ WARNING: Command line arguments to the Universal Profiling Agent have precedence | `PRODFILER_COLLECTION_AGENT` | `PRODFILER_COLLECTION_AGENT=example.com:443` | Set the destination for reporting profiling information to `example.com:443`. | `PRODFILER_PROBABILISTIC_THRESHOLD` | `PRODFILER_PROBABILISTIC_THRESHOLD=50` | Set the probabilistic threshold to `50`. See <> for more details. | `PRODFILER_PROBABILISTIC_INTERVAL` |`PRODFILER_PROBABILISTIC_INTERVAL=2m30s` | Set the probabilistic interval to `2m30s`. See <> for more details. +| `PRODFILER_CONFIG` | `PRODFILER_CONFIG=/opt/Elastic/universal-profiling/pf-host-agent.conf` | Set the path for the configuration file of the Universal Profiling Agent. See <> for more details. |================================== From f2f397535e308c604ca6305a32697c517bcde5d5 Mon Sep 17 00:00:00 2001 From: Florian Lehner Date: Mon, 21 Oct 2024 09:58:34 +0200 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Christos Kalkanis --- .../en/observability/profiling-advanced-configuration.asciidoc | 3 ++- docs/en/observability/profiling-config-file.asciidoc | 2 +- docs/en/observability/profiling-envs.asciidoc | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/en/observability/profiling-advanced-configuration.asciidoc b/docs/en/observability/profiling-advanced-configuration.asciidoc index 5bf584eb7c..9bbb91dc47 100644 --- a/docs/en/observability/profiling-advanced-configuration.asciidoc +++ b/docs/en/observability/profiling-advanced-configuration.asciidoc @@ -10,7 +10,8 @@ See the following sections for more information: * <>: Configure the Universal Profiling Agent to bypass the kernel version compatibility check. * <>: Configure the Universal Profiling Agent using the environment. -WARNING: Command line arguments to the Universal Profiling Agent have precedence over environment variables. And environment varaibles have precedence over configuration files. +WARNING: Command line arguments to the Universal Profiling Agent have precedence over environment variables. And environment variables have precedence over the configuration file. + The Universal Profiling Agent accepts the following CLI arguments: diff --git a/docs/en/observability/profiling-config-file.asciidoc b/docs/en/observability/profiling-config-file.asciidoc index e6372c7b5b..9e51ce9612 100644 --- a/docs/en/observability/profiling-config-file.asciidoc +++ b/docs/en/observability/profiling-config-file.asciidoc @@ -14,7 +14,7 @@ secret-token: abc123 collection-agent: example.com:443 ---- -WARNING: Command line arguments to the Universal Profiling Agent have precedence over environment variables. And environment varaibles have precedence over configuration files. +WARNING: Command line arguments to the Universal Profiling Agent have precedence over environment variables. And environment variables have precedence over the configuration file. [options="header"] |================================== diff --git a/docs/en/observability/profiling-envs.asciidoc b/docs/en/observability/profiling-envs.asciidoc index 0f2eb94c5d..5613121a0e 100644 --- a/docs/en/observability/profiling-envs.asciidoc +++ b/docs/en/observability/profiling-envs.asciidoc @@ -3,7 +3,7 @@ The Universal Profiling Agent can be configured with environment variables. -WARNING: Command line arguments to the Universal Profiling Agent have precedence over environment variables. And environment varaibles have precedence over configuration files. +WARNING: Command line arguments to the Universal Profiling Agent have precedence over environment variables. And environment variables have precedence over the configuration file. [options="header"] |================================== From 0c3b63db33bd730022d9003003b27657a30c977f Mon Sep 17 00:00:00 2001 From: Florian Lehner Date: Wed, 23 Oct 2024 10:15:11 +0200 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Christos Kalkanis --- .../observability/profiling-advanced-configuration.asciidoc | 3 ++- docs/en/observability/profiling-config-file.asciidoc | 4 ++-- docs/en/observability/profiling-envs.asciidoc | 2 +- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/en/observability/profiling-advanced-configuration.asciidoc b/docs/en/observability/profiling-advanced-configuration.asciidoc index 9bbb91dc47..de3a4ff98b 100644 --- a/docs/en/observability/profiling-advanced-configuration.asciidoc +++ b/docs/en/observability/profiling-advanced-configuration.asciidoc @@ -26,5 +26,6 @@ The Universal Profiling Agent accepts the following CLI arguments: | `-collection-agent` | `string` | `-collection-agent=example.com:443` | Set the destination for reporting profiling information to `example.com:443`. | `-probabilistic-interval` | `duration` | `-probabilistic-interval=2m30s`| Set the probabilistic interval to `2m30s`. See <> for more details. | `-probabilistic-threshold` | `uint` | `-probabilistic-threshold=50` | Set the probabilistic threshold to `50`. See <> for more details. -| `-config` | `string` | `-config=/opt/Elastic/universal-profiling/pf-host-agent.conf` | Set the path for the configuration file of the Universal Profiling Agent. See <> for more details. +| `-config` | `string` | `-config=/etc/Elastic/universal-profiling/pf-host-agent.conf` | Set the path for the configuration file of the Universal Profiling Agent. See <> for more details. + |================================== \ No newline at end of file diff --git a/docs/en/observability/profiling-config-file.asciidoc b/docs/en/observability/profiling-config-file.asciidoc index 9e51ce9612..630c0da108 100644 --- a/docs/en/observability/profiling-config-file.asciidoc +++ b/docs/en/observability/profiling-config-file.asciidoc @@ -4,7 +4,7 @@ The Universal Profiling Agent can be configured using a configuration file. The path to the configuration file can be specified by the CLI argument `-config`. By default `/etc/Elastic/universal-profiling/pf-host-agent.conf` is looked up as location for the configuration file. -The expected format of the configuration file is a plaintext file, where each line holds one argument. +The expected format of the configuration file is a plaintext file, where each line holds one option. Example: [source] @@ -18,7 +18,7 @@ WARNING: Command line arguments to the Universal Profiling Agent have precedence [options="header"] |================================== -| Config file argument | Type | Example | Description +| Config file option | Type | Example | Description | `verbose` | `bool` | `verbose: true` | Run the Universal Profiling Agent in verbose mode. | `no-kernel-version-check` | `bool` | `no-kernel-version-check: true` | Disable the kernel version check. See <> for more details. | `tags` | `string` | `tags: 'cloud_region:us-central1;env:staging'` | Set specific tags. See <> for more details. diff --git a/docs/en/observability/profiling-envs.asciidoc b/docs/en/observability/profiling-envs.asciidoc index 5613121a0e..f31a378056 100644 --- a/docs/en/observability/profiling-envs.asciidoc +++ b/docs/en/observability/profiling-envs.asciidoc @@ -16,5 +16,5 @@ WARNING: Command line arguments to the Universal Profiling Agent have precedence | `PRODFILER_COLLECTION_AGENT` | `PRODFILER_COLLECTION_AGENT=example.com:443` | Set the destination for reporting profiling information to `example.com:443`. | `PRODFILER_PROBABILISTIC_THRESHOLD` | `PRODFILER_PROBABILISTIC_THRESHOLD=50` | Set the probabilistic threshold to `50`. See <> for more details. | `PRODFILER_PROBABILISTIC_INTERVAL` |`PRODFILER_PROBABILISTIC_INTERVAL=2m30s` | Set the probabilistic interval to `2m30s`. See <> for more details. -| `PRODFILER_CONFIG` | `PRODFILER_CONFIG=/opt/Elastic/universal-profiling/pf-host-agent.conf` | Set the path for the configuration file of the Universal Profiling Agent. See <> for more details. +| `PRODFILER_CONFIG` | `PRODFILER_CONFIG=/etc/Elastic/universal-profiling/pf-host-agent.conf` | Set the path for the configuration file of the Universal Profiling Agent. See <> for more details. |================================== From c40a07124f756d5ad62dbec523a79436d6a18fab Mon Sep 17 00:00:00 2001 From: Florian Lehner Date: Thu, 7 Nov 2024 13:35:15 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Mike Birnstiehl <114418652+mdbirnstiehl@users.noreply.github.com> --- .../profiling-advanced-configuration.asciidoc | 6 ++++-- docs/en/observability/profiling-config-file.asciidoc | 8 ++++---- docs/en/observability/profiling-envs.asciidoc | 2 +- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/en/observability/profiling-advanced-configuration.asciidoc b/docs/en/observability/profiling-advanced-configuration.asciidoc index de3a4ff98b..db1e9187c0 100644 --- a/docs/en/observability/profiling-advanced-configuration.asciidoc +++ b/docs/en/observability/profiling-advanced-configuration.asciidoc @@ -10,7 +10,8 @@ See the following sections for more information: * <>: Configure the Universal Profiling Agent to bypass the kernel version compatibility check. * <>: Configure the Universal Profiling Agent using the environment. -WARNING: Command line arguments to the Universal Profiling Agent have precedence over environment variables. And environment variables have precedence over the configuration file. +WARNING: Command line arguments to the Universal Profiling Agent take precedence over environment variables, and environment variables take precedence over the configuration file. + The Universal Profiling Agent accepts the following CLI arguments: @@ -22,7 +23,8 @@ The Universal Profiling Agent accepts the following CLI arguments: | `-no-kernel-version-check` | `bool` | `-no-kernel-version-check` | Disable the kernel version check. See <> for more details. | `-tags` | `string` | `-tags='cloud_region:us-central1;env:staging'` | Set specific tags. See <> for more details. | `-project-id` | `uint` | `-project-id 73` | Splits profiling data into logical groups that you control. You can assign any non-zero, unsigned integer <= 4095. -| `-secret-token` | `string` | `-secret-token=abc123` | Set the secret token for the communication with the Universal Profiling Collector to `abc123`. +| `-secret-token` | `string` | `-secret-token=abc123` | Set the secret token for communicating with the Universal Profiling Collector to `abc123`. + | `-collection-agent` | `string` | `-collection-agent=example.com:443` | Set the destination for reporting profiling information to `example.com:443`. | `-probabilistic-interval` | `duration` | `-probabilistic-interval=2m30s`| Set the probabilistic interval to `2m30s`. See <> for more details. | `-probabilistic-threshold` | `uint` | `-probabilistic-threshold=50` | Set the probabilistic threshold to `50`. See <> for more details. diff --git a/docs/en/observability/profiling-config-file.asciidoc b/docs/en/observability/profiling-config-file.asciidoc index 630c0da108..e737ced7ba 100644 --- a/docs/en/observability/profiling-config-file.asciidoc +++ b/docs/en/observability/profiling-config-file.asciidoc @@ -1,8 +1,8 @@ [[profiling-config-file]] = Configuration file of the Universal Profiling Agent -The Universal Profiling Agent can be configured using a configuration file. The path to the configuration file can be specified by the CLI argument `-config`. -By default `/etc/Elastic/universal-profiling/pf-host-agent.conf` is looked up as location for the configuration file. +The Universal Profiling Agent can be configured using a configuration file. Specify the path to the configuration file using the CLI argument `-config`. +The default path for the configuration file is `/etc/Elastic/universal-profiling/pf-host-agent.conf`. The expected format of the configuration file is a plaintext file, where each line holds one option. @@ -14,7 +14,7 @@ secret-token: abc123 collection-agent: example.com:443 ---- -WARNING: Command line arguments to the Universal Profiling Agent have precedence over environment variables. And environment variables have precedence over the configuration file. +WARNING: Command line arguments to the Universal Profiling Agent take precedence over environment variables, and environment variables take precedence over the configuration file. [options="header"] |================================== @@ -23,7 +23,7 @@ WARNING: Command line arguments to the Universal Profiling Agent have precedence | `no-kernel-version-check` | `bool` | `no-kernel-version-check: true` | Disable the kernel version check. See <> for more details. | `tags` | `string` | `tags: 'cloud_region:us-central1;env:staging'` | Set specific tags. See <> for more details. | `project-id` | `uint` | `project-id: 73` | Splits profiling data into logical groups that you control. You can assign any non-zero, unsigned integer <= 4095. -| `secret-token` | `string` | `secret-token: abc123` | Set the secret token for the communication with the Universal Profiling Collector to `abc123`. +| `secret-token` | `string` | `secret-token: abc123` | Set the secret token for communicating with the Universal Profiling Collector to `abc123`. | `collection-agent` | `string` | `collection-agent: example.com:443` | Set the destination for reporting profiling information to `example.com:443`. | `probabilistic-interval` | `duration` | `probabilistic-interval: 2m30s`| Set the probabilistic interval to `2m30s`. See <> for more details. | `probabilistic-threshold` | `uint` | `probabilistic-threshold: 50` | Set the probabilistic threshold to `50`. See <> for more details. diff --git a/docs/en/observability/profiling-envs.asciidoc b/docs/en/observability/profiling-envs.asciidoc index f31a378056..d98599e4df 100644 --- a/docs/en/observability/profiling-envs.asciidoc +++ b/docs/en/observability/profiling-envs.asciidoc @@ -3,7 +3,7 @@ The Universal Profiling Agent can be configured with environment variables. -WARNING: Command line arguments to the Universal Profiling Agent have precedence over environment variables. And environment variables have precedence over the configuration file. +WARNING: Command line arguments to the Universal Profiling Agent take precedence over environment variables, and environment variables take precedence over the configuration file. [options="header"] |==================================