Task 03: Enable HCI Insights
DOCUMENT CATEGORY: Runbook
SCOPE: HCI Insights monitoring integration
PURPOSE: Enable Azure Local Insights workbook for cluster health and performance monitoring
MASTER REFERENCE: Microsoft Learn - Azure Local Insights
Status: Active
Azure Local Insights provides a rich, pre-built Azure Monitor Workbook that visualizes cluster health, node status, storage performance, and VM state. Enabling Insights automatically installs the Azure Monitor Agent (if not already present) and configures the required Data Collection Rules for HCI-specific telemetry.
Prerequisites
| Requirement | Description | Validation |
|---|---|---|
| Log Analytics Workspace | Created in Step 1 | Workspace accessible |
| Azure Monitor Agent | Installed on cluster nodes (Step 2) | Extension status: Succeeded |
| Arc-Enabled Cluster | Azure Local cluster registered | Portal shows cluster resource |
| RBAC Permissions | Monitoring Contributor | Role assignment verified |
Values from infrastructure.yml
The script reads these keys from infrastructure.yml (schema 5). Each key, with its type, default and example, is in the variables reference.
azure.tenant_id, azure.subscription_id, azure.resource_group, cluster.name, nodes[] (name, arc_machine_name)
operations.monitoring.enabled false means: do nothing
operations.monitoring.workspace_resource_group the resource group of the rule
operations.monitoring.data_collection_rule the name of the existing rule
operations.monitoring.log_analytics_workspace optional: the workspace the rule must send to
Overview
HCI Insights collects data from specific Windows Event Log channels and performance counters:
| Data Type | Source | Purpose |
|---|---|---|
| Health Events | Microsoft-Windows-Health/Operational | Node and component health status |
| SDDC Events | Microsoft-Windows-SDDC-Management/Operational | Cluster management events |
| Memory | Memory\Available Bytes | Memory utilization |
| Network | Network Interface(*)\Bytes Total/sec | Network throughput |
| CPU | Processor(_Total)\% Processor Time | CPU utilization |
| RDMA | RDMA Activity(*)\RDMA Inbound/Outbound Bytes/sec | Storage network performance |
Configuration Options
- Azure Portal
- Orchestrated Script
- Azure CLI
Step 3.1: Enable Insights from Cluster Resource
- Navigate to Azure Portal → Azure Local → Select your cluster
- Under Capabilities tab, locate the Insights tile
- Click Insights to open the configuration page
- Click Get Started
Step 3.2: Configure Data Collection Rule
- On the Insights configuration page:
- Select an existing DCR from the dropdown, OR
- Click Create New to create a dedicated Insights DCR
- For New DCR:
| Setting | Value |
|---|---|
| Subscription | {{AZURE_SUBSCRIPTION_NAME}} |
| DCR Name | AzureStackHCI-{{CLUSTER_NAME}}-dcr |
| Data Collection Endpoint | dce-{{SITE_CODE}}-azl-01 |
- Click Review + create
When you configure Insights, Azure Monitor Agent is automatically installed on all cluster nodes if not already present. The DCRs created by Insights have the prefix AzureStackHCI-.
Step 3.3: Verify Insights Configuration
- Return to your cluster's Capabilities tab
- The Insights tile should now show Configured
- Click Insights to view the workbook
PowerShell
When to use: Run the task from a management workstation or a pipeline. The script reads
infrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/05-operational-foundations/phase-02-monitoring-observability/task-03-enable-hci-insights/powershell/Enable-HciInsights.ps1 | Enables Insights for Azure Local: checks the Insights data collection rule against what Learn lists for Insights, then associates it with the Arc machine of every node. Supports -WhatIf. |
Parameters: -InfrastructureFile (mandatory), -LogPath.
One step stays in the portal: creating the rule (Step 3.1 and 3.2). The script never creates or changes a rule. It needs the Azure Monitor Agent on the instance (Task 02). In order, it:
- Looks up the rule
operations.monitoring.data_collection_ruleinoperations.monitoring.workspace_resource_group. A missing rule stops it with exit code 1. - Checks the rule, read only, against the Data collection rules section of Learn: the five performance counters (any instance), the two event log channels
Microsoft-Windows-Health/OperationalandMicrosoft-Windows-SDDC-Management/Operational, and a Log Analytics destination. Whenoperations.monitoring.log_analytics_workspaceis set, the rule must send to that workspace inoperations.monitoring.workspace_resource_group. When something is missing it stops with exit code 1, lists what is missing and associates nothing, also under-WhatIf. Learn's way back is the portal: the instance, Capabilities, Insights, Update. - Associates the rule with the Arc machine of every
nodes[]entry under the name<machine>-dataCollectionRuleAssociations. An association that exists is left alone (AlreadyExists); one with that name that points to another rule is reported asConflict, never changed.
Requires: PowerShell 7; modules Az.Accounts, Az.StackHCI, Az.Monitor. Sign in first with Connect-AzAccount -Tenant <azure.tenant_id>.
Run
./Enable-HciInsights.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Enable-HciInsights.ps1 -InfrastructureFile ./infrastructure.yml
Exit codes: 0 every node is associated (created now, already there, or planned under -WhatIf) or monitoring is off; 1 an Azure call or a precondition failed (no agent, the rule is missing or lacks what Insights needs, an association failed or is in conflict); 2 a value in the file is missing or not usable.
The Insights views themselves are Azure's own workbook (Learn: Insights is managed by Azure and built on Azure Monitor workbook templates). The toolkit deploys no workbook of its own.
Azure CLI
When to use: Run the task from a host that has the Azure CLI and not the Az PowerShell modules. The script is PowerShell 7 that calls
az; it readsinfrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/05-operational-foundations/phase-02-monitoring-observability/task-03-enable-hci-insights/azurecli/Enable-HciInsights.azcli.ps1 | Enables Insights for Azure Local with the Azure CLI: associates the Insights data collection rule with the Arc machine of every node. Supports -WhatIf. |
Requires: PowerShell 7 and the Azure CLI, signed in with az login --tenant <azure.tenant_id>. Needs the Azure CLI extension stack-hci (az extension add --name stack-hci); the script does not install it.
One step stays in the portal: creating the rule. Microsoft documents no template for the rule of Insights, so the script never creates or changes a rule. Enable Insights once for the instance in the Azure portal, name the rule in operations.monitoring.data_collection_rule, then run the script; without the rule it stops with exit code 1. It needs the Azure Monitor Agent on the instance (Task 02). Like the PowerShell script, it reads the rule (az monitor data-collection rule show) and stops with exit code 1, associating nothing, when the rule lacks a counter, a channel or the Log Analytics destination that Learn lists for Insights. An association that points to another rule is reported as Conflict and never changed.
Run
./Enable-HciInsights.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Enable-HciInsights.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Using the Insights Workbook
Once enabled, the Insights workbook provides several views:
Cluster Health Overview
| Metric | Description | Alert Threshold |
|---|---|---|
| Cluster Health | Overall cluster status | Warning/Critical |
| Node Health | Individual node status | Any node unhealthy |
| Storage Health | Storage pool and volume status | Degraded/Unhealthy |
| VM Health | Virtual machine states | Failed VMs |
Performance Monitoring
The workbook displays:
- CPU utilization across all nodes
- Memory availability trends
- Network throughput (total bytes/sec)
- RDMA performance for storage traffic
- Storage latency for CSV volumes
Scripts for this task are located in the azurelocal-toolkit repository under scripts/deploy/ in the appropriate task folder.
Alternatives
The procedures in this task use the methods shown in the tabs above. The toolkit is PowerShell 7 only and has no Bash scripts. A few tasks that act on Azure also have an Azure CLI script written in PowerShell. The script status page of the toolkit lists which task has which script.
Navigation Tabs
| Tab | Content |
|---|---|
| Overview | Cluster summary, health status, quick stats |
| Nodes | Per-node CPU, memory, network metrics |
| Storage | Volume health, capacity, latency |
| VMs | VM count, state distribution |
Validation
Verify Insights Status
# Check cluster Insights configuration
$cluster = Get-AzStackHciCluster `
-ResourceGroupName "{{AZURE_RESOURCE_GROUP}}" `
-ClusterName "{{CLUSTER_NAME}}"
# Check for AMA extensions on nodes
$nodes = @("{{CLUSTER_NODE_01_NAME}}", "{{CLUSTER_NODE_02_NAME}}")
foreach ($node in $nodes) {
$ext = Get-AzConnectedMachineExtension `
-ResourceGroupName "{{AZURE_RESOURCE_GROUP}}" `
-MachineName $node `
-Name "AzureMonitorWindowsAgent"
Write-Host "$node AMA Status: $($ext.ProvisioningState)"
}
Verify Data Collection
Run these queries in Log Analytics to confirm data is flowing:
// Check Health events
Event
| where Source == "Microsoft-Windows-Health"
| where TimeGenerated > ago(1h)
| summarize count() by Computer
| order by Computer asc
// Check SDDC Management events
Event
| where Source == "Microsoft-Windows-SDDC-Management"
| where TimeGenerated > ago(1h)
| summarize count() by Computer
Sample Health Query
// Cluster health summary
Event
| where Source == "Microsoft-Windows-SDDC-Management"
| where EventID == 3000 // Server health event
| where TimeGenerated > ago(24h)
| extend ParsedData = parse_json(RenderedDescription)
| project TimeGenerated, Computer, HealthState = ParsedData.HealthState
| summarize LatestHealth = arg_max(TimeGenerated, *) by Computer
Troubleshooting
| Issue | Possible Cause | Resolution |
|---|---|---|
| Insights shows "Not configured" | AMA not installed | Check Extensions on cluster nodes |
| No data in workbook | DCR not associated | Verify DCR associations in Monitor → DCRs |
Enable-HciInsights.ps1 stops: the rule is not ready for Insights | A counter, a channel or the workspace destination was removed from the rule, or the file names another rule | On the instance, Capabilities, Insights, Update (Learn: Update Insights), or name the rule Insights created in operations.monitoring.data_collection_rule |
| Stale data (>15 min old) | Agent connectivity issue | Check azcmagent show on nodes |
| Missing health events | Event log channel not enabled | Verify Windows Event Log settings |
| Cluster shows "Other" status | Recent Arc reconnection | Wait for next health check cycle |
Event Log Verification
On each cluster node, verify the required event logs are enabled:
# Run on each cluster node
$logs = @(
"Microsoft-Windows-Health/Operational",
"Microsoft-Windows-SDDC-Management/Operational"
)
foreach ($log in $logs) {
$logInfo = Get-WinEvent -ListLog $log -ErrorAction SilentlyContinue
if ($logInfo) {
Write-Host "✅ $log - Enabled: $($logInfo.IsEnabled)" -ForegroundColor Green
} else {
Write-Host "❌ $log - Not found" -ForegroundColor Red
}
}
Variables Reference
| Variable | Description | Example |
|---|---|---|
{{CLUSTER_NAME}} | Azure Local cluster name | azl-dal-cluster-01 |
{{CLUSTER_NODE_01_NAME}} | First node hostname | azl-dal-n01 |
{{LOG_ANALYTICS_WORKSPACE_NAME}} | Workspace name | law-azl-dal-prod-01 |
Next Steps
After enabling HCI Insights:
- ➡️ Task 4: Setup Alerting — Configure alert rules based on Insights data
- Review the Insights workbook for baseline understanding
- Bookmark key workbook views for operational monitoring
- Consider enabling at scale using Azure Policy for multiple clusters
Navigation
| Previous | Up | Next |
|---|---|---|
| ← Task 02: Azure Monitor Agent | Phase 02: Monitoring & Observability | Task 04: Setup Alerting → |
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2026-03-24 | Azure Local Cloud | Initial release |
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |
| 1.1.0 | 2026-11-16 | Azure Local Cloud | The scripts check the Insights rule against Learn's counters, channels and destination before they associate it; parameters, run and exit codes |