Alerting on runZero system events

runZero logs system events on a wide range of administrative actions related to assets, agents, tasks, users, and other components of the platform. Creating alerts on system events will allow you to more effectively monitor your runZero environment. The agent-offline system event specifically targets scenarios where an Explorer goes offline.

Who is this playbook for and why?

System events can be useful for a broad range of personnel depending on roles and responsibilities associated with your runZero implementation. However, IT operations and cybersecurity personnel are most common. Sending alerts via email or webhook allows you to standardize monitoring of runZero with other platforms in your technology stack, which will increase overall efficiency.

How will runZero help?

runZero is able to monitor the health of Explorers and provide notification when an Explorer goes offline.

What will I need to do?

In order to monitor for agent-offline system events, you will need to take the following steps:

  1. Determine appropriate system event action based on your use case.
  2. Create an alert template.
  3. Configure a notification channel.
  4. Create a rule.

Steps to implement

The following are step-by-step instructions for configuring a notification rule for the agent-offline system event.

Configure an alert template

  1. Go to Alerts > Templates and select Create Template.
  2. Provide a Name.
  3. Select a Template type.
  4. Choose a Subject line for message.
  5. Format the Body of message.
  6. Click Save Template.

Both the subject line and the body of the message can be customized to fit your needs. Details associated with the system event can also be included in the subject line and the message body using event detail objects. You can view specific fields that are available in the use cases section below. Additional variables are listed on our page about creating alert templates.

Configure a notification channel

  1. Go to Alerts > Channels and select Create Channel.
  2. Type a Name.
  3. Select a Channel type.
    • If Email, enter the Email address that will receive notifications.
    • If Webhook, enter the Webhook URL and any Additional headers that may be required for the notification.
  4. Select Save Channel.
Tip: If you would like to send alerts via SMS, select the Email address option and use the desired phone's SMS email address. For example, 1235556789 @msg.fi.google.com would send an SMS message to a Google Fi device with the number 123-555-6789.

Configure an alert rule

  1. Go to Alerts > Rules and select Create Rule.
  2. Select an event type.
  3. Select Configure Rule.
  4. Provide a Name for the new rule.
  5. Select appropriate Conditions for the rule. By default, Any organization and Any site will be selected.
  6. Select the Notification channel that you created.
  7. Select the Notification template that you created.
  8. Ensure that Enabled is checked and click Save Rule.

Use cases

The following is a list of specific use cases that can be applied to the previous instructions. For each use case, a brief description is provided along with the appropriate event type to use when configuring the alert rule and any specific event detail objects that can be used when configuring an alert template.

Alerting on agent-offline system events

The agent-offline event type provides notification when an Explorer goes offline. This event is valuable for personnel responsible for administering the runZero platform as well as IT Operations and SRE personnel responsible for monitoring the overall health of IT infrastructure.

Event details

The following event detail objects are available when configuring an alert template for agent-offline events. View all objects available for configuration.

Field Contents Example
{{event.agent_external_ip}} The external IP address of the Explorer that is offline 13.248.161.247
{{event.agent_host_id}} The UUID of the host where the offline Explorer is installed a3b7245bde3ddd053bd0d477ade8f364
{{event.agent_id}} The UUID of the runZero Explorer that is offline d388b66a-8052-466e-8d38-1a406c240bb2
{{event.agent_internal_ip}} The internal IP address of the Explorer that is offline 192.168.1.100
{{event.agent_last_seen}} The epoch date and time that the offline Explorer was last seen 1662544551
{{event.agent_name}} The name of the Explorer that is offline EXPLORER01
{{event.agent_os}} A summary of the Explorer’s operating system Microsoft Windows Server 2016
{{event.agent_tags}} An array of tags set on the Explorer location=datacenter
{{event.agent_version}} The version of the Explorer software installed 3.0.15 (build 20220901210518) [c538aa22b33e72ad048d7d03204397ecba0bb354]
{{event.organization_id}} The UUID of the organization where the offline Explorere is located 98828456-f9ee-485d-aff6-11ddc91b2468
{{event.organization_name}} The name of the organization where the offline Explorer is located runZero
{{event.site_id}} The UUID of the site where the Explorer is assigned, if applicable 22f9bfba-31ef-4640-8c95-379474c1ffb1
{{event.site_name}} The name of the site where the Explorer is assigned, if applicable Datacenter

Alerting on agent-reconnect system events

The agent-reconnected event type supplements the agent-offline system event by providing notification when an offline Explorer reconnects to the console. This event is valuable for personnel that are responsible for administering the runZero platform as well as IT Operations and SRE personnel who are responsible for monitoring the overall health of your IT infrastructure.

Event details

The following event detail objects are available when configuring an alert template for agent-reconnect events. View all objects available for configuration.

Field Contents Example
{{event.agent_external_ip}} The external IP address of the Explorer that is offline 13.248.161.247
{{event.agent_host_id}} The UUID of the host where the offline Explorer is installed a3b7245bde3ddd053bd0d477ade8f364
{{event.agent_id}} The UUID of the runZero Explorer that is offline d388b66a-8052-466e-8d38-1a406c240bb2
{{event.agent_internal_ip}} The internal IP address of the Explorer that is offline 192.168.1.100
{{event.agent_last_seen}} The epoch date and time that the offline Explorer was last seen 1662544551
{{event.agent_offline_time}} The period of time that the Explorer was offline 19h37m19.848350811s
{{event.agent_name}} The name of the Explorer that is offline EXPLORER01
{{event.agent_os}} A summary of the Explorer’s operating system Microsoft Windows Server 2016
{{event.agent_tags}} An array of tags set on the Explorer location=datacenter
{{event.agent_version}} The version of the Explorer software installed 3.0.15 (build 20220901210518) [c538aa22b33e72ad048d7d03204397ecba0bb354]
{{event.organization_id}} The UUID of the organization where the offline Explorer is located 98828456-f9ee-485d-aff6-11ddc91b2468
{{event.organization_name}} The name of the organization where the offline Explorer is located runZero
{{event.site_id}} The UUID of the site where the Explorer is assigned, if applicable 22f9bfba-31ef-4640-8c95-379474c1ffb1
{{event.site_name}} The name of the site where the Explorer is assigned, if applicable Datacenter

Alerting on license-limit-exceeded system events

The license-limit-exceeded event type will notify you when your total number of live assets exceeds the maximum number of assets allowed by your license.

Event details

The following event detail objects are available when configuring an alert template for license-limit-exceeded events. View all objects available for configuration.

Field Contents Example
{{event.asset_overage}} The total number of assets over the max asset limit 150
{{event.license_live_asset_count}} The total number of live assets associated with your account 1150
{{event.license_max_assets}} The maximum number of assets permitted under your license 1000
{{event.license_project_asset_count}} The total number of project assets associated with your account 3000
{{event.license_recent_asset_count}} The total number of assets seen in the last 30 days 1150
{{event.license_recent_project_asset_count}} The total number of project assets seen in the last 30 days 3500
{{event.license_type}} The type of license that is assigned to your account enterprise
{{event.source_id}} The ID of the source that lead to the license overage 1
{{event.source_type}} The name of the source that lead to the license overage runZero
{{event.task_type}} The type of task that lead to the license overage import

Outcome demo

This video is a short demo of what the outcome of alerting on runZero system events may look like.