Labels für logbasierte Messwerte konfigurieren

In diesem Dokument werden Labels logbasierter Messwerte behandelt. Außerdem wird erläutert, wie Labels für Logmesswerte erstellt und verwendet werden.

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

Labels für logbasierte Messwerte

Durch Labels können logbasierte Messwerte mehrere Zeitreihen enthalten – eine für jede Kombination von Labelwerten. 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 (z. B., 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.

Fügen Sie dem Extrahiererausdruck keine vertraulichen Informationen hinzu und extrahieren Sie auch keine sensiblen Daten in Labels. Diese werden als Dienstdaten behandelt.

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.

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

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

Alle logbasierten Messwerte haben vordefinierte Label:

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

Beispiel: Metrics Explorer verwenden

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. Sie können logbasierten Systemmesswerten keine Label hinzufügen.

Console

1. Wenn Sie einen logbasierten Messwert erstellen, enthält der Bereich Logmesswert erstellen eine Option zum Hinzufügen eines Labels.

2. Klicken Sie auf Label hinzufügen.

   Tipp: So rufen Sie die Felder und Werte in einem Logeintrag auf:

   1. Klicken Sie im Abschnitt Filterauswahl auf Logvorschau ansehen.
   2. Wählen Sie im Bereich Logs ansehen einen Logeintrag aus und klicken Sie daneben auf Maximieren .
   3. Klicken Sie auf Verschachtelte Felder erweitern.

3. Legen Sie im Abschnitt Details folgende Felder fest:

   1. Labelname: Geben Sie einen Namen für das Label ein. 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: Wenn der Labelwert aus allen Inhalten des Feldes besteht, können Sie dieses Feld leer lassen. Geben Sie andernfalls eine Regex-Erfassungsgruppe an, die den Labelwert aus dem Feldwert extrahiert.

      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. Im folgenden Ausdruck sind die Klammern beispielsweise eine Erfassungsgruppe, die den zu extrahierenden Teil des Texts angibt:

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

      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.

5. Klicken Sie zum Erstellen des Messwerts auf Messwert erstellen.

gcloud

Zum Erstellen eines logbasierten Messwerts mit benutzerdefinierten Labels müssen Sie eine Datei erstellen, die eine Darstellung Ihrer LogMetric-Definition im JSON- oder YAML-Format enthält, einschließlich der benutzerdefinierten Labels. Erstellen Sie dann den Messwert, indem Sie den Befehl create mit dem Flag --config-from-file aufrufen und FILENAME durch den Namen Ihrer JSON- oder YAML-Datei ersetzen:

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

Weitere Informationen finden Sie unter gcloud logging metrics create.

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. Der Extrahiererausdruck kann einen der folgenden Werte haben:

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