Beispielnutzlasten für Protokollsuchwarnungen mithilfe von Webhook-Aktionen

  • Artikel

Sie können Webhook-Aktionen in einer Warnungsregel für die Protokollsuche verwenden, um eine einzelne HTTP POST-Anforderung aufzurufen. In diesem Artikel werden die Eigenschaften beschrieben, die verfügbar sind, wenn Sie Aktionsgruppen für die Verwendung von Webhooks konfigurieren. Der aufgerufene Dienst muss Webhooks unterstützen und wissen, wie die empfangene Nutzlast verwendet wird.

Sie sollten das allgemeine Warnungsschema für Ihre Webhookintegrationen verwenden. Das allgemeine Warnungsschema bietet den Vorteil einer einzelnen, erweiterbaren und einheitlichen Warnungsnutzlast für alle Benachrichtigungsdienste in Azure Monitor.

For log search alert rules that have a custom JSON payload defined, enabling the common alert schema reverts the payload schema to the one described in Common alert schema. Wenn Sie eine benutzerdefinierte JSON-Nutzlast definieren möchten, kann der Webhook das allgemeine Warnungsschema nicht verwenden.

Für Warnungen mit aktiviertem allgemeinem Schema gilt für die Größe ein oberer Grenzwert von 256 KB pro Warnung. Eine größere Warnung enthält keine Suchergebnisse. Wenn die Suchergebnisse nicht enthalten sind, verwenden Sie LinkToFilteredSearchResultsAPI oder LinkToSearchResultsAPI, um mit der Log Analytics-API auf die Suchergebnisse zuzugreifen.

Die Beispielnutzlasten enthalten Beispiele dafür, wenn die Nutzlast Standard ist und wenn sie benutzerdefiniert ist.

Protokollsuchwarnung für alle Ressourcenprotokolle (aus API-Version 2021-08-01)

Die folgende Beispielnutzlast ist für einen Standard-Webhook bestimmt, wenn er für Protokollsuchwarnungen basierend auf Ressourcenprotokollen verwendet wird:

{
    "schemaId": "azureMonitorCommonAlertSchema",
    "data": {
        "essentials": {
            "alertId": "/subscriptions/12345a-1234b-123c-123d-12345678e/providers/Microsoft.AlertsManagement/alerts/12345a-1234b-123c-123d-12345678e",
            "alertRule": "AcmeRule",
            "severity": "Sev4",
            "signalType": "Log",
            "monitorCondition": "Fired",
            "monitoringService": "Log Alerts V2",
            "alertTargetIDs": [
                "/subscriptions/12345a-1234b-123c-123d-12345678e/resourcegroups/ai-engineering/providers/microsoft.compute/virtualmachines/testvm"
            ],
            "originAlertId": "123c123d-1a23-1bf3-ba1d-dd1234ff5a67",
            "firedDateTime": "2020-07-09T14:04:49.99645Z",
            "description": "log alert rule V2",
            "essentialsVersion": "1.0",
            "alertContextVersion": "1.0"
        },
        "alertContext": {
            "properties": {
              "name1": "value1",
              "name2": "value2"
            },
            "conditionType": "LogQueryCriteria",
            "condition": {
                "windowSize": "PT10M",
                "allOf": [
                    {
                        "searchQuery": "Heartbeat",
                        "metricMeasureColumn": "CounterValue",
                        "targetResourceTypes": "['Microsoft.Compute/virtualMachines']",
                        "operator": "LowerThan",
                        "threshold": "1",
                        "timeAggregation": "Count",
                        "dimensions": [
                            {
                                "name": "ResourceId",
                                "value": "/subscriptions/12345a-1234b-123c-123d-12345678e/resourceGroups/TEST/providers/Microsoft.Compute/virtualMachines/testvm"
                            }
                        ],
                        "metricValue": 0.0,
                        "failingPeriods": {
                            "numberOfEvaluationPeriods": 1,
                            "minFailingPeriodsToAlert": 1
                        },
                        "linkToSearchResultsUI": "https://portal.azure.com#@12f345bf-12f3-12af-12ab-1d2cd345db67/blade/Microsoft_Azure_Monitoring_Logs/LogsBlade/source/Alerts.EmailLinks/scope/%7B%22resources%22%3A%5B%7B%22resourceId%22%3A%22%2Fsubscriptions%2F12345a-1234b-123c-123d-12345678e%2FresourceGroups%2FTEST%2Fproviders%2FMicrosoft.Compute%2FvirtualMachines%2Ftestvm%22%7D%5D%7D/q/eJzzSE0sKklKTSypUSjPSC1KVQjJzE11T81LLUosSU1RSEotKU9NzdNIAfJKgDIaRgZGBroG5roGliGGxlYmJlbGJnoGEKCpp4dDmSmKMk0A/prettify/1/timespan/2020-07-07T13%3a54%3a34.0000000Z%2f2020-07-09T13%3a54%3a34.0000000Z",
                        "linkToFilteredSearchResultsUI": "https://portal.azure.com#@12f345bf-12f3-12af-12ab-1d2cd345db67/blade/Microsoft_Azure_Monitoring_Logs/LogsBlade/source/Alerts.EmailLinks/scope/%7B%22resources%22%3A%5B%7B%22resourceId%22%3A%22%2Fsubscriptions%2F12345a-1234b-123c-123d-12345678e%2FresourceGroups%2FTEST%2Fproviders%2FMicrosoft.Compute%2FvirtualMachines%2Ftestvm%22%7D%5D%7D/q/eJzzSE0sKklKTSypUSjPSC1KVQjJzE11T81LLUosSU1RSEotKU9NzdNIAfJKgDIaRgZGBroG5roGliGGxlYmJlbGJnoGEKCpp4dDmSmKMk0A/prettify/1/timespan/2020-07-07T13%3a54%3a34.0000000Z%2f2020-07-09T13%3a54%3a34.0000000Z",
                        "linkToSearchResultsAPI": "https://api.loganalytics.io/v1/subscriptions/12345a-1234b-123c-123d-12345678e/resourceGroups/TEST/providers/Microsoft.Compute/virtualMachines/testvm/query?query=Heartbeat%7C%20where%20TimeGenerated%20between%28datetime%282020-07-09T13%3A44%3A34.0000000%29..datetime%282020-07-09T13%3A54%3A34.0000000%29%29&timespan=2020-07-07T13%3a54%3a34.0000000Z%2f2020-07-09T13%3a54%3a34.0000000Z",
                        "linkToFilteredSearchResultsAPI": "https://api.loganalytics.io/v1/subscriptions/12345a-1234b-123c-123d-12345678e/resourceGroups/TEST/providers/Microsoft.Compute/virtualMachines/testvm/query?query=Heartbeat%7C%20where%20TimeGenerated%20between%28datetime%282020-07-09T13%3A44%3A34.0000000%29..datetime%282020-07-09T13%3A54%3A34.0000000%29%29&timespan=2020-07-07T13%3a54%3a34.0000000Z%2f2020-07-09T13%3a54%3a34.0000000Z"
                    }
                ],
                "windowStartTime": "2020-07-07T13:54:34Z",
                "windowEndTime": "2020-07-09T13:54:34Z"
            }
        }
    }
}

Protokollsuchwarnung für Log Analytics (bis zur API-Version 2018-04-16)

Die folgende Beispielnutzlast ist für eine Standardwebhookaktion gedacht, die für Warnungen verwendet wird, die auf Log Analytics basieren:

Hinweis

Der Wert des Felds "Severity" ändert sich, wenn Sie von der älteren Log Analytics-Warnungs-API zur aktuellen scheduledQueryRules-API gewechselt haben.

{
    "SubscriptionId": "12345a-1234b-123c-123d-12345678e",
    "AlertRuleName": "AcmeRule",
    "SearchQuery": "Perf | where ObjectName == \"Processor\" and CounterName == \"% Processor Time\" | summarize AggregatedValue = avg(CounterValue) by bin(TimeGenerated, 5m), Computer",
    "SearchIntervalStartTimeUtc": "2018-03-26T08:10:40Z",
    "SearchIntervalEndtimeUtc": "2018-03-26T09:10:40Z",
    "AlertThresholdOperator": "Greater Than",
    "AlertThresholdValue": 0,
    "ResultCount": 2,
    "SearchIntervalInSeconds": 3600,
    "LinkToSearchResults": "https://portal.azure.com/#Analyticsblade/search/index?_timeInterval.intervalEnd=2018-03-26T09%3a10%3a40.0000000Z&_timeInterval.intervalDuration=3600&q=Usage",
    "LinkToFilteredSearchResultsUI": "https://portal.azure.com/#Analyticsblade/search/index?_timeInterval.intervalEnd=2018-03-26T09%3a10%3a40.0000000Z&_timeInterval.intervalDuration=3600&q=Usage",
    "LinkToSearchResultsAPI": "https://api.loganalytics.io/v1/workspaces/workspaceID/query?query=Heartbeat&timespan=2020-05-07T18%3a11%3a51.0000000Z%2f2020-05-07T18%3a16%3a51.0000000Z",
    "LinkToFilteredSearchResultsAPI": "https://api.loganalytics.io/v1/workspaces/workspaceID/query?query=Heartbeat&timespan=2020-05-07T18%3a11%3a51.0000000Z%2f2020-05-07T18%3a16%3a51.0000000Z",
    "Description": "log alert rule",
    "Severity": "Warning",
    "AffectedConfigurationItems": [
        "INC-Gen2Alert"
    ],
    "Dimensions": [
        {
            "name": "Computer",
            "value": "INC-Gen2Alert"
        }
    ],
    "SearchResult": {
        "tables": [
            {
                "name": "PrimaryResult",
                "columns": [
                    {
                        "name": "$table",
                        "type": "string"
                    },
                    {
                        "name": "Computer",
                        "type": "string"
                    },
                    {
                        "name": "TimeGenerated",
                        "type": "datetime"
                    }
                ],
                "rows": [
                    [
                        "Fabrikam",
                        "33446677a",
                        "2018-02-02T15:03:12.18Z"
                    ],
                    [
                        "Contoso",
                        "33445566b",
                        "2018-02-02T15:16:53.932Z"
                    ]
                ]
            }
        ]
    },
    "WorkspaceId": "12345a-1234b-123c-123d-12345678e",
    "AlertType": "Metric measurement"
}

Protokollsuchwarnung für Application Insights (bis zur API-Version 2018-04-16)

Die folgende Beispielnutzlast ist für einen Standardwebhook bestimmt, wenn er für Protokollsuchwarnungen basierend auf Application Insights-Ressourcen verwendet wird:

{
    "schemaId": "Microsoft.Insights/LogAlert",
    "data": {
        "SubscriptionId": "12345a-1234b-123c-123d-12345678e",
        "AlertRuleName": "AcmeRule",
        "SearchQuery": "requests | where resultCode == \"500\" | summarize AggregatedValue = Count by bin(Timestamp, 5m), IP",
        "SearchIntervalStartTimeUtc": "2018-03-26T08:10:40Z",
        "SearchIntervalEndtimeUtc": "2018-03-26T09:10:40Z",
        "AlertThresholdOperator": "Greater Than",
        "AlertThresholdValue": 0,
        "ResultCount": 2,
        "SearchIntervalInSeconds": 3600,
        "LinkToSearchResults": "https://portal.azure.com/AnalyticsBlade/subscriptions/12345a-1234b-123c-123d-12345678e/?query=search+*+&timeInterval.intervalEnd=2018-03-26T09%3a10%3a40.0000000Z&_timeInterval.intervalDuration=3600&q=Usage",
        "LinkToFilteredSearchResultsUI": "https://portal.azure.com/AnalyticsBlade/subscriptions/12345a-1234b-123c-123d-12345678e/?query=search+*+&timeInterval.intervalEnd=2018-03-26T09%3a10%3a40.0000000Z&_timeInterval.intervalDuration=3600&q=Usage",
        "LinkToSearchResultsAPI": "https://api.applicationinsights.io/v1/apps/0MyAppId0/metrics/requests/count",
        "LinkToFilteredSearchResultsAPI": "https://api.applicationinsights.io/v1/apps/0MyAppId0/metrics/requests/count",
        "Description": null,
        "Severity": "3",
        "Dimensions": [
            {
                "name": "IP",
                "value": "1.1.1.1"
            }
        ],
        "SearchResult": {
            "tables": [
                {
                    "name": "PrimaryResult",
                    "columns": [
                        {
                            "name": "$table",
                            "type": "string"
                        },
                        {
                            "name": "Id",
                            "type": "string"
                        },
                        {
                            "name": "Timestamp",
                            "type": "datetime"
                        }
                    ],
                    "rows": [
                        [
                            "Fabrikam",
                            "33446677a",
                            "2018-02-02T15:03:12.18Z"
                        ],
                        [
                            "Contoso",
                            "33445566b",
                            "2018-02-02T15:16:53.932Z"
                        ]
                    ]
                }
            ]
        },
        "ApplicationId": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "AlertType": "Metric measurement"
    }
}

Protokollsuchwarnung mit einer benutzerdefinierten JSON-Nutzlast (bis zur API-Version 2018-04-16)

Hinweis

Benutzerdefinierte JSON-basierte Webhooks werden ab API-Version 2021-08-01 nicht unterstützt.

Die folgende Tabelle führt standardmäßige Webhookaktionseigenschaften und deren benutzerdefinierte JSON-Parameternamen auf.

Parameter Variable BESCHREIBUNG
AlertRuleName #alertrulename Der Name der Warnungsregel.
Severity #severity Schweregrad für die Warnung für die ausgelöste Protokollsuche festgelegt.
AlertThresholdOperator #thresholdoperator Schwellenwertoperator für die Warnungsregel
AlertThresholdValue #thresholdvalue Wert des Schwellenwerts für die Warnungsregel
LinkToSearchResults #linktosearchresults Link zum Analyseportal, das die Datensätze aus der Abfrage zurückgibt, mit der die Warnung erstellt wurde.
LinkToSearchResultsAPI #linktosearchresultsapi Link zur Analytics-API, die die Datensätze aus der Abfrage zurückgibt, mit der die Warnung erstellt wurde
LinkToFilteredSearchResultsUI #linktofilteredsearchresultsui Link zum Analyticsportal, das die Datensätze aus der nach Dimensionswertkombinationen gefilterten Abfrage zurückgibt, mit der die Warnung erstellt wurde
LinkToFilteredSearchResultsAPI #linktofilteredsearchresultsapi Link zur Analytics-API, die die Datensätze aus der nach Dimensionswertkombinationen gefilterten Abfrage zurückgibt, mit der die Warnung erstellt wurde
ResultCount #searchresultcount Anzahl von Datensätzen in den Suchergebnissen
Search Interval End time #searchintervalendtimeutc Abschlusszeit der Abfrage im UTC-Format, mit dem Format mm/tt/jjjj HH:mm:ss AM/PM.
Search Interval #searchinterval Zeitfenster für die Warnungsregel im Format HH:mm:ss.
Search Interval StartTime #searchintervalstarttimeutc Startzeit der Abfrage im UTC-Format, mit dem Format mm/tt/jjjj HH:mm:ss AM/PM.
SearchQuery #searchquery Von der Warnungsregel verwendete Protokollsuchabfrage
SearchResults "IncludeSearchResults": true Hierbei handelt es sich um die von der Abfrage als JSON-Tabelle zurückgegebenen Datensätze, beschränkt auf die ersten 1.000 Datensätze. "IncludeSearchResults": true wird in einer benutzerdefinierten JSON-Webhookdefinition als Eigenschaft der obersten Ebene hinzugefügt.
Dimensions "IncludeDimensions": true Hierbei handelt es sich um Dimensionswertkombinationen, die diese Warnung ausgelöst haben, als JSON-Abschnitt. "IncludeDimensions": true wird in einer benutzerdefinierten JSON-Webhookdefinition als Eigenschaft der obersten Ebene hinzugefügt.
Alert Type #alerttype Der Typ der Warnungsregel für die Protokollsuche, die als Metrikmessung oder Anzahl der Ergebnisse konfiguriert ist.
WorkspaceID #workspaceid ID Ihres Log Analytics-Arbeitsbereichs.
Application ID #applicationid ID Ihrer Application Insights-App.
Subscription ID #subscriptionid ID des von Ihnen verwendeten Azure-Abonnements.

Sie können Benutzerdefinierte JSON-Nutzlast für Webhook einschließen verwenden, um eine benutzerdefinierte JSON-Nutzlast unter Verwendung der Parameter zu erhalten. Sie können auch zusätzliche Eigenschaften generieren.

Sie können beispielsweise die folgende benutzerdefinierte Nutzlast angeben, die einen einzelnen Parameter wie textenthält. Der Dienst, der von diesem Webhook aufgerufen wird, erwartet diesen Parameter:


    {
        "text":"#alertrulename fired with #searchresultcount over threshold of #thresholdvalue."
    }

Diese Beispielnutzlast wird ähnlich wie hier dargestellt aufgelöst, wenn sie an den Webhook gesendet wird:

    {
        "text":"My Alert Rule fired with 18 records over threshold of 10 ."
    }

Variablen in einem benutzerdefinierten Webhook müssen in einer JSON-Struktur angegeben werden. Wenn Sie beispielsweise im Webhook-Beispiel auf #searchresultcount verweisen, wird die Ausgabe auf der Grundlage der Warnergebnisse erfolgen.

Fügen Sie zum Einschließen von Suchergebnissen IncludeSearchResults als Eigenschaft der obersten Ebene im benutzerdefinierten JSON-Code hinzu. Die Suchergebnisse werden als JSON-Struktur eingeschlossen, sodass nicht auf Ergebnisse in benutzerdefinierten Feldern verwiesen werden kann.

Hinweis

Die Schaltfläche Webhook anzeigen neben der Option Benutzerdefinierte JSON-Nutzlast für Webhook einschließen zeigt eine Vorschau der bereitgestellten Informationen an. Es sind keine tatsächlichen Daten enthalten, aber sie ist repräsentativ für das verwendete JSON-Schema.

Sie können beispielsweise diese Konfiguration verwenden, um eine benutzerdefinierte Nutzlast zu erstellen, die nur den Warnungsnamen und die Suchergebnisse enthält:

    {
       "alertname":"#alertrulename",
       "IncludeSearchResults":true
    }

Die folgende Beispielnutzlast ist für eine benutzerdefinierte Webhook-Aktion für jede Protokollsuchbenachrichtigung vorgesehen:

    {
    "alertname":"AcmeRule","IncludeSearchResults":true,
    "SearchResults":
        {
        "tables":[
                    {"name":"PrimaryResult","columns":
                        [
                        {"name":"$table","type":"string"},
                        {"name":"Id","type":"string"},
                        {"name":"TimeGenerated","type":"datetime"}
                        ],
                    "rows":
                        [
                            ["Fabrikam","33446677a","2018-02-02T15:03:12.18Z"],
                            ["Contoso","33445566b","2018-02-02T15:16:53.932Z"]
                        ]
                    }
                ]
        }
    }

Nächste Schritte