Abfragezeit mit benutzerdefinierter Indexierung verbessern

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

Übersicht

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

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

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

Angenommen, Ihre Abfrageausdrücke enthalten häufig das Feld jsonPayload.request.status. Sie können einen benutzerdefinierten Index für einen Bucket konfigurieren, der jsonPayload.request.status enthält. Bei jeder nachfolgenden Abfrage der Daten dieses Buckets wird auf die indexierten jsonPayload.request.status-Daten verwiesen, 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. Wenn Sie zusätzliche Felder auswählen, die in den benutzerdefinierten Index aufgenommen werden sollen, beachten Sie die folgenden Einschränkungen:

  • Sie können pro benutzerdefiniertem Index bis zu 20 Felder hinzufügen.
  • Nachdem Sie den benutzerdefinierten Index eines Buckets konfiguriert oder aktualisiert haben, müssen Sie eine Stunde warten, bis die Änderungen auf Ihre Abfragen angewendet werden. Diese Latenz sorgt für die Richtigkeit der Abfrageergebnisse und akzeptiert Logs, die in der Vergangenheit geschrieben wurden.
  • Logging wendet die benutzerdefinierte Indexierung auf Daten an, die nach dem Erstellen oder Ändern des Index in Log-Buckets gespeichert werden. Änderungen an benutzerdefinierten Indexen werden nicht rückwirkend auf Logs angewendet.

Hinweis

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

  • Prüfen Sie, ob Sie die aktuelle Version der gcloud CLI verwenden. Weitere Informationen finden Sie unter Komponenten der Google Cloud CLI verwalten.

  • Prüfen Sie, ob Sie eine Identity and Access Management-Rolle mit den folgenden Berechtigungen haben:

    Weitere Informationen zu diesen Rollen finden Sie unter Zugriffssteuerung mit IAM.

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 LogEntry Feld in Ihren Logeinträgen. Beispiel: jsonPayload.req_status.
  • type: Gibt an, ob das Feld vom Typ „String“ oder „Ganzzahl“ ist. Die möglichen Werte sind INDEX_TYPE_STRING und INDEX_TYPE_INTEGER.

Ein benutzerdefinierter Index kann entweder durch Erstellen eines neuen Buckets oder durch Aktualisieren eines vorhandenen Buckets hinzugefügt werden. 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 gcloud logging buckets create Befehl und legen Sie das --index Flag 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 in der Logging API die Methode projects.locations.buckets.create. Bereiten Sie die Argumente für die Methode so vor:

  1. Legen Sie für den parent Parameter 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 in der asia-east2 Region 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 Anfragetext LogBucket 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, um einen benutzerdefinierten Index einzufügen:

gcloud

Verwenden Sie den gcloud logging buckets update Befehl und legen Sie das --add-index Flag 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 IndexConfig Objekt, um die LogEntry Felder einzufügen, 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 gcloud logging buckets update Befehl und legen Sie das --remove-indexes Flag 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 Anfragetext, die LogEntry-Felder aus dem IndexConfig-Objekt.

Datentyp des benutzerdefinierten indexierten Felds aktualisieren

So korrigieren Sie den Datentyp eines benutzerdefinierten indexierten Felds:

gcloud

Verwenden Sie den gcloud logging buckets update Befehl und legen Sie das --update-index Flag 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 IndexConfig Objekt, um den richtigen Datentyp für ein LogEntry Feld anzugeben.

Pfad eines benutzerdefinierten indexierten Felds aktualisieren

So korrigieren Sie den Feldpfad eines benutzerdefinierten indexierten Felds:

gcloud

Verwenden Sie den gcloud logging buckets update Befehl und legen Sie die --remove-indexes und --update-index Flags 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 IndexConfig das Objekt, um den richtigen Feldpfad für ein LogEntry Feld anzugeben.

Alle indexierten Felder für einen Bucket auflisten

So rufen Sie die Details eines Buckets einschließlich der benutzerdefinierten indexierten Felder auf:

gcloud

Verwenden Sie den gcloud logging buckets describe Befehl:

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 gcloud logging buckets update Befehl und fügen Sie das --clear-indexes Flag 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 Anfragetext LogBucket das Objekt IndexConfig.

Indexierte Daten abfragen und ansehen

Wenn Sie die Daten abfragen möchten, die in benutzerdefinierten indexierten Feldern enthalten sind, beschränken Sie den Umfang Ihrer Abfrage auf den Bucket, der die benutzerdefinierten indexierten Felder enthält, und geben Sie die entsprechende Logansicht an:

gcloud

Verwenden Sie zum Lesen von Logs aus einem Log-Bucket den Befehl gcloud logging read und fügen Sie einen LOG_FILTER hinzu, um Ihre indexierten Daten einzufügen:

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

API

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

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

Indexierung und Feldtypen

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

Beim Schreiben

Logging versucht, den benutzerdefinierten Index für Daten zu verwenden, die nach dem Erstellen des Index in Log-Buckets gespeichert werden.

Indexierte Felder sind typisiert, was Auswirkungen auf den Zeitstempel im Logeintrag hat. Wenn der Logeintrag im Log-Bucket gespeichert wird, wird das Logfeld anhand der folgenden Regeln mit dem Index-Typ verglichen:

  • Wenn der Typ eines Felds mit dem Typ des Index übereinstimmt, werden die Daten unverändert zum Index hinzugefügt.
  • Wenn der Typ des Felds vom Typ des Index abweicht, versucht Logging, ihn in den Typ des Index zu konvertieren (z. B. Ganzzahl in String).
    • Wenn die Typkonvertierung fehlschlägt, werden die Daten nicht indexiert. Wenn die Typkonvertierung erfolgreich ist, werden die Daten indexiert.

Beim Abfragen

Wenn Sie einen Index für ein Feld aktivieren, ändert sich die Art und Weise, wie Sie dieses Feld abfragen müssen. Standardmäßig wendet Logging Filterbeschränkungen auf Felder an, die auf dem Typ der Daten in jedem Logeintrag basieren, der ausgewertet wird. Wenn die Indexierung aktiviert ist, werden Filterbeschränkungen für ein Feld basierend auf dem Typ des Index angewendet. Durch das Hinzufügen eines Index für ein Feld wird ein Schema für dieses Feld festgelegt.

Wenn ein benutzerdefinierter Index für einen Bucket konfiguriert ist, unterscheidet sich das Verhalten beim Schemabgleich, wenn beide folgenden Bedingungen erfüllt sind:

  • Der Quelldatentyp für ein Feld stimmt nicht mit dem Index-Typ 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 jede an:

jsonPayload.value > 20

Wenn das Feld jsonPayoad.value keine benutzerdefinierte Indexierung hat, wendet Logging einen flexiblen Typabgleich an:

  • Für „A“ stellt Logging fest, dass der Wert des Schlüssels „value“ eigentlich eine Ganzzahl ist und dass die Beschränkung „20“ in eine Ganzzahl konvertiert werden kann. Logging wertet dann 12345 > 20 aus und gibt „true“ zurück, da dies numerisch der Fall ist.

  • Für „B“ stellt Logging fest, dass der Wert des Schlüssels „value“ eigentlich ein String ist. Dann wird "3" > "20" ausgewertet und „true“ zurückgegeben, da dies alphanumerisch der Fall ist.

Wenn das Feld jsonPayload.value im benutzerdefinierten Index enthalten ist, wertet Logging diese Beschränkung mit dem 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 Ganzzahlvergleiche.
    • Der Eintrag „B“ stimmt nicht überein, da „3“ numerisch nicht größer als „20“ ist. Der Eintrag „A“ stimmt überein, da „12345“ größer als „20“ ist.

Dieser Verhaltensunterschied ist geringfügig und sollte bei der Definition und Verwendung benutzerdefinierter Indexe berücksichtigt werden.

Grenzfall bei der Filterung

Angenommen, für den Index vom Typ „Ganzzahl“ jsonPayload.value wird ein Stringwert gefiltert:

jsonPayload.value = "hello"

Wenn der Abfragewert nicht in den Index-Typ konvertiert werden kann, wird der Index ignoriert.

Angenommen, Sie übergeben für einen Index vom Typ „String“ einen Ganzzahlwert:

jsonPayload.value > 50

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