Labels für logbasierte Messwerte konfigurieren

In diesem Dokument werden Label für logbasierte Messwerte erläutert. Weiter wird beschrieben, wie Sie Label für logbasierte Messwerte erstellen und verwenden.

Wenn Sie mit Labels vertraut sind, können Sie direkt zum Abschnitt Label erstellen auf dieser Seite gehen.

Übersicht über Labels für logbasierte Messwerte

Durch die Verwendung von Labels können logbasierte Messwerte mehrere Zeitachsen – eine pro Kombination von Labelwerten – enthalten. Alle logbasierten Messwerte haben Standardlabel.

Sie können sowohl für Zähler- als auch für Verteilungsmesswerte zusätzliche, benutzerdefinierte Labels erstellen, indem Sie Extrahiererausdrücke angeben. Ein Extrahiererausdruck teilt Cloud Logging mit, wie der Wert des Labels aus Logeinträgen extrahiert werden soll. So können Sie den Wert des Labels angeben:

• Als gesamten Inhalt eines benannten Felds im LogEntry-Objekt
• Als Teil eines benannten Felds, das mit einem regulären Ausdruck übereinstimmt

Sie können Labels aus den integrierten Feldern von LogEntry, wie httpRequest.status, oder aus einem der Nutzlastfelder textPayload, jsonPayload oder protoPayload extrahieren. Die ID einer Fehlergruppe kann jedoch nicht aus dem Feld errorGroups extrahiert werden.

Weitere Informationen zu regulären Ausdrücken finden Sie auf der Seite zur RE2-Syntax.

Geben Sie keine vertraulichen Informationen in den Extraktorausdruck ein und extrahieren Sie keine vertraulichen Daten in Labels. Diese werden als Dienstdaten behandelt.

Beschränkungen von benutzerdefinierten Labels

Für benutzerdefinierte Labels gelten folgende Beschränkungen:

• Sie können pro Messwert bis zu 10 benutzerdefinierte Labels erstellen.

• Nachdem Sie ein Label erstellt haben, können Sie es nicht mehr löschen.

  • Sie können den Extrahiererausdruck und die Beschreibung eines bereits erstellten Labels ändern.

  • Sie können den Namen oder Werttyp eines bereits erstellten Labels nicht ändern.

• Nur die ersten 1.024 Zeichen eines Labelwerts werden beibehalten.

• Jeder logbasierte Messwert ist auf etwa 30.000 aktive Zeitachsen beschränkt, die von der Anzahl der möglichen Werte für jedes Label, einschließlich der Standardlabels, abhängen.

  Wenn Ihre Logeinträge beispielsweise aus 100 Ressourcen (z. B. VM-Instanzen) stammen und Sie eine Bezeichnung mit 20 möglichen Werten definieren, können Sie für Ihren Messwert bis zu 2.000 Zeitachsen verwenden.

Wenn Sie zu viele Zeitachsen oder zu viele Datenpunkte haben, steigen Ihre Kosten und Ihre Aktivitäten könnten behindert werden. Weitere Informationen zu den Kosten logbasierter Messwerte finden Sie unter Cloud Monitoring-Preise: Kostenpflichtige Messwerte. Informationen zu den Limits für logbasierte Messwerte finden Sie unter Kontingente und Limits: Logbasierte Messwerte und Fehlerbehebung bei logbasierten Messwerten.

Standardlabels

Die meisten logbasierten Messwerte haben vordefinierte Labels:

• Ressourcenlabel: Bei allen Messwerten wird ein überwachtes Ressourcenobjekt verwendet, um die Quelle von Zeitachsendaten zu identifizieren. Jeder Ressourcentyp enthält einen Typnamen und ein oder mehrere Label. Beispiele für Ressourcentypen sind VM-Instanzen, Cloud SQL-Datenbanken und Load-Balancer.

  Die Ressource und ihre Labels werden in Cloud Monitoring von anderen Messwertlabels getrennt aufgelistet. Sie dienen jedoch alle dem Zweck, zusätzliche Zeitachsen im Messwert zu erstellen. Weitere Informationen finden Sie unter Messwerte, Zeitachsen und Ressourcen.

• log: Dieses Label enthält den LOG_ID-Anteil des Felds logName in den Logeinträgen.

• severity: Dieses Label enthält den Wert des Felds severity in Logeinträgen. Der Schweregrad wird standardmäßig nur in logbasierten Systemmesswerten bereitgestellt.

Labels mit dem Metrics Explorer ansehen

So rufen Sie die Labels für eine Zeitreihe auf, die für einen logbasierten Messwert generiert wurde:

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. Suchen Sie den Messwert, den Sie anzeigen möchten, und wählen Sie im more_vert-Menü Mehr die Option Im Metrics Explorer ansehen aus.

   Warten Sie, bis im Diagramm Daten angezeigt werden. Das kann einige Minuten dauern, wenn Sie eine logbasierte Messwert erstellt haben.

3. Maximieren Sie das Feld Filter, um die verfügbaren Labels aufzurufen. Möglicherweise werden Ressourcen- und Messwertlabels angezeigt. Die Liste der Labels ist spezifisch für den Ressourcentyp und den Messwerttyp. Beispiel:

   • Der Ressourcentyp gce_instance hat drei Ressourcenlabels: project_id, instance_id und zone.

   • Der Messwerttyp logging/log_entry_count hat zwei Messwertlabels: log und severity. Ihre benutzerdefinierten Labels werden ebenfalls in diesem Abschnitt angezeigt.

4. So prüfen Sie, ob ein benutzerdefiniertes Label die richtigen Daten aus Ihren Logeinträgen extrahiert:

   1. Ändern Sie das Element Aggregation in Nicht aggregiert.

   2. Wählen Sie im Diagramm entweder Tabelle oder Beides aus.

   3. Wählen Sie in der Symbolleiste view_column Menü für die Spaltendarstellung und dann die gewünschten Labels aus. In diesem Menü werden alle Labels angezeigt, für die Daten vorhanden sind.

      Wenn Sie ein erstelltes Label nicht sehen, prüfen Sie den Feldnamen und den Extraktorausdruck.

Label erstellen

Benutzerdefinierte Labels werden zusammen mit dem Messwert erstellt. Sowohl Zählermesswerte als auch Verteilungsmesswerte können Labels haben. Sie können logbasierten Systemmesswerten keine Label hinzufügen.

Um ein Label zu erstellen, geben Sie das Feld im Logeintrag an und definieren dann einen Ausdruck, mit dem ein Wert aus dem angegebenen Feld extrahiert wird.

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

{
  ...
  metricDescriptor: {
      labels: [
        { key: LABEL_NAME, valueType: LABEL_TYPE,
          description: LABEL_DESCRIPTION },
        ...
      ]
  },
  labelExtractors: {
    LABEL_NAME: EXTRACTOR_EXPRESSION,
    ...
  },
}

{
  ...
  metricDescriptor: {
      labels: [
        { key: "label_name_a", valueType: STRING },
        { key: "label_name_b", valueType: INT64 },
      ]
  },
  labelExtractors: {
    "label_name_a":
      "REGEXP_EXTRACT(jsonPayload.field_a, \"before ([a-zA-Z ]+) after\")",
    "label_name_b": "EXTRACT(jsonPayload.field_b)",
  },
}

Beispiele

In diesem Abschnitt finden Sie einige Beispiele, die Ihnen den Einstieg in die Erstellung von Labels für Ihre benutzerdefinierten logbasierten Messwerte erleichtern sollen. Nachdem Sie ein Label erstellt haben, empfehlen wir, es mit dem Metrics Explorer zu überprüfen.

Tipps:

• Wenn Sie einen Extraktor-Ausdruck angeben, müssen Sie eine Erfassungsgruppe verwenden.
• Wenn Sie keinen Extraktor-Ausdruck angeben, wird der gesamte Wert des Felds extrahiert.

• Achten Sie darauf, dass die Menge der möglichen Werte für ein Label eingeschränkt ist. Ein kleiner Satz diskreter Werte (z. B. „Rot“, „Grün“ und „Blau“) wird bevorzugt. Wenn Sie beispielsweise die 8‑Bit-RGB-Werte für ein Farblabel extrahieren, können Sie über 16 Millionen verschiedene Werte erhalten. Das bedeutet, dass Sie über 16 Millionen Zeitreihen haben könnten.

  Extrahieren Sie keine Werte mit hoher Auflösung wie Zeitstempel, eindeutige Kennungen, Nutzer-IDs, IP-Adressen, nicht parametrisierte URLs usw.

Statuscode aus einem Audit-Log extrahieren

Wenn ein Feld keine Sonderzeichen enthält, können Sie den Feldnamen im Label für den logbasierten Messwert verwenden.

Bei Audit-Logs entspricht das Feld protoPayload beispielsweise der Struktur AuditLog. Wenn Sie das Feld status aus einem Audit-Log extrahieren möchten, können Sie den Feldnamen auf protoPayload.status.code festlegen und den Extraktor-Ausdruck leer lassen.

Wenn Sie nur die erste Ziffer des Fehlercodes extrahieren möchten, können Sie den Extraktorausdruck auf (\d)\d\d festlegen.

Werte aus einem Feld mit Sonderzeichen extrahieren

Wenn ein Feld in einem Logeintrag Sonderzeichen enthält, muss es in doppelte Anführungszeichen gesetzt werden.

Wenn Sie beispielsweise den gesamten Wert des Labels k8s-pod/k8s-app extrahieren möchten, legen Sie den Feldnamen auf labels."k8s-pod/k8s-app" fest und lassen Sie den Ausdruck leer.

Wert aus einem Text-Payload extrahieren

Betrachten Sie einen Logeintrag mit dem folgenden Format:

textPayload: "unfinished_task_instance_count.py:61 Unfinished task instance count metric value 0 for state: deferred"

Um den Wert für den Status, z. B. deferred, aus Logeinträgen mit dem vorherigen Format zu extrahieren, können Sie Folgendes tun:

• Feldname: textPayload
• Ausdruck für Extraktor: ^unfinished.*state: ([a-z]+)

Wert aus einem wiederholten Feld extrahieren

Ein Logeintrag kann ein Feld mit wiederholten Feldern enthalten. In JSON werden diese Felder mit eckigen Klammern ([]) dargestellt. Aus Sicht der Labels werden die wiederholten Felder als Gruppe und der Label-Extractor als Iterator betrachtet. Sie geben die Kriterien für die Übereinstimmung an, wenn Sie das Label definieren. Der Extraktor durchläuft die Menge, bis eine Übereinstimmung gefunden wird. Die erste Übereinstimmung wird immer zurückgegeben, auch wenn mehrere Elemente der Gruppe den Kriterien entsprechen.

Sie möchten einen logbasierten Messwert erstellen, der Audit-Logs zählt. Bevor Sie Ihr Label konfigurieren, sehen Sie sich mehrere Audit-Logs an und stellen fest, dass das Format von protoPayload der Struktur AuditLog entspricht. Das folgende Beispiel zeigt einen Ausschnitt eines Audit-Logeintrags.

{
  ...
  protoPayload: {
    @type: "type.googleapis.com/google.cloud.audit.AuditLog"
    authenticationInfo: {1}
    authorizationInfo: [
      0: {
        granted: true
        permission: "io.k8s.coordination.v1.leases.get"
        resource: "coordination.k8s.io/v1/namespaces/kube-system/leases/maintenance-controller"
      }
    ]
    requestMetadata: {2}
    status: {1}
    ...
  }
  ...
}

Sie möchten ein Label für Ihren logbasierten Messwert erstellen, in dem Informationen aus dem Feld permission gespeichert werden. Sie sehen, dass diese Felder wie io.k8s.xyz formatiert sind, wobei xyz ein String ist, der weitere Details zur Anfrage enthält. Dieser String kann einen Wert wie get oder eine komplexere Formatierung wie io.k8s.coordination.v1.leases.get haben.

Um die Anzahl der Labelwerte zu minimieren, sollten Sie keine detaillierten Informationen extrahieren. Sie möchten nur Werte wie get oder coordination im Label speichern. Außerdem möchten Sie das gemeinsame Präfix io.k8s. nicht in den Labelwert aufnehmen.

Als Nächstes konfigurieren Sie das Label. Da das Feld permission ein wiederholtes Feld ist und das übergeordnete Feld authorizationInfo ist, legen Sie den Feldnamen so fest:

protoPayload.authorizationInfo.permission

Schließlich erstellen Sie den folgenden regulären Ausdruck:

io.k8s.([a-z]+).*