Raccogliere dati in Log Analytics con un runbook di Automazione di AzureCollect data in Log Analytics with an Azure Automation runbook

È possibile raccogliere una quantità significativa di dati in Log Analytics da una serie di origini, tra cui origini dati negli agenti e dati raccolti da Azure.You can collect a significant amount of data in Log Analytics from a variety of sources including data sources on agents and also data collected from Azure. Esistono tuttavia scenari in cui è necessario raccogliere dati non accessibili tramite queste origini standard.There are a scenarios though where you need to collect data that isn't accessible through these standard sources. In questi casi è possibile usare l'API di raccolta dati HTTP per inviare dati a Log Analytics da qualsiasi client dell'API REST.In these cases, you can use the HTTP Data Collector API to write data to Log Analytics from any REST API client. Un modo comune per eseguire questa raccolta dati è usare un runbook in Automazione di Azure.A common method to perform this data collection is using a runbook in Azure Automation.

Questa esercitazione illustra il processo di creazione e pianificazione di un runbook in Automazione di Azure per l'invio di dati a Log Analytics.This tutorial walks through the process for creating and scheduling a runbook in Azure Automation to write data to Log Analytics.

PrerequisitiPrerequisites

Questo scenario richiede la configurazione delle risorse seguenti nella sottoscrizione di Azure.This scenario requires the following resources configured in your Azure subscription. Per entrambe è possibile usare un account gratuito.Both can be a free account.

Panoramica dello scenarioOverview of scenario

Per questa esercitazione si scriverà un runbook che raccoglie informazioni sui processi di automazione.For this tutorial, you'll write a runbook that collects information about Automation jobs. I runbook in Automazione di Azure vengono implementati con PowerShell, quindi si inizia scrivendo e testando uno script nell'editor di Automazione di Azure.Runbooks in Azure Automation are implemented with PowerShell, so you'll start by writing and testing a script in the Azure Automation editor. Dopo aver verificato che vengano raccolte le informazioni necessarie, si invieranno i dati a Log Analytics e si verificherà il tipo di dati personalizzato.Once you verify that you're collecting the required information, you'll write that data to Log Analytics and verify the custom data type. Si creerà infine una pianificazione per avviare il runbook a intervalli regolari.Finally, you'll create a schedule to start the runbook at regular intervals.

Nota

È possibile configurare Automazione di Azure per l'invio di informazioni sui processi a Log Analytics senza questo runbook.You can configure Azure Automation to send job information to Log Analytics without this runbook. Questo scenario viene usato principalmente a supporto dell'esercitazione e si consiglia di inviare i dati a un'area di lavoro di test.This scenario is primarily used to support the tutorial, and it's recommended that you send the data to a test workspace.

1. Installare il modulo dell'API di raccolta dati1. Install Data Collector API module

Ogni richiesta inviata dall'API di raccolta dati HTTP deve essere nel formato corretto e includere un'intestazione dell'autorizzazione.Every request from the HTTP Data Collector API must be formatted appropriately and include an authorization header. Questa operazione può essere eseguita nel runbook, ma è possibile ridurre la quantità di codice necessario usando un modulo che semplifica questo processo.You can do this in your runbook, but you can reduce the amount of code required by using a module that simplifies this process. Uno dei moduli che è possibile usare è OMSIngestionAPI in PowerShell Gallery.One module that you can use is OMSIngestionAPI module in the PowerShell Gallery.

Per usare un modulo in un runbook, il modulo deve essere installato nell'account di Automazione.To use a module in a runbook, it must be installed in your Automation account. Qualsiasi runbook presente nello stesso account potrà quindi usare le funzioni disponibili nel modulo.Any runbook in the same account can then use the functions in the module. È possibile installare un nuovo modulo selezionando Asset > Moduli > Aggiungi un modulo nell'account di Automazione.You can install a new module by selecting Assets > Modules > Add a module in your Automation account.

PowerShell Gallery offre tuttavia un'opzione rapida per distribuire un modulo direttamente nell'account di Automazione, quindi è possibile usare questa opzione per l'esercitazione.The PowerShell Gallery though gives you a quick option to deploy a module directly to your automation account so you can use that option for this tutorial.

Modulo OMSIngestionAPI

  1. Passare a PowerShell Gallery.Go to PowerShell Gallery.
  2. Cercare OMSIngestionAPI.Search for OMSIngestionAPI.
  3. Fare clic sul pulsante Deploy to Azure Automation (Distribuisci in Automazione di Azure).Click on the Deploy to Azure Automation button.
  4. Selezionare l'account di Automazione e fare clic su OK per installare il modulo.Select your automation account and click OK to install the module.

2. Creare variabili di Automazione2. Create Automation variables

Le variabili di Automazione contengono valori che possono essere usati da tutti i runbook presenti nell'account di Automazione.Automation variables hold values that can be used by all runbooks in your Automation account. Rendono i runbook più flessibili perché consentono di modificare questi valori senza modificare il runbook vero e proprio.They make runbooks more flexible by allowing you to change these values without editing the actual runbook. Ogni richiesta inviata dall'API di raccolta dati HTTP richiede l'ID e la chiave dell'area di lavoro OMS e gli asset di tipo variabile sono ideali per archiviare queste informazioni.Every request from the HTTP Data Collector API requires the ID and key of the OMS workspace, and variable assets are ideal to store this information.

Variabili

  1. Nel portale di Azure passare all'account di Automazione.In the Azure portal, navigate to your Automation account.
  2. Selezionare Variabili in Risorse condivise.Select Variables under Shared Resources.
  3. Fare clic su Aggiungi variabile e creare le due variabili nella tabella seguente.Click Add a variable and create the two variables in the following table.
ProprietàProperty Valore ID area di lavoroWorkspace ID Value Valore chiave area di lavoroWorkspace Key Value
NomeName WorkspaceIdWorkspaceId WorkspaceKeyWorkspaceKey
TipoType StringString StringString
ValoreValue Incollare l'ID dell'area di lavoro di Log Analytics.Paste in the Workspace ID of your Log Analytics workspace. Incollare la chiave primaria o secondaria dell'area di lavoro di Log Analytics.Paste in with the Primary or Secondary Key of your Log Analytics workspace.
CrittografatoEncrypted NoNo Yes

3. Creare un runbook3. Create runbook

Automazione di Azure offre un editor nel portale in cui è possibile modificare e testare il runbook.Azure Automation has an editor in the portal where you can edit and test your runbook. È possibile usare l'editor di script direttamente con PowerShell oppure creare un runbook grafico.You have the option to use the script editor to work with PowerShell directly or create a graphical runbook. Per questa esercitazione si userà uno script di PowerShell.For this tutorial, you will work with a PowerShell script.

Modificare il runbook

  1. Passare all'account di Automazione.Navigate to your Automation account.
  2. Fare clic su Runbook > Aggiungi runbook > Crea un nuovo runbook.Click Runbooks > Add a runbook > Create a new runbook.
  3. Per il nome del runbook digitare Collect-Automation-jobs.For the runbook name, type Collect-Automation-jobs. Per il tipo di runbook selezionare PowerShell.For the runbook type, select PowerShell.
  4. Fare clic su Crea per creare il runbook e avviare l'editor.Click Create to create the runbook and start the editor.
  5. Copiare e incollare il codice seguente nel runbook.Copy and paste the following code into the runbook. Vedere i commenti nello script per la spiegazione del codice.Refer to the comments in the script for explanation of the code.

     # Get information required for the automation account from parameter values when the runbook is started.
     Param
     (
         [Parameter(Mandatory = $True)]
         [string]$resourceGroupName,
         [Parameter(Mandatory = $True)]
         [string]$automationAccountName
     )
    
     # Authenticate to the Automation account using the Azure connection created when the Automation account was created.
     # Code copied from the runbook AzureAutomationTutorial.
     $connectionName = "AzureRunAsConnection"
     $servicePrincipalConnection=Get-AutomationConnection -Name $connectionName         
     Add-AzureRmAccount `
         -ServicePrincipal `
         -TenantId $servicePrincipalConnection.TenantId `
         -ApplicationId $servicePrincipalConnection.ApplicationId `
         -CertificateThumbprint $servicePrincipalConnection.CertificateThumbprint 
    
     # Set the $VerbosePreference variable so that we get verbose output in test environment.
     $VerbosePreference = "Continue"
    
     # Get information required for Log Analytics workspace from Automation variables.
     $customerId = Get-AutomationVariable -Name 'WorkspaceID'
     $sharedKey = Get-AutomationVariable -Name 'WorkspaceKey'
    
     # Set the name of the record type.
     $logType = "AutomationJob"
    
     # Get the jobs from the past hour.
     $jobs = Get-AzureRmAutomationJob -ResourceGroupName $resourceGroupName -AutomationAccountName $automationAccountName -StartTime (Get-Date).AddHours(-1)
    
     if ($jobs -ne $null) {
         # Convert the job data to json
         $body = $jobs | ConvertTo-Json
    
         # Write the body to verbose output so we can inspect it if verbose logging is on for the runbook.
         Write-Verbose $body
    
         # Send the data to Log Analytics.
         Send-OMSAPIIngestionFile -customerId $customerId -sharedKey $sharedKey -body $body -logType $logType -TimeStampField CreationTime
     }
    

4. Testare il runbook4. Test runbook

Automazione di Azure include un ambiente che consente di testare il runbook prima di pubblicarlo.Azure Automation includes an environment to test your runbook before you publish it. È possibile esaminare i dati raccolti dal runbook e verificare che il runbook invii i dati a Log Analytics come previsto prima della pubblicazione nell'ambiente di produzione.You can inspect the data collected by the runbook and verify that it writes to Log Analytics as expected before publishing it to production.

Testare il runbook

  1. Fare clic su Salva per salvare il runbook.Click Save to save the runbook.
  2. Fare clic su Riquadro di test per aprire il runbook nell'ambiente di test.Click Test pane to open the runbook in the test environment.
  3. Il runbook include parametri, quindi verrà chiesto di inserire i relativi valori.Since your runbook has parameters, you're prompted to enter values for them. Immettere il nome del gruppo di risorse e l'account di Automazione dal quale verranno raccolte le informazioni sui processi.Enter the name of the resource group and the automation account that your going to collect job information from.
  4. Fare clic su Avvia per avviare il runbook.Click Start to the start the runbook.
  5. Il runbook verrà avviato con lo stato In coda prima di passare allo stato In esecuzione eThe runbook will start with a status of Queued before it goes to Running.
  6. Il runbook visualizzerà un output dettagliato con i processi raccolti in formato JSON.The runbook should display verbose output with the jobs collected in json format. Se non è elencato alcun processo, probabilmente non sono stati creati processi nell'account di Automazione nell'ultima ora.If no jobs are listed, then there may have been no jobs created in the automation account in the last hour. Provare ad avviare un runbook nell'account di Automazione e quindi eseguire di nuovo il test.Try starting any runbook in the automation account and then perform the test again.
  7. Assicurarsi che l'output non visualizzi eventuali errori nel comando POST per Log Analytics.Ensure that the output doesn't show any errors in the post command to Log Analytics. Verrà visualizzato un messaggio simile al seguente.You should have a message similar to the following.

    Output del comando POST

5. Verificare i record in Log Analytics5. Verify records in Log Analytics

Dopo aver completato il test del runbook e aver verificato che l'output sia stato ricevuto correttamente, è possibile verificare che i record siano stati creati usando una ricerca log in Log Analytics.Once the runbook has completed in test, and you verified that the output was successfully received, you can verify that the records were created using a log search in Log Analytics.

Output del log

  1. Nel portale di Azure selezionare l'area di lavoro di Log Analytics.In the Azure portal, select your Log Analytics workspace.
  2. Fare clic su Ricerca log.Click on Log Search.
  3. Digitare il comando Type=AutomationJob_CL e fare clic sul pulsante di ricerca.Type the following command Type=AutomationJob_CL and click the search button. Si noti che il tipo di record include _CL, non specificato nello script.Note that the record type includes _CL that isn't specified in the script. Tale suffisso viene aggiunto automaticamente al tipo di log per indicare che si tratta di un tipo di log personalizzato.That suffix is automatically appended to the log type to indicate that it's a custom log type.
  4. Verranno restituiti uno o più record, a indicare che il runbook funziona come previsto.You should see one or more records returned indicating that the runbook is working as expected.

6. Pubblicare il runbook6. Publish the runbook

Dopo aver verificato che il runbook funzioni correttamente, è necessario pubblicarlo per eseguirlo nell'ambiente di produzione.Once you've verified that the runbook is working correctly, you need to publish it so you can run it in production. È possibile continuare a modificare e testare il runbook senza modificare la versione pubblicata.You can continue to edit and test the runbook without modifying the published version.

Pubblicare il runbook

  1. Tornare all'account di Automazione.Return to your automation account.
  2. Fare clic su Runbook e selezionare Collect-Automation-jobs.Click on Runbooks and select Collect-Automation-jobs.
  3. Fare clic su Modifica e quindi su Pubblica.Click Edit and then Publish.
  4. Fare clic su quando viene chiesto di confermare l'intenzione di sovrascrivere la versione pubblicata in precedenza.Click Yes when asked to verify that you want to overwrite the previously published version.

7. Impostare le opzioni di registrazione7. Set logging options

Per l'ambiente di test è stato possibile esaminare l'output dettagliato perché è stata impostata la variabile $VerbosePreference nello script.For test, you were able to view verbose output because you set the $VerbosePreference variable in the script. Per l'ambiente di produzione è necessario impostare le proprietà di registrazione per il runbook se si intende visualizzare l'output dettagliato.For production, you need to set the logging properties for the runbook if you want to view verbose output. Per il runbook usato in questa esercitazione, verranno visualizzati i dati JSON inviati a Log Analytics.For the runbook used in this tutorial, this will display the json data being sent to Log Analytics.

Registrazione e traccia

  1. Nelle proprietà del runbook selezionare Registrazione e traccia in Impostazioni del runbook.In the properties for your runbook select Logging and tracing under Runbook Settings.
  2. Impostare Registra record dettagliati su .Change the setting for Log verbose records to On.
  3. Fare clic su Salva.Click Save.

8. Pianificare il runbook8. Schedule runbook

Il modo più comune per avviare un runbook che raccoglie dati di monitoraggio è di pianificarne l'esecuzione automatica.The most common way to start a runbook that collects monitoring data is to schedule it to run automatically. Per eseguire questa operazione, creare una pianificazione in Automazione di Azure e associarla al runbook.You do this by creating a schedule in Azure Automation and attaching it to your runbook.

Pianificare il runbook

  1. Nelle proprietà del runbook selezionare Pianificazioni in Risorse.In the properties for your runbook, select Schedules under Resources.
  2. Fare clic su Aggiungi pianificazione > Collegare una pianificazione al runbook > Crea una nuova pianificazione.Click Add a schedule > Link a schedule to your runbook > Create a new schedule.
  3. Immettere i valori seguenti per la pianificazione e fare clic su Crea.Type in the following values for the schedule and click Create.
ProprietàProperty ValoreValue
NomeName AutomationJobs-HourlyAutomationJobs-Hourly
IniziaStarts Selezionare un orario successivo di almeno 5 minuti all'ora corrente.Select any time at least 5 minutes past the current time.
RicorrenzaRecurrence RicorrenteRecurring
Ricorre ogniRecur every 1 ora1 hour
Imposta scadenzaSet expiration NoNo

Dopo aver creato la pianificazione è necessario impostare i valori dei parametri che verranno usati ogni volta che la pianificazione avvia il runbook.Once the schedule is created, you need to set the parameter values that will be used each time this schedule starts the runbook.

  1. Fare clic su Configura i parametri e le impostazioni di esecuzione.Click Configure parameters and run settings.
  2. Specificare i valori per ResourceGroupName e AutomationAccountName.Fill in values for your ResourceGroupName and AutomationAccountName.
  3. Fare clic su OK.Click OK.

9. Verificare che il runbook venga avviato secondo la pianificazione9. Verify runbook starts on schedule

Ogni volta che un runbook viene avviato, viene creato un processo e l'output viene registrato.Everytime a runbook is started, a job is created and any output logged. Si tratta in realtà degli stessi processi che vengono raccolti dal runbook.In fact, these are the same jobs that the runbook is collecting. È possibile verificare che il runbook si avvii come previsto controllando i processi del runbook quando è trascorsa l'ora di inizio della pianificazione.You can verify that the runbook starts as expected by checking the jobs for the runbook after the start time for the schedule has passed.

Processi

  1. Nelle proprietà del runbook selezionare Processi in Risorse.In the properties for your runbook, select Jobs under Resources.
  2. Verrà visualizzato un elenco di processi per ogni volta in cui è stato avviato il runbook.You should see a listing of jobs for each time the runbook was started.
  3. Fare clic su un processo per visualizzarne i dettagli.Click on one of the jobs to view its details.
  4. Fare clic su Tutti i log per visualizzare i log e l'output del runbook.Click on All logs to view the logs and output from the runbook.
  5. Scorrere verso il basso per trovare una voce simile a quella riportata di seguito.Scroll to the bottom to find an entry similar to the image below.
    Dettagliato
  6. Fare clic su questa voce per visualizzare i dati JSON dettagliati che sono stati inviati a Log Analytics.Click on this entry to view the detailed json data that was sent to Log Analytics.

Passaggi successiviNext steps