Getting started

v0.1

AzL Sonar v0.1 was used live on a two-node Local Identity deployment (Azure Local 2609) on 10 and 11 Oct 2026. Report problems as GitHub issues; see the plan for what comes next.

Requirements

• PowerShell 7.4 or later on an admin workstation or jump server (Windows PowerShell 5.1 cannot run Sonar).
• Az.Accounts, signed in with Connect-AzAccount, with read access (Reader) to the resource group that holds the Azure Local instance.
• For live logs, one of:
  • WinRM to the seed node (5985/5986) with an account in the node's local Administrators. Workgroup (Local Identity) nodes, and any node reached by IP address, must be in this workstation's WinRM TrustedHosts.
  • SSH to the seed node with the Posh-SSH module (Install-Module Posh-SSH -Scope CurrentUser), for when WinRM is blocked. sshd must run on the node.
• Az.KeyVault, only when the log account comes from Key Vault.

Without log access Sonar still shows the step tree, the phase and the node status from Azure, and tells you why the logs are unavailable.

Get Sonar

Clone the repository (or download the ZIP from GitHub and extract it):

git clone https://github.com/AzureLocal/azurelocal-sonar.git
cd azurelocal-sonar

If you downloaded the ZIP, unblock the files once so PowerShell runs them: Get-ChildItem -Recurse | Unblock-File. There is nothing to install: no service, no database, no build step.

Run

Connect-AzAccount
New-Item -ItemType Directory -Force ./config | Out-Null   # config/ is git-ignored
Copy-Item ./examples/sonar.config.example.json ./config/my-cluster.json   # then edit it
./Start-AzlSonar.ps1 -ConfigPath ./config/my-cluster.json

Sonar asks for the account that reads the logs, starts a local back end on http://localhost:8642/ and opens your browser. Use -Port for another port, -Credential (Get-Credential) to pass the account, -NoBrowser to skip the browser. Press Ctrl+C to stop. Sonar never changes the deployment, Azure or the nodes.

For a workgroup node or an IP address, add the seed node to TrustedHosts first (elevated; Sonar checks it but never changes it):

Set-Item WSMan:\localhost\Client\TrustedHosts -Value '192.0.2.11' -Concatenate -Force

To look at the page without a deployment, open http://localhost:8642/?demo=1 (built-in sample data), or ?demo=1&replay=1 for the replay controls with a built-in recording.

Record a run, replay it later

Add -Record to keep the run in a local file (JSON Lines, masked, appended to after a restart):

./Start-AzlSonar.ps1 -ConfigPath ./config/my-cluster.json -Record ./recordings/my-cluster.jsonl   # recordings/ is git-ignored

A normal recording masks secrets but keeps identifiers (GUIDs, IP addresses, host and cluster names). To share one, record with -Publishable (a new file) or rewrite a recording you have with scripts/Protect-Recording.ps1: every identifier becomes a stable pseudonym and the finished file is checked. See Publishable recordings; scripts/Export-SonarBundle.ps1 turns any recording into a timeline JSON and a self-contained HTML report.

Play it back later, anywhere, with no Azure sign-in and no access to the nodes:

./Start-AzlSonar.ps1 -Replay ./recordings/my-cluster.jsonl -Speed 240 -StartAt deployment

The page is labelled Replay of <cluster> · recorded <date> and has a transport bar: play/pause, speed (1×, 30×, 60×, 240×), a scrubber with markers for Arc registration, Validate, Deploy and its main steps (click one to jump), and the position as Deploy +1:42:10. -StartAt takes an offset (1:42:10, 90m), a UTC time or a phase (arc-registration, validation, deployment); -Autoplay starts playing at once. Details: How it works and the README.

Configuration

One JSON file per cluster: subscription, resource group, cluster name, identity model (LocalIdentity or ActiveDirectory), how the machines get ready (provisioningRoute: auto, simplified or oem-image), the nodes (name, address, which one is the seed; the Arc resource name only to override what Sonar resolves), the log folders and limits, and where the log account comes from (prompt, parameter or keyvault with secret names). No secret ever goes in the file.

{
  "subscriptionId": "00000000-0000-0000-0000-000000000000",
  "resourceGroup": "rg-example-azl",
  "clusterName": "clus01",
  "identityModel": "LocalIdentity",
  "provisioningRoute": "auto",
  "nodes": [
    { "name": "node01", "address": "192.0.2.11", "seed": true },
    { "name": "node02", "address": "192.0.2.12" }
  ],
  "credential": { "source": "prompt" }
}

Every field, its default and its limits are in the README configuration reference. The defaults tail the folders verified live during a deployment: C:\CloudContent\MASLogs, C:\MASLogs, C:\CloudDeployment\Logs (appears later in the run), C:\Observability and C:\Windows\System32\Bootstrap\Logs.

Which account

Use the non-built-in deployment local admin (Local Identity) or the local administrator (Active Directory). Do not use the built-in Administrator for validation and deployment: deployment renames it to ASBuiltInAdmin (it is fine while the machines register with Arc). The page's Log access card shows the account, folders and timing for each phase and your identity model.

If something does not work

The README troubleshooting table covers the sign-in, TrustedHosts, access denied, WinRM blocked (SSH fallback), a port in use and a log folder that does not exist yet.