From afc8f4195f5ecc837cacad2468acee5cf06f5cd3 Mon Sep 17 00:00:00 2001 From: Amith Shet Date: Fri, 28 Aug 2026 15:27:02 +0530 Subject: [PATCH 1/2] REL-1368082: Add configure-retention CLI command user guide for Environment Watch --- ...k-configure-retention-environment-watch.md | 190 ++++++++++++++++++ ...lastic-stack-setup-02-environment-watch.md | 6 + 2 files changed, 196 insertions(+) create mode 100644 elastic-stack-setup/elastic-stack-setup-02-environment-watch/elastic-stack-configure-retention-environment-watch.md diff --git a/elastic-stack-setup/elastic-stack-setup-02-environment-watch/elastic-stack-configure-retention-environment-watch.md b/elastic-stack-setup/elastic-stack-setup-02-environment-watch/elastic-stack-configure-retention-environment-watch.md new file mode 100644 index 00000000..0969ff1f --- /dev/null +++ b/elastic-stack-setup/elastic-stack-setup-02-environment-watch/elastic-stack-configure-retention-environment-watch.md @@ -0,0 +1,190 @@ +# Configure Elasticsearch ILM Retention using the Relativity Server CLI + +The `configure-retention` command sets Elasticsearch Index Lifecycle Management (ILM) retention policies for logs, metrics, and traces data streams. Use this command to control how long monitoring data is retained in Elasticsearch for the Environment Watch InfraWatch cluster. + +> [!NOTE] +> It is recommended to run the CLI from the Primary SQL Server. + +> This guide assumes the Relativity Server bundle was extracted to `C:\Server.Bundle.x.y.z` or a similar directory chosen by the user. + +## Prerequisites + +- The Server-bundle zip file has been downloaded and extracted to `C:\Server.Bundle.x.y.z` +- Access to the Relativity Secret Store (Whitelisted for Secret Store access. Please see [here](https://help.relativity.com/Server2025/Content/System_Guides/Secret_Store/Secret_Store.htm#Configuringclients) for information on whitelisting.) +- Elasticsearch is running and accessible +- The initial Environment Watch setup has been completed. See [Set up Environment Watch using the Relativity Server CLI](./elastic-stack-setup-02-environment-watch.md) + +## Options + +| Flag | Description | Default | +|------|-------------|---------| +| `--logs-days ` | Retention period in days for the logs ILM policy (`infrawatch-logs-policy`). Must be greater than 0. | Prompted interactively | +| `--metrics-days ` | Retention period in days for the metrics ILM policy (`infrawatch-metrics-policy`). Must be greater than 0. | Prompted interactively | +| `--traces-days ` | Retention period in days for the traces ILM policy (`infrawatch-traces-policy`). Must be greater than 0. | Prompted interactively | +| `--quiet` | Suppress all prompts and the confirmation gate. Credentials are read exclusively from the Secret Store. At least one `--*-days` flag must be supplied. Use for automated or scripted execution. | `false` | +| `--dryrun` | Preview the ILM policy JSON that would be submitted without making any changes to Elasticsearch. Compatible with both interactive and quiet modes. | `false` | + +## Usage + +### Interactive + +Running `configure-retention` without `--quiet` launches an interactive session. If `relsvr setup` has been run, credentials are fetched silently from the Secret Store — no prompt for cluster URL, admin username, or password. If setup has not been run, the CLI prompts for those credentials before continuing. + +The command then displays the current ILM retention values for all three signals and prompts for each one individually. Press **Enter** at any signal prompt to skip that signal — the policy for that signal is left unchanged. + +``` +C:\Server.Bundle.x.y.z\relsvr.exe configure-retention + +Relativity Server CLI - 102.1.26 +Copyright (c) 2026, Relativity ODA LLC + +Current retention policies: + Logs (infrawatch-logs-policy): 90 days + Metrics (infrawatch-metrics-policy): 90 days + Traces (infrawatch-traces-policy): 7 days + +Logs retention in days [current: 90, Enter to skip]: 30 +Metrics retention in days [current: 90, Enter to skip]: +Traces retention in days [current: 7, Enter to skip]: + +Changes to apply: + Logs: 90 days -> 30 days + Metrics: (no change) + Traces: (no change) + +Apply retention changes? [yes/N]: yes + +Updating ILM policies ------------------------------------------------- 100% + +Successfully updated 1 ILM retention policy. +``` + +Entering anything other than `yes` at the confirmation prompt aborts with no changes made: + +``` +No changes were applied. +``` + +### Interactive with a pre-filled default + +Passing a `--*-days` flag in interactive mode pre-fills that signal's prompt with the flag value. The current value is still shown as context and confirmation is still required. + +``` +C:\Server.Bundle.x.y.z\relsvr.exe configure-retention --logs-days 30 + +Relativity Server CLI - 102.1.26 +Copyright (c) 2026, Relativity ODA LLC + +Current retention policies: + Logs (infrawatch-logs-policy): 90 days + Metrics (infrawatch-metrics-policy): 90 days + Traces (infrawatch-traces-policy): 7 days + +Logs retention in days [current: 90, default: 30, Enter to accept]: 30 +Metrics retention in days [current: 90, Enter to skip]: +Traces retention in days [current: 7, Enter to skip]: + +Changes to apply: + Logs: 90 days -> 30 days + Metrics: (no change) + Traces: (no change) + +Apply retention changes? [yes/N]: yes + +Updating ILM policies ------------------------------------------------- 100% + +Successfully updated 1 ILM retention policy. +``` + +### Quiet mode (automated / scripted) + +Combining `--quiet` with one or more `--*-days` flags suppresses all prompts and the confirmation gate. Credentials come exclusively from the Secret Store — `relsvr setup` must have been run first. This is suitable for scheduled tasks or unattended automation scripts. + +``` +C:\Server.Bundle.x.y.z\relsvr.exe configure-retention --quiet --logs-days 30 --metrics-days 90 + +Relativity Server CLI - 102.1.26 +Copyright (c) 2026, Relativity ODA LLC + +Updating ILM policies ------------------------------------------------- 100% + +Successfully updated 2 ILM retention policies. +``` + +### Dry run + +Use `--dryrun` to preview the ILM policy JSON that would be submitted without writing any changes to Elasticsearch. Dry run works in both interactive and quiet modes. + +**Quiet dry run — no prompts:** + +``` +C:\Server.Bundle.x.y.z\relsvr.exe configure-retention --quiet --logs-days 30 --dryrun + +Relativity Server CLI - 102.1.26 +Copyright (c) 2026, Relativity ODA LLC + +Dry run mode — no ILM policies will be modified. +Dry run — ILM policy 'infrawatch-logs-policy' would be submitted with: +{"policy":{"phases":{"delete":{"min_age":"30d","actions":{"delete":{}}}}}} +``` + +**Interactive dry run — prompts and confirmation appear, no changes applied after `yes`:** + +``` +C:\Server.Bundle.x.y.z\relsvr.exe configure-retention --dryrun + +Relativity Server CLI - 102.1.26 +Copyright (c) 2026, Relativity ODA LLC + +Current retention policies: + Logs (infrawatch-logs-policy): 90 days + Metrics (infrawatch-metrics-policy): 90 days + Traces (infrawatch-traces-policy): 7 days + +Logs retention in days [current: 90, Enter to skip]: 30 +Metrics retention in days [current: 90, Enter to skip]: +Traces retention in days [current: 7, Enter to skip]: + +Changes to apply: + Logs: 90 days -> 30 days + Metrics: (no change) + Traces: (no change) + +Apply retention changes? [yes/N]: yes + +Dry run mode — no ILM policies will be modified. +Dry run — ILM policy 'infrawatch-logs-policy' would be submitted with: +{"policy":{"phases":{"delete":{"min_age":"30d","actions":{"delete":{}}}}}} +``` + +## Verify the changes + +### Kibana Dev Tools + +After running `configure-retention`, confirm the updated retention value in Kibana Dev Tools. + +1. In Kibana, navigate to **Dev Tools** > **Console**. +2. Run the following query for each signal you updated, replacing `` with `logs`, `metrics`, or `traces`: + + ``` + GET /_ilm/policy/infrawatch--policy + ``` + +3. In the response, locate the `delete` phase and confirm `min_age` matches the value you set: + + ```json + { + "infrawatch-logs-policy": { + "policy": { + "phases": { + "delete": { + "min_age": "30d", + "actions": { + "delete": {} + } + } + } + } + } + } + ``` diff --git a/elastic-stack-setup/elastic-stack-setup-02-environment-watch/elastic-stack-setup-02-environment-watch.md b/elastic-stack-setup/elastic-stack-setup-02-environment-watch/elastic-stack-setup-02-environment-watch.md index 30d45aea..a18ca323 100644 --- a/elastic-stack-setup/elastic-stack-setup-02-environment-watch/elastic-stack-setup-02-environment-watch.md +++ b/elastic-stack-setup/elastic-stack-setup-02-environment-watch/elastic-stack-setup-02-environment-watch.md @@ -83,6 +83,12 @@ Refer to the [Troubleshooting Guide](../troubleshooting/relativity-server-cli.md) if you encounter any issues. +## Managing ILM Retention + +By default, Environment Watch uses the retention periods configured in Elasticsearch Index Lifecycle Management (ILM) policies. To view or update the retention period for logs, metrics, or traces data streams after setup, use the `configure-retention` command: + +See [Configure Elasticsearch ILM Retention using the Relativity Server CLI](./elastic-stack-configure-retention-environment-watch.md) for full instructions, including interactive mode, quiet mode for scripted updates, and how to verify changes in Kibana Dev Tools. + ## Next Steps * [Click here to continue Environment Watch Setup](./ew-01-install-monitoring-agents.md) From ef5f2195ff09cc0fac74f73b126d57ebd562d7eb Mon Sep 17 00:00:00 2001 From: Amith Shet Date: Fri, 28 Aug 2026 16:12:56 +0530 Subject: [PATCH 2/2] REL-1368082: Correct terminal output in guide to match actual CLI output from test VM --- ...k-configure-retention-environment-watch.md | 71 ++++++++++--------- 1 file changed, 36 insertions(+), 35 deletions(-) diff --git a/elastic-stack-setup/elastic-stack-setup-02-environment-watch/elastic-stack-configure-retention-environment-watch.md b/elastic-stack-setup/elastic-stack-setup-02-environment-watch/elastic-stack-configure-retention-environment-watch.md index 0969ff1f..cd193101 100644 --- a/elastic-stack-setup/elastic-stack-setup-02-environment-watch/elastic-stack-configure-retention-environment-watch.md +++ b/elastic-stack-setup/elastic-stack-setup-02-environment-watch/elastic-stack-configure-retention-environment-watch.md @@ -30,7 +30,7 @@ The `configure-retention` command sets Elasticsearch Index Lifecycle Management Running `configure-retention` without `--quiet` launches an interactive session. If `relsvr setup` has been run, credentials are fetched silently from the Secret Store — no prompt for cluster URL, admin username, or password. If setup has not been run, the CLI prompts for those credentials before continuing. -The command then displays the current ILM retention values for all three signals and prompts for each one individually. Press **Enter** at any signal prompt to skip that signal — the policy for that signal is left unchanged. +The command fetches and displays the current ILM retention values for all three signals, then prompts for each one individually. Press **Enter** at any signal prompt to skip that signal — the policy for that signal is left unchanged. If you press **Enter** at all prompts with no values entered, the command exits immediately with no confirmation prompt and no ILM changes made. ``` C:\Server.Bundle.x.y.z\relsvr.exe configure-retention @@ -38,31 +38,32 @@ C:\Server.Bundle.x.y.z\relsvr.exe configure-retention Relativity Server CLI - 102.1.26 Copyright (c) 2026, Relativity ODA LLC -Current retention policies: - Logs (infrawatch-logs-policy): 90 days - Metrics (infrawatch-metrics-policy): 90 days - Traces (infrawatch-traces-policy): 7 days +Fetching current ILM retention policies... -Logs retention in days [current: 90, Enter to skip]: 30 -Metrics retention in days [current: 90, Enter to skip]: -Traces retention in days [current: 7, Enter to skip]: + Logs (infrawatch-logs-policy): 30d + Metrics (infrawatch-metrics-policy): 30d + Traces (infrawatch-traces-policy): 7d + +Configure logs retention in days (current: 30d, press Enter to skip): 60 +Configure metrics retention in days (current: 30d, press Enter to skip): +Configure traces retention in days (current: 7d, press Enter to skip): Changes to apply: - Logs: 90 days -> 30 days + Logs: 30d -> 60d Metrics: (no change) Traces: (no change) -Apply retention changes? [yes/N]: yes +Apply changes? [yes/N]: yes Updating ILM policies ------------------------------------------------- 100% Successfully updated 1 ILM retention policy. ``` -Entering anything other than `yes` at the confirmation prompt aborts with no changes made: +Entering anything other than `yes` at the confirmation prompt aborts cleanly with no changes made: ``` -No changes were applied. +Operation cancelled. ``` ### Interactive with a pre-filled default @@ -70,26 +71,27 @@ No changes were applied. Passing a `--*-days` flag in interactive mode pre-fills that signal's prompt with the flag value. The current value is still shown as context and confirmation is still required. ``` -C:\Server.Bundle.x.y.z\relsvr.exe configure-retention --logs-days 30 +C:\Server.Bundle.x.y.z\relsvr.exe configure-retention --logs-days 60 Relativity Server CLI - 102.1.26 Copyright (c) 2026, Relativity ODA LLC -Current retention policies: - Logs (infrawatch-logs-policy): 90 days - Metrics (infrawatch-metrics-policy): 90 days - Traces (infrawatch-traces-policy): 7 days +Fetching current ILM retention policies... + + Logs (infrawatch-logs-policy): 30d + Metrics (infrawatch-metrics-policy): 30d + Traces (infrawatch-traces-policy): 7d -Logs retention in days [current: 90, default: 30, Enter to accept]: 30 -Metrics retention in days [current: 90, Enter to skip]: -Traces retention in days [current: 7, Enter to skip]: +Configure logs retention in days (current: 30d, default: 60, press Enter to accept): 60 +Configure metrics retention in days (current: 30d, press Enter to skip): +Configure traces retention in days (current: 7d, press Enter to skip): Changes to apply: - Logs: 90 days -> 30 days + Logs: 30d -> 60d Metrics: (no change) Traces: (no change) -Apply retention changes? [yes/N]: yes +Apply changes? [yes/N]: yes Updating ILM policies ------------------------------------------------- 100% @@ -124,8 +126,7 @@ Relativity Server CLI - 102.1.26 Copyright (c) 2026, Relativity ODA LLC Dry run mode — no ILM policies will be modified. -Dry run — ILM policy 'infrawatch-logs-policy' would be submitted with: -{"policy":{"phases":{"delete":{"min_age":"30d","actions":{"delete":{}}}}}} +Dry run — ILM policy 'infrawatch-logs-policy' would be submitted with: {"policy":{"phases":{"delete":{"min_age":"30d","actions":{"delete":{}}}}}} ``` **Interactive dry run — prompts and confirmation appear, no changes applied after `yes`:** @@ -136,25 +137,25 @@ C:\Server.Bundle.x.y.z\relsvr.exe configure-retention --dryrun Relativity Server CLI - 102.1.26 Copyright (c) 2026, Relativity ODA LLC -Current retention policies: - Logs (infrawatch-logs-policy): 90 days - Metrics (infrawatch-metrics-policy): 90 days - Traces (infrawatch-traces-policy): 7 days +Fetching current ILM retention policies... + + Logs (infrawatch-logs-policy): 30d + Metrics (infrawatch-metrics-policy): 30d + Traces (infrawatch-traces-policy): 7d -Logs retention in days [current: 90, Enter to skip]: 30 -Metrics retention in days [current: 90, Enter to skip]: -Traces retention in days [current: 7, Enter to skip]: +Configure logs retention in days (current: 30d, press Enter to skip): 30 +Configure metrics retention in days (current: 30d, press Enter to skip): +Configure traces retention in days (current: 7d, press Enter to skip): Changes to apply: - Logs: 90 days -> 30 days + Logs: 30d -> 30d Metrics: (no change) Traces: (no change) -Apply retention changes? [yes/N]: yes +Apply changes? [yes/N]: yes Dry run mode — no ILM policies will be modified. -Dry run — ILM policy 'infrawatch-logs-policy' would be submitted with: -{"policy":{"phases":{"delete":{"min_age":"30d","actions":{"delete":{}}}}}} +Dry run — ILM policy 'infrawatch-logs-policy' would be submitted with: {"policy":{"phases":{"delete":{"min_age":"30d","actions":{"delete":{}}}}}} ``` ## Verify the changes