Azure Resource Notifications - Health Resources events in Azure Event Grid (Preview)

  • Article

HealthResources system topic provides accurate, reliable, and comprehensive health information, enabling deeper understanding of the diverse service issues impacting your Azure resources namely, single instance virtual machines (VMs), Virtual Machine Scale Set VMS, and Virtual Machine Scale Sets. Health Resources offers two event types for consumption: AvailabilityStatusChanged and ResourceAnnotated.

This article provides the properties and the schema for Azure Resource Notifications Health Resources events. For an introduction to event schemas in general, see Azure Event Grid event schema. In addition, you can find samples of generated events and a link to a related article on how to create system topic for this topic type.

Event types

Health Resources offers two event types for consumption:

Event type Description
Microsoft.ResourceNotifications.HealthResources.AvailabilityStatusChanged Raised when the availability status of a single instance VM, a virtual machine scale set, or a VM in a virtual machine scale set changes.

This information provides insight into all the times your single instance VMs, VMs in virtual machine scale sets, or virtual machine scale sets themselves have been unavailable because of Azure service issues. For more information on the various health statuses, see Azure Resource Health overview - Azure Service Health.

Microsoft.ResourceNotifications.HealthResources.ResourceAnnotated Raised when the health of a VM, a virtual machine scale set, or a VM in a virtual machine scale set, is impacted by availability impacting disruptions. The platform emits context as to why the disruption has occurred to assist you in responding appropriately.

This information helps you to infer the availability state of your resources by providing crucial information on the reasons and causes for changes in availability. Using this data, you can take faster and more targeted mitigation measures. For more information on the various annotations emitted, see Resource Health virtual machine Health Annotations.

Role-based access control

Currently, these events are exclusively emitted at the Azure subscription scope. It implies that the entity creating the event subscription for this topic type receives notifications throughout this Azure subscription. For security reasons, it's imperative to restrict the ability to create event subscriptions on this topic to principals with read access over the entire Azure subscription. To access data via this system topic, in addition to the generic permissions required by Event Grid, the following Azure Resource Notifications specific permission is necessary: Microsoft.ResourceNotifications/systemTopics/subscribeToHealthResources/action.

Event schemas

Here's the schema:

{
    "id": string,
    "source": string,
    "subject": string,
    "type": "Microsoft.ResourceNotifications.HealthResources.AvailabilityStatusChanged | Microsoft.ResourceNotifications.HealthResources.ResourceAnnotated",
    "time ": string, 
    "data": {
        "resourceInfo": {
            "id": string,
            "name": string,
            "type": string,
            "properties": { 
                <<Different for AvailabilityStatusChanged event and ResourceAnnotated event>>            
            }
        },
        "operationalInfo":{
			"resourceEventTime": date-time
		},
        "apiVersion": string 
    }, 
    "specversion": string
}

An event has the following top-level data:

Property Type Description
id String Unique identifier of the event
source String The Azure subscription for which this system topic is being created.
subject String Publisher defined path to the base resource on which this event is emitted.
type String Registered event type of this system topic type
time String
Format: 2022-11-07T18:43:09.2894075Z		 The time the event is generated based on the provider's UTC time
data Object Contains event data specific to the resource provider. For more information, see the next table.
specversion String CloudEvents schema specification version.

The data object has the following properties:

Property Type Description
resourceInfo Object Data specific to the resource. For more information, see the next table.
apiVersion String API version of the resource properties.
operationalInfo Object Details of operational information pertaining to the resource.

The resourceInfo object has the following properties:

Property Type Description
id String Publisher defined path to the event subject
name String This field indicates the Event-id. It always takes the value of the last section of the id field.
type String The type of event that is being emitted. In this context, it's either Microsoft.ResourceHealth/AvailabilityStatuses or Microsoft.ResourceHealth/ResourceAnnotated.
properties Object Payload of the resource. For more information, see the next table.

The operationalInfo object has the following properties:

Property Type Description
resourceEventTime DateTime Date and time when the resource was updated.

The properties within the data object is different for AvailabilityStatusChanged and ResourceAnnotated events.

Properties for the AvailabilityStatusChanged event

            "properties": {
                "targetResourceId": string,
                "targetResourceType": string,
                "occurredTime": string,
                "previousAvailabilityState": string,
                "availabilityState": string
            }

For the AvailabilityStatusChanged event, the properties object has the following properties:

Property Type Description
targetResourceId String The base resource for which the availability information is being emitted.
targetResourceType String The type of the base resource.
occurredTime String The time when this actual event was emitted.
previousAvailabilityState String Previous availability status.
availabilityState String Current availability status. For the list of values, see Availability Statuses - Get By Resource - REST API (Azure Resource Health).

Properties for the ResourceAnnotated event

            "properties": {
                "targetResourceId": string,
                "targetResourceType": string,
                "occurredTime": string,
                "annotationName": string,
                "reason": string,
                "summary": string,
                "context": string,
                "category": string,
            }

For the ResourceAnnotated event, the properties object has the following properties:

Property Type Description
targetResourceId String The base resource for which the annotation information is being emitted.
targetResourceType String The type of the base resource.
occurredTime String Timestamp when the annotation was emitted by the Azure platform in response to availability-influencing event.
annotationName String The name of the annotation. For the list of annotations and the corresponding descriptions, see Resource Health virtual machine Health Annotations - Azure Service Health.
reason String Brief statement on why resource availability has changed or was influenced.
summary String Detailed statement on the activity and cause for resource availability to change or be influenced.
context String Determines whether resource availability was influenced due to Azure or user caused activity.
category String Determines whether resource availability was influenced due to planned or unplanned activity. This property is only applicable to Platform-Initiated events.

Example events

AvailabilityStatusChanged event

The following example shows the schema of a key-value modified event:

{
  "id": "1fb6fa94-d965-4306-abeq-4810f0774e97",
  "source": "/subscriptions/{subscription-id}",
  "subject": "/subscriptions/{subscription-id}/resourceGroups/{rg-name}/providers/Microsoft.Compute/virtualMachines/{vm-name}",
  "data": {
    "resourceInfo": {
      "id": "/subscriptions/{subscription-id}/resourceGroups/{rg-name}/providers/Microsoft.Compute/virtualMachines/{vm-name}/providers/Microsoft.ResourceHealth/availabilityStatuses/{event-id}",
      "name": "{event-id}",
      "type": "Microsoft.ResourceHealth/availabilityStatuses",
      "properties": {
        "targetResourceId": "/subscriptions/{subscription-id}/resourceGroups/{rg-name}/providers/Microsoft.Compute/virtualMachines/{vm-name}",
        "targetResourceType": "Microsoft.Compute/virtualMachines",
        "occurredTime": "2023-07-24T19:20:37.9245071Z",
        "previousAvailabilityState": "Unavailable",
        "availabilityState": "Available"
      }
    },
    "operationalInfo": {
      "resourceEventTime": "2023-07-24T19:20:37.9245071Z"
    },
    "apiVersion": "2023-12-01"
  },
  "type": "Microsoft.ResourceNotifications.HealthResources.AvailabilityStatusChanged",
  "specversion": "1.0",
  "time": "2023-07-24T19:20:37.9245071Z"
}

ResourceAnnotated event

The following example shows the schema of a key-value modified event:

{
  "id": "8945cf9b-e220-496e-ab4f-f3a239318995",
  "source": "/subscriptions/{subscription-id}",
  "subject": "/subscriptions/{subscription-id}/resourceGroups/{rg-name}/providers/Microsoft.Compute/virtualMachines/{vm-name}",
  "data": {
    "resourceInfo": {
      "id": "/subscriptions/{subscription-id}/resourceGroups/{rg-name}/providers/Microsoft.Compute/virtualMachines/{vm-name}/providers/Microsoft.ResourceHealth/resourceAnnotations/{event-id}",
      "name": "{event-id}",
      "type": "Microsoft.ResourceHealth/resourceAnnotations",
      "properties": {
        "targetResourceId": "/subscriptions/{subscription-id}/resourceGroups/{rg-name}/providers/Microsoft.Compute/virtualMachines/{vm-name}",
        "targetResourceType": "Microsoft.Compute/virtualMachines",
        "occurredTime": "2023-07-24T19:20:37.9245071Z",
        "annotationName": "VirtualMachineDeallocationInitiated",
        "reason": "Stopping and deallocating",
        "summary": "This virtual machine is stopped and deallocated as requested by an authorized user or process.",
        "context": "Customer Initiated",
        "category": "Not Applicable"
      }
    },
    "operationalInfo": {
      "resourceEventTime": "2023-07-24T19:20:37.9245071Z"
    },
    "apiVersion": "2022-08-01"
  },
  "type": "Microsoft.ResourceNotifications.HealthResources.ResourceAnnotated",
  "specversion": "1.0",
  "time": "2023-07-24T19:20:37.9245071Z"
}

Contact us

If you have any questions or feedback on this feature, don't hesitate to reach us at arnsupport@microsoft.com.

To better assist you with specific feedback about a certain event, provide the following information:

For missing events:

  • System topic type name
  • Approximate timestamp in UTC when the operation was executed
  • Base resource ID for which the notification was generated
  • Navigate to your resource in Azure portal and select JSON view at the far right corner. Resource ID is the first field on the JSON view page.
  • Expected event type
  • Operation executed (for example, VM started or stopped, Storage account created etc.)
  • Description of issue encountered (for example, VM started and no Microsoft.ResourceNotifications.HealthResources.AvailabilityStatusChanged event generated)
  • If possible, provide the correlation ID of operation executed

For event that was delayed or has unexpected content

  • System topic type name
  • Entire contents of the notification excluding data.resourceInfo.properties
  • Description of issue encountered and impacted field values

Ensure that you aren't providing any end user identifiable information while you're sharing this data.