Skip to content

Commit 767a21f

Browse files
Cortex-DMSCortex-DMS
authored
Feature/update documentation for new observability release (#242)
1 parent 991ccdc commit 767a21f

File tree

22 files changed

+434
-12
lines changed

22 files changed

+434
-12
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,5 @@
22
title: "3.0.0 to 4.0.0"
33
linkTitle: "3.0.0 to 4.0.0"
44
description: "Instructions to upgrade your observability platform for {{% ctx %}} from 3.0.0 to 4.0.0."
5-
weight: 999
5+
weight: 990
66
---

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,7 @@ These steps will need to be performed on all application servers that host a Pro
2626
2727
1. Click *Yes* when prompted for confirmation that you wish to remove the service.
2828
1. Click *OK* when the successful removal of the Promtail service is confirmed.
29-
1. Open a File Explorer and navigate to the folder where Promtail was running from, e.g. `C:\ProgramData\Cortex\Observability\Promtail`
30-
1. In File Explorer, navigate to the extracted alloy-installer-windows-amd64.exe folder created as part of [Make Artefacts Available][].
29+
1. Open a File Explorer and navigate to the extracted alloy-installer-windows-amd64.exe folder created as part of [Make Artefacts Available][].
3130
1. Copy the alloy-installer-windows-amd64.exe into a suitable location, e.g. `C:\ProgramData\Cortex\Observability\Grafana Alloy`.
3231
1. In File Explorer, navigate to the extracted Grafana.Alloy.Install folder created as part of [Make Artefacts Available][].
3332
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‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,7 @@ These steps will need to be performed on all application servers that host a Pro
3535
3636
1. Click *Yes* when prompted for confirmation that you wish to remove the service.
3737
1. Click *OK* when the successful removal of the Promtail service is confirmed.
38-
1. Open a File Explorer and navigate to the folder where Promtail was running from, e.g. `C:\ProgramData\Cortex\Observability\Promtail`
39-
1. In File Explorer, navigate to the extracted alloy-installer-windows-amd64.exe folder created as part of [Make Artefacts Available][].
38+
1. Open a File Explorer and navigate to the extracted alloy-installer-windows-amd64.exe folder created as part of [Make Artefacts Available][].
4039
1. Copy the alloy-installer-windows-amd64.exe into a suitable location, e.g. `C:\ProgramData\Cortex\Observability\Grafana Alloy`.
4140
1. In File Explorer, navigate to the extracted Grafana.Alloy.Install folder created as part of [Make Artefacts Available][].
4241
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‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "4.0.0 to 4.1.0"
3+
linkTitle: "4.0.0 to 4.1.0"
4+
description: "Instructions to upgrade your observability platform for {{% ctx %}} from 4.0.0 to 4.1.0."
5+
weight: 980
6+
---

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Cloud"
3+
linkTitle: "Cloud"
4+
description: "Information about upgrading a cloud-hosted observability platform for {{% ctx %}}."
5+
weight: 500
6+
---

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Grafana"
3+
linkTitle: "Grafana"
4+
description: "Information about upgrading a cloud-hosted Grafana platform for {{% ctx %}}."
5+
weight: 1000
6+
---

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: "Prerequisites"
3+
linkTitle: "Prerequisites"
4+
description: "The prerequisites required before performing the observability upgrade."
5+
weight: 1
6+
---
7+
8+
# {{% param title %}}
9+
10+
## Verify Upgrade Required
11+
12+
On each Application Server:
13+
14+
1. Log in to the application server.
15+
1. Open a File Explorer and navigate to the folder that Grafana Alloy is running from, e.g. `C:\ProgramData\Cortex\Observability\Grafana Alloy`.
16+
1. Open the `config.alloy` configuration file in a text editor.
17+
1. Search the file for `local.file_match "ExecutionService"`.
18+
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.
19+
20+
## Backup Old Files
21+
22+
1. On each Application Server that Grafana Alloy is installed on:
23+
24+
1. Create a folder called `Observability Backups` in a known location.
25+
1. Open File Explorer and navigate to the location that Grafana Alloy is running from, e.g. `C:\ProgramData\Cortex\Observability\Grafana Alloy`.
26+
1. Copy the `config.alloy` file and save it to the `Observability Backups` folder created at step 1.1.
27+
28+
## Next Steps?
29+
30+
1. [Upgrade Grafana Alloy][]
31+
32+
[3.0.0 to 4.0.0]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.3.0.0to4.0.0.Cloud.Grafana.MainDoc" >}}
33+
[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‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
title: "Try it out"
3+
linkTitle: "Try it out"
4+
description: "Information about trying out the observability platform after upgrade."
5+
weight: 3
6+
---
7+
8+
# {{% param title %}}
9+
10+
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.
11+
12+
## Confirm New Data is Processed
13+
14+
{{% alert title="Note" %}}
15+
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.
16+
{{% / alert %}}
17+
18+
1. Open an HTTP client, such as [Postman][]. Make a request with the following format:
19+
| Property | Value |
20+
|---------------|-------------------------------------------------------------------------------------|
21+
| Action | POST |
22+
| 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`|
23+
| Content Type | application/json |
24+
| Body | {} |
25+
| Authentication| Basic |
26+
| 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.|
27+
| 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.|
28+
29+
{{% 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 %}}
30+
31+
1. Once the request has completed, in your web browser, navigate to and log in to your configured Grafana.
32+
1. Open the *Dashboards* page via the menu on the left sidebar.
33+
1. Click the folder name that the dashboards were imported to.
34+
1. Click the *Flow Execution Requests* dashboard to open it.
35+
1. The request made at step 1 should be visible on the dashboard.
36+
{{% alert title="Note" %}}
37+
If other requests have been made then there may be more than one request visible on the dashboard.
38+
{{% / alert %}}
39+
1. Open the *Dashboards* page via the menu on the left sidebar.
40+
1. Click the folder name that the dashboards were imported to.
41+
1. Click the *Platform Health* dashboard to open it.
42+
1. The request made at step 1 should be visible on the dashboard.
43+
{{% alert title="Note" %}}
44+
If other requests have been made then there may be more than one request visible on the dashboard.
45+
{{% / alert %}}
46+
47+
[Postman]: {{< url path="Postman.Downloads.MainDoc" >}}
48+
[HA Installation script configuration]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.MultipleServerWithHA.ConfigureInstallationScriptNew" >}}
49+
[Upgrade Alloy]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.4.0.0to4.1.0.Cloud.Grafana.UpgradeAlloy" >}}
50+
[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‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: "Upgrade Grafana Alloy"
3+
linkTitle: "Upgrade Grafana Alloy"
4+
description: "The steps to Upgrade Grafana Alloy."
5+
weight: 2
6+
---
7+
8+
# {{% param title %}}
9+
10+
This guide describes how to upgrade Grafana Alloy. Please ensure that the [Prerequisites][] have been completed before starting this upgrade.
11+
12+
## Perform Upgrade
13+
14+
{{% alert title="Note" %}}
15+
These steps will need to be performed on all application servers that host a Grafana Alloy service.
16+
{{% / alert %}}
17+
18+
1. Log in to the application server.
19+
1. Open a File Explorer and navigate to the folder that Grafana Alloy is running from, e.g. `C:\ProgramData\Cortex\Observability\Grafana Alloy`.
20+
1. Open the `config.alloy` configuration file in a text editor.
21+
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.
22+
23+
``` text
24+
local.file_match "ExecutionService" {
25+
path_targets = [{
26+
__address__ = "localhost",
27+
__path__ = "C:/ProgramData/Cortex/Execution Service/Logs/**/*.json",
28+
job = "ExecutionService",
29+
}]
30+
}
31+
32+
loki.process "ExecutionService" {
33+
forward_to = [loki.write.default.receiver]
34+
35+
stage.json {
36+
expressions = {
37+
level = "\"@l\"",
38+
timestamp = "\"@t\"",
39+
}
40+
}
41+
42+
stage.timestamp {
43+
source = "timestamp"
44+
format = "RFC3339Nano"
45+
}
46+
47+
stage.match {
48+
selector = "{job=\"ExecutionService\"}|~ \"\\\"SourceContext\\\":.?\\\"Cortex[.]ServiceFabric[.]Service[.]Execution[.]ExecutionService\\\"\""
49+
50+
stage.json {
51+
expressions = {
52+
BlockName = "Event.Tags.Cortex.\"Block.Name\" || 'Unknown'",
53+
BlockResult = "Event.Tags.Cortex.\"Block.Result.Status\" || 'Unknown'",
54+
ExceptionCategory = "Event.Tags.Cortex.\"Exception.Category\" || 'N/A'",
55+
ExceptionErrorCode = "Event.Tags.Cortex.\"Exception.ErrorCode\" || 'N/A'",
56+
ExceptionType = "Event.Tags.Cortex.\"Exception.Type\" || 'N/A'",
57+
FlowName = "Event.Tags.Cortex.\"Flow.Name\" || 'Unknown'",
58+
Node = "Event.Platform.Node.Name || 'Unknown'",
59+
PackageName = "Event.Tags.Cortex.\"Package.Name\" || 'Unknown'",
60+
System = "Event.Tags.Cortex.\"System.Name\" || 'Unknown'",
61+
Tenant = "Event.Tags.Cortex.\"Tenant.Name\" || 'Unknown'",
62+
Type = "Event.LogType || 'Cortex'",
63+
}
64+
}
65+
66+
stage.labels {
67+
values = {
68+
BlockName = null,
69+
BlockResult = null,
70+
ExceptionCategory = null,
71+
ExceptionErrorCode = null,
72+
ExceptionType = null,
73+
FlowName = null,
74+
Node = null,
75+
PackageName = null,
76+
System = null,
77+
Tenant = null,
78+
Type = null,
79+
}
80+
}
81+
}
82+
}
83+
84+
loki.source.file "ExecutionService" {
85+
targets = local.file_match.ExecutionService.targets
86+
forward_to = [loki.process.ExecutionService.receiver]
87+
}
88+
89+
```
90+
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"`.
91+
1. Save the file.
92+
1. Restart the Grafana Alloy Service:
93+
1. Open `services.msc`.
94+
1. Locate the `Alloy` service.
95+
1. Right click on the service name and select `Restart`. If the service is not already running, select `Start`.
96+
97+
## Next Steps?
98+
99+
1. [Try it out][]
100+
101+
[Prerequisites]: {{< url path="Cortex.Guides.UpgradeGuides.UpgradeObservability.4.0.0to4.1.0.Cloud.Grafana.Prerequisites" >}}
102+
[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‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "On-Premise"
3+
linkTitle: "On-Premise"
4+
description: "Information about upgrading an on-premise observability platform for {{% ctx %}}."
5+
weight: 1
6+
---

0 commit comments

Comments
 (0)