Chiamare un runbook di Automazione di Azure da un avviso di Log AnalyticsCall an Azure Automation runbook from a Log Analytics alert

È possibile configurare un avviso in Azure Log Analytics per creare un record di avviso quando i risultati corrispondono ai criteri.You can configure an alert in Azure Log Analytics to create an alert record when results match your criteria. L'avviso può quindi eseguire automaticamente un runbook di Automazione di Azure per provare a risolvere automaticamente il problema.That alert can then automatically run an Azure Automation runbook in an attempt to auto-remediate the issue.

Un avviso potrebbe ad esempio indicare un picco prolungato nell'utilizzo del processoreFor example, an alert might indicate a prolonged spike in processor utilization. o un errore in un processo dell'applicazione fondamentale per il funzionamento di un'applicazione aziendale.Or it might indicate when an application process that's critical to the functionality of a business application fails. Un runbook può quindi scrivere un evento corrispondente nel registro eventi di Windows.A runbook can then write a corresponding event in the Windows event log.

Per chiamare un runbook nella configurazione di un avviso sono disponibili due opzioni:There are two options to call a runbook in the alert configuration:

  • Usare un webhook.Use a webhook.

    • Questa è l'unica opzione disponibile se l'area di lavoro di Log Analytics non è collegata a un account di Automazione.This is the only option available if your Log Analytics workspace is not linked to an Automation account.
    • Se si ha già un account di Automazione collegato a un'area di lavoro di Log Analytics, questa opzione è disponibile.If you already have an Automation account linked to a Log Analytics workspace, this option is still available.
  • Selezione diretta di un runbook.Select a runbook directly.

    • Questa opzione è disponibile solo se l'area di lavoro di Log Analytics è collegata a un account di Automazione.This option is available only if the Log Analytics workspace is linked to an Automation account.

Chiamata di un runbook con un webhookCalling a runbook by using a webhook

È possibile usare un webhook per avviare un runbook specifico in Automazione di Azure tramite una singola richiesta HTTP.You can use a webhook to start a particular runbook in Azure Automation through a single HTTP request. Prima di configurare l'l'azione del webhook per gli avvisi del log per chiamare il runbook usando un webhook come azione di avviso, è necessario creare un webhook per il runbook chiamato con questo metodo.Before you configure the Webhook action for log alerts to call the runbook by using a webhook as an alert action, you need to create a webhook for the runbook that's called through this method. Ricordarsi di annotare l'URL del webhook per potervi fare riferimento durante la configurazione della regola di avviso.Remember to record the webhook URL so you can reference it while configuring the alert rule.

Chiamata diretta di un runbookCalling a runbook directly

È possibile installare e configurare l'offerta Automazione e controllo nell'area di lavoro di Log Analytics.You can install and configure the Automation and Control offering in your Log Analytics workspace. Durante la configurazione dell'opzione relativa alle azioni del runbook per l'avviso è possibile visualizzare tutti i runbook nell'elenco a discesa Seleziona un runbook e quindi selezionare il runbook specifico da eseguire in risposta all'avviso.While you're configuring the runbook actions option for the alert, you can view all runbooks from the Select a runbook drop-down list and select the specific runbook that you want to run in response to the alert. Il runbook selezionato può essere eseguito in un'area di lavoro di Azure o in un ruolo di lavoro ibrido per runbook.The selected runbook can run in an Azure workspace or on a hybrid runbook worker.

Dopo la creazione dell'avviso con l'opzione relativa al runbook, viene creato un webhook per il runbook.After you create the alert by using the runbook option, a webhook is created for the runbook. Per visualizzare il webhook, passare all'account di Automazione e aprire il riquadro del webhook per il runbook selezionato.You can see the webhook if you go to the Automation account and open the webhook pane of the selected runbook.

Il webhook non viene eliminato in caso di eliminazione dell'avviso,If you delete the alert, the webhook is not deleted. ma ciò non costituisce un problema.This is not a problem. Il webhook diventa semplicemente un elemento orfano che dovrà essere eliminato manualmente per mantenere organizzato l'account di Automazione.The webhook just becomes an orphaned item that you should eventually delete manually, to maintain an organized Automation account.

Caratteristiche di un runbookCharacteristics of a runbook

Entrambi i metodi per chiamare il runbook dall'avviso di Log Analytics hanno caratteristiche che è necessario comprendere prima di configurare le regole di avviso.Both methods for calling the runbook from the Log Analytics alert have characteristics that you need to understand before you configure your alert rules.

I dati dell'avviso sono contenuti in formato JSON in una singola proprietà denominata SearchResult.The alert data is in JSON format in a single property called SearchResult. Questo formato è per le azioni di runbook e webhook con un payload standard.This format is for runbook and webhook actions with a standard payload. Per le azioni webhook con payload personalizzati, che includono IncludeSearchResults:True in RequestBody, la proprietà è SearchResults.For webhook actions with custom payloads (including IncludeSearchResults:True in RequestBody), the property is SearchResults.

È necessario avere un parametro di input del runbook denominato WebhookData di tipo Object.You must have a runbook input parameter called WebhookData that is an Object type. Questo parametro può essere obbligatorio o facoltativo.It can be mandatory or optional. L'avviso passa i risultati della ricerca al runbook usando questo parametro di input.The alert passes the search results to the runbook by using this input parameter.

param  
    (  
    [Parameter (Mandatory=$true)]  
    [object] $WebhookData  
    )

È necessario includere anche il codice per convertire WebhookData in un oggetto di PowerShell.You must also have code to convert WebhookData to a PowerShell object.

$SearchResult = (ConvertFrom-Json $WebhookData.RequestBody).SearchResult.value

$SearchResult è una matrice di oggetti,$SearchResult is an array of objects. ognuno dei quali contiene i campi con i valori di un risultato della ricerca.Each object contains the fields with values from one search result.

Procedura dettagliata di esempioExample walkthrough

L'esempio seguente di un runbook grafico illustra il funzionamento del processo.The following example of a graphical runbook demonstrates how this process works. Il runbook avvia un servizio di Windows.It starts a Windows service.

Runbook grafico per l'avvio di un servizio di Windows

Il runbook ha un parametro di input di tipo Object denominato WebhookData,The runbook has one input parameter of type Object that is called WebhookData. che include i dati del webhook passati dall'avviso contenente SearchResult.It includes the webhook data passed from the alert that contains SearchResult.

Parametri di input dei runbook

Per questo esempio, in Log Analytics sono stati creati due campi personalizzati: SvcDisplayName_CF e SvcState_CF.For this example, we created two custom fields in Log Analytics: SvcDisplayName_CF and SvcState_CF. In questi campi vengono estratti il nome visualizzato e lo stato del servizio (che può essere in esecuzione o arrestato) dall'evento scritto nel registro eventi di sistema.These fields extract the service display name and the state of the service (that is, running or stopped) from the event that's written to the system event log. Viene quindi creata una regola di avviso con la query di ricerca seguente, per poter rilevare l'arresto del servizio Spooler di stampa nel sistema Windows:We then created an alert rule with the following search query, so that we can detect when the Print Spooler service is stopped on the Windows system:

Type=Event SvcDisplayName_CF="Print Spooler" SvcState_CF="stopped"

Può trattarsi di qualsiasi servizio a cui si è interessati.It can be any service of interest. Per questo esempio si fa riferimento a uno dei servizi preesistenti inclusi nel sistema operativo Windows.For this example, we're referencing one of the pre-existing services that are included with the Windows OS. L'azione di avviso viene configurata per eseguire il runbook usato in questo esempio nel ruolo di lavoro ibrido per runbook, abilitato nel sistema di destinazione.The alert action is configured to execute the runbook used in this example and run on the hybrid runbook worker, which is enabled on the target system.

L'attività di codice del runbook Get Service Name from LA converte la stringa in formato JSON in un tipo Object e applica un filtro per l'elemento SvcDisplayName_CF.The runbook code activity Get Service Name from LA converts the JSON-formatted string into an object type and filters on the item SvcDisplayName_CF. Estrae quindi il nome visualizzato del servizio di Windows e passa questo valore all'attività successiva, che verifica che il servizio sia stato arrestato prima di tentarne il riavvio.It extracts the display name of the Windows service and passes this value to the next activity, which verifies that the service is stopped before attempting to restart it. SvcDisplayName_CF è un campo personalizzato che è stato creato in Log Analytics per illustrare questo esempio.SvcDisplayName_CF is a custom field that we created in Log Analytics to demonstrate this example.

$SearchResult = (ConvertFrom-Json $WebhookData.RequestBody).SearchResult.value
$SearchResult.SvcDisplayName_CF  

Quando il servizio viene arrestato, la regola di avviso in Log Analytics rileva una corrispondenza, attiva il runbook e invia il contesto dell'avviso al runbook.When the service stops, the alert rule in Log Analytics detects a match, triggers the runbook, and sends the alert context to the runbook. Il runbook prova a verificare che il servizio sia stato arrestato.The runbook tries to verify that the service is stopped. In questo caso, tenta di riavviare il servizio, verificare che sia stato avviato correttamente e visualizzare i risultati.If so, the runbook attempts to restart the service, verify that it started correctly, and display the results.

In alternativa, se l'account di Automazione non è collegato all'area di lavoro di Log Analytics, è possibile configurare la regola di avviso con un'azione webhook.Alternatively, if you don't have your Automation account linked to your Log Analytics workspace, you can configure the alert rule with a webhook action. L'azione webhook attiva il runbookThe webhook action triggers the runbook. e lo configura anche per la conversione della stringa in formato JSON e l'applicazione di un filtro per SearchResult in base alle indicazioni precedenti.It also configures the runbook to convert the JSON-formatted string and filter on SearchResult by following the guidance mentioned earlier.

Nota

Se l'area di lavoro è stata aggiornata al nuovo linguaggio di query di Log Analytics, il payload del webhook è stato modificato.If your workspace has been upgraded to the new Log Analytics query language, the webhook payload has changed. Per informazioni dettagliate sul formato, vedere la documentazione relativa all'API REST di Azure Log Analytics.Details of the format are in the Azure Log Analytics REST API.

Passaggi successiviNext steps