Dashboards nach API erstellen und verwalten

In diesem Dokument wird beschrieben, wie Sie und Widgets auf diesen Dashboards mithilfe von Die Ressource Dashboard in der Cloud Monitoring API. Die folgenden Beispiele veranschaulichen, wie Sie Ihre Dashboards mithilfe von curl zum Aufrufen der API und sie zeigen, wie die Google Cloud CLI verwendet wird. Sie können Ihre benutzerdefinierten Dashboards auch über die Google Cloud Console können Sie die API eine programmatische Möglichkeit, viele Dashboards gleichzeitig zu verwalten.

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

• dashboards.create: Erstellt ein Dashboard
• dashboards.delete: Löscht ein bestimmtes Dashboard
• dashboards.list: Ruft eine Liste aller Dashboards in einem bestimmten Projekt ab
• dashboards.get: Ruft ein bestimmtes Dashboard ab
• dashboards.patch: Aktualisiert die Struktur eines bestimmten Dashboards

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

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

Informationen zu 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 auch Fügen Sie Ihrem Dashboard Labels und Filter hinzu. Labels helfen Ihnen, ein Dashboard zu finden oder die Art der Inhalte auf dem Dashboard angeben.

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 Typen von Widget-Objekten:

• Diagramm- und Tabellen-Widgets:

  • XyChart: Zeigt Daten mithilfe der X- und Y-Achse an. Die folgenden Diagramme sind Instanzen des XyChart-Widgets:

  • Liniendiagramme

  • Balkendiagramme

  • Gestapelte Flächendiagramme

  • Heatmaps

  • Loganalysendiagramme

  • SLO-Widgets. Das Erstellen von SLO-Diagrammen mithilfe der API wird jedoch nicht unterstützt.

  Wenn Sie Linien-, Balken- oder Flächendiagramm gestapelt, wird angegeben, dass sich ein Messwert auf die linke oder rechte Y-Achse bezieht. Wenn mehrere werden, können Sie beide Y-Achsen verwenden.

  • PieChart: Zeigt den neuesten Wert eines Messwerts an. wobei jede Zeitreihe ein Segment zum Kreis beiträgt.

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

  • TimeSeriesTable: Zeigt den neuesten Wert eines Messwerts an. Sie können die Tabelle nach Spalten sortieren, die Tabelle filtern und Spalten aus der Anzeige zu entfernen.

• Diagramme für Benachrichtigungsrichtlinien und Widgets für Vorfälle:

  • AlertChart: Zeigt eine Zusammenfassung einer einzelnen Bedingung an Benachrichtigungsrichtlinie Dieses Widget zeigt die Daten als Liniendiagramm an, Grenzwert und die Anzahl der offenen Vorfälle.

  • IncidentList: zeigt eine Liste der Vorfälle an. Sie können das Widget so konfigurieren, dass Vorfälle für bestimmte Benachrichtigungsrichtlinien oder für bestimmte Ressourcentypen.

• Protokoll- und Fehler-Widgets:

  • ErrorReportingPanel: Displays Fehlergruppen, die in der ausgewählten Google Cloud-Projekt

  • LogsPanel: Displays projektbezogene Logeinträge, die in der aktuellen Google Cloud-Projekt Sie können das Widget so konfigurieren, dass Logeinträge angezeigt werden die in Google Cloud-Projekten gespeichert sind, Messwertbereich.

• Text- und Organisations-Widgets:

  Um diese Widgets auf einem Dashboard muss eine MosaicLayout vorhanden sein.

  • CollapsibleGroup: Zeigt eine Sammlung von Widgets an. Sie können die Ansicht einer Gruppe minimieren.

  • SingleViewGroup: zeigt ein Widget in einem Widget-Sammlung. Du kannst auswählen, welches Widget angezeigt werden soll.

  • SectionHeader: Erstellt eine horizontale Trennlinie Ihr Dashboard und es wird ein Eintrag in der Tabelle des Dashboards Inhalte.

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

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

Im Folgenden sehen Sie beispielsweise die JSON-Darstellung eines XyChart-Widget, dessen rechte Y-Achse konfiguriert ist:

{
  "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"
          }
        }
      }
    ]
  }
}

Dashboard labels

Mit Labels können Sie Ihre Dashboards verwalten und organisieren. Zum Beispiel haben Sie kann ein Label mit dem Namen prod hinzufügen, um anzuzeigen, dass das Dashboard Zeitreihendaten und Protokolldaten für Ihre Produktionsressourcen. Alternativ können Sie können Sie das Label playbook hinzufügen, um anzuzeigen, enthält Informationen zur Fehlerbehebung.

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

Das folgende Beispiel zeigt ein Dashboard-Objekt, das gibt das Label playbook an.

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

Wie das vorherige Beispiel zeigt, ist das Feld labels als map, wobei die Felder key und value beide Strings sind. Wenn Sie eine einem Dashboard, legen Sie für key den Namen des Labels fest und value in einen leeren String.

Dashboard-Filter

Beim Entwerfen eines Dashboards identifizieren Sie möglicherweise mehrere Möglichkeiten, Daten, die im Dashboard angezeigt werden. Zum Beispiel, wenn in einem Dashboard Messwerte Bei VM-Instanzen sollten Sie sich Messwerte für alle und Sie möchten sich Messwerte für eine bestimmte Zone ansehen. Bei dieser Art von empfehlen wir, einen dauerhaften Filter zu erstellen und die Standardfiltereinstellung dieses Filters in die am häufigsten verwendete Datenansicht ein. Dauerfilter können auf einige oder alle Dashboard-Widgets anwenden. Wenn Sie das Dashboard mit der In der Google Cloud Console werden in der Dashboard-Symbolleiste Ihre permanenten Filter und ein Menü, mit dem Sie den Wert des Filters vorübergehend ändern können.

Es gibt mehrere Arten von dauerhaften Dashboard-Filtern:

• Dashboardweite Filter gelten für alle Widgets auf einem Dashboard, die die Filterlabel und keinen Wert für dieses Label angeben.

  Enthält ein Diagramm beispielsweise den Filter zone = us-central1-a, Diagramm ignoriert einen Dashboard-Filter, der auf dem Label zone basiert. In ähnlicher Weise Diagramme ohne zone-Label ignorieren Dashboard-Filter mit diesem Label.

• Vorlagenvariablen sind benannte Variablen, die für bestimmte Widgets gelten. Jede Variable gilt für ein bestimmtes Label und einen bestimmten Wert. Sie bestimmen, Widgets, für die eine Vorlagenvariable gilt.

Alle Filtertypen haben dieselbe Datenstruktur. Weitere Informationen finden Sie unter DashboardFilter.

Das folgende Beispiel zeigt die JSON-Teildarstellung eines Dashboards. definiert eine Vorlagenvariable und einen Dashboard-weiten Filter:

{
  "dashboardFilters": [
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "templateVariable": "iid"
      },
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "zone"
      }
    ],
  "displayName": "Illustrate Template Variables",
  ...

In der angezeigten JSON-Datei ist der erste Eintrag in der dashboardFilters-Struktur ist für eine Vorlagenvariable mit dem Namen iid und einen Dashboard-weiten Filter mit Labelschlüssel zone Die Vorlagenvariable ist Alias des Labels instance_id.

In der Datenstruktur einer Vorlagenvariablen sind die Widgets nicht aufgeführt, angewandt wird. Stattdessen verknüpfen Sie ein Widget mit einer Vorlagenvariablen, indem Sie die Abfrage des Widgets ändern, sodass sie einen Verweis auf die Variable enthält. Wenn das Widget auf dem Dashboard angezeigt wird, wird der Wert der Vorlagenvariablen aufgelöst.

In den folgenden Abschnitten erfahren Sie, wie Sie Logbereiche und Diagramme mit Anmerkungen versehen:

• Logbereich
• MQL-definierte Diagramme und Tabellen
• PromQL-definierte Diagramme und Tabellen
• Mit Zeitreihenfiltern definierte Diagramme und Tabellen

Logbereich

So konfigurieren Sie einen Logbereich, um die Anzeige anhand des Werts eines Vorlagenvariablen hinzufügen, fügen Sie sie im Abfragebereich hinzu. Im folgenden Beispiel stellt eine Abfrage dar, die nach dem Wert der Vorlagenvariablen iid filtert:

${iid}

Bevor das Logfeld die anzuzeigenden Logs abfragt, gelöst wird. Wenn in diesem Beispiel der Wert der Vorlagenvariablen ist "12345", dann wird ${iid} durch die Anweisung ersetzt resource.labels."instance_id"="12345"

Sie können auch nur den Wert einer Vorlagenvariablen in eine Abfrage einbeziehen. Wir empfehlen, den Wert nur als Teil eines Filters zu verwenden, der mit einem regulärer Ausdruck. Die folgende Abfrage verwendet beispielsweise einen regulären Ausdruck um Logeinträge mit einer JSON-Nutzlast abzugleichen, die die beschriebenen String:

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

Wenn Sie eine Abfrage für das Logfeld konfiguriert haben und dann auf die Schaltfläche um den Log-Explorer zu öffnen, werden die Vorlagenvariablen aufgelöst, bevor wird der Log-Explorer geöffnet.

Die folgende Tabelle zeigt, wie die Vorlagenvariable vom Logfeld:

MQL-definierte Diagramme und Tabellen

Wenn Sie mit Monitoring Query Language (MQL) ein Diagramm konfigurieren, hängen Sie eine Pipe und den in die Abfragezeichenfolge ein:

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

Bevor das Diagramm die anzuzeigende Zeitreihe abfragt, wird die Vorlagenvariable gelöst wird. Wenn in diesem Beispiel der Wert der Vorlagenvariablen ist "12345", dann wird ${iid} durch die Anweisung ersetzt filter (resource.instance_id == '12345') Dieser Filter entspricht der Zeit mit dem Label resource.instance_id und nur wenn der Wert dieses Labels ist genau 12345.

Wenn Sie Zeitreihen mithilfe eines regulären Ausdrucks filtern möchten, dann: konfigurieren Sie die Abfrage so, dass sie nur den Wert der Vorlagenvariablen enthält. Um die Syntax zu veranschaulichen, wird Folgendes dargestellt: zeigt, wie mit einem regulären Ausdruck festgestellt wird, ob der Wert des Das Label resource.instance_id enthält den Wert der Vorlagenvariablen iid:

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

Die folgende Tabelle zeigt, wie die Vorlagenvariable für MQL aufgelöst wird Suchanfragen:

PromQL-definierte Diagramme und Tabellen

Wenn Sie ein Diagramm mit PromQL definieren, hängen Sie an den Abfragestring den Variable in geschweiften Klammern:

compute_googleapis_com:instance_cpu_utilization {
    project_id="my-project", ${iid}
}

Bevor das Diagramm die anzuzeigende Zeitreihe abfragt, wird die Vorlagenvariable gelöst wird. Wenn in diesem Beispiel der Wert der Vorlagenvariablen ist "12345", dann wird ${iid} durch die Anweisung ersetzt instance_id == '12345'

Ähnlich wie bei MQL wird die Abfrage, wenn Sie ein Widget mit PromQL definieren, nur den Wert der Vorlagenvariablen extrahieren kann. Wir empfehlen Ihnen, Verwenden Sie den Wert nur als Teil eines Filters, der mit einem regulären Ausdruck definiert ist. Bis um die Syntax zu veranschaulichen. Im Folgenden wird gezeigt, wie Sie mit einem regulären Ausdruck Ermittelt, ob der Wert des Labels instance_id den Wert des Attributs Vorlagenvariable iid:

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

Die folgende Tabelle zeigt, wie die Vorlagenvariable für PromQL aufgelöst wird Suchanfragen:

Mit Zeitreihenfiltern definierte Diagramme und Tabellen

Wenn Sie ein Diagramm mit Zeitreihenfiltern definieren, hängen Sie die Variable zum Filterstring an:

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
           resource.type=\"gce_instance\" ${iid}"

Im Gegensatz zu MQL- und PromQL-definierten Diagrammen können Sie den Wert einer Vorlagenvariablen in einem Zeitreihenfilter.

Die folgende Tabelle zeigt, wie die Vorlagenvariable aufgelöst wird:

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}"

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 monitoring dashboards create --config-from-file=my-dashboard.json

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

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.

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

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

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.

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

gcloud monitoring dashboards list

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.

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

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

gcloud monitoring dashboards list --page-size=1

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.

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

{
  "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 monitoring dashboards describe ${DASHBOARD_ID} --format=json

{
  "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"
}

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.

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}

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

In den Beispielen wird ein vorhandenes benutzerdefiniertes Dashboard mithilfe der my-updated-dashboard.json-Datei und geben Sie eine Kopie der aktualisierten Datei an Dashboardeintrag. Die zurückgegebenen Daten enthalten einen neuen etag-Wert.

Nächste Schritte

• Beispiele für Dashboards und Layouts
• Benutzerdefinierte Dashboards mit der Google Cloud Console erstellen und verwalten