Condividi tramite

Strumenti Kusto nell'agente SRE di Azure

Gli strumenti Kusto consentono di trasformare le migliori query KQL in strumenti riutilizzabili e con parametri. L'agente esegue la query esatta che scrivi senza interpretazione, senza variazioni. L'esperienza del team diventa una funzionalità condivisa.

Suggerimento

  • Standardizzare le query sugli eventi imprevisti : la stessa KQL collaudata viene eseguita ogni volta, senza variazioni.
  • Trasformare le conoscenze tribali in strumenti riutilizzabili : le migliori query diventano funzionalità condivise.
  • Query con parametri : gli utenti chiedono in linguaggio normale e l'agente sostituisce automaticamente i valori.
  • Test prima della distribuzione : convalidare le query vengono eseguite correttamente prima dell'aggiunta ai subagenti.

Il problema: tutti scrivono le proprie query

Durante gli incidenti, i tecnici senior del team usano query testate in situazioni critiche che individuano rapidamente i problemi. Ma queste conoscenze rimangono nelle loro teste, nei thread di Slack e nei notebook personali. Quando non sono su chiamata, i risponditori meno esperti sprecano tempo:

  • Reinventare le query da zero, spesso con errori
  • Scrittura di query eccessivamente estese che restituiscono troppi dati o trascurano i casi limite
  • Colonne critiche mancanti che potrebbero rivelare la causa principale
  • Uso di finestre temporali errate o dimenticare di filtrare in base all'ambiente

Ogni tecnico esegue query sugli stessi dati in modo diverso. Uno trova il problema in cinque minuti. Un altro passa 30 minuti girando in tondo utilizzando KQL ad hoc.

Come gli strumenti Kusto risolveranno questo problema

Gli strumenti Kusto consentono di salvare le query migliori del team come strumenti deterministici con parametri. L'agente esegue la query esatta che definisci, quindi la competenza del team diventa una capacità condivisa.

Prima Dopo
Ingegnere senior scrive query dalla memoria La query viene salvata come strumento, chiunque può usarla
Indovinate su chiamata a intervalli di tempo e filtri I parametri richiedono gli elementi necessari
Ogni risponditore ottiene risultati diversi La stessa query viene eseguita ogni volta
I join complessi devono essere memorizzati La logica in più passaggi è predefinita

Invece di chiedere agli ingegneri su chiamata di "capire come eseguire query sui log degli errori", chiedono all'agente:

Show me errors from the last 24 hours

L'agente usa lo strumento predefinito con timeRange=24h, restituendo esattamente le colonne e i filtri di cui ha bisogno il team.

Come funziona

Seguire questa procedura per creare e usare uno strumento Kusto:

  1. Connetti — Aggiungi il cluster di Esplora Dati di Azure come connettore.
  2. Create — definire query con parametri usando la sintassi ##parameterName##.
  3. Test : convalidare che la query venga eseguita correttamente nel portale.
  4. Attach : aggiungere lo strumento a un subagente.
  5. Use : l'agente chiama lo strumento quando le domande dell'utente corrispondono alla descrizione dello strumento.

Due approcci alle query di dati

Quando si aggiunge un connettore di Azure Data Explorer, scegliere tra query deterministiche o flessibili.

Avvicinarsi Descrizione Usare quando
Connettore di query di database Agent usa query predefinite (strumenti Kusto) Si vogliono query deterministiche ed esatte
Connettore di indicizzazione del database L'agente genera query apprendendo il tuo schema Si vogliono query flessibili e ad hoc

Creare uno strumento Kusto

Passare a Generatore>Generatore di subagente e selezionare Crea>Strumento>Strumento Kusto.

Campo Descrizione Esempio
Nome strumento Come l'agente fa riferimento allo strumento QueryAppLogs
Descrizione Quando l'agente deve usare questo strumento "Eseguire query sulla tabella AppLogs per individuare gli errori nell'intervallo di tempo specificato"
Connettore Il tuo connettore ADX kusto-helloworld
Banca dati Nome database (popolato automaticamente dall'URL del connettore) helloworld-app
Quesito KQL con segnaposto per parametri Vedere l'esempio seguente

La query di esempio seguente usa un parametro :

AppLogs
| where Timestamp > ago(##timeRange##)
| where Level == "Error"
| order by Timestamp desc
| take 10

La ##timeRange## sintassi crea un parametro. L'agente richiede o sostituisce automaticamente questo valore in base all'input dell'utente, ad esempio "errori delle ultime 24 ore".

Testare la query prima di creare lo strumento. Il portale lo convalida per il tuo cluster. Un test riuscito mostra il tempo di esecuzione e conferma che la query viene eseguita correttamente.

Aggiungere uno strumento a un subagente

Dopo aver creato lo strumento, collegarlo a un subagente:

  1. Nella visualizzazione Canvas trovare il sottoagente.
  2. Selezionare il + pulsante sul lato destro della scheda.
  3. Selezionare Aggiungi strumenti esistenti.
  4. Verifica i tuoi strumenti Kusto dall'elenco.
  5. Selezionare Aggiungi strumenti.

Il sottoagente ha ora accesso alla tua query.

Suggerimento

Per istruzioni dettagliate con screenshot, vedere Esercitazione: Creare uno strumento Kusto.

Prerequisiti

Prima di creare gli strumenti Kusto, soddisfare i requisiti seguenti.

Autorizzazioni di Esplora dati di Azure

L'identità gestita dell'agente ha bisogno del ruolo AllDatabasesViewer nel cluster di Azure Data Explorer.

Usare il comando di gestione KQL seguente:

.add cluster AllDatabasesViewer ('aadapp=<MANAGED_IDENTITY_CLIENT_ID>;<TENANT_ID>')

In alternativa, nel portale di Azure, passare al cluster >"Esplora dati di Azure">"Sicurezza e rete">"Autorizzazioni", quindi cliccare su >"Aggiungi" "AllDatabasesViewer".

Connettore Kusto

Prima di creare gli strumenti, configurare un connettore ADX. Quando si aggiunge il connettore:

  • Selezionare connettore per query di database per le query predefinite, non l'apprendimento degli schemi.
  • Usare l'URL completo del cluster, incluso il database : https://<CLUSTER_NAME>.<REGION>.kusto.windows.net/<DATABASE_NAME>.

Query con parametri

Rendi i tuoi strumenti flessibili con i parametri usando la sintassi ##parameterName##.

AppEvents
| where TimeGenerated > ago(##timeRange##)
| where EventLevel == "Error"
| where Message contains "##searchPattern##"
| take 100

Quando l'agente usa questo strumento, sostituisce i parametri in base all'input dell'utente.

L'utente dice Sostituti dell'agente
"errori dell'ultimo giorno" timeRange=24h
"Trovare eccezioni puntatore Null" searchPattern=NullPointerException

I parametri consentono a uno strumento di gestire molte varianti della stessa domanda.

Modalità di esecuzione (YAML)

Quando si definiscono gli strumenti in YAML, scegliere una modalità di esecuzione.

Modalità Descrizione Usare quando
Query Esegue una query KQL in linea Più comune. La query viene definita direttamente in YAML.
Function Chiama una funzione archiviata nel cluster La logica di query viene definita in Esplora dati di Azure come funzione
Script Esegue uno script KQL da un file esterno Query complesse a più dichiarazioni 
# Query mode (most common)
spec:
  mode: Query
  query: |-
    AppEvents | take 10

# Function mode
spec:
  mode: Function
  function: GetRecentErrors

Procedure consigliate per le query

Per la scrittura di query sugli strumenti Kusto, seguire queste indicazioni.

Usare intervalli di tempo appropriati : impostazione predefinita per i dati recenti:

| where TimeGenerated > ago(1h)

Aggiungere i limiti dei risultati - Impedire l'output eccessivo:

| take 100

Includi proiezioni utili: restituisce solo le colonne necessarie per l'agente:

| project TimeGenerated, Name, DurationMs, ResultCode

Quando usare gli strumenti Kusto e le query ad hoc

Scegliere l'approccio corretto in base allo scenario in uso.

Scenario Strumenti Kusto Query ad hoc
Passaggi standardizzati del runbook Sì No
Modelli di indagine ripetibili Sì No
Query multi join complesse Sì No
Esplorazione di dati non familiari No Sì
Indagini monouso No Sì

Passo successivo

Creare uno strumento Kusto

Contenuti correlati

  • Last updated on