Benutzerdefinierte Indexierung konfigurieren

In diesem Dokument wird beschrieben, wie Sie Ihren Cloud Logging-Buckets indexierte LogEntry-Felder hinzufügen, um die Abfrage von Logdaten zu beschleunigen.

Überblick

Die Abfrageleistung ist für jede Logging-Lösung von entscheidender Bedeutung. Wenn Arbeitslasten skaliert werden und die entsprechenden Logvolumen zunehmen, kann die Indexierung der am häufigsten verwendeten Logdaten die Abfragezeit verkürzen.

Zur Verbesserung der Abfrageleistung indexiert Logging automatisch die folgenden LogEntry-Felder:

Neben den Feldern, die Logging automatisch indexiert, können Sie einen Log-Bucket auch anweisen, andere LogEntry-Felder zu indexieren. Dazu erstellen Sie einen benutzerdefinierten Index für den Bucket.

Angenommen, Ihre Abfrageausdrücke enthalten oft das Feld jsonPayload.request.status. Sie können einen benutzerdefinierten Index für einen Bucket konfigurieren, der jsonPayload.request.status enthält. Jede nachfolgende Abfrage der Daten dieses Buckets würde auf die indexierten jsonPayload.request.status-Daten verweisen, wenn der Abfrageausdruck dieses Feld enthält.

Mit der Google Cloud CLI oder der Logging API können Sie vorhandenen oder neuen Log-Buckets benutzerdefinierte Indexe hinzufügen. Beachten Sie die folgenden Einschränkungen, wenn Sie zusätzliche Felder auswählen, die in den benutzerdefinierten Index aufgenommen werden sollen:

  • Sie können bis zu 20 Felder pro benutzerdefiniertem Index hinzufügen.
  • Nachdem Sie den benutzerdefinierten Index eines Buckets konfiguriert oder aktualisiert haben, müssen Sie eine Stunde warten, bis die Änderungen für Ihre Abfragen übernommen wurden. Diese Latenz gewährleistet die Richtigkeit der Abfrageergebnisse und akzeptiert Logs, die in der Vergangenheit geschrieben wurden.
  • Logging wendet die benutzerdefinierte Indexierung auf Daten an, die in Log-Buckets gespeichert werden, nachdem der Index erstellt oder geändert wurde. Änderungen an benutzerdefinierten Indexen gelten nicht rückwirkend für Logs.

Hinweise

Führen Sie die folgenden Schritte aus, bevor Sie mit der Konfiguration eines benutzerdefinierten Index beginnen:

Benutzerdefinierten Index definieren

Für jedes Feld, das Sie dem benutzerdefinierten Index eines Buckets hinzufügen, definieren Sie zwei Attribute: einen Feldpfad und einen Feldtyp:

  • fieldPath: Beschreibt den spezifischen Pfad zum Feld LogEntry in Ihren Logeinträgen. Beispiel: jsonPayload.req_status
  • type: Gibt an, ob das Feld vom Typ „String“ oder „Ganzzahl“ ist. Mögliche Werte sind INDEX_TYPE_STRING und INDEX_TYPE_INTEGER.

Sie können einen benutzerdefinierten Index hinzufügen, indem Sie entweder einen neuen Bucket erstellen oder einen vorhandenen Bucket aktualisieren. Weitere Informationen zum Konfigurieren von Buckets finden Sie unter Log-Buckets konfigurieren.

So konfigurieren Sie einen benutzerdefinierten Index beim Erstellen eines Buckets:

gcloud

Verwenden Sie den Befehl gcloud logging buckets create und legen Sie das Flag --index fest:

gcloud logging buckets create BUCKET_NAME\
--location=LOCATION\
--description="DESCRIPTION" \
--index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

Beispielbefehl:

gcloud logging buckets create int_index_test_bucket \
--location=global \
--description="Bucket with integer index" \
--index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

Verwenden Sie zum Erstellen eines Buckets projects.locations.buckets.create in der Logging API. Bereiten Sie die Argumente für die Methode so vor:

  1. Legen Sie den Parameter parent auf die Ressource fest, in der der Bucket erstellt werden soll: projects/PROJECT_ID/locations/LOCATION

    Die Variable LOCATION bezieht sich auf die Region, in der Ihre Logs gespeichert werden sollen.

    Wenn Sie beispielsweise einen Bucket für das Projekt my-project in der Region asia-east2 erstellen möchten, sieht der Parameter parent so aus: projects/my-project/locations/asia-east2

  2. Legen Sie den Parameter bucketId fest, z. B. my-bucket.

  3. Konfigurieren Sie im LogBucket-Anfragetext das Objekt IndexConfig, um den benutzerdefinierten Index zu erstellen.

  4. Rufen Sie projects.locations.buckets.create auf, um den Bucket zu erstellen.

So aktualisieren Sie einen vorhandenen Bucket mit einem benutzerdefinierten Index:

gcloud

Verwenden Sie den Befehl gcloud logging buckets update und legen Sie das Flag --add-index fest:

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--add-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

Beispielbefehl:

gcloud logging buckets update \
int_index_test_bucket \
--location=global \ --add-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

Verwenden Sie projects.locations.buckets.patch in der Logging API. Konfigurieren Sie im LogBucket-Anfragetext das Objekt IndexConfig so, dass es die LogEntry enthält, die Sie indexieren möchten.

Benutzerdefiniertes indexiertes Feld löschen

So löschen Sie ein Feld aus dem benutzerdefinierten Index eines Buckets:

gcloud

Verwenden Sie den Befehl gcloud logging buckets update und legen Sie das Flag --remove-indexes fest :

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--remove-indexes=INDEX_FIELD_NAME

Beispielbefehl:

gcloud logging buckets update int_index_test_bucket \
--location=global \
--remove-indexes=jsonPayload.req_status

API

Verwenden Sie projects.locations.buckets.patch in der Logging API. Entfernen Sie im LogBucket die Felder von LogEntry aus dem Objekt IndexConfig.

Datentyp des benutzerdefinierten indexierten Felds aktualisieren

Wenn Sie den Datentyp eines benutzerdefinierten indexierten Felds korrigieren müssen, gehen Sie so vor:

gcloud

Verwenden Sie den Befehl gcloud logging buckets update und legen Sie das Flag --update-index fest:

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--update-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

Beispielbefehl:

gcloud logging buckets update \
int_index_test_bucket \
--location=global \
--update-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

Verwenden Sie projects.locations.buckets.patch in der Logging API. Aktualisieren Sie im LogBucket-Anfragetext das Objekt IndexConfig, um den richtigen Datentyp für das LogEntry-Feld anzugeben.

Pfad eines benutzerdefinierten indexierten Felds aktualisieren

Wenn Sie den Feldpfad eines benutzerdefinierten indexierten Felds korrigieren müssen, gehen Sie so vor:

gcloud

Verwenden Sie den Befehl gcloud logging buckets update und legen Sie die Flags --remove-indexes und --update-index fest:

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--remove-indexes=OLD_INDEX_FIELD_NAME \
--update-index=fieldPath=NEW_INDEX_FIELD_NAME,type=INDEX_TYPE

Beispielbefehl:

gcloud logging buckets update \
int_index_test_bucket \
--location=global \
--remove-indexes=jsonPayload.req_status_old_path \
--add-index=fieldPath=jsonPayload.req_status_new_path,type=INDEX_TYPE_INTEGER

API

Verwenden Sie projects.locations.buckets.patch in der Logging API. Aktualisieren Sie im LogBucket-Anfragetext das Objekt IndexConfig, um den richtigen Feldpfad für ein LogEntry-Feld anzugeben.

Alle indexierten Felder für einen Bucket auflisten

So listen Sie die Details eines Buckets einschließlich seiner benutzerdefinierten indexierten Felder auf:

gcloud

Führen Sie den Befehl gcloud logging buckets describe aus:

gcloud logging buckets describe BUCKET_NAME\
--location=LOCATION

Beispielbefehl:

gcloud logging buckets describe indexed-bucket \
--location global

API

Verwenden Sie projects.locations.buckets.get in der Logging API.

Benutzerdefinierte indexierte Felder löschen

So entfernen Sie alle benutzerdefinierten indexierten Felder aus einem Bucket:

gcloud

Verwenden Sie den Befehl gcloud logging buckets update und fügen Sie das Flag --clear-indexes hinzu:

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--clear-indexes

Beispielbefehl:

gcloud logging buckets update \
int_index_test_bucket \
--location=global \
--clear-indexes

API

Verwenden Sie projects.locations.buckets.patch in der Logging API. Löschen Sie im LogBucket-Anfragetext das Objekt IndexConfig.

Indexierte Daten abfragen und aufrufen

Zum Abfragen der Daten in benutzerdefinierten indexierten Feldern beschränken Sie den Abfragebereich auf den Bucket, der die benutzerdefinierten indexierten Felder enthält, und geben Sie die entsprechende Logansicht an:

gcloud

Wenn Sie Logs aus einem Log-Bucket lesen möchten, verwenden Sie den Befehl gcloud logging read und fügen Sie einen LOG_FILTER hinzu, um die indexierten Daten einzubeziehen:

gcloud logging read LOG_FILTER --bucket=BUCKET_ID --location=LOCATION --view=VIEW_ID

API

Verwenden Sie die Methode entries.list, um Logs aus einem Log-Bucket zu lesen. Legen Sie resourceNames fest, um den entsprechenden Bucket und die Logansicht anzugeben, und legen Sie filter fest, um die indexierten Daten auszuwählen.

Ausführliche Informationen zur Filtersyntax finden Sie unter Logging-Abfragesprache.

Indexierung und Feldtypen

Die Konfiguration der Indexierung benutzerdefinierter Felder kann sich darauf auswirken, wie Logs in Log-Buckets gespeichert und Abfragen verarbeitet werden.

Zum Zeitpunkt des Schreibens

Logging versucht, den benutzerdefinierten Index für Daten zu verwenden, die in Log-Buckets gespeichert sind, nachdem der Index erstellt wurde.

Indexierte Felder werden typisiert, was Auswirkungen auf den Zeitstempel im Logeintrag hat. Wenn der Logeintrag im Log-Bucket gespeichert ist, wird das Logfeld anhand der folgenden Regeln anhand des Indextyps ausgewertet:

  • Wenn der Typ eines Felds mit dem des Index übereinstimmt, werden die Daten wortgetreu dem Index hinzugefügt.
  • Wenn sich der Typ des Felds vom Indextyp unterscheidet, wird in Logging versucht, das Feld in den Indextyp (z. B. Ganzzahl in String) umzuwandeln.
    • Wenn die Typerzwingung fehlschlägt, werden die Daten nicht indexiert. Wenn der Typerzwingung erfolgreich ist, werden die Daten indexiert.

Zum Zeitpunkt der Abfrage

Wenn Sie einen Index für ein Feld aktivieren, ändert sich, wie Sie dieses Feld abfragen müssen. Logging wendet Filtereinschränkungen standardmäßig auf Felder an, die auf dem Typ der Daten in jedem auszuwertenden Logeintrag basieren. Wenn die Indexierung aktiviert ist, werden Filtereinschränkungen auf ein Feld basierend auf dem Indextyp angewendet. Durch das Hinzufügen eines Index zu einem Feld wird ein Schema auf das Feld angewendet.

Wenn ein benutzerdefinierter Index für einen Bucket konfiguriert ist, unterscheidet sich das Verhalten des Schemaabgleichs, wenn diese beiden Bedingungen erfüllt sind:

  • Der Quelldatentyp für ein Feld stimmt nicht mit dem Indextyp für dieses Feld überein.
  • Der Nutzer wendet eine Beschränkung auf dieses Feld an.

Betrachten Sie die folgenden JSON-Nutzlasten:

{"jsonPayload": {"name": "A", "value": 12345}}
{"jsonPayload": {"name": "B", "value": "3"}}

Wenden Sie nun diesen Filter auf Folgendes an:

jsonPayload.value > 20

Wenn im Feld jsonPayoad.value keine benutzerdefinierte Indexierung vorhanden ist, wendet Logging einen Abgleich mit flexiblem Typ an:

  • Bei „A“ stellt Logging fest, dass der Wert des Schlüssels „value“ tatsächlich eine Ganzzahl ist und die Einschränkung „20“ in eine Ganzzahl umgewandelt werden kann. Logging wertet dann 12345 > 20 aus und gibt "true" zurück, da dies numerisch der Fall ist.

  • Bei „B“ stellt Logging fest, dass der Wert des Schlüssels „Wert“ tatsächlich ein String ist. Dann wird "3" > "20" ausgewertet und es wird „true“ zurückgegeben, da dies alphanumerisch ist.

Wenn das Feld jsonPayload.value im benutzerdefinierten Index enthalten ist, wertet Logging diese Einschränkung mithilfe des Index anstelle der üblichen Logging-Logik aus. Das Verhalten ändert sich:

  • Wenn der Index vom Typ „String“ ist, sind alle Vergleiche Stringvergleiche.
    • Der Eintrag „A“ stimmt nicht überein, da „12345“ alphanumerisch nicht größer als „20“ ist. Der Eintrag "B" stimmt überein, da der String "3" größer als "20" ist.
  • Wenn der Index vom Typ „Ganzzahl“ ist, sind alle Vergleiche ganzzahlige Vergleiche.
    • Der Eintrag "B" stimmt nicht überein, da die Zahl "3" nicht größer als "20" ist. Der Eintrag „A“ stimmt überein, da „12345“ größer als „20“ ist.

Dieser Verhaltensunterschied ist gering und sollte beim Definieren und Verwenden von benutzerdefinierten Indexen berücksichtigt werden.

Grenzfall filtern

Angenommen, für den Index des Ganzzahltyps jsonPayload.value wird ein Stringwert gefiltert:

jsonPayload.value = "hello"

Wenn der Abfragewert nicht als Indextyp erzwungen werden kann, wird der Index ignoriert.

Angenommen, Sie übergeben bei einem Index des Typs "String" einen ganzzahligen Wert:

jsonPayload.value > 50

Weder A noch B stimmt überein, da weder "12345" noch "3" alphanumerisch größer als "50" ist.