From 99bfbf8a3c074c9be02b059d87d8b460af9451c5 Mon Sep 17 00:00:00 2001 From: Florian Lehner Date: Thu, 7 Nov 2024 15:05:37 +0100 Subject: [PATCH] profiling: add documentation for the config file and CLI arguments (#4398) * profiling: add documentation for the config file Signed-off-by: Florian Lehner * Apply suggestions from code review Co-authored-by: Christos Kalkanis * Apply suggestions from code review Co-authored-by: Christos Kalkanis * Apply suggestions from code review Co-authored-by: Mike Birnstiehl <114418652+mdbirnstiehl@users.noreply.github.com> --------- Signed-off-by: Florian Lehner Co-authored-by: Christos Kalkanis Co-authored-by: Mike Birnstiehl <114418652+mdbirnstiehl@users.noreply.github.com> (cherry picked from commit e335f2779b43c8e77e30e793cff1cf63dea7c4ff) # Conflicts: # docs/en/observability/index.asciidoc # docs/en/observability/profiling-envs.asciidoc --- docs/en/observability/index.asciidoc | 5 ++++ .../profiling-advanced-configuration.asciidoc | 21 +++++++++++++ .../profiling-config-file.asciidoc | 30 +++++++++++++++++++ docs/en/observability/profiling-envs.asciidoc | 20 +++++++++++++ 4 files changed, 76 insertions(+) create mode 100644 docs/en/observability/profiling-config-file.asciidoc create mode 100644 docs/en/observability/profiling-envs.asciidoc diff --git a/docs/en/observability/index.asciidoc b/docs/en/observability/index.asciidoc index 17b8440e34..f426f45a87 100644 --- a/docs/en/observability/index.asciidoc +++ b/docs/en/observability/index.asciidoc @@ -146,6 +146,11 @@ include::profiling-tag-data-query.asciidoc[leveloffset=+4] include::profiling-add-symbols.asciidoc[leveloffset=+4] include::profiling-use-a-proxy.asciidoc[leveloffset=+4] include::profiling-no-kernel-version-check.asciidoc[leveloffset=+4] +<<<<<<< HEAD +======= +include::profiling-envs.asciidoc[leveloffset=+4] +include::profiling-config-file.asciidoc[leveloffset=+4] +>>>>>>> e335f277 (profiling: add documentation for the config file and CLI arguments (#4398)) 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 9bcdd7f6e1..a2dd22d66b 100644 --- a/docs/en/observability/profiling-advanced-configuration.asciidoc +++ b/docs/en/observability/profiling-advanced-configuration.asciidoc @@ -10,3 +10,24 @@ See the following sections for more information: * <>: Configure the Universal Profiling Agent to bypass the kernel version compatibility check. +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: + +[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 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. +| `-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 new file mode 100644 index 0000000000..e737ced7ba --- /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. 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. + +Example: +[source] +---- +project-id: 73 +secret-token: abc123 +collection-agent: example.com:443 +---- + +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"] +|================================== +| 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. +| `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 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. +|================================== \ No newline at end of file diff --git a/docs/en/observability/profiling-envs.asciidoc b/docs/en/observability/profiling-envs.asciidoc new file mode 100644 index 0000000000..d98599e4df --- /dev/null +++ b/docs/en/observability/profiling-envs.asciidoc @@ -0,0 +1,20 @@ +[[profiling-envs]] += Environment variables to configure the Universal Profiling Agent + +The Universal Profiling Agent can be configured with environment variables. + +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"] +|================================== +| Environment variable | Example | Description +| `PRODFILER_VERBOSE` | `PRODFILER_VERBOSE=true` | Run the Universal Profiling Agent in verbose mode. +| `PRODFILER_NO_KERNEL_VERSION_CHECK` | `PRODFILER_NO_KERNEL_VERSION_CHECK=true` | Disable the kernel version check. See <> for more details. +| `PRODFILER_TAGS` | `PRODFILER_TAGS="cloud_region:us-central1;env:staging"` | Set specific tags. See <> for more details. +| `PRODFILER_PROJECT_ID` | `PRODFILER_PROJECT_ID=73` | Set project ID to 73. +| `PRODFILER_SECRET_TOKEN` | `PRODFILER_SECRET_TOKEN=my_secret_token` | Set the secret token to `my_secret_token`. +| `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=/etc/Elastic/universal-profiling/pf-host-agent.conf` | Set the path for the configuration file of the Universal Profiling Agent. See <> for more details. +|==================================