Feature/update documentation for new observability release

content/en/docs/2025.9/Guides/upgrade-guides/upgrade-observability/3.0.0-to-4.0.0/_index.md

@@ -2,5 +2,5 @@
 title: "3.0.0 to 4.0.0"
 linkTitle: "3.0.0 to 4.0.0"
 description: "Instructions to upgrade your observability platform for {{% ctx %}} from 3.0.0 to 4.0.0."
-weight: 999
+weight: 990
 ---

content/en/docs/2025.9/Guides/upgrade-guides/upgrade-observability/3.0.0-to-4.0.0/cloud/grafana/migrate-to-alloy.md

@@ -26,8 +26,7 @@ These steps will need to be performed on all application servers that host a Pro
 
 1. Click *Yes* when prompted for confirmation that you wish to remove the service.
 1. Click *OK* when the successful removal of the Promtail service is confirmed.
-1. Open a File Explorer and navigate to the folder where Promtail was running from, e.g. `C:\ProgramData\Cortex\Observability\Promtail`
-1. In File Explorer, navigate to the extracted alloy-installer-windows-amd64.exe folder created as part of [Make Artefacts Available][].
+1. Open a File Explorer and navigate to the extracted alloy-installer-windows-amd64.exe folder created as part of [Make Artefacts Available][].
 1. Copy the alloy-installer-windows-amd64.exe into a suitable location, e.g. `C:\ProgramData\Cortex\Observability\Grafana Alloy`.
 1. In File Explorer, navigate to the extracted Grafana.Alloy.Install folder created as part of [Make Artefacts Available][].
 1. Copy the contents of the folder to the same location as the previously copied alloy-installer-windows-amd64.exe.

content/en/docs/2025.9/Guides/upgrade-guides/upgrade-observability/3.0.0-to-4.0.0/on-premise/grafana/migrate-to-alloy.md

@@ -35,8 +35,7 @@ These steps will need to be performed on all application servers that host a Pro
 
 1. Click *Yes* when prompted for confirmation that you wish to remove the service.
 1. Click *OK* when the successful removal of the Promtail service is confirmed.
-1. Open a File Explorer and navigate to the folder where Promtail was running from, e.g. `C:\ProgramData\Cortex\Observability\Promtail`
-1. In File Explorer, navigate to the extracted alloy-installer-windows-amd64.exe folder created as part of [Make Artefacts Available][].
+1. Open a File Explorer and navigate to the extracted alloy-installer-windows-amd64.exe folder created as part of [Make Artefacts Available][].
 1. Copy the alloy-installer-windows-amd64.exe into a suitable location, e.g. `C:\ProgramData\Cortex\Observability\Grafana Alloy`.
 1. In File Explorer, navigate to the extracted Grafana.Alloy.Install folder created as part of [Make Artefacts Available][].
 1. Copy the contents of the folder to the same location as the previously copied alloy-installer-windows-amd64.exe.

content/en/docs/2025.9/Guides/upgrade-guides/upgrade-observability/4.0.0-to-4.1.0/_index.md

@@ -0,0 +1,6 @@
+---
+title: "4.0.0 to 4.1.0"
+linkTitle: "4.0.0 to 4.1.0"
+description: "Instructions to upgrade your observability platform for {{% ctx %}} from 4.0.0 to 4.1.0."
+weight: 980
+---

content/en/docs/2025.9/Guides/upgrade-guides/upgrade-observability/4.0.0-to-4.1.0/cloud/_index.md

@@ -0,0 +1,6 @@
+---
+title: "Cloud"
+linkTitle: "Cloud"
+description: "Information about upgrading a cloud-hosted observability platform for {{% ctx %}}."
+weight: 500
+---

content/en/docs/2025.9/Guides/upgrade-guides/upgrade-observability/4.0.0-to-4.1.0/cloud/grafana/_index.md

@@ -0,0 +1,6 @@
+---
+title: "Grafana"
+linkTitle: "Grafana"
+description: "Information about upgrading a cloud-hosted Grafana platform for {{% ctx %}}."
+weight: 1000
+---

content/en/docs/2025.9/Guides/upgrade-guides/upgrade-observability/4.0.0-to-4.1.0/cloud/grafana/prerequisites.md

@@ -0,0 +1,33 @@
+---
+title: "Prerequisites"
+linkTitle: "Prerequisites"
+description: "The prerequisites required before performing the observability upgrade."
+weight: 1
+---
+
+# {{% param title %}}
+
+## Verify Upgrade Required
+
+On each Application Server:
+
+1. Log in to the application server.
+1. Open a File Explorer and navigate to the folder that Grafana Alloy is running from, e.g. `C:\ProgramData\Cortex\Observability\Grafana Alloy`.
+1. Open the `config.alloy` configuration file in a text editor.
+1. Search the file for `local.file_match "ExecutionService"`.
+1. If the search returns no results, proceed with the upgrade process, if results are returned then Observability has already been updated to 4.1.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 each Application Server that Grafana Alloy is installed on:
+
+    1. Create a folder called `Observability Backups` in a known location.
+    1. Open File Explorer and navigate to the location that Grafana Alloy is running from, e.g. `C:\ProgramData\Cortex\Observability\Grafana Alloy`.
+    1. Copy the `config.alloy` file and save it to the `Observability Backups` folder created at step 1.1.
+
+## Next Steps?
+
+1. [Upgrade Grafana Alloy][]
+
+[3.0.0 to 4.0.0]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.3.0.0to4.0.0.Cloud.Grafana.MainDoc" >}}
+[Upgrade Grafana Alloy]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.4.0.0to4.1.0.Cloud.Grafana.UpgradeAlloy" >}}

content/en/docs/2025.9/Guides/upgrade-guides/upgrade-observability/4.0.0-to-4.1.0/cloud/grafana/try-it-out.md

@@ -0,0 +1,50 @@
+---
+title: "Try it out"
+linkTitle: "Try it out"
+description: "Information about trying out the observability platform after upgrade."
+weight: 3
+---
+
+# {{% param title %}}
+
+This guide describes how to verify that the upgrade has been successful. Please ensure that [Upgrade Grafana Alloy][Upgrade Alloy] 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 %}}
+
+[Postman]: {{< url path="Postman.Downloads.MainDoc" >}}
+[HA Installation script configuration]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureInstallationScriptNew" >}}
+[Upgrade Alloy]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.4.0.0to4.1.0.Cloud.Grafana.UpgradeAlloy" >}}
+[Non-HA Installation script configuration]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureInstallationScriptNew" >}}

content/en/docs/2025.9/Guides/upgrade-guides/upgrade-observability/4.0.0-to-4.1.0/cloud/grafana/upgrade-alloy.md

@@ -0,0 +1,102 @@
+---
+title: "Upgrade Grafana Alloy"
+linkTitle: "Upgrade Grafana Alloy"
+description: "The steps to Upgrade Grafana Alloy."
+weight: 2
+---
+
+# {{% param title %}}
+
+This guide describes how to upgrade Grafana Alloy. Please ensure that the [Prerequisites][] have been completed before starting this upgrade.
+
+## Perform Upgrade
+
+{{% alert title="Note" %}}
+These steps will need to be performed on all application servers that host a Grafana Alloy service.
+{{% / alert %}}
+
+1. Log in to the application server.
+1. Open a File Explorer and navigate to the folder that Grafana Alloy is running from, e.g. `C:\ProgramData\Cortex\Observability\Grafana Alloy`.
+1. Open the `config.alloy` configuration file in a text editor.
+1. Copy the following code and paste it in to the `config.alloy` file.  It should be added to the end of the file but before the `loki.write "default" {` section typically found on line 99.
+
+    ``` text
+    local.file_match "ExecutionService" {
+        path_targets = [{
+            __address__ = "localhost",
+            __path__    = "C:/ProgramData/Cortex/Execution Service/Logs/**/*.json",
+            job         = "ExecutionService",
+        }]
+    }
+
+    loki.process "ExecutionService" {
+        forward_to = [loki.write.default.receiver]
+
+        stage.json {
+            expressions = {
+                level     = "\"@l\"",
+                timestamp = "\"@t\"",
+            }
+        }
+
+        stage.timestamp {
+            source = "timestamp"
+            format = "RFC3339Nano"
+        }
+
+        stage.match {
+            selector = "{job=\"ExecutionService\"}|~ \"\\\"SourceContext\\\":.?\\\"Cortex[.]ServiceFabric[.]Service[.]Execution[.]ExecutionService\\\"\""
+
+            stage.json {
+                expressions = {
+                    BlockName          = "Event.Tags.Cortex.\"Block.Name\" || 'Unknown'",
+                    BlockResult        = "Event.Tags.Cortex.\"Block.Result.Status\" || 'Unknown'",
+                    ExceptionCategory  = "Event.Tags.Cortex.\"Exception.Category\" || 'N/A'",
+                    ExceptionErrorCode = "Event.Tags.Cortex.\"Exception.ErrorCode\" || 'N/A'",
+                    ExceptionType      = "Event.Tags.Cortex.\"Exception.Type\" || 'N/A'",
+                    FlowName           = "Event.Tags.Cortex.\"Flow.Name\" || 'Unknown'",
+                    Node               = "Event.Platform.Node.Name || 'Unknown'",
+                    PackageName        = "Event.Tags.Cortex.\"Package.Name\" || 'Unknown'",
+                    System             = "Event.Tags.Cortex.\"System.Name\" || 'Unknown'",
+                    Tenant             = "Event.Tags.Cortex.\"Tenant.Name\" || 'Unknown'",
+                    Type               = "Event.LogType || 'Cortex'",
+                }
+            }
+
+            stage.labels {
+                values = {
+                    BlockName          = null,
+                    BlockResult        = null,
+                    ExceptionCategory  = null,
+                    ExceptionErrorCode = null,
+                    ExceptionType      = null,
+                    FlowName           = null,
+                    Node               = null,
+                    PackageName        = null,
+                    System             = null,
+                    Tenant             = null,
+                    Type               = null,
+                }
+            }
+        }
+    }
+
+    loki.source.file "ExecutionService" {
+        targets               = local.file_match.ExecutionService.targets
+        forward_to            = [loki.process.ExecutionService.receiver]
+    }
+
+    ```
+1. Set the `__path__` in the `local.file_match "ExecutionService"` > `path_targets` section to the path of the `Logs` folder for the Execution Service, e.g. `"C:/ProgramData/Cortex/Execution Service/Logs/**/*.json"`.
+1. Save the file.
+1. Restart the Grafana Alloy Service:
+    1. Open `services.msc`.
+    1. Locate the `Alloy` 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][]
+
+[Prerequisites]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.4.0.0to4.1.0.Cloud.Grafana.Prerequisites" >}}
+[Try it out]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.4.0.0to4.1.0.Cloud.Grafana.TryItOut" >}}

content/en/docs/2025.9/Guides/upgrade-guides/upgrade-observability/4.0.0-to-4.1.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.9/Guides/upgrade-guides/upgrade-observability/4.0.0-to-4.1.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.9/Guides/upgrade-guides/upgrade-observability/4.0.0-to-4.1.0/on-premise/grafana/prerequisites.md

@@ -0,0 +1,33 @@
+---
+title: "Prerequisites"
+linkTitle: "Prerequisites"
+description: "The prerequisites required before performing the observability upgrade."
+weight: 1
+---
+
+# {{% param title %}}
+
+## Verify Upgrade Required
+
+On each Application Server:
+
+1. Log in to the application server.
+1. Open a File Explorer and navigate to the folder that Grafana Alloy is running from, e.g. `C:\ProgramData\Cortex\Observability\Grafana Alloy`.
+1. Open the `config.alloy` configuration file in a text editor.
+1. Search the file for `local.file_match "ExecutionService"`.
+1. If the search returns no results, proceed with the upgrade process, if results are returned then Observability has already been updated to 4.1.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 each Application Server that Grafana Alloy is installed on:
+
+    1. Create a folder called `Observability Backups` in a known location.
+    1. Open File Explorer and navigate to the location that Grafana Alloy is running from, e.g. `C:\ProgramData\Cortex\Observability\Grafana Alloy`.
+    1. Copy the `config.alloy` file and save it to the `Observability Backups` folder created at step 1.1.
+
+## Next Steps?
+
+1. [Upgrade Grafana Alloy][]
+
+[3.0.0 to 4.0.0]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.3.0.0to4.0.0.OnPremise.Grafana.MainDoc" >}}
+[Upgrade Grafana Alloy]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.4.0.0to4.1.0.OnPremise.Grafana.UpgradeAlloy" >}}

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

@@ -0,0 +1,50 @@
+---
+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 Alloy][Upgrade Alloy] 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 %}}
+
+[HA Installation script configuration]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureInstallationScriptNew" >}}
+[Upgrade Alloy]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.4.0.0to4.1.0.OnPremise.Grafana.UpgradeAlloy" >}}
+[Non-HA Installation script configuration]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.ConfigureInstallationScriptNew" >}}
+[Postman]: {{< url path="Postman.Downloads.MainDoc" >}}