Skip to content

Commit 2172099

Browse files
xBirahimxBirahim
committed
docs: split Service & CLI, add Windows Scheduled Task guide
- Separate 'Service & CLI' collapsed group into top-level items - Rename Linux page: 'Service Management' → 'Service (Linux)' - Add Service (Windows) page with XML + PowerShell Scheduled Task setup - Update all cross-references across 5 files
1 parent 5334515 commit 2172099

7 files changed

Lines changed: 180 additions & 17 deletions

File tree

‎astro.config.mjs‎

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -93,14 +93,9 @@ export default defineConfig({
9393
{ slug: "collector/v2/runbook" },
9494
{ slug: "collector/v2/upgrade" },
9595
{ slug: "collector/v2/migration" },
96-
{
97-
label: "Service & CLI",
98-
collapsed: true,
99-
items: [
100-
{ slug: "collector/v2/service" },
101-
{ slug: "collector/v2/cli" },
102-
],
103-
},
96+
{ slug: "collector/v2/service" },
97+
{ slug: "collector/v2/service-windows" },
98+
{ slug: "collector/v2/cli" },
10499
{
105100
label: "Extension",
106101
collapsed: true,

‎src/content/docs/collector/v2/cli.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ ms-teams-agent run --config ./config.yaml --ignore-state
7676
ms-teams-agent run --config ./config.yaml --state-file ./state/state.db
7777
```
7878

79-
## Service Management (Linux)
79+
## Service (Linux)
8080

8181
Most service actions require `sudo`.
8282

@@ -105,7 +105,7 @@ sudo ms-teams-agent service disable-service --instance default
105105

106106
Available service actions are: `install`, `install-config`, `enable`, `restart`, `status`, `disable`, `remove`, `provision`, `enable-service`, `disable-service`.
107107

108-
See [Service Management](../service/) for lifecycle procedures and rollout-safe updates.
108+
See [Service (Linux)](../service/) for lifecycle procedures and rollout-safe updates.
109109

110110
## State Operations
111111

‎src/content/docs/collector/v2/installation.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ sudo ms-teams-agent service enable-service --config /absolute/path/config.yaml
113113
sudo ms-teams-agent service status
114114
```
115115

116-
See [Service Management](../service/) for Linux service operation.
116+
See [Service (Linux)](../service/) for Linux service operation.
117117

118118
## Verify Ingestion
119119

‎src/content/docs/collector/v2/runbook.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ sudo ms-teams-agent service restart --instance default
4646
sudo journalctl -u ms-teams-observability-agent@default.service -f
4747
```
4848

49-
See [Service Management](../service/) for setup and upgrade flow.
49+
See [Service (Linux)](../service/) for setup and upgrade flow.
5050

5151
## Common Errors and Fixes
5252

‎src/content/docs/collector/v2/service-windows.mdx‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
title: Windows Service
3+
description: Run the MS Teams Observability collector as a Windows Scheduled Task — XML import or PowerShell setup, with boot trigger and configuration steps.
4+
sidebar:
5+
label: Service (Windows)
6+
order: 9
7+
---
8+
9+
import { Tabs, TabItem, Aside } from '@astrojs/starlight/components';
10+
11+
On Windows, the collector runs as a **Scheduled Task** triggered at system startup. This page provides two setup methods: importing an XML task definition, or creating the task via PowerShell.
12+
13+
## Prerequisites
14+
15+
- Collector binary (`ms-teams-agent.exe`) placed in a permanent directory (e.g., `C:\Program Files\Phenisys\`)
16+
- A valid `config.yaml` in the same directory
17+
- Administrator privileges on the Windows host
18+
- The service account must have **Log on as a batch job** rights
19+
20+
## Method 1: Import XML Task Definition
21+
22+
Save the following XML as `MSTeamsObservabilityAgent.xml`, update the paths and user, then import.
23+
24+
<Tabs>
25+
<TabItem label="XML Template">
26+
```xml
27+
<?xml version="1.0" encoding="UTF-16"?>
28+
<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
29+
<RegistrationInfo>
30+
<Author>YOURDOMAIN\youruser</Author>
31+
<URI>\MSTeamsObservabilityAgent</URI>
32+
</RegistrationInfo>
33+
<Triggers>
34+
<BootTrigger>
35+
<Enabled>true</Enabled>
36+
</BootTrigger>
37+
</Triggers>
38+
<Principals>
39+
<Principal id="Author">
40+
<UserId>YOURDOMAIN\youruser</UserId>
41+
<LogonType>Password</LogonType>
42+
<RunLevel>HighestAvailable</RunLevel>
43+
</Principal>
44+
</Principals>
45+
<Settings>
46+
<MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
47+
<DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
48+
<StopIfGoingOnBatteries>true</StopIfGoingOnBatteries>
49+
<AllowHardTerminate>true</AllowHardTerminate>
50+
<StartWhenAvailable>false</StartWhenAvailable>
51+
<RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
52+
<IdleSettings>
53+
<StopOnIdleEnd>true</StopOnIdleEnd>
54+
<RestartOnIdle>false</RestartOnIdle>
55+
</IdleSettings>
56+
<AllowStartOnDemand>true</AllowStartOnDemand>
57+
<Enabled>true</Enabled>
58+
<Hidden>false</Hidden>
59+
<RunOnlyIfIdle>false</RunOnlyIfIdle>
60+
<WakeToRun>false</WakeToRun>
61+
<ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
62+
<Priority>7</Priority>
63+
</Settings>
64+
<Actions Context="Author">
65+
<Exec>
66+
<Command>"C:\Program Files\Phenisys\ms-teams-agent.exe"</Command>
67+
<Arguments>run --config "C:\Program Files\Phenisys\config.yaml"</Arguments>
68+
<WorkingDirectory>C:\Program Files\Phenisys</WorkingDirectory>
69+
</Exec>
70+
</Actions>
71+
</Task>
72+
```
73+
</TabItem>
74+
</Tabs>
75+
76+
### Import the task
77+
78+
1. Update the XML:
79+
- Replace `YOURDOMAIN\youruser` with your service account
80+
- Replace paths under `<Command>`, `<Arguments>`, and `<WorkingDirectory>` with your installation path
81+
2. Open **Task Scheduler** (`taskschd.msc`)
82+
3. Click **Import Task…** in the right sidebar
83+
4. Select your XML file
84+
5. Enter the password for the service account when prompted
85+
86+
## Method 2: PowerShell
87+
88+
Run the following in an elevated PowerShell session:
89+
90+
```powershell
91+
$User = "YOURDOMAIN\youruser"
92+
$Credential = Get-Credential -UserName $User -Message "Enter your password"
93+
$PlainPassword = $Credential.GetNetworkCredential().Password
94+
95+
$Action = New-ScheduledTaskAction `
96+
-Execute "C:\Program Files\Phenisys\ms-teams-agent.exe" `
97+
-Argument 'run --config "C:\Program Files\Phenisys\config.yaml"'
98+
99+
$Trigger = New-ScheduledTaskTrigger -AtStartup
100+
101+
$Settings = New-ScheduledTaskSettingsSet `
102+
-ExecutionTimeLimit (New-TimeSpan -Days 3) `
103+
-StartWhenAvailable:$true `
104+
-MultipleInstances "IgnoreNew" `
105+
-RunOnlyIfIdle:$false
106+
107+
$Principal = New-ScheduledTaskPrincipal `
108+
-UserId $User `
109+
-LogonType Password `
110+
-RunLevel Highest
111+
112+
$Task = New-ScheduledTask `
113+
-Action $Action `
114+
-Trigger $Trigger `
115+
-Settings $Settings `
116+
-Principal $Principal
117+
118+
Register-ScheduledTask `
119+
-TaskName "MSTeamsObservabilityAgent" `
120+
-InputObject $Task `
121+
-User $Credential.UserName `
122+
-Password $PlainPassword `
123+
-Force
124+
```
125+
126+
## Task Settings Summary
127+
128+
| Setting | Value | Rationale |
129+
| --- | --- | --- |
130+
| **Trigger** | At startup | Starts collection as soon as the host boots |
131+
| **Multiple instances** | IgnoreNew | Prevents duplicate collector processes |
132+
| **Run level** | HighestAvailable | Ensures network and filesystem access |
133+
| **Execution time limit** | Unlimited (PT0S) / 3 days | Collector runs indefinitely; no hard timeout |
134+
| **Start when available** | true (PowerShell) | Retries if the task misses its scheduled start |
135+
| **Stop on batteries** | true | Preserves laptop battery when unplugged |
136+
| **Allow start on demand** | true | Lets you manually trigger a run from Task Scheduler |
137+
138+
<Aside type="tip">
139+
The collector logs to `stdout` and `stderr`. To capture logs, redirect output in the `<Arguments>`:
140+
`run --config "config.yaml" > "C:\Program Files\Phenisys\logs\agent.log" 2>&1`
141+
</Aside>
142+
143+
## Verifying the Service
144+
145+
1. Open **Task Scheduler** and locate `MSTeamsObservabilityAgent`
146+
2. Right-click → **Run** to test immediately
147+
3. Check **History** tab for execution results
148+
4. Verify data appears in your backend after one collection cycle
149+
150+
## Stopping the Collector
151+
152+
To stop the running collector:
153+
154+
```powershell
155+
Stop-ScheduledTask -TaskName "MSTeamsObservabilityAgent"
156+
```
157+
158+
To permanently disable:
159+
160+
```powershell
161+
Disable-ScheduledTask -TaskName "MSTeamsObservabilityAgent"
162+
```
163+
164+
To remove:
165+
166+
```powershell
167+
Unregister-ScheduledTask -TaskName "MSTeamsObservabilityAgent" -Confirm:$false
168+
```

‎src/content/docs/collector/v2/service.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
2-
title: Service Management
2+
title: Linux Service (systemd)
33
description: Run ms-teams-agent as a Linux systemd service.
44
sidebar:
5-
label: Service Management
6-
order: 5
5+
label: Service (Linux)
6+
order: 8
77
badge:
88
text: Linux only
99
variant: caution

‎src/content/docs/reference/faq/standalone.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@ Dynatrace, Splunk, Console, and OTLP outputs are available. See <a href={`${impo
2424

2525
### What should I do after changing standalone configuration?
2626

27-
In service mode, restart the service and verify status and logs. See <a href={`${import.meta.env.BASE_URL}collector/v2/service/`}>Service Management</a>.
27+
In service mode, restart the service and verify status and logs. See <a href={`${import.meta.env.BASE_URL}collector/v2/service/`}>Service (Linux)</a>.
2828

2929
### How should tokens and sensitive files be protected?
3030

31-
Use restricted file permissions, keep tokens out of version control, and store secrets in controlled paths. See <a href={`${import.meta.env.BASE_URL}backends/dynatrace/collector-connection/`}>Collector Connection</a> and <a href={`${import.meta.env.BASE_URL}collector/v2/service/`}>Service Management</a>.
31+
Use restricted file permissions, keep tokens out of version control, and store secrets in controlled paths. See <a href={`${import.meta.env.BASE_URL}backends/dynatrace/collector-connection/`}>Collector Connection</a> and <a href={`${import.meta.env.BASE_URL}collector/v2/service/`}>Service (Linux)</a>.

0 commit comments

Comments
 (0)