[8.x](backport #4398) profiling: add documentation for the config fil…

…e and CLI arguments (#4499) * profiling: add documentation for the config file and CLI arguments (#4398) * profiling: add documentation for the config file Signed-off-by: Florian Lehner <florian.lehner@elastic.co> * Apply suggestions from code review Co-authored-by: Christos Kalkanis <christos.kalkanis@elastic.co> * Apply suggestions from code review Co-authored-by: Christos Kalkanis <christos.kalkanis@elastic.co> * Apply suggestions from code review Co-authored-by: Mike Birnstiehl <114418652+mdbirnstiehl@users.noreply.github.com> --------- Signed-off-by: Florian Lehner <florian.lehner@elastic.co> Co-authored-by: Christos Kalkanis <christos.kalkanis@elastic.co> Co-authored-by: Mike Birnstiehl <114418652+mdbirnstiehl@users.noreply.github.com> (cherry picked from commit e335f27) # Conflicts: # docs/en/observability/index.asciidoc # docs/en/observability/profiling-envs.asciidoc * Update docs/en/observability/index.asciidoc --------- Co-authored-by: Florian Lehner <florianl@users.noreply.github.com> Co-authored-by: Mike Birnstiehl <114418652+mdbirnstiehl@users.noreply.github.com>
elastic · Nov 7, 2024 · 553e9d7 · 553e9d7
1 parent 2976434
commit 553e9d7
Show file tree

Hide file tree

Showing 4 changed files with 73 additions and 0 deletions.
diff --git a/docs/en/observability/index.asciidoc b/docs/en/observability/index.asciidoc
@@ -146,6 +146,8 @@ 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]
+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
@@ -10,3 +10,24 @@ See the following sections for more information:
 * <<profiling-no-kernel-version-check, Override kernel version check >>: 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 <<profiling-no-kernel-version-check, Override kernel version check >> for more details.
+| `-tags` | `string` | `-tags='cloud_region:us-central1;env:staging'` |  Set specific tags. See <<profiling-tag-data-query, Tag data for querying>> 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 <<profiling-probabilistic-profiling, Probabilistic profiling>> for more details.
+| `-probabilistic-threshold` | `uint` | `-probabilistic-threshold=50` | Set the probabilistic threshold to `50`. See <<profiling-probabilistic-profiling, Probabilistic profiling>> 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 <<profiling-config-file, Configuration file of the Universal Profiling Agent>> for more details.
+
+|==================================
diff --git a/docs/en/observability/profiling-config-file.asciidoc 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 <<profiling-no-kernel-version-check, Override kernel version check >> for more details.
+| `tags` | `string` | `tags: 'cloud_region:us-central1;env:staging'` |  Set specific tags. See <<profiling-tag-data-query, Tag data for querying>> 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 <<profiling-probabilistic-profiling, Probabilistic profiling>> for more details.
+| `probabilistic-threshold` | `uint` | `probabilistic-threshold: 50` | Set the probabilistic threshold to `50`. See <<profiling-probabilistic-profiling, Probabilistic profiling>> for more details.
+|==================================
diff --git a/docs/en/observability/profiling-envs.asciidoc 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 <<profiling-no-kernel-version-check, Override kernel version check >> for more details.
+| `PRODFILER_TAGS` | `PRODFILER_TAGS="cloud_region:us-central1;env:staging"` | Set specific tags. See <<profiling-tag-data-query, Tag data for querying>> 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 <<profiling-probabilistic-profiling, Probabilistic profiling>> for more details.
+| `PRODFILER_PROBABILISTIC_INTERVAL` |`PRODFILER_PROBABILISTIC_INTERVAL=2m30s` | Set the probabilistic interval to `2m30s`. See <<profiling-probabilistic-profiling, Probabilistic profiling>> 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 <<profiling-config-file, Configuration file of the Universal Profiling Agent>> for more details.
+|==================================