Labels von logbasierten Messwerten

Auf dieser Seite werden Standardlabels für logbasierte Messwerte erläutert und es wird beschrieben, wie Sie Labels für logbasierte Messwerte erstellen und verwenden.

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

Überblick

Durch die Verwendung von Labels können logbasierte Messwerte mehrere Zeitachsen – eine für jeden Labelwert – enthalten. Alle logbasierten Messwerte haben Standardlabels.

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.

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

Hinweis: Erstellen Sie Labels nur, wenn Sie Werte für die Kategorisierung oder Zusammenfassung Ihrer Messwertdaten ermitteln müssen. Verwenden Sie Labels nicht, um Datenfelder zu benennen.

Beschränkungen von benutzerdefinierten Labels

Für benutzerdefinierte Labels gelten folgende Beschränkungen:

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

• Ein Label kann nicht gelöscht werden, nachdem es erstellt wurde.

  • 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.

Achtung: Extrahieren Sie niemals einen Labelwert, der für jeden Logeintrag eindeutig ist, z. B. die vollständigen Felder insertId oder timestamp. Ansonsten erhalten Sie ebenso viele Zeitachsen wie Logeinträge, die jeweils einen Punkt enthalten.

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 erhalten Sie unter Cloud Logging-Preise. Informationen zu messwertbezogenen Kontingenten und Limits finden Sie unter Kontingente und Limits und Fehlerbehebung.

Standardlabels

Alle logbasierten Messwerte, einschließlich logbasierter Systemmesswerte, enthalten einige vordefinierte Labels:

• Ressourcenlabels: 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 Labels. 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.

  Hinweis: Das Label severity haben standardmäßig nur logbasierte Systemmesswerte.

Beispiel

Im folgenden Screenshot des Messwert-Explorers sind die Labels für einen der logbasierten Systemmesswerte zu sehen. Klicken Sie im Textfeld Filter, um die Labelliste aufzurufen:

Der Screenshot zeigt folgende Informationen:

• Der Metrics Explorer verwendet Zeitachsen aus dem Messwert logging/log_entry_count und dem Ressourcentyp gce_instance (Compute Engine-VM-Instanzen).

  Dieser Messwert enthält auch Zeitachsen anderer Ressourcentypen. Im Metrics Explorer wird jedoch immer nur ein Ressourcentyp eingeblendet.

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

• Der Messwert hat zwei Messwertlabels: log und severity. Ihre benutzerdefinierten Labels werden ebenfalls in diesem Abschnitt angezeigt.

Label erstellen

Benutzerdefinierte Labels werden zusammen mit dem Messwert erstellt. Sowohl Zählermesswerte als auch Verteilungsmesswerte können Labels haben. Logbasierten Systemmesswerten können keine Labels hinzugefügt werden.

Console

1. Beim Erstellen eines logbasierten Messwerts wird im Feld Messwerteditor eine Option zum Einfügen von Labels angezeigt:

   

2. Klicken Sie auf Add item (Zeile hinzufügen). Sie sehen das folgende Formular zur Beschreibung Ihres Labels. Dieses hier ist bereits ausgefüllt:

   

   Tipp: Wählen Sie einen Logeintrag aus, klicken Sie daneben auf das Erweiterungssymbol und wählen Sie anschließend Alle einblenden aus, um alle Felder und Werte in Ihren Logeinträgen anzusehen.

3. Füllen Sie im Formular Label die folgenden Felder aus:

   1. Name: Wählen Sie einen Namen für das Label aus. Beispiel: ID
      

      Der Name muss folgende Kriterien erfüllen:

      • Nicht länger als 100 Zeichen sein
      • Dem regulären Ausdruck [a-zA-Z][a-zA-Z0-9_]* entsprechen
      • Aus mehr als nur dem String "log" bestehen

   2. Beschreibung: Geben Sie eine Beschreibung des Labels ein. Seien Sie so genau wie möglich, was das Format erwarteter Logwerte angeht. Beispiel: Instance number

   3. Label type (Labeltyp): Wählen Sie String, Boolesch oder Ganzzahl aus.

   4. Feldname: Geben Sie den Namen des Feldes für den Logeintrag ein, das den Labelwert enthält. Bei der Eingabe werden Optionen zur Auswahl angezeigt. Das Feld ist in diesem Beispiel:

      labels."compute.googleapis.com/resource_id"
      

   5. Regulärer Ausdruck zur Extraktion: Wenn der Labelwert aus dem gesamten Inhalt des Felds besteht, können Sie dieses Feld leer lassen. Geben Sie andernfalls einen regulären Ausdruck (RegExp) ein, um den Labelwert aus dem Feldwert zu extrahieren. Angenommen, das Feld enthält in der Regel folgenden Text:

      The instance number is 0123456789; the ID is my-test-instance22
      

      Wenn der Labelwert die Instanznummer sein soll, können Sie zum Extrahieren der richtigen Nummer verschiedene reguläre Ausdrücke verwenden. Hier ein Beispiel:

      The instance number is ([0-9]+); .*
      

      Die Klammern kennzeichnen die Erfassungsgruppe für reguläre Ausdrücke, d. h. den zu extrahierenden Teil des übereinstimmenden Texts. Weitere Informationen zu regulären Ausdrücken finden Sie auf der Seite zur RE2-Syntax.

4. Klicken Sie auf Fertig, um das Label zu erstellen. Wiederholen Sie diese Schritte, um weitere Labels hinzuzufügen.

Logging API

Labels werden als Teil des LogMetric-Objekts im Anfragetext von Aufrufen der Methode projects.metrics.create der Logging API angegeben. Informationen zu den vollständigen Aufrufen von Methoden finden Sie unter Zählermesswerte erstellen oder Verteilungsmesswerte erstellen.

Für jedes Label müssen Sie in LogMetric ein Segment zu den Feldern metricDescriptor und labelExtractors hinzufügen.

Die Syntax lautet so:

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

Die Syntaxelemente haben folgende Bedeutung:

• [LABEL_NAME]: Der Labelname als String
• [VALUE_TYPE]: Der Typ des Labels: STRING, BOOL oder INT64
• [LABEL_DESCRIPTION]: Eine Beschreibung des Labels

• [EXTRACTOR_EXPRESSION]: Ein String, mit dem der Name des Felds für den Logeintrag mit einem optionalen regulären Ausdruck kombiniert wird. Beispiele:

  EXTRACT([FIELD])
  REGEXP_EXTRACT([FIELD], [REGEXP])
  

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

Im folgenden Beispiel werden zwei Labels verwendet:

{
  ...
  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)",
  },
}

Weitere Informationen finden Sie auf der Seite zum LogMetric-Typ.

gcloud

Eine Anleitung zum Erstellen eines logbasierten Messwerts mit Labels mithilfe des gcloud-Befehlszeilentools finden Sie unter gcloud beta logging metrics create.