Verteilungsmesswerte konfigurieren

Auf dieser Seite wird erläutert, wie Sie mit derGoogle Cloud -Console, der Logging API und der Google Cloud CLI logbasierte Verteilungsmesswerte erstellen. Eine Gesamtübersicht über logbasierte Messwerte finden Sie unter Übersicht über logbasierte Messwerte.

Übersicht

Verteilungsmesswerte benötigen sowohl einen Filter zur Auswahl relevanter Logeinträge als auch einen Wertextrahierer, um den numerischen Wert für die Verteilung abzurufen. Dieser Wertextrahierer wird auch für benutzerdefinierte Labels verwendet.

Mithilfe eines Verteilungsmesswerts wird die statistische Verteilung der extrahierten Werte in Histogramm-Buckets aufgezeichnet. Die extrahierten Werte werden nicht einzeln aufgezeichnet, sondern ihre Verteilung über die konfigurierten Buckets wird zusammen mit der Anzahl, dem Mittelwert und der Summe der quadratischen Abweichungen der Werte aufgezeichnet. Sie können das Standardlayout von Histogramm-Buckets in Ihrer Verteilung verwenden oder die Grenzwerte für die Buckets anpassen, um die Werte ungefähr zu erfassen.

Weitere Informationen zum Ansehen und Interpretieren von Verteilungsmesswerten finden Sie unter Verteilungsmesswerte.

Hinweise

  1. Wenn Sie logbasierte Messwerte verwenden möchten, benötigen Sie ein Google Cloud -Projekt mit aktivierter Abrechnungsfunktion:

    1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

    2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

      Go to project selector

    3. Make sure that billing is enabled for your Google Cloud project.

    4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

      Go to project selector

    5. Make sure that billing is enabled for your Google Cloud project.

    6. Prüfen Sie, ob Ihre IAM-Rolle (Identity and Access Management) die Berechtigungen enthält, die zum Erstellen und Aufrufen logbasierter Messwerte und zum Erstellen von Benachrichtigungsrichtlinien erforderlich sind. Weitere Informationen finden Sie unter Berechtigungen für logbasierte Messwerte.

      7. Verteilungsmesswert erstellen

      Mit dem Messwert werden die Logeinträge gezählt, die durch einen von Ihnen angegebenen Filter identifiziert werden. Sie können reguläre Ausdrücke in Ihrem Filter verwenden. Wir empfehlen, einen Ressourcentyp anzugeben. Ein Filter darf nicht länger als 20.000 Zeichen sein.

      Geben Sie keine vertraulichen Informationen in den Filter ein. Filter werden als Dienstdaten behandelt.

      Console

      So erstellen Sie in derGoogle Cloud -Konsole in Ihrem Google Cloud -Projekt einen logbasierten Zählermesswert:

      1. Rufen Sie in der Google Cloud Console die Seite Logbasierte Messwerte auf:

        Zu Logbasierte Messwerte

        Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Logging ist.

      2. Klicken Sie auf Messwert erstellen. Der Bereich Logmesswert erstellen wird angezeigt.

      3. Legen Sie den Messwerttyp fest: Wählen Sie Verteilung aus.

      4. Legen Sie im Abschnitt Details die folgenden Felder fest:

        • Name des Logmesswerts: Wählen Sie einen Namen aus, der unter den logbasierten Messwerten in Ihrem Google Cloud Projekt einmalig ist. Für die Benennung gelten einige Einschränkungen. Weitere Informationen dazu finden Sie unter Fehlerbehebung.
        • Beschreibung: Geben Sie eine Beschreibung für den Messwert ein.
        • Einheiten: (Optional) Für Verteilungsmesswerte können Sie optional Einheiten wie s und ms eingeben. Weitere Informationen finden Sie im Feld unit des MetricDescriptor.

      5. Definieren Sie den Messwertfilter im Abschnitt Filterauswahl.

        1. Wählen Sie im Menü Projekt oder Log-Bucket auswählen aus, ob der Messwert die Logeinträge in Ihrem Google Cloud Projekt oder nur die Logeinträge in einem bestimmten Log-Bucket zählt.

        2. Erstellen Sie einen Filter, der nur die Logeinträge erfasst, die Sie in Ihrem Messwert mit der Logging-Abfragesprache zählen möchten. Sie können auch reguläre Ausdrücke verwenden, um Filter des Messwerts zu erstellen.

        3. Feldname: Geben Sie das Feld des Logeintrags ein, das den Wert der Verteilung enthält. Bei der Eingabe werden Optionen zur Auswahl angezeigt. Beispiel:

          protoPayload.latency

        4. Regulärer Ausdruck: (optional) Wenn Feldname immer einen numerischen Wert enthält, der in den Typ double umgewandelt werden kann, können Sie dieses Feld leer lassen. Geben Sie andernfalls einen regulären Ausdruck an, mit dem der numerische Verteilungswert aus dem Feldwert extrahiert wird.

          Beispiel: Angenommen, das Logeintragsfeld latency enthält eine Zahl gefolgt von ms für Millisekunden. Mit dem folgenden regulären Ausdruck wird die Zahl ohne die nachstehende Einheit ausgewählt:

          ([0-9.]+)

          Die Klammern kennzeichnen die Erfassungsgruppe für reguläre Ausdrücke, d. h. den zu extrahierenden Teil des übereinstimmenden Texts. Weitere Informationen finden Sie unter Reguläre Ausdrücke verwenden.

        • Erweitert (Histogramm-Buckets): (Optional) Durch Klicken auf Erweitert wird ein Abschnitt des Formulars geöffnet, in dem Sie benutzerdefinierte Bucket-Layouts angeben können. Wenn Sie keine Bucket-Layouts angeben, wird ein Standard-Bucket-Layout verwendet. Weitere Informationen finden Sie auf dieser Seite unter Histogramm-Buckets.
        1. Wenn Sie sehen möchten, welche Logeinträge Ihrem Filter entsprechen, klicken Sie auf Vorschau von Logs.

      6. (Optional) Fügen Sie im Abschnitt Labels ein Label hinzu. Eine Anleitung zum Erstellen von Labels finden Sie unter Label erstellen.

      7. Klicken Sie auf Messwert erstellen, um den Messwert zu erstellen.

      gcloud

      Wenn Sie eine logbasierte Messwert vom Typ „Verteilung“ erstellen möchten, erstellen Sie eine Datei, die eine Darstellung Ihrer LogMetric-Definition im JSON- oder YAML-Format enthält. Verwenden Sie dann den folgenden Befehl, um die Konfiguration aus Ihrer Datei zu lesen:

      gcloud logging metrics create METRIC_NAME --config-from-file FILENAME

      Informationen zum Beschreiben der Histogramm-Buckets für eine Verteilung finden Sie unter Histogramm-Buckets.

      API

      Verwenden Sie zum Erstellen eines Verteilungsmesswerts die Methode projects.metrics.create der Logging API. Wenn Sie den APIs Explorer-Bereich auf der Referenzseite verwenden, bereiten Sie die Argumente so vor:

      1. Geben Sie für das Feld parent das Projekt oder den Bucket an, in dem der Messwert erstellt werden soll:

        • Geben Sie für einen logbasierten Messwert mit Projektbereich das Projekt an:
        projects/PROJECT_ID
        • Geben Sie für einen logbasierten Messwert mit Bucket-Bereich den Bucket an:
        projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID

      2. Legen Sie für den Anfragetext ein LogMetric-Objekt fest. Im Folgenden sehen Sie ein Beispielobjekt für einen Verteilungsmesswert.

        {
  name:        "my-metric"
  description: "Description of my-metric."
  filter:      "resource.type=gce_instance AND log_id(\"syslog\")",
  valueExtractor: "REGEXP_EXTRACT(jsonPayload.latencyField, \"([0-9.]+)ms\")",

  labelExtractors: {
    "my-label-1":
      "REGEXP_EXTRACT(jsonPayload.someField, \"before ([[:word:]]+) after\")",
    "my-label-2":
      "EXTRACT(jsonPayload.anotherField, \"before ([0-9]+) after\")",
  },
  bucketOptions: { [SEE_BELOW] },

  metricDescriptor: {
      metricKind: DELTA,
      valueType: DISTRIBUTION,
      unit: "ms",

      labels: [
        {
          key: "my-label-1",
          valueType: STRING,
          description: "Description of string my-label-1.",
        },
        {
          key: "my-label-2",
          valueType: INT64,
          description: "Description of integer my-label-2.",
        }
      ]
  },
}

      Hinweise:

      • Für die Benennung gelten einige Einschränkungen. Weitere Informationen dazu finden Sie unter Fehlerbehebung.

      • metricDescriptor: ein MetricDescriptor-Objekt. metricKind muss DELTA sein. valueType muss DISTRIBUTION sein.

      Histogramm-Buckets

      Verteilungsmesswerte beinhalten ein Histogramm, mit dem die Anzahl der Werte gezählt wird, die in bestimmte Bereiche (Buckets) fallen. Sie können bis zu 200 Buckets in einem Verteilungsmesswert verwenden.

      Jeder Bucket hat zwei Grenzwerte, L und H, die den niedrigsten und den höchsten Wert der vom Bucket abgedeckten Werte definieren. Die Breite des Buckets ist H - L. Da es zwischen Buckets keine Lücken geben kann, ist der untere Grenzwert eines Buckets mit dem oberen Grenzwert des vorherigen Buckets identisch. Damit Grenzwerte nicht in mehr als einem Bucket enthalten sind, enthält ein Bucket seinen unteren Grenzwert, während sein oberer Grenzwert zum nächsten Bucket gehört.

      Sie können alle Bucket-Layouts angeben, indem Sie die Grenzwerte zwischen einzelnen Buckets in aufsteigender Reihenfolge auflisten. Der erste Bucket ist der Unterlauf-Bucket. Damit werden unter dem ersten Grenzwert liegende Werte gezählt. Der letzte Bucket ist der Überlauf-Bucket zum Zählen der Werte, die größer oder gleich dem letzten Grenzwert sind. Mit den anderen Buckets werden Werte gezählt, die größer oder gleich ihrer Untergrenze und kleiner als ihre Obergrenze sind. Wenn n Grenzwerte vorhanden sind, gibt es n+1 Buckets. Neben dem Unterlauf- und dem Überlauf-Bucket gibt es n-1 endliche Buckets.

      Sie können die Grenzwerte zwischen Histogramm-Buckets für Verteilungsmesswerte auf drei verschiedene Arten angeben: Sie geben entweder eine Formel für die Grenzwerte an oder listen die Grenzwerte auf:

      • Linear (offset, width, i): Jeder Bucket hat dieselbe Breite. Die Grenzwerte sind offset + width * i, wobei i = 0, 1, 2, …, N. Weitere Informationen zu linearen Buckets finden Sie in der API-Referenz.

      • Exponentiell (scale, growth_factor, i): Die Buckets werden bei höheren Werten breiter. Die Grenzwerte sind scale * growth_factori, wobei i = 0, 1, 2, …, N. Weitere Informationen zu exponentiellen Buckets finden Sie in der API-Referenz.

      • Explizit: Sie listen alle Grenzwerte für die Buckets im Array bounds auf. Der Bucket i hat diese Grenzwerte:

        Upper bound: bounds[*i*] for (0 <= *i* < *N*-1)
Lower bound: bounds[*i* - 1] for (1 <= *i* < *N*)

        Weitere Informationen zu expliziten Buckets finden Sie in der API-Referenz.

      Wie Sie Ihre Histogramm-Buckets festlegen, wird im folgenden Abschnitt erläutert.

      Console

      Das Untermenü Histogramm-Buckets wird geöffnet, wenn Sie einen Verteilungsmesswert erstellen und im Formular Messwert-Editor auf Mehr klicken. Das folgende Unterformular ist für das Bucket-Layout Linear:

      Histogramm-Buckets

      Lineare Buckets: Füllen Sie das Histogramm-Bucket-Formular so aus:

      • Typ: Linear
      • Start value (Startwert) (a): Der untere Grenzwert des ersten endlichen Buckets. Dieser Wert wird in der API als Versatz bezeichnet.
      • Number of buckets (Anzahl der Buckets) (N): Die Anzahl der endlichen Buckets. Der Wert muss größer oder gleich 0 sein.
      • Bucket width (Bucket-Breite) (b): Die Differenz zwischen der Ober- und Untergrenze jedes endlichen Buckets. Der Wert muss größer als 0 sein.

      Angenommen, der Startwert ist 5, es sind insgesamt vier Buckets vorhanden und diese haben eine Breite von 15. Dadurch ergeben sich die folgenden Bucket-Bereiche:

      (-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)

      Explizite Buckets: Füllen Sie das Histogramm-Bucket-Formular wie folgt aus:

      • Typ: Explizit
      • Grenzwerte (b): Eine durch Kommas getrennte Liste der Grenzwerte der endlichen Buckets. Damit wird auch die Anzahl der Buckets und deren Breite bestimmt.

      Beispiel: Die Liste der Grenzwerte lautet wie folgt:

      0, 1, 2, 5, 10, 20

      In diesem Fall sind fünf endliche Buckets mit folgenden Bereichen vorhanden:

      (-INF, 0), [0, 1), [1, 2), [2,5), [5, 10), [10, 20), [20, +INF)

      Exponentielle Buckets: Füllen Sie das Histogramm-Bucket-Formular so aus:

      • Type (Typ): Exponentiell

      • Number of buckets (Anzahl der Buckets) (N): Die Gesamtzahl der endlichen Buckets. Der Wert muss größer als 0 sein.

      • Linear scale (Lineare Skala) (a): Die lineare Skala für die Buckets. Der Wert muss größer als 0 sein.

      • Exponential growth factor (Faktor für exponentielles Wachstum) (b): Der Faktor für exponentielles Wachstum für die Buckets. Der Wert muss größer als 1 sein.

      Beispiel: Wenn N=4, a=3 und b=2, gelten die folgenden Bucket-Bereiche:

      (-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)

      Weitere Informationen zu den Buckets finden Sie unter BucketOptions in der Cloud Monitoring API.

      API

      Das optionale Bucket-Layout wird über das Feld bucketOptions im LogMetric-Objekt festgelegt, das für projects.metrics.create bereitgestellt wird. Das vollständige LogMetric-Objekt finden Sie auf dieser Seite unter Verteilungsmesswert erstellen. Die Zusätze für Bucket-Layouts sind unten dargestellt:

      Lineare Buckets:

      { # LogMetric object
  ...
  bucketOptions: {
    linearBuckets: {
      numFiniteBuckets: 4,
      width: 15,
      offset: 5
    }
  },
  ...
}

      Mit dem vorangegangenen Beispiel werden folgende Buckets erstellt:

      (-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)

      Explizite Buckets: Die Grenzwerte werden individuell aufgelistet.

      { # LogMetric object
  ...
  bucketOptions: {
    explicitBuckets: {
      bounds: [0, 1, 2, 5, 10, 20 ]
    }
  },
  ...
}

      Mit dem vorangegangenen Beispiel werden folgende Buckets erstellt:

      (-INF, 0), [0, 1), [1, 2), [2, 5), [5, 10), [10, 20), [20, +INF)

      Exponentielle Buckets: Die Grenzwerte sind scale * growthFactor ^ i, wobei i = 0, 1, 2, ..., numFiniteBuckets ist.

      { # LogMetric object
  ...
  bucketOptions: {
    exponentialBuckets: {
      numFiniteBuckets: 4,
      growthFactor: 2,
      scale: 3
    }
  },
  ...
}

      Mit dem vorangegangenen Beispiel werden folgende Buckets erstellt:

      (-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)

      Latenz für neue Messwerte

      Ihr neuer Messwert wird unmittelbar in der Messwertliste der Loganzeige und in den relevanten Menüs von Monitoring angezeigt. Es kann jedoch bis zu einer Minute dauern, bis für den Messwert Daten für die entsprechenden Logeinträge erhoben werden.

      Verteilungsmesswerte prüfen

      So listen Sie die benutzerdefinierten logbasierten Messwerte in Ihrem Google Cloud Projekt auf oder prüfen einen bestimmten Messwert in Ihrem Google Cloud Projekt:

      Console

      1. Rufen Sie in der Google Cloud Console die Seite Logbasierte Messwerte auf:

        Zu Logbasierte Messwerte

        Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Logging ist.

      2. Im Bereich Benutzerdefinierte Messwerte werden die benutzerdefinierten logbasierten Messwerte im aktuellen Google Cloud Projekt angezeigt:

      3. Klicken Sie in der Zeile des Messwerts auf das Menü und wählen Sie In Metrics Explorer ansehen aus, um die Daten eines logbasierten Messwerts anzuzeigen.

      gcloud

      Verwenden Sie den folgenden Befehl, um die benutzerdefinierten logbasierten Messwerte in Ihrem Google Cloud -Projekt aufzulisten:

      gcloud logging metrics list

      Verwenden Sie den folgenden Befehl, um einen benutzerdefinierten logbasierten Messwert in Ihrem Google Cloud Projekt anzuzeigen:

      gcloud logging metrics describe METRIC_NAME

      Rufen Sie mit dem folgenden Befehl die Hilfe auf:

      gcloud logging metrics --help

      Sie können die Zeitachsendaten eines Messwerts nicht aus der Google Cloud CLI auslesen.

      API

      Messwerte auflisten

      Verwenden Sie zum Auflisten der benutzerdefinierten logbasierten Messwerte in einem Google Cloud -Projekt die API-Methode projects.metrics.list. Geben Sie die Parameter der Methode so an:

      • parent: Der Ressourcenname des Google Cloud -Projekts: projects/PROJECT_ID.
      • pageSize: Die maximale Anzahl der Ergebnisse.
      • pageToken: Ruft die nächste Seite mit Ergebnissen auf. Informationen zur Verwendung von Seitentokens finden Sie unter projects.metrics.list.

      Messwertdefinitionen abrufen

      Verwenden Sie zum Abrufen eines einzelnen benutzerdefinierten logbasierten Messwerts die API-Methode projects.metrics.get. Geben Sie die Parameter der Methode so an:

      • metricName: Der Ressourcenname des Messwerts:

        projects/PROJECT_ID/metrics/METRIC_ID

      Messwertdaten lesen

      Verwenden Sie zum Lesen der Zeitachsendaten in einem logbasierten Messwert die Methode projects.timeseries.list in der Cloud Monitoring API. Weitere Informationen zu Zeitachsendaten finden Sie unter Zeitachsen lesen.

      Wenn Sie einen einzelnen benutzerdefinierten logbasierten Messwert lesen möchten, geben Sie in die Parameter der Methode diesen Messwerttyp und diese Kennung ein:

      logging.googleapis.com/user/METRIC_ID

      Verteilungsmesswerte aktualisieren

      Sie können einen benutzerdefinierten logbasierten Messwert bearbeiten, um dessen Beschreibung, Filter und die Namen der im Messwert angegebenen Felder zu ändern. Sie können dem Messwert neue Labels hinzufügen und die regulären Ausdrücke ändern, mit denen Werte für den Messwert und dessen Labels extrahiert werden. Wenn Sie einen messwertbezogenen Messwert verwenden, können Sie auch den Bucket des Messwerts aktualisieren.

      Sie können die Namen oder Typen von benutzerdefinierten logbasierten Messwerten oder deren Labels nicht ändern und vorhandene Labels in einem logbasierten Messwert nicht löschen.

      So bearbeiten Sie einen logbasierten Messwert:

      Console

      1. Rufen Sie in der Google Cloud Console die Seite Logbasierte Messwerte auf:

        Zu Logbasierte Messwerte

        Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Logging ist.

      2. Klicken Sie im Menü für den logbasierten Messwert, den Sie ändern möchten, auf Messwert bearbeiten.

      3. Ändern Sie nur die zulässigen Elemente des Messwerts.

      4. Klicken Sie auf Messwert aktualisieren.

      gcloud

      Mit der Google Cloud CLI können Sie die Beschreibung, die Filterabfrage und den Bucket eines Zählermesswerts ändern. Sie können alle oder nur einige der Felder auf einmal aktualisieren.

      gcloud logging update METRIC_NAME \
  --description="METRIC_DESCRIPTION" \
  --log-filter="FILTER" \
  --bucket-name=BUCKET_NAME

      Wenn Sie den Bucket ändern, der einem Bucket-bezogenen Messwert zugeordnet ist, spiegeln alle Messwertdaten, die vor der Änderung erhoben wurden, nicht mehr die aktuelle Konfiguration wider. Die für den vorherigen Bucket erhobenen Messwertdaten werden nicht entfernt.

      Wenn Sie Verteilungsstatistiken oder andere Zählermesswertfelder mit Ausnahme von METRIC_NAME aktualisieren möchten, erstellen Sie eine Datei, die die überarbeitete Spezifikation Ihres LogMetric im JSON- oder YAML-Format enthält. Aktualisieren Sie dann die Messwertkonfiguration, indem Sie den Befehl update mit dem Feld „--config-from-file“ aufrufen und FILENAME durch den Namen Ihrer JSON- oder YAML-Datei ersetzen:

      gcloud logging update METRIC_NAME --config-from-file FILENAME

      Rufen Sie mit folgendem Befehl weitere Details ab:

      gcloud logging metrics update --help

      API

      Verwenden Sie zum Bearbeiten eines logbasierten Messwerts in der API die Methode projects.metrics.update. Legen Sie die Felder so fest:

      • metricName: Der vollständige Ressourcenname des Messwerts:

        projects/PROJECT_ID/metrics/METRIC_ID

        Beispiel:

        projects/my-gcp-project/metrics/my-error-metric

      • Der Anfragetext muss ein LogMetric-Objekt enthalten, das abgesehen von den gewünschten Änderungen und Ergänzungen genau dem vorhandenen Messwert entspricht.

      Verteilungsmesswerte löschen

      So löschen Sie einen benutzerdefinierten logbasierten Messwert:

      Console

      1. Rufen Sie in der Google Cloud Console die Seite Logbasierte Messwerte auf:

        Zu Logbasierte Messwerte

        Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Logging ist.

      2. Wählen Sie den zu löschenden Messwert aus und klicken Sie auf Löschen.

        Alternativ können Sie im Menü des logbasierten Messwerts, den Sie löschen möchten, auf Messwert löschen klicken.

      gcloud

      Verwenden Sie den folgenden Befehl, um einen benutzerdefinierten logbasierten Messwert im aktuellen Google Cloud Projekt zu löschen:

      gcloud logging metrics delete METRIC_NAME

      Rufen Sie mit folgendem Befehl weitere Details ab:

      gcloud logging metrics delete --help

      API

      Verwenden Sie in der API die Methode projects.metrics.delete, um einen benutzerdefinierten logbasierten Messwert zu löschen.

      Außerdem finden Sie in der Google Cloud Console auf der Seite Logbasierte Messwerte im Bereich Benutzerdefinierte Messwerte weitere Features, mit denen Sie die benutzerdefinierten Messwerte in IhremGoogle Cloud -Projekt verwalten können. Weitere Informationen finden Sie unter Benutzerdefinierte Messwerte.