Verteilungsmesswerte erstellen

Auf dieser Seite wird erläutert, wie Sie mit der Cloud Console, der Logging API und dem Cloud SDK (Befehl gcloud logging) logbasierte Verteilungsmesswerte erstellen.

Eine Übersicht über logbasierte Messwerte finden Sie unter Übersicht über logbasierte Messwerte.

Übersicht

Für Verteilungsmesswerte sind sowohl eine Abfrage zum Auswählen der relevanten Logeinträge als auch ein Wertextrahierer zum Abrufen des numerischen Werts für die Verteilung erforderlich. 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.

Verteilungsmesswert erstellen

Für das Filtern nach den Logeinträgen, deren Anzahl Sie mit Ihrem Messwert ermitteln möchten, können Sie reguläre Ausdrücke verwenden.

Console

Führen Sie die folgenden Schritte aus, um in der Cloud Console einen logbasierten Messwert zu erstellen:

  1. Klicken Sie in der Cloud Console in der linken Navigationsliste auf Logging > Logbasierte Messwerte der Operations-Suite von Google Cloud oder klicken Sie auf die folgende Schaltfläche:

    Zur Legacy-Loganzeige

  2. Wählen Sie oben auf der Seite im Drop-down-Menü das gewünschte Projekt aus.

  3. Klicken Sie oben auf der Seite auf Messwert erstellen. Rechts auf der Seite sehen Sie den Metric Editor (Messwerteditor). Links im Anzeigebereich sind Ihre Logs aufgeführt:

    Verteilungsmesswerte erstellen

  4. Erstellen Sie im Anzeigebereich eine Abfrage, durch die nur jene Logeinträge angezeigt werden, die Sie im Messwert berücksichtigen möchten.

    Die einfache Abfrage ist in den Drop-down-Menüs über den Logeinträgen verfügbar. Sie können auch auf die erweiterte Abfrageoberfläche zugreifen, wenn Sie auf das Drop-down-Menü rechts in der Suchleiste klicken und In erweiterten Filter umwandeln auswählen.

    Weitere Informationen finden Sie im Abschnitt zu den Benutzeroberflächen.

  5. Legen Sie im Messwerteditor Werte für die folgenden Felder fest:

    • Name: Verwenden Sie einen neuen Messwertnamen, der unter den logbasierten Messwerten Ihres Projekts noch nicht vorhanden ist. Für die Benennung gelten einige Einschränkungen. Weitere Informationen dazu finden Sie unter Fehlerbehebung.
    • Beschreibung: Beschreiben Sie den Messwert.
    • Labels: (optional) Klicken Sie zum Hinzufügen von Labels auf Element hinzufügen. Weitere Informationen zum Definieren von Labels finden Sie unter Labels von logbasierten Messwerten.
    • Units (Einheiten): (optional) Für Verteilungsmesswerte können Sie optional Einheiten wie s, ms usw. eingeben. Weitere Informationen finden Sie beim Feld unit der Ressource MetricDescriptor.
    • Typ: Verteilung
    • Feldname: Geben Sie das Feld des Logeintrags ein, das den Wert der Verteilung enthält. Bei der Eingabe werden Optionen zur Auswahl angezeigt. Beispiel:

      jsonPayload.latency
      
    • Extraction regular expression (Regulärer Ausdruck zur Extraktion): (optional) Wenn Field name (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. Sie können den regulären Ausdruck über das Menü Build (Entwickeln) interaktiv erstellen und prüfen.

      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.]+)ms
      

      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.

    • Mehr (Histogramm-Buckets): (optional) Durch Klicken auf Mehr 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.

  6. Klicken Sie auf Messwert erstellen.

Logging API

Verwenden Sie zum Erstellen eines Verteilungsmesswerts die Methode projects.metrics.create der Logging API. Sie können die Methode in [APIs Explorer][apis-explorer-create] ausprobieren. Bereiten Sie die Argumente für die Methode so vor:

  1. Geben Sie im Feld parent das Projekt an, in dem der Messwert erstellt werden soll:

    projects/[PROJECT_ID]
    
  2. Legen Sie für den Anfragetext ein LogMetric-Objekt fest. Im folgenden Beispiel wird das Objekt für einen Verteilungsmesswert festgelegt:

    {
      name:        "my-metric"
      description: "Description of my-metric."
      filter:      "resource.type=gce_instance AND logName:\"logs/syslog\"",
      valueExtractor: "REGEX_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 zu Verteilungsmesswerten:

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

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

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_factor ^ i, 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:

    Obere Grenze: bounds[i], wobei (0 <= i < N-1)
    Untere Grenze: bounds[i - 1], wobei (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. Nachfolgend sehen Sie das Unterformular für das Layout eines Buckets vom Typ 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 wie folgt 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.

Logging API

Das optionale Bucket-Layout wird über das Feld bucketOptions 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 erscheint unmittelbar in der Messwertliste der Legacy-Loganzeige und in den relevanten Monitoring-Menüs. Es kann jedoch bis zu eine Minute dauern, bis für den Messwert Daten für die entsprechenden Logeinträge erhoben werden.

Verteilungsmesswerte untersuchen

Gehen Sie wie folgt vor, damit die logbasierten Messwerte Ihres GCP-Projekts aufgeführt werden oder um einen bestimmten Messwert Ihres Projekts zu überprüfen:

Logging-Konsole

Rufen Sie die Seite Logbasierte Messwerte auf. Dort sind alle logbasierten Messwerte des aktuellen Projekts aufgeführt. Klicken Sie hierfür auf folgende Schaltfläche:

Zu "Logbasierte Messwerte"

Wählen Sie im Menü rechts neben dem Messwert die Option In Messwert-Explorer anzeigen aus, um die Daten eines logbasierten Messwerts anzuzeigen.

Logging API

Messwerte auflisten

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

  • parent: Ressourcenname des Projekts: projects/[PROJECT_ID].
  • pageSize: Die maximale Anzahl der Ergebnisse.
  • pageToken: Ruft die nächste Seite mit Ergebnissen auf. Siehe 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 finden Sie unter Messwertdaten lesen. Hier finden Sie die für logbasierte Messwerte erforderlichen Angaben:

  • Der Messwerttyp ist logging.googleapis.com/user/[METRIC_ID].

Cloud SDK

Verwenden Sie den folgenden Befehl, um die benutzerdefinierten logbasierten Messwerte aus Ihrem Projekt aufzulisten:

gcloud logging metrics list

Verwenden Sie den folgenden Befehl, um einen benutzerdefinierten logbasierten Messwert aus Ihrem Projekt anzuzeigen:

gcloud logging metrics describe [METRIC_NAME]

Rufen Sie mit folgendem Befehl weitere Details ab:

gcloud logging metrics --help

Die Zeitachsendaten eines Messwerts können Sie nicht aus dem Cloud SDK auslesen.

Verteilungsmesswerte aktualisieren

Sie können einen logbasierten Messwert aktualisieren, um die Beschreibung, Abfragen und die Namen von im Messwert angegebenen Feldern 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 seine Labels extrahiert werden.

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

Gehen Sie zur Bearbeitung oder Aktualisierung eines logbasierten Messwerts wie folgt vor:

Logging-Konsole

  1. Rufen Sie die Seite Logbasierte Messwerte auf:

    Zu "Logbasierte Messwerte"

  2. Klicken Sie im Menü rechts neben dem zu bearbeitenden logbasierten Messwert auf Messwert bearbeiten.

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

  4. Klicken Sie auf Fertig.

Logging API

Verwenden Sie zum Bearbeiten oder Aktualisieren 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.

Cloud SDK

Mit dem Cloud SDK können Sie nur die Beschreibung und die Abfrage für einen vorhandenen Messwert ändern.

Verwenden Sie folgenden Befehl, um einen logbasierten Messwert zu aktualisieren. Sie können ein oder beide Flags angeben:

gcloud logging metrics update [METRIC_NAME] --description=[DESCRIPTION] --log-filter=[FILTER]

Rufen Sie mit folgendem Befehl weitere Details ab:

gcloud logging metrics update --help

Verteilungsmesswerte löschen

Gehen Sie wie folgt vor, um einen logbasierten Messwert zu löschen:

Logging-Konsole

  1. Rufen Sie die Seite Logbasierte Messwerte auf:

    Zu "Logbasierte Messwerte"

  2. Wählen Sie die zu löschenden Messwerte aus und klicken Sie oben auf der Seite auf Löschen.

    Alternativ können Sie im Menü rechts neben dem zu löschenden logbasierten Messwert auf Messwert löschen klicken.

Logging API

Verwenden Sie in der API die Methode projects.metrics.delete.

Cloud SDK

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

gcloud logging metrics delete [METRIC_NAME]

Rufen Sie mit folgendem Befehl weitere Details ab:

gcloud logging metrics delete --help