Samouczek: tworzenie narzędzia Kusto w agencie SRE platformy Azure

W tym samouczku utworzysz sparametryzowane narzędzie Kusto, które uruchamia dokładne zapytania KQL z deterministycznymi, powtarzalnymi wynikami. Gdy użytkownicy zadają pytania, takie jak "pokaż mi błędy z ostatnich siedmiu dni", agent zastępuje parametr i uruchamia dokładne zapytanie względem bazy danych usługi Azure Data Explorer.

W tym poradniku nauczysz się, jak:

• Utwórz narzędzie Kusto na kanwie agenta
• Definiowanie sparametryzowanego zapytania KQL
• Testowanie zapytania w portalu
• Podłącz narzędzie do agenta niestandardowego i zweryfikuj je na placu zabaw

Szacowany czas: 15 minut

Wymagania wstępne

Przed rozpoczęciem upewnij się, że masz następujące wymagania wstępne:

• Klaster usługi Azure Data Explorer, w którym tożsamości zarządzanej agenta przypisano rolę AllDatabasesViewer. Aby uzyskać więcej informacji, zobacz Wymagania wstępne dotyczące narzędzi Kusto.
• Skonfigurowany łącznik Kusto. Aby uzyskać więcej informacji, zobacz Konfigurowanie łącznika Kusto.
• Dostęp do narzędzia Builder w portalu agenta usługi Azure SRE.

Przejdź do kanwy agenta

Otwórz kanwę agenta, w której tworzysz narzędzia i zarządzasz nimi.

1. Otwórz portal agenta SRE.
2. Wybierz swój agent.
3. Wybierz Builder w lewym menu nawigacyjnym.
4. Wybierz Kanwa agenta.

Otwieranie formularza tworzenia narzędzia

Uruchom proces tworzenia narzędzia na pasku narzędzi.

1. Wybierz listę rozwijaną Utwórz na górnym pasku narzędzi.
2. Wybierz Narzędzie>Kusto.

Wypełnij szczegóły narzędzia

Wypełnij formularz przy użyciu konfiguracji narzędzia.

Pole	Wartość	Opis
Nazwa narzędzia	QueryAppLogs	Jak agent odwołuje się do tego narzędzia.
Opis	"Kwerenda tabeli AppLogs pod kątem błędów w określonym zakresie czasu"	Kiedy agent powinien używać tego narzędzia.
Łącznik	(wybierz łącznik Kusto)	Połączenie z usługi Azure Data Explorer do wykorzystania.
Baza danych	(automatycznie wypełniane z adresu URL łącznika)	Nazwa bazy danych.
Zapytanie	Zobacz poniższy przykład.	Zapytanie KQL z parametrami.

Wprowadź następujące przykładowe zapytanie:

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

Składnia ##timeRange## tworzy parametr. Gdy ktoś pyta "pokaż błędy z ostatnich 24 godzin", agent wypełnia element timeRange = 24h.

Dodawanie parametru

Zdefiniuj parametr używany przez zapytanie.

1. Przewiń do sekcji Parametry .
2. Wybierz pozycję Dodaj parametr.
3. Wprowadź następujące wartości:
   • Nazwa: timeRange
   • Typ: Ciąg
   • Opis: "Jak daleko wstecz szukać (na przykład 1h, 24h, 7d)"

Parametr zostanie wyświetlony w tabeli Parameters poniżej zapytania.

Testowanie zapytania

Sprawdź, czy zapytanie działa pomyślnie przed zapisaniem.

1. Wybierz pozycję Testuj w dolnej części formularza.
2. Wprowadź wartość testową dla timeRange (na przykład 7d).
3. Sprawdź, czy zapytanie zostało wykonane pomyślnie.

Zobaczysz czas wykonania i zielony znaczek potwierdzający uruchomienie zapytania. Nawet jeśli zapytanie zwraca zero wierszy, znacznik wyboru oznacza, że składnia zapytania jest prawidłowa.

Tworzenie narzędzia

Wybierz Utwórz, aby zapisać narzędzie Kusto.

Dodawanie narzędzia do agenta niestandardowego

Twoje narzędzie zostało utworzone, ale nie dołączyłeś go do agenta niestandardowego. Dołącz narzędzie, aby agent mógł go użyć.

1. W widoku Kanwy znajdź agenta niestandardowego.
2. + Wybierz przycisk po prawej stronie karty agenta niestandardowego.
3. Wybierz pozycję Dodaj istniejące narzędzia.
4. Sprawdź narzędzie Kusto z listy.
5. Wybierz pozycję Dodaj narzędzia.

Liczba narzędzi na karcie agenta niestandardowego zwiększa się po dodaniu.

Zweryfikuj narzędzie na placu zabaw

Sprawdź, czy agent poprawnie wywołuje narzędzie Kusto.

1. Wybierz Test Playground w lewym pasku nawigacji.
2. Wybierz agenta niestandardowego z listy rozwijanej.
3. Zapytaj: "Pokaż mi błędy z ostatnich siedmiu dni"
4. Agent uruchamia twoje narzędzie za pomocą timeRange = 7d.

Powinieneś zobaczyć, jak agent wywołuje Twoje narzędzie Kusto i zwraca wyniki zapytania. Dokładnie napisane zapytanie jest uruchamiane względem klastra.

Składnia parametrów

Użyj ##parameterName## lub $parameterName aby oznaczyć symbole zastępcze parametrów w zapytaniach.

query: |-
  AppExceptions
  | where TimeGenerated > ago(##timeRange##)
  | where ServiceName == "$serviceName"

Obie składnie działają identycznie. Agent programowy zastępuje wartości w czasie wykonywania.

Tryby wykonywania

W poniższej tabeli opisano dostępne tryby wykonywania dla narzędzi Kusto.

Tryb	Użyj, gdy
Query	Zdefiniuj zapytanie bezpośrednio w języku YAML (najczęściej).
Function	Zapisz logikę zapytań jako funkcję w klastrze usługi Azure Data Explorer.
Script	Umieść zapytanie w pliku zewnętrznym .kql .

# Function mode example
spec:
  type: KustoTool
  mode: Function
  function: GetRecentErrors

# Script mode example
spec:
  type: KustoTool
  mode: Script
  file: queries/complex-analysis.kql

Przykład: narzędzie korelacji wdrożenia

Poniższa definicja YAML tworzy narzędzie Kusto, które koreluje wdrożenia z określoną usługą i zakresem czasu.

api_version: azuresre.ai/v2
kind: ExtendedAgentTool
metadata:
  name: get-recent-deployments
spec:
  type: KustoTool
  connector: devops-logs
  mode: Query
  database: deployments
  description: "Get deployments in a time range for a service"
  toolMode: Auto
  query: |-
    Deployments
    | where TimeGenerated > ago(##timeRange##)
    | where ServiceName == "##serviceName##"
    | project TimeGenerated, Version, DeployedBy, Environment
    | order by TimeGenerated desc
  parameters:
    - name: serviceName
      type: string
      description: "Name of the service"
    - name: timeRange
      type: string
      description: "How far back to look (e.g., 1h, 24h)"

Edytowanie lub usuwanie narzędzia

Narzędzia można modyfikować lub usuwać po utworzeniu.

Edytuj

1. Na płótnie agenta wybierz węzeł narzędzia, aby otworzyć panel informacyjny.
2. Wybierz ikonę edycji (ołówka) w nagłówku panelu.
3. Zostanie otwarte okno dialogowe edycji z bieżącymi ustawieniami. Zmodyfikuj zapytanie, parametry lub łącznik.
4. Wybierz opcję Zapisz.

Delete

1. Wybierz węzeł narzędzia, aby otworzyć panel informacyjny.
2. Wybierz menu ⋯ (więcej akcji) w nagłówku panelu.
3. Wybierz pozycję Usuń narzędzie.
4. Potwierdź usunięcie w oknie dialogowym.

Uwaga / Notatka

Usuwając narzędzie, natychmiast usuwasz je ze wszystkich agentów niestandardowych, którzy z tego narzędzia korzystają.

Następne kroki

Testowanie narzędzia na placu zabaw

Treści powiązane

• Narzędzia Kusto
• Tworzenie narzędzia języka Python
• Agenci niestandardowi