Abfragezeit mit benutzerdefinierter Indexierung verbessern

Mit benutzerdefinierten Indexen in Cloud Logging können Sie häufig abgefragte LogEntry-Felder in Ihren Log-Buckets indexieren, um Abfragen für große Mengen an Logdaten zu beschleunigen. Zusätzlich zu den Feldern, die Logging automatisch indexiert, können Sie benutzerdefinierte Indexe für String- oder Ganzzahlfelder für neue oder vorhandene Buckets konfigurieren.

Übersicht

Die Abfrageleistung ist für jede Logging-Lösung entscheidend. Wenn Arbeitslasten hochskaliert 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:

Zusätzlich zu den Feldern, die Logging automatisch indexiert, können Sie einen Log-Bucket auch 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. 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 beim Auswählen zusätzlicher Felder für den benutzerdefinierten Index die folgenden Einschränkungen:

  • 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 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 gelten nicht rückwirkend für Logs.

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.

    an.

  • Prüfen Sie, ob Sie eine IAM-Rolle (Identity and Access Management) 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 Feld LogEntry in Ihren Logeinträgen. Beispiel: jsonPayload.req_status
  • type: Gibt an, ob das Feld vom Typ „String“ oder „Integer“ 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 Befehl gcloud logging buckets create und setzen Sie das Flag --index:

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 für den Parameter parent 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 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 Befehl gcloud logging buckets update und setzen Sie das Flag --add-index:

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 Anfragetext LogBucket das Objekt IndexConfig so, dass es die Felder 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 setzen Sie das Flag --remove-indexes :

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

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 setzen Sie das Flag --update-index:

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 Anfragetext LogBucket das Objekt IndexConfig, um den richtigen Datentyp für ein 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 Anfragetext LogBucket 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 auf, einschließlich seiner benutzerdefinierten indexierten Felder:

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 Anfragetext LogBucket das Objekt IndexConfig.

Indexierte Daten abfragen und ansehen

Wenn Sie die Daten in benutzerdefinierten indexierten Feldern abfragen möchten, beschränken Sie den Bereich Ihrer Abfrage 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 Ihre indexierten Daten einzuschließen:

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

API

Wenn Sie Logs aus einem Log-Bucket lesen möchten, verwenden Sie die Methode entries.list. Legen Sie resourceNames fest, um den entsprechenden Bucket und die 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 Indexierung benutzerdefinierter Felder kann sich darauf auswirken, wie Logs in Log-Buckets gespeichert und Abfragen verarbeitet werden.

Beim Schreiben

Logging versucht, den benutzerdefinierten Index für Daten zu verwenden, die nach der Erstellung des Index in Log-Buckets gespeichert wurden.

Indexierte Felder sind typisiert, was Auswirkungen auf den Zeitstempel des Logeintrags hat. Wenn der Logeintrag im Log-Bucket gespeichert wird, wird das Logfeld anhand dieser Regeln mit dem Indextyp abgeglichen:

  • Wenn der Typ eines Felds mit dem Typ des Index übereinstimmt, werden die Daten unverändert in den Index aufgenommen.
  • Wenn der Typ des Felds sich vom Typ des Index unterscheidet, versucht Logging, ihn in den Typ des Index umzuwandeln (z. B. Ganzzahl in String).
    • Wenn die implizite Typumwandlung fehlschlägt, werden die Daten nicht indexiert. Wenn die Typumwandlung erfolgreich ist, werden die Daten indexiert.

Zum Zeitpunkt der Abfrage

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 Filtereinschränkungen auf Felder an, die auf dem Datentyp in jedem Logeintrag basieren, der ausgewertet wird. Wenn die Indexierung aktiviert ist, werden Filtereinschränkungen für ein Feld basierend auf dem Typ des Index angewendet. Wenn Sie einem Feld einen Index hinzufügen, wird diesem Feld ein Schema zugewiesen.

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

  • Der Quelldatentyp für ein Feld stimmt nicht mit dem Indextyp für dieses Feld überein.
  • Der Nutzer wendet eine Einschrä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 alle an:

jsonPayload.value > 20

Wenn für das Feld jsonPayload.value keine benutzerdefinierte Indexierung vorhanden ist, wird in Logging der Abgleich mit flexiblen Typen angewendet:

  • Bei „A“ stellt Logging fest, dass der Wert des Schlüssels „value“ tatsächlich eine Ganzzahl ist und dass die Einschrä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.

  • Bei „B“ stellt Logging fest, dass der Wert des Schlüssels „value“ tatsächlich ein String ist. Anschließend 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 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 „Integer“ 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 subtil und sollte beim Definieren und Verwenden benutzerdefinierter Indexe berücksichtigt werden.

Grenzfall mit Filterung

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

jsonPayload.value = "hello"

Wenn der Abfragewert nicht in den Indextyp umgewandelt werden kann, wird der Index ignoriert.

Angenommen, Sie übergeben für einen String-Index einen Ganzzahlwert:

jsonPayload.value > 50

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