Dashboards per API erstellen und verwalten

In diesem Dokument wird beschrieben, wie Sie benutzerdefinierte Dashboards und die Widgets auf diesen Dashboards mithilfe der Ressource Dashboard in der Cloud Monitoring API erstellen und verwalten. In den folgenden Beispielen wird gezeigt, wie Sie Ihre Dashboards verwalten, indem Sie die API über curl aufrufen, und wie Sie die Google Cloud CLI verwenden. Sie können Ihre benutzerdefinierten Dashboards auch über die Google Cloud Console verwalten. Die API bietet jedoch eine programmatische Möglichkeit, viele Dashboards gleichzeitig zu verwalten.

Der Endpunkt unterstützt die folgenden Methoden zum Verwalten und Konfigurieren von Dashboards:

Sie können die API direkt mit dem Dienstprogramm curl oder mit der Google Cloud CLI aufrufen.

Sie können vordefinierte Dashboards nicht abrufen, bearbeiten oder löschen.

Dashboards

Beim Erstellen eines Dashboards müssen Sie angeben, welche Komponenten oder Widgets angezeigt werden sollen. Außerdem müssen Sie das Layout für diese Widgets festlegen. Sie können Ihrem Dashboard auch Labels und Filter hinzufügen. Labels können Ihnen dabei helfen, ein Dashboard zu finden oder die Art der Inhalte auf dem Dashboard anzugeben.

Dashboard-Layouts

Layouts definieren die Reihenfolge der Komponenten eines Dashboards. Die API stellt die folgenden Layouts zur Verfügung:

  • GridLayout: Teilt den verfügbaren Platz in vertikale Spalten mit gleicher Breite und ordnet einen Satz von Widgets mit einer Strategie an, bei der zuerst die Zeilen berücksichtigt werden (Row-first).

  • MosaicLayout: Teilt den verfügbaren Speicherplatz in ein Raster. Jedes Widget kann einen oder mehrere Rasterblöcke einnehmen.

  • RowLayout: Teilt den verfügbaren Platz in Zeilen und ordnet einen Satz von Widgets horizontal in jeder Zeile an.

  • ColumnLayout: Teilt den verfügbaren Platz in vertikale Spalten und ordnet einen Satz von Widgets vertikal in jeder Spalte an.

Im Folgenden wird die JSON-Darstellung eines Dashboards in RowLayout mit drei Text-Widgets dargestellt:

{
  "displayName": "Row-layout example",
  "rowLayout": {
    "rows": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  }
}

Dashboardwidgets

Ein Widget enthält eine einzelne Dashboard-Komponente und die Konfiguration, wie die Komponente im Dashboard dargestellt wird. Ein Dashboard kann mehrere Widgets enthalten. Es gibt mehrere Arten von Widget-Objekten:

  • Im Widget XyChart werden Daten über die X- und Y-Achse dargestellt.

    In diesem Widget wird ein Datensatz angezeigt, der Zeitreihendaten enthalten oder durch eine SQL-Abfrage generiert werden kann. Mit diesem Widget können Sie die Diagrammdaten entweder der linken oder der rechten Y-Achse zuordnen. Wenn mehrere Messwerttypen in einem Diagramm dargestellt werden, können Sie beide Y-Achsen verwenden. Das XyChart-Widget unterstützt die folgenden Darstellungsstile:

    • Liniendiagramme
    • Balkendiagramme
    • Gestapelte Flächendiagramme
    • Heatmaps

  • Widgets, die Daten aus einer Dimension enthalten, z. B. den letzten Wert:

    • PieChart: Hier werden die aktuellen Werte einer Sammlung von Zeitreihen angezeigt. Jede Zeitreihe trägt einen Tortenstück zum Ganzen bei.

    • Scorecard: Zeigt den aktuellsten Wert einer Zeitreihe an und wie sich dieser Wert auf einen oder mehrere Grenzwerte bezieht.

    • TimeSeriesTable: Zeigt den aktuellsten Wert oder einen aggregierten Wert für jede Zeitreihe an. Tabellen können angepasst werden. Sie können beispielsweise Zellen farblich codieren und Spaltennamen und Datenausrichtung konfigurieren.

  • Widgets, die Informationen zu Benachrichtigungsrichtlinien oder Vorfällen enthalten:

    • AlertChart: Zeigt eine Zusammenfassung einer Benachrichtigungsrichtlinie mit einer einzelnen Bedingung an. In diesem Widget werden Daten als Liniendiagramm dargestellt. Außerdem sind der Grenzwert und die Anzahl der offenen Vorfälle zu sehen.

    • IncidentList: Zeigt eine Liste von Vorfällen an. Sie können das Widget so konfigurieren, dass Vorfälle für bestimmte Benachrichtigungsrichtlinien oder für bestimmte Ressourcentypen angezeigt werden.

  • Widgets, die Logeinträge und Fehler anzeigen:

  • Text- und Organisations-Widgets:

    • CollapsibleGroup: Hier werden eine Reihe von Widgets angezeigt. Sie können die Ansicht einer Gruppe minimieren.

    • SingleViewGroup: Hier wird ein Widget in einer Sammlung von Widgets angezeigt. Sie können auswählen, welches Widget angezeigt werden soll.

    • SectionHeader: Erstellt einen horizontalen Trennstrich in Ihrem Dashboard und einen Eintrag im Inhaltsverzeichnis des Dashboards.

    • Text: Zeigt den Textinhalt entweder als Rohtext oder als Markdown-String an.

    Damit Text- und Organisations-Widgets in einem Dashboard enthalten sind, muss es ein MosaicLayout haben.

Zusätzlich zu diesen Objekten können Sie auch einen leeren Platzhalter zu einem Dashboard hinzufügen.

Im Folgenden wird beispielsweise die JSON-Darstellung eines XyChart-Widgets mit konfigurierter rechter Y-Achse angezeigt:

{
  "displayName": "Demo dashboard",
  "gridLayout": {
    "widgets": [
      {
        "title": "Sample line chart",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesFilter": {
                  "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
                  "aggregation": {
                    "perSeriesAligner": "ALIGN_MEAN",
                    "crossSeriesReducer": "REDUCE_MAX",
                    "groupByFields": [
                      "resource.label.zone"
                    ]
                  }
                },
                "unitOverride": "1"
              },
              "plotType": "LINE"
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

Dashboardlabels

Mit Labels können Sie Ihre Dashboards verwalten und organisieren. Sie können beispielsweise das Label prod hinzufügen, um anzugeben, dass im Dashboard Zeitreihendaten und Logdaten für Ihre Produktionsressourcen angezeigt werden. Alternativ können Sie das Label playbook hinzufügen, um anzugeben, dass das Dashboard Informationen zur Fehlerbehebung enthält.

Das Hinzufügen von Labels zu einem Dashboard ist optional.

Im folgenden Beispiel wird beispielsweise ein Dashboard-Objekt mit dem Label playbook gezeigt.

{
  "displayName": "Example",
  "mosaicLayout": {
    "columns": 12,
    "tiles": [
      ...
    ]
  },
  "dashboardFilters": [],
  "labels": {
    "playbook": ""
  }
}

Wie das vorherige Beispiel zeigt, wird das Feld labels als map implementiert. Die Felder key und value sind Strings. Wenn Sie einem Dashboard ein Label hinzufügen, geben Sie für key den Namen des Labels und für das Feld value einen leeren String ein.

Dashboard-Filter und ‑Variablen

Beim Entwerfen eines Dashboards können Sie mehrere Möglichkeiten zur Anzeige der Daten im Dashboard angeben. Angenommen, in einem Dashboard werden Zeitreihendaten für Ihre VM-Instanzen angezeigt. Sie können sich die Zeitreihendaten für alle VMs oder nur für eine bestimmte Zone ansehen. In diesem Fall empfehlen wir, einen angepinnten Filter oder eine Variable zu erstellen und dann den Standardwert dieses Filters auf die am häufigsten aufgerufene Zone festzulegen.

Angepinnte Filter werden auf alle Dashboard-Widgets angewendet, die das im Filter angegebene Label unterstützen, es sei denn, das Widget enthält einen Filter mit demselben Labelschlüssel. Wenn ein Diagramm beispielsweise den Filter zone = us-central1-a enthält, wird ein angepinnter Filter mit dem Labelschlüssel zone ignoriert. Ebenso wird dieser Filter von Diagrammen ignoriert, die kein Label mit dem Schlüssel zone haben.

Variablen ähneln angepinnten Filtern, werden aber nur auf bestimmte Widgets angewendet. Variablen können auf Labels basieren, wie angepinnte Filter, oder nur einen Wert haben. Variablen mit nur Werten enthalten einen oder mehrere Standardwerte und eine Liste aller möglichen Werte. Wenn Sie keinen Standardwert angeben, wird der Platzhalteroperator (*) verwendet. Um den Satz aller möglichen Werte zu definieren, geben Sie entweder ein Array von Werten an oder schreiben Sie eine SQL-Abfrage.

Sowohl angepinnte Filter als auch Variablen werden in der Dashboard-Symbolleiste angezeigt, zusammen mit einem Menü, über das Sie den Wert der Variablen vorübergehend ändern können. Die gleiche Datenstruktur wird verwendet, um angepinnte Filter und Variablen darzustellen. Weitere Informationen finden Sie unter DashboardFilter.

Weitere Informationen dazu, wie Sie eine labelbasierte Variable oder eine reine Wertvariable auf ein Widget anwenden, finden Sie in den folgenden Abschnitten:

Filter und Variablen erstellen

Console

Informationen zum Erstellen angepinnter Filter und Variablen mit der Google Cloud Console finden Sie in den folgenden Dokumenten:

API

Verwenden Sie die Datenstruktur dashboardFilters, um angepinnte Filter und Variablen zu definieren.

  • Wenn Sie eine Variable erstellen möchten, legen Sie den Wert des Felds templateVariable auf den Namen der Variablen fest. Lassen Sie dieses Feld aus oder legen Sie den Wert auf einen leeren String fest, wenn Sie einen angepinnten Filter erstellen möchten.
  • Wenn Sie einen angepinnten Filter oder eine labelbasierte Variable erstellen möchten, müssen Sie das Feld labelKey angeben. Lassen Sie dieses Feld aus, wenn Sie eine Variable mit nur einem Wert benötigen.

  • Legen Sie den Standardwert für den Filter oder die Variable fest. Die Konfiguration dieses Felds bestimmt, ob ein Nutzer genau eine Option aus dem Menü mit Werten auswählen kann oder mehrere Werte.

    • Wenn Sie einen einzelnen Standardwert festlegen und Nutzer darauf beschränken möchten, genau eine Option im Wertemenü auszuwählen, legen Sie das Feld valueType auf STRING und das Feld stringValue fest:
    "valueType": "STRING",
"stringValue": "my-default-value",
    • Wenn Sie mindestens einen Standardwert festlegen und Nutzern die Möglichkeit geben möchten, mehrere Optionen im Wertemenü auszuwählen, legen Sie das Feld valueType als STRING_ARRAY und das Feld stringArrayValue fest. Im folgenden Beispiel gibt es drei Standardwerte.
    "valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},

  • Optional: Wenn Sie eine Liste aller möglichen Werte für eine Variable mit nur einem Wert angeben möchten, legen Sie entweder das Feld stringArray oder das Feld timeSeriesQuery fest. Wenn Sie eine Abfrage angeben, muss es sich um eine Analyseabfrage handeln.

Betrachten Sie beispielsweise das folgende dashboardFilters-Objekt:

{
  "dashboardFilters": [
      {
        "labelKey": "zone"
        "stringValue": "us-central1-c",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL"
      },
      {
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL",
        "templateVariable": "my_label_based_variable"
      },
      {
        "filterType": "VALUE_ONLY",
        "templateVariable": "my_value_only_variable",
        timeSeriesQuery: {
          opsAnalyticsQuery: {
            sql: "
              SELECT log_name
              FROM `MY_TABLE`
              GROUP BY log_name
            ",
          }
        }
      }
    ],
  "displayName": "Illustrate Variables",
  ...
}

Im vorherigen JSON-Code werden ein angepinnter Filter und zwei Variablen definiert:

  • Der angepinnte Filter hat den Labelschlüssel zone, der in der Symbolleiste angezeigt wird. Die Felder valueType und stringValue geben den einzelnen Standardwert an. Weitere Informationen finden Sie auf der Seite „API-Referenzen“ für die Datenstruktur dashboardFilters.

  • Die labelbasierte Variable hat den Namen my_label_based_variable und den Labelschlüssel instance_id. Der Standardwert für diese Variable ist eine bestimmte Instanz-ID. Sie können den Standardwert auch mithilfe eines Arrays konfigurieren. In der Symbolleiste wird der Filter mit dem Namen my_label_based_variable angezeigt.

  • Die Variable mit nur einem Wert heißt my_value_only_variable. Da für diesen Eintrag kein Standardwert angegeben ist, wird der Platzhalteroperator (*) automatisch angewendet. Außerdem wird für diese Variable eine SQL-Abfrage verwendet, um die Liste der möglichen Werte für die Variable zu generieren.

Im dashboardFilters-Objekt sind nicht die Widgets aufgeführt, auf die sich die Variable bezieht. Wenn Sie eine Variable auf ein Widget anwenden möchten, ändern Sie die Abfrage für das Widget.

Allgemeine Syntax zum Aufheben der Dereferenzierung einer Variablen

Verwenden Sie für alle Widgets, mit Ausnahme derjenigen, die per SQL definiert sind, die folgende Syntax, um eine Variable auf eine Abfrage anzuwenden:

  • Wenn Sie eine labelbasierte Variable anwenden und den Labelschlüssel und den Labelwert in einen gültigen Filterausdruck für die Abfragesprache auflösen möchten, verwenden Sie ${my_label_based_variable}.

  • Wenn Sie nur den Wert einer labelbasierten Variablen anwenden möchten, verwenden Sie ${my_label_based_variable.value}. Für den Vergleich muss ein regulärer Ausdruck verwendet werden.

  • Wenn Sie nur den Wert einer Variablen verwenden möchten, verwenden Sie ${my_value_only_variable}. Fügen Sie für Variablen, die nur Werte enthalten, keine .value-Klausel ein. Für den Vergleich muss ein regulärer Ausdruck verwendet werden.

Widgets für den Logbereich

Wenn Sie eine Variable auf ein Widget im Bereich „Protokolle“ anwenden möchten, aktualisieren Sie den Bereich „Abfragen“. Die Syntax für diese Widgets entspricht der unter Allgemeine Syntax angegebenen Syntax.

Console

In der folgenden Abfrage wird beispielsweise mit einem regulären Ausdruck der Wert des Felds jsonPayload.message mit einem Stringwert verglichen, der den Wert einer labelbasierten Variablen enthält:

jsonPayload.message=~"Connected to instance: ${my_label_based_variable.value}"

Angenommen, Sie haben eine Variable vom Typ „Nur Wert“, value_only_severity_variable, und im Menü mit den Werten sind drei Werte ausgewählt: ERROR, INFO und NOTICE. Fügen Sie als Nächstes Folgendes in den Abfragebereich des Widgets für den Logbereich ein:

severity =~ "${value_only_severity_variable}"

Im Folgenden ist das gerenderte Formular zu sehen:

severity =~ "^(ERROR|INFO|NOTICE)$"

API

Im folgenden JSON-Beispiel wird beispielsweise veranschaulicht, wie eine labelbasierte Variable auf die Abfrage eines Logs-Steuerfeld-Widgets angewendet wird:

"logsPanel": {
  "filter": "${my_label_based_variable}",
  "resourceNames": [
    "projects/1234512345"
  ]
},

In der folgenden Abfrage wird beispielsweise mit einem regulären Ausdruck der Wert des Felds jsonPayload.message mit einem Stringwert verglichen, der den Wert einer labelbasierten Variablen enthält:

"logsPanel": {
  "filter": "resource.type=\"gce_instance\"\n
             resource.labels.project_id=~\"${my_label_based_variable.value}\"\n",
  "resourceNames": [
    "projects/012345"
  ]
}

Angenommen, Sie haben eine Variable vom Typ „Nur Wert“, value_only_severity_variable, und im Menü sind drei Werte ausgewählt: ERROR, INFO und NOTICE. Fügen Sie als Nächstes Folgendes in den Abfragebereich des Widgets für den Logbereich ein:

"logsPanel": {
  "filter": "severity =~ \"${value_only_severity_variable}\"\n",
  ...
}

Im Folgenden wird die Abfrage dargestellt, die vom Widget „Logbereich“ ausgeführt wird:

severity =~ "^(ERROR|INFO|NOTICE)$"

Wenn Sie eine Abfrage für den Logbereich konfiguriert und dann die Schaltfläche zum Öffnen des Log-Explorers ausgewählt haben, werden die Variablen aufgelöst, bevor der Log-Explorer geöffnet wird.

In der folgenden Tabelle wird veranschaulicht, wie die Beispielvariablen im Bereich „Protokolle“ aufgelöst werden. Wie bereits erwähnt, müssen Sie als Vergleichsoperator einen regulären Ausdruck verwenden, wenn nur der Wert einer Variablen verwendet wird:

Syntax Ausgewählter
Wert		 Ausdruck für den Bereich mit den gelösten Protokollen
${my_label_based_variable} 12345 resource.labels."instance_id"="12345"

Die Beispielvariable basiert auf dem Ressourcenlabel instance_id.
${my_label_based_variable} * ""
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .*

Diagramme mit PromQL-Abfragen

Wenn Sie eine labelbasierte Variable auf ein Diagramm mit einer PromQL-Abfrage anwenden möchten, folgen Sie der Anleitung unter Allgemeine Syntax.

Console

In der folgenden Abfrage wird beispielsweise davon ausgegangen, dass die labelbasierte Variable my_label_based_variable in einen Filterausdruck aufgelöst wird:

compute_googleapis_com:instance_cpu_utilization{
    monitored_resource="gce_instance", ${my_label_based_variable} }

Sie können die Abfrage auch so ändern, dass nur der Wert einer Variablen ermittelt wird. Im folgenden Beispiel wird mit einem regulären Ausdruck der Wert einer labelbasierten Abfrage mit dem instance_id verglichen:

compute_googleapis_com:instance_cpu_utilization{
    instance_id=~"${my_label_based_variable.value}"
}

Wenn es sich um eine Variable mit nur einem Wert handelt, lassen Sie die .value-Klausel weg. Wenn Sie beispielsweise mit einer Variablen, die nur Werte enthält, nach Zone filtern möchten, würde die Abfrage in etwa so aussehen:

zone=~"${my_value_only_variable}"

API

Das folgende JSON-Beispiel zeigt beispielsweise eine Abfrage, bei der die labelbasierte Variable my_label_based_variable in einen Filterausdruck umgewandelt wird:

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
      monitored_resource=\"gce_instance\",
      ${my_label_based_variable}
      }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

Sie können die Abfrage auch so ändern, dass nur der Wert einer Variablen ermittelt wird. Im folgenden Beispiel wird mit einem regulären Ausdruck der Wert einer labelbasierten Abfrage mit dem instance_id verglichen:

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
    monitored_resource=\"gce_instance\",
    instance_id=~\"${my_label_based_variable.value}\"
    }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

Wenn es sich um eine Variable mit nur einem Wert handelt, lassen Sie die .value-Klausel weg. Wenn Sie beispielsweise mit einer Variablen, die nur Werte enthält, nach Zone filtern möchten, würde die Abfrage in etwa so aussehen:

zone=~\"${my_value_only_variable}\"

In der folgenden Tabelle wird veranschaulicht, wie die Beispielvariablen von PromQL aufgelöst werden. Wie bereits erwähnt, müssen Sie als Vergleichsoperator einen regulären Ausdruck verwenden, wenn nur der Wert einer Variablen verwendet wird:

Syntax Ausgewählter
Wert		 Aufgelöster PromQL-Ausdruck
${my_label_based_variable} 12345 instance_id == '12345'

Die Beispielvariable basiert auf dem Ressourcenlabel instance_id.
${my_label_based_variable} * noop_filter=~".*"
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .+

Diagramme mit SQL-Abfragen

Wenn Sie eine Variable auf ein SQL-definiertes Widget anwenden möchten, aktualisieren Sie die WHERE-Klausel, damit sie auf den Wert der Variablen verweist. Setzen Sie vor allen Variablennamen das At-Zeichen, z. B.: @variable_name. Fügen Sie bei labelbasierten Variablen dem Variablennamen @my_label_based_variabe.value das Präfix .value hinzu.

Bei SQL-Abfragen erfolgt die Variablensubstitution über BigQuery und ist vor SQL-Injection geschützt. Weitere Informationen finden Sie unter Parametrisierte Abfragen ausführen.

Console

Da der Platzhalteroperator in SQL nicht als „beliebiger Wert“ interpretiert wird, empfehlen wir, immer eine IF-Anweisung zu verwenden, wenn Sie Variablen auf eine SQL-Abfrage anwenden. Im folgenden Beispiel wird die Verwendung einer Variablen mit nur einem Wert veranschaulicht, deren Datentyp ein String ist:

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

Wenn Nutzer über die Menüoption für die Variable mehrere Werte auswählen können, müssen Sie den Wert der Variablen mithilfe der Funktion CAST in einen GoogleSQL-Datentyp umwandeln. Die folgende Abfrage veranschaulicht diese Syntax:

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

Die in den vorherigen Beispielen gezeigte IF-Anweisung wird empfohlen, da der Platzhalter in SQL nicht als „beliebiger Wert“ interpretiert wird. Wenn Sie die Anweisung IF weglassen und den Platzhalteroperator auswählen, ist das Ergebnis der Abfrage eine leere Tabelle. Im zweiten Beispiel wird das Array mit der Funktion UNNEST in eine Tabelle umgewandelt.

So fügen Sie eine korrekt formatierte WHERE-Klausel hinzu:

  1. Bearbeiten Sie das Widget.
  2. Wählen Sie in der Symbolleiste Variablenfilter einfügen und dann die Variable aus, die Sie auf die WHERE-Klausel anwenden möchten.
  3. Prüfen Sie im angezeigten Dialogfeld den generierten Code und klicken Sie dann auf Kopieren und schließen.

  4. Fügen Sie den kopierten Code in den Bereich Abfrage ein und nehmen Sie die erforderlichen Änderungen vor.

    Angenommen, Sie erstellen eine Variable namens LogName, die eine Liste von Protokollnamen generiert und das Ergebnis in einer Tabelle mit einer einzelnen Spalte namens log_name ausgibt. Als Nächstes erstellen Sie ein Diagramm, wählen Variablenfilter einfügen und dann die Variable LogName aus. Der folgende Code wird generiert:

    WHERE IF(@LogName = '*', TRUE, LogName = @LogName)

    In diesem Beispiel müssen Sie den generierten Code bearbeiten und LogName = durch log_name = ersetzen, damit die Tabellenverknüpfung erfolgen kann:

    WHERE IF(@LogName = '*', TRUE, log_name = @LogName)

  5. Klicken Sie auf Ausführen und dann auf Übernehmen.

  6. Klicken Sie in der Symbolleiste auf Speichern, um das geänderte Dashboard zu speichern.

API

Da der Platzhalteroperator in SQL nicht als „beliebiger Wert“ interpretiert wird, empfehlen wir, immer eine IF-Anweisung zu verwenden, wenn Sie Variablen auf eine SQL-Abfrage anwenden. Im folgenden Beispiel wird die Verwendung einer Variablen mit nur einem Wert veranschaulicht, deren Datentyp ein String ist:

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

Im Folgenden sehen Sie beispielsweise eine teilweise JSON-Darstellung eines Diagramms, in dem die Ergebnisse einer SQL-Abfrage angezeigt werden. Um die Ergebnisse nach dem Namen eines Protokolls filtern zu können, wurde eine WHERE-Klausel hinzugefügt, die auf die Variable LogName verweist:

"plotType": "STACKED_BAR",
"targetAxis": "Y1",
"timeSeriesQuery": {
  "opsAnalyticsQuery": {
    "queryExecutionRules": {},
    "queryHandle": "",
    "sql": "SELECT\n timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload\n
            FROM\n `my-project.global._Default._Default`\n
            WHERE \n IF (@LogName = \"*\", TRUE, log_name=@LogName)\nLIMIT 10000"
  }
}

Die Variable LogName gibt auch eine Abfrage aus, um die Liste der möglichen Protokollnamen zu ermitteln:

"dashboardFilters": [
  {
    "filterType": "VALUE_ONLY",
    "templateVariable": "LogName",
    "valueType": "STRING",
    "timeSeriesQuery": {
      "opsAnalyticsQuery": {
        "savedQueryId": "",
        "sql": "SELECT log_name FROM `my-project.global._Default._Default` GROUP BY log_name LIMIT 1000",
        "queryHandle": ""
      },
      "unitOverride": "",
      "outputFullDuration": false
    }
  }
],

Wenn Nutzer über die Menüoption für die Variable mehrere Werte auswählen können, müssen Sie den Wert der Variablen mithilfe der Funktion CAST in einen GoogleSQL-Datentyp umwandeln. Die folgende Abfrage veranschaulicht diese Syntax:

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

Die in den vorherigen Beispielen gezeigte IF-Anweisung wird empfohlen, da der Platzhalter in SQL nicht als „beliebiger Wert“ interpretiert wird. Wenn Sie die Anweisung IF weglassen und den Platzhalteroperator auswählen, ist das Ergebnis der Abfrage eine leere Tabelle. Im zweiten Beispiel wird das Array mit der Funktion UNNEST in eine Tabelle umgewandelt.

Diagramme mit MQL-Abfragen

Wenn Sie eine labelbasierte Variable auf ein Diagramm mit einer MQL-Abfrage anwenden möchten, fügen Sie ein Pipesymbol (|) an und folgen Sie der Anleitung unter Allgemeine Syntax.

Wenn Sie über die menügesteuerte Benutzeroberfläche ein Diagramm mit Zeitreihendaten erstellen, werden Ihre Auswahlen in einen Monitoring-Filter umgewandelt.

Console

In der folgenden Abfrage wird beispielsweise eine labelbasierte Variable (my_label_based_variable) in einen Filterausdruck umgewandelt:

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${my_label_based_variable}

Sie können die Abfrage auch so ändern, dass nur der Wert einer Variablen ermittelt wird. Im folgenden Beispiel wird mit einem regulären Ausdruck der Wert einer labelbasierten Abfrage mit dem instance_id verglichen:

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| filter resource.instance_id=~'${my_label_based_variable.value}'
| group_by 1m, [value_utilization_mean: mean(value.utilization)]
| every 1m

Wenn es sich um eine Variable mit nur einem Wert handelt, lassen Sie die .value-Klausel weg. Wenn Sie beispielsweise mit einer Variablen, die nur Werte enthält, nach Zone filtern möchten, würde die Abfrage in etwa so aussehen:

resource.zone=~'${my_value_only_variable}'

API

Das folgende JSON-Beispiel zeigt beispielsweise eine Abfrage, bei der eine labelbasierte Variable (my_label_based_variable) in einen Filterausdruck umgewandelt wird:

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n
    | ${my_label_based_variable}",
  "unitOverride": "",
  "outputFullDuration": false
},

Sie können die Abfrage auch so ändern, dass nur der Wert einer Variablen ermittelt wird. Im folgenden Beispiel wird mit einem regulären Ausdruck der Wert einer labelbasierten Abfrage mit dem instance_id verglichen:

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | filter resource.instance_id=~'${my_label_based_variable.value}'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n",
  "unitOverride": "",
  "outputFullDuration": false
},

Wenn es sich um eine Variable mit nur einem Wert handelt, lassen Sie die .value-Klausel weg. Wenn Sie beispielsweise mit einer Variablen, die nur Werte enthält, nach Zone filtern möchten, würde die Abfrage in etwa so aussehen:

resource.zone=~'${my_value_only_variable}'

In der folgenden Tabelle wird veranschaulicht, wie die Beispielvariablen in der MQL aufgelöst werden. Wie bereits erwähnt, müssen Sie als Vergleichsoperator einen regulären Ausdruck verwenden, wenn nur der Wert einer Variablen verwendet wird:

Syntax Ausgewählter
Wert		 Aufgelöster MQL-Ausdruck
${my_label_based_variable} 12345 filter (resource.instance_id == '12345')

Die Beispielvariable basiert auf dem Ressourcenlabel instance_id.
${my_label_based_variable} * filter (true)
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .*

Diagramme mit Monitoring-Filterabfragen

Wenn Sie eine labelbasierte Variable auf ein Diagramm mit einer Abfrage in Form eines Überwachungsfilters anwenden möchten, folgen Sie der Anleitung unter Allgemeine Syntax.

Console

Wenn Sie die Google Cloud Console zum Erstellen von Diagrammen verwenden und die menübasierte Benutzeroberfläche nutzen, können Sie eine labelbasierte Variable auf ein Diagramm anwenden. Verwenden Sie dazu das Feld Auf Diagramme anwenden der Variablen oder bearbeiten Sie das Widget und wählen Sie im Menü Filter die Option „Labelbasierte Variable“ aus. Im Menü Filter werden alle labelbasierten Variablen und alle Labelschlüssel aufgeführt.

So wenden Sie eine wertbezogene Variable auf diese Diagrammtypen an:

  1. Das Diagramm bearbeiten.
  2. Klicken Sie im Abfragebereich auf Filter hinzufügen und wählen Sie einen Labelschlüssel aus. Sie können beispielsweise zone auswählen.
  3. Wählen Sie im Menü Wert die Variable aus, die nur einen Wert enthält.
  4. Klicken Sie auf Anwenden.
  5. Klicken Sie in der Symbolleiste auf Speichern, um das geänderte Dashboard zu speichern.

Das folgende JSON-Beispiel zeigt beispielsweise eine Abfrage, bei der eine labelbasierte Variable (my_label_based_variable) in einen Filterausdruck umgewandelt wird:

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance" ${my_label_based_variable}"

Bei Widgets, die eine Abfrage in Form eines Monitoring-Filters verwenden, kann die Zeitreihe nicht nach dem Wert in einer labelbasierten Variablen gefiltert werden. Sie können jedoch nach Variablen filtern, die nur Werte enthalten. In der folgenden Abfrage wird beispielsweise der Wert des Felds Filter einer Abfrage angezeigt, die nach zone filtert, basierend auf dem Wert einer Variablen vom Typ „Nur Wert“:

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance"
resource.label."zone"=monitoring.regex.full_match(${my_value_only_variable})

API

Das folgende JSON-Beispiel zeigt beispielsweise eine Abfrage, bei der eine labelbasierte Variable (my_label_based_variable) in einen Filterausdruck umgewandelt wird:

"timeSeriesQuery": {
  "timeSeriesFilter": {
    "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
               resource.type=\"gce_instance\"
               ${my_label_based_variable} ",
    "aggregation": {
      "alignmentPeriod": "60s",
      "perSeriesAligner": "ALIGN_MEAN",
      "groupByFields": []
    }
  },
  "unitOverride": "",
  "outputFullDuration": false
},

Bei Widgets, die eine Abfrage in Form eines Monitoring-Filters verwenden, kann die Zeitreihe nicht nach dem Wert in einer labelbasierten Variablen gefiltert werden. Sie können jedoch nach Variablen filtern, die nur Werte enthalten. In der folgenden Abfrage ist beispielsweise das Feld "filter" einer Abfrage zu sehen, die nach zone filtert, basierend auf dem Wert einer Variablen vom Typ „Nur Wert“:

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
          resource.type=\"gce_instance\"
          resource.labels.\"zone\"=monitoring.regex.full_match(${my_value_only_variable})"

In der folgenden Tabelle wird veranschaulicht, wie die Beispielvariablen vom Monitoring-Filter aufgelöst werden. Wie bereits erwähnt, müssen Sie als Vergleichsoperator einen regulären Ausdruck verwenden, wenn nur der Wert einer Variablen verwendet wird:

Syntax Ausgewählter
Wert		 Aufgelöster Filterausdruck
${my_label_based_variable} 12345 resource.instance_id == "12345"

Die Beispielvariable basiert auf dem Ressourcenlabel instance_id.
${my_label_based_variable} * Ausgelassen
${my_label_based_variable.value} 12345 Nicht unterstützt
${my_label_based_variable.value} * Nicht unterstützt
${my_value_based_variable} 12345 "12345"
${my_value_based_variable} * ".*"

Dashboard erstellen

Zum Erstellen eines neuen benutzerdefinierten Dashboards rufen Sie dieMethode dashboards.create auf und geben das Layout und die Widgets zur Anzeige im Dashboard an.

Wenn Sie ein Dashboard erstellen, generiert die API automatisch die dashboard_id. Wenn Sie eine benutzerdefinierte dashboard_id angeben möchten, können Sie das name-Feld eines Dashboard-Objekts festlegen. Das Format des Namensfelds sieht so aus:

"name": "projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}"

API

Um ein neues Dashboard zu erstellen, senden Sie eine POST-Anfrage an den Endpunkt Dashboard.

curl -d @my-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X POST https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

Verwenden Sie den Befehl gcloud monitoring dashboards create, um ein Dashboard in einem Projekt zu erstellen.

gcloud monitoring dashboards create --config-from-file=my-dashboard.json

So duplizieren Sie beispielsweise ein Dashboard:

  1. Führen Sie die Schritte unter Dashboard abrufen aus, um die Definition des ursprünglichen Dashboards herunterzuladen.
  2. Bearbeiten Sie die zurückgegebene JSON-Datei, um die Felder etag und name zu entfernen, und ändern Sie den Wert des Felds displayName.
  3. Führen Sie den Befehl aus, um das Dashboard zu erstellen.

Weitere Informationen finden Sie in der Referenz zu gcloud monitoring dashboards create.

Terraform

Informationen zum Anwenden oder Entfernen einer Terraform-Konfiguration finden Sie unter Grundlegende Terraform-Befehle. Weitere Informationen finden Sie in der Anbieterreferenzdokumentation zu Terraform.

Verwenden Sie zum Erstellen eines Dashboards mit Terraform die Terraform-Ressource google_monitoring_dashboard.

Legen Sie im Befehl die folgenden Felder fest:

  • dashboard_json: Die JSON-Darstellung des Dashboards im Format Dashboards.

    Beispiele für dieses Format finden Sie, wenn Sie Ihre Dashboards entweder mit dem APIs Explorer auflisten oder ein Dashboard in der Google Cloud Console öffnen und sich die JSON-Darstellungen ansehen.

  • parent: Der voll qualifizierte Name Ihres Projekts. Sie können dieses Feld beispielsweise auf "projects/PROJECT_ID" festlegen, wobei PROJECT_ID die ID Ihres Google Cloud-Projekts ist.

In den Beispielen wird ein Beispiel-Dashboard mithilfe der Datei my-dashboard.json erstellt. Sie können Ihr Dashboard über die Google Cloud Console verwalten.

Weitere Dashboard-Konfigurationen finden Sie unter Beispiele für Dashboards und Layouts.

Dashboards löschen

Um ein benutzerdefiniertes Dashboard zu löschen, rufen Sie die Methode dashboards.delete auf und geben Sie das zu löschende Dashboard an.

API

Senden Sie zum Löschen eines benutzerdefinierten Dashboards eine DELETE-Anfrage an den Endpunkt Dashboard, der mit der ID des zu löschenden Dashboards qualifiziert ist.

curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Bei Erfolg gibt die Methode eine leere Antwort zurück. Andernfalls wird ein Fehler zurückgegeben.

gcloud

Verwenden Sie zum Löschen eines benutzerdefinierten Dashboards gcloud monitoring dashboards delete und geben Sie die vollständig qualifizierte ID des zu löschenden Dashboards an:

gcloud monitoring dashboards delete projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Weitere Informationen finden Sie in der Referenz zu gcloud monitoring dashboards delete.

Terraform

Sie können Ressourcen mit Terraform löschen. Informationen zum Löschen von Ressourcen finden Sie im Terraform-Befehl destroy.

Dashboards auflisten

Zum Auflisten aller Dashboards, die zu einem Projekt gehören, rufen Sie die Methode dashboards.list auf und geben die Projekt-ID an.

API

Wenn Sie alle benutzerdefinierten Dashboards eines Projekts auflisten möchten, senden Sie die Projekt-ID an den Endpunkt Dashboard.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

Verwenden Sie den Befehl gcloud monitoring dashboards list, um alle benutzerdefinierten Dashboards eines Projekts aufzulisten:

gcloud monitoring dashboards list

Weitere Informationen finden Sie in der Referenz zu gcloud monitoring dashboards list.

Terraform

Sie können mit Terraform keine Abfrage an Ihr Projekt senden, die eine Liste von Dashboards zurückgibt. Sie können diese Dashboards jedoch über die Google Cloud Console aufrufen.

Die Beispiele geben die mit Ihrem Projekt verknüpften benutzerdefinierten Dashboards zurück.

Listenantwort paginieren

Die dashboards.list-Methode unterstützt die Paginierung, sodass Sie die Ergebnisse jeweils pro Seite statt alle gleichzeitig verarbeiten können.

API

Geben Sie für die erste Seite der Ergebnisliste den Suchparameter pageSize mit der Anfrage an:

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards?page_size=1

Die Methode gibt die erste Seite der Liste und das nextPageToken zurück. Beispiel:

{
  "dashboards" : [
    {
       "displayName" : "Grid Layout Example",
       "gridLayout" : {
         "widgets" : [
            { ... },
            { ... },
            { ... },
          ]
       }
    }
  ]
},
"nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"

Für jede verbleibende Seite müssen Sie das entsprechende nextPageToken in der Anfrage angeben.

gcloud

Um die Anzahl der Ressourcen pro Seite anzugeben, übergeben Sie das Flag --page-size mit dem Befehl. Beispiel:

gcloud monitoring dashboards list --page-size=1

Terraform

Sie können mit Terraform keine Abfrage an Ihr Projekt senden, die eine paginierte Liste von Dashboards zurückgibt. Sie können diese Dashboards jedoch über die Google Cloud Console aufrufen.

Dashboard abrufen

Wenn Sie ein bestimmtes benutzerdefiniertes Dashboard für ein Projekt abrufen möchten, rufen Sie die Methode dashboards.get auf, die mit der Dashboard-ID qualifiziert ist.

API

Wenn Sie ein bestimmtes benutzerdefiniertes Dashboard abrufen möchten, senden Sie die Dashboard-ID an den Endpunkt Dashboard.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Die Methode gibt eine Antwort in etwa wie im folgenden Beispiel zurück:

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

gcloud

Um ein bestimmtes benutzerdefiniertes Dashboard abzurufen, verwenden Sie den Befehl gcloud monitoring dashboards describe und geben die Dashboard-ID an:

gcloud monitoring dashboards describe ${DASHBOARD_ID} --format=json

Der Befehl gibt das angeforderte Dashboard zurück:

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

Weitere Informationen finden Sie in der Referenz zu gcloud monitoring dashboards describe.

Terraform

Sie können mit Terraform keine Abfrage an Ihr Projekt senden, die ein einzelnes Dashboard als Antwort enthält. Sie können diese Dashboards jedoch über die Google Cloud Console aufrufen.

Dashboard aktualisieren

Rufen Sie zum Aktualisieren eines vorhandenen benutzerdefinierten Dashboards die Methode dashboards.patch auf. Zum Abrufen des aktuellen etag-Werts können Sie die Methode dashboards.get aufrufen und ihn in der Antwort finden.

API

Senden Sie zum Aktualisieren eines benutzerdefinierten Dashboards eine PATCH-Anfrage an den Endpunkt Dashboard und geben Sie das überarbeitete Dashboard-Objekt und den etag-Wert aus der letzten dashboards.get-Antwort.

curl -d @my-updated-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X PATCH https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Im vorherigen Beispiel wird ein vorhandenes benutzerdefiniertes Dashboard mithilfe der Datei my-updated-dashboard.json aktualisiert. Die Antwort, die einen neuen etag-Wert enthält, ist eine Kopie des aktualisierten Dashboard-Eintrags.

gcloud

Verwenden Sie gcloud monitoring dashboards update zum Aktualisieren eines benutzerdefinierten Dashboards, geben Sie die ID des zu aktualisierenden Dashboards an und geben Sie die Änderungen im Dashboard an.

gcloud monitoring dashboards update ${DASHBOARD_ID} --config-from-file=my-updated-dashboard.json

Weitere Informationen finden Sie in der Referenz zu gcloud monitoring dashboards update.

Im vorherigen Beispiel wird ein vorhandenes benutzerdefiniertes Dashboard mithilfe der Datei my-updated-dashboard.json aktualisiert. Die Antwort, die einen neuen etag-Wert enthält, ist eine Kopie des aktualisierten Dashboard-Eintrags.

Terraform

Informationen zum Anwenden oder Entfernen einer Terraform-Konfiguration finden Sie unter Grundlegende Terraform-Befehle. Weitere Informationen finden Sie in der Anbieterreferenzdokumentation zu Terraform.

Verwenden Sie zum Aktualisieren eines Dashboards mit Terraform die Terraform-Ressource google_monitoring_dashboard.

Legen Sie im Befehl die folgenden Felder fest:

  • dashboard_json: Die JSON-Darstellung des Dashboards im Format Dashboards.

  • parent: Der voll qualifizierte Name Ihres Projekts. Sie können dieses Feld beispielsweise auf "projects/PROJECT_ID" festlegen, wobei PROJECT_ID die ID Ihres Google Cloud-Projekts ist.

Nächste Schritte