added steps for configuring Loki Retention Period (#247)

Co-authored-by: Donna-Marie Smith <donna.smith@wearecortex.com>

Author: Cortex-DMS

content/en/docs/2025.11/Guides/upgrade-guides/upgrade-observability/4.1.0-to-4.2.0/_index.md

@@ -0,0 +1,10 @@
+---
+title: "4.1.0 to 4.2.0"
+linkTitle: "4.1.0 to 4.2.0"
+description: "Instructions to upgrade your observability platform for {{% ctx %}} from 4.1.0 to 4.2.0."
+weight: 970
+---
+
+{{% alert title="Note" %}}
+There is no upgrade to 4.2.0 required for cloud-hosted observability platforms.
+{{% / alert %}}

content/en/docs/2025.11/Guides/upgrade-guides/upgrade-observability/4.1.0-to-4.2.0/on-premise/_index.md

@@ -0,0 +1,6 @@
+---
+title: "On-Premise"
+linkTitle: "On-Premise"
+description: "Information about upgrading an on-premise observability platform for {{% ctx %}}."
+weight: 1
+---

content/en/docs/2025.11/Guides/upgrade-guides/upgrade-observability/4.1.0-to-4.2.0/on-premise/grafana/_index.md

@@ -0,0 +1,6 @@
+---
+title: "Grafana"
+linkTitle: "Grafana"
+description: "Information about upgrading an on-premise Grafana platform for {{% ctx %}}."
+weight: 1
+---

content/en/docs/2025.11/Guides/upgrade-guides/upgrade-observability/4.1.0-to-4.2.0/on-premise/grafana/prerequisites.md

@@ -0,0 +1,31 @@
+---
+title: "Prerequisites"
+linkTitle: "Prerequisites"
+description: "The prerequisites required before performing the observability upgrade."
+weight: 1
+---
+
+# {{% param title %}}
+
+## Verify Upgrade Required
+
+On the server that Grafana Loki is installed on:
+
+1. Log in to the server.
+1. Open a File Explorer and navigate to the folder that Grafana Loki is running from, e.g. `C:\ProgramData\Cortex\Observability\Loki`.
+1. Open the `loki-local-config.yaml` configuration file in a text editor.
+1. Search the file for `compactor:`.
+1. If the search returns no results, proceed with the upgrade process, if results are returned then Observability has already been updated to 4.2.0 automatically as part of the [3.0.0 to 4.0.0][] upgrade and no further steps are required.
+
+## Backup Old Files
+
+1. On the server that Grafana Loki is installed on, create a folder called `Observability Backups` in a known location.
+1. Open File Explorer and navigate to the location that Grafana Loki is running from, e.g. `C:\ProgramData\Cortex\Observability\Loki\`.
+1. Copy the `loki-local-config.yaml` file and save it to the `Observability Backups` folder created at step 1.
+
+## Next Steps?
+
+1. [Upgrade Grafana Loki][]
+
+[3.0.0 to 4.0.0]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.3.0.0to4.0.0.OnPremise.Grafana.MainDoc" >}}
+[Upgrade Grafana Loki]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.4.1.0to4.2.0.OnPremise.Grafana.UpgradeLoki" >}}

content/en/docs/2025.11/Guides/upgrade-guides/upgrade-observability/4.1.0-to-4.2.0/on-premise/grafana/try-it-out.md

@@ -0,0 +1,61 @@
+---
+title: "Try it out"
+linkTitle: "Try it out"
+description: "Information about trying out the observability platform after upgrade."
+weight: 5
+---
+
+# {{% param title %}}
+
+This guide describes how to verify that the upgrade has been successful. Please ensure that [Upgrade Grafana Loki][Upgrade Loki] has been completed before taking these steps.
+
+## Confirm New Data is Processed
+
+{{% alert title="Note" %}}
+This test uses the test flow published as part of testing the {{% ctx %}} installation. See {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.TryItOutPublishedFlowNew" title="Testing HA installation" >}} or {{< ahref path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.TryItOutPublishedFlowNew" title="Testing non-HA installation" >}}. An alternative flow can be used that exists on the system and can be executed.
+{{% / alert %}}
+
+1. Open an HTTP client, such as [Postman][]. Make a request with the following format:
+    | Property      | Value                                                                               |
+    |---------------|-------------------------------------------------------------------------------------|
+    | Action        | POST                                                                                |
+    | URL           | For HA installation use: <br />`https://{FQDN of Load Balancer Server}/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}`<br />e.g. `https://load-balancer.domain.com/api/default/default/flows/NewFlow/executions?packageName=NewPackage` <br /><br /> For non-HA installation use: <br />`https://{FQDN of server}:8722/api/default/default/flows/{Flow Name}/executions?packageName={Package Name}`<br />e.g. `https://server.domain.com:8722/api/default/default/flows/NewFlow/executions?packageName=NewPackage`|
+    | Content Type  | application/json                                                                    |
+    | Body          | {}                                                                                  |
+    | Authentication| Basic                                                                               |
+    | Username      | The value used for `ApiGatewayBasicAuthUsername` when installing Application Services. See [HA Installation script configuration][] or [Non-HA Installation script configuration][] for the value specified.|
+    | Password      | The value used for `ApiGatewayBasicAuthPassword` when installing Application Services (Unencrypted). See [HA Installation script configuration][] or [Non-HA Installation script configuration][] for the value specified.|
+
+    {{% alert title="Note" %}} If you used self-signed certificates when installing the Application Servers you may need to disable SSL certificate validation in your HTTP client. {{% /alert %}}
+
+1. Once the request has completed, in your web browser, navigate to and log in to your configured Grafana.
+1. Open the *Dashboards* page via the menu on the left sidebar.
+1. Click the folder name that the dashboards were imported to.
+1. Click the *Flow Execution Requests* dashboard to open it.
+1. The request made at step 1 should be visible on the dashboard.
+{{% alert title="Note" %}}
+If other requests have been made then there may be more than one request visible on the dashboard.
+{{% / alert %}}
+1. Open the *Dashboards* page via the menu on the left sidebar.
+1. Click the folder name that the dashboards were imported to.
+1. Click the *Platform Health* dashboard to open it.
+1. The request made at step 1 should be visible on the dashboard.
+{{% alert title="Note" %}}
+If other requests have been made then there may be more than one request visible on the dashboard.
+{{% / alert %}}
+
+## Confirm Retention Period is being Applied
+
+1. In a web browser, navigate to and log in to your configured Grafana.
+1. Open the *Flow Execution Requests* dashboard.
+1. Set the *Time Filter* to be a period greater than the retention period that has been set.
+1. Ensure that there is no data available for the time period that is greater than the retention period.
+
+    {{% alert title="Note" %}}
+Loki may take some time to remove logs older than the retention period, therefore, if there is still data available beyond the retention period, repeat the above steps at a later time.
+    {{% / alert %}}
+
+[HA Installation script configuration]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureInstallationScriptNew" >}}
+[Upgrade Loki]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.4.1.0to4.2.0.OnPremise.Grafana.UpgradeLoki" >}}
+[Non-HA Installation script configuration]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureInstallationScriptNew" >}}
+[Postman]: {{< url path="Postman.Downloads.MainDoc" >}}

content/en/docs/2025.11/Guides/upgrade-guides/upgrade-observability/4.1.0-to-4.2.0/on-premise/grafana/upgrade-loki.md

@@ -0,0 +1,48 @@
+---
+title: "Upgrade Grafana Loki"
+linkTitle: "Upgrade Grafana Loki"
+description: "The steps to Upgrade Grafana Loki."
+weight: 4
+---
+
+# {{% param title %}}
+
+This guide describes how to upgrade Grafana Loki. Please ensure that the [Prerequisites][] have been completed before starting this upgrade.
+
+## Perform Upgrade
+
+On the server that Grafana Loki is installed on:
+
+1. Log in to the server.
+1. Open a File Explorer and navigate to the folder that Grafana Loki is running from, e.g. `C:\ProgramData\Cortex\Observability\Loki`.
+1. Open the `loki-local-config.yaml` configuration file in a text editor.
+1. Copy the following code and paste it in to the `loki-local-config.yaml` file.  It should be added immediately before the `schema_config:` section typically found on line 30.
+
+    ``` text
+    compactor:
+      retention_enabled: true
+      delete_request_store: filesystem
+      working_directory: /data/retention
+
+    ```
+
+1. Copy the following code and paste it in to the `loki-local-config.yaml` file.  It should be added to the end of the `limits_config:` section typically found on line 55 after the addition of the code in the previous step.
+
+    ``` text
+      retention_period: 8760h
+    ```
+
+1. If a different retention period to the default of 12 months (8760 hours) is required, change the value ensuring that only the required retention is configured.
+1. Save the file.
+1. Restart the Grafana Loki Service:
+    1. Open `services.msc`.
+    1. Locate the `Loki` service.
+    1. Right click on the service name and select `Restart`. If the service is not already running, select `Start`.
+
+## Next Steps?
+
+1. [Try it out][]
+
+[backed up]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.4.1.0to4.2.0.OnPremise.Grafana.BackupOldFiles" >}}
+[Prerequisites]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.4.1.0to4.2.0.OnPremise.Grafana.Prerequisites" >}}
+[Try it out]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.4.1.0to4.2.0.OnPremise.Grafana.TryItOut" >}}

content/en/docs/2025.11/getting-started/cloud/add-observability-to-innovation/Grafana/import-dashboards.md

@@ -66,6 +66,6 @@ To do this, follow these steps for all default {{% ctx %}} dashboards imported:
 
 [configured Loki data source]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.SetupLoki.MainDoc" >}}
 [Grafana]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.SetupGrafana.MainDoc" >}}
-[Grafana.Dashboards.zip]: {{< url path="GitHub.Cortex.Observability.4.1.0.GrafanaDashboardsZip" >}}
+[Grafana.Dashboards.zip]: {{< url path="GitHub.Cortex.Observability.4.2.0.GrafanaDashboardsZip" >}}
 [Loki]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.SetupLoki.MainDoc" >}}
 [Try it Out]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.TryItOut.MainDoc" >}}

content/en/docs/2025.11/getting-started/cloud/add-observability-to-innovation/Grafana/install-alloy/install-alloy.md

@@ -27,5 +27,5 @@ This archive contains the `config.alloy` configuration file and PowerShell scrip
 
 [Configure Grafana Alloy]: {{< url path="Cortex.GettingStarted.Cloud.AddObservabilityToInnovation.Grafana.InstallAlloy.ConfigureAlloy.MainDoc" >}}
 [Grafana Alloy 1.10.2]:  {{< url path="Grafana.Products.Loki.Alloy.1.10.2" >}}
-[Grafana Alloy.zip]: {{< url path="GitHub.Cortex.Observability.4.1.0.GrafanaAlloyInstallZip" >}}
+[Grafana Alloy.zip]: {{< url path="GitHub.Cortex.Observability.4.2.0.GrafanaAlloyInstallZip" >}}
 [Prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.Prerequisites" >}}

content/en/docs/2025.11/getting-started/on-premise/add-observability-to-innovation/Grafana/install-alloy/install-alloy.md

@@ -27,6 +27,6 @@ This archive contains the `config.alloy` configuration file and PowerShell scrip
 
 [Configure Grafana Alloy]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallAlloy.ConfigureAlloy" >}}
 [Grafana Alloy 1.10.2]:  {{< url path="Grafana.Products.Loki.Alloy.1.10.2" >}}
-[Grafana Alloy.zip]: {{< url path="GitHub.Cortex.Observability.4.1.0.GrafanaAlloyInstallZip" >}}
+[Grafana Alloy.zip]: {{< url path="GitHub.Cortex.Observability.4.2.0.GrafanaAlloyInstallZip" >}}
 [Prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.Prerequisites" >}}
 [Reverse Proxy Authentication]: {{< url path="Cortex.GettingStarted.OnPremise.AddObservabilityToInnovation.Grafana.InstallLoki.ConfigureAuthentication" >}}

content/en/docs/2025.11/getting-started/on-premise/add-observability-to-innovation/Grafana/install-loki/configure-loki.md

@@ -134,6 +134,25 @@ If the order is incorrect:
 1. Select the newly created website.
 1. In the *Manage Website* pane, click *Restart*.
 
+## Configure Log Retention
+
+Grafana Loki is configured with a default retention period of 12 months for it's logs. This means that Grafana can query data up to 12 months old. Once the 12 months is reached, Loki will remove older logs.
+
+If a different retention period is required then this can be set, however, it should only be set to the period that is needed otherwise excessive disk space may be used unnecessarily.
+
+To change the retention period:
+
+1. Open the `loki-local-config.yaml` configuration file, which is located in the folder that Loki was installed to eg `C:\ProgramData\Cortex\Observability\Loki`.
+1. Locate the `retention_period:` configuration value at approximately line 55.
+1. Set the value of the retention required in hours, e.g. 6 months would be `4380h` or 9 months would be `6570h`.
+1. Save the file.
+
+### Re-Start the Grafana Loki Service
+
+1. Open `services.msc`.
+1. Locate the `Loki` service.
+1. Right click on the service name and select `Restart`. If the service is not already running, select `Start`.
+
 ## Next Steps?
 
 1. [Install Grafana Alloy][]