Benutzerdefinierte Indexierung konfigurieren

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

Übersicht

Die Abfrageleistung ist für jede Logging-Lösung entscheidend. Wenn Arbeitslasten skaliert werden und sich das entsprechende Protokollvolumen erhöht, kann die Indexierung der am häufigsten verwendeten Protokolldaten die Abfragezeit verkürzen.

Zur Verbesserung der Abfrageleistung werden in der Protokollierung automatisch die folgenden LogEntry-Felder indexiert:

Zusätzlich zu den Feldern, die automatisch indexiert werden, 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 mit jsonPayload.request.status konfigurieren. Jede nachfolgende Abfrage auf die Daten dieses Buckets verweist dann auf die indexierten jsonPayload.request.status-Daten, 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 bei der Auswahl zusätzlicher Felder, die in den benutzerdefinierten Index aufgenommen werden sollen, die folgenden Einschränkungen:

  • Sie können pro benutzerdefinierten 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 korrekte Abfrageergebnisse und akzeptiert Protokolle, die in der Vergangenheit geschrieben wurden.
  • Bei der Protokollierung wird eine benutzerdefinierte Indexierung auf Daten angewendet, die in Log-Buckets gespeichert werden, nachdem der Index erstellt oder geändert wurde. Änderungen an benutzerdefinierten Indexen werden nicht rückwirkend auf Protokolle angewendet.

Hinweise

Bevor Sie mit der Konfiguration eines benutzerdefinierten Index beginnen, gehen Sie so vor:

  • Prüfen Sie, ob Sie die neueste 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, müssen Sie zwei Attribute definieren: 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. Die möglichen Werte sind INDEX_TYPE_STRING und INDEX_TYPE_INTEGER.

Sie können einen benutzerdefinierten Index entweder durch Erstellen eines neuen Buckets oder durch Aktualisieren eines vorhandenen Buckets hinzufügen. Weitere Informationen zum Konfigurieren von Buckets finden Sie unter Log-Buckets konfigurieren.

So konfigurieren Sie beim Erstellen eines Buckets einen benutzerdefinierten Index:

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 als 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 Region asia-east2 erstellen möchten, würde Ihr parent-Parameter so aussehen: projects/my-project/locations/asia-east2

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

  3. Konfigurieren Sie im Anfragetext von 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 hinzuzufü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 Anfragetext LogBucket die Felder LogEntry aus dem Objekt IndexConfig.

Datentyp des benutzerdefinierten indexierten Felds aktualisieren

Wenn Sie den Datentyp eines benutzerdefinierten indexierten Felds korrigieren möchten, 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öchten, gehen Sie so vor:

gcloud

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

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

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 aufrufen

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 Protokollen aus einem Protokoll-Bucket den Befehl gcloud logging read und fügen Sie ein LOG_FILTER hinzu, um Ihre indexierten Daten einzubeziehen:

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

API

Verwenden Sie die Methode entries.list, um Protokolle aus einem Protokoll-Bucket zu lesen. Legen Sie mit resourceNames den entsprechenden Bucket und die Protokollansicht fest und wählen Sie mit filter die indexierten Daten aus.

Weitere Informationen zur Filtersyntax finden Sie unter Logging-Abfragesprache.

Indexierung und Feldtypen

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

Beim Schreiben

Es werden Versuche protokolliert, den benutzerdefinierten Index auf Daten anzuwenden, 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 Indextyp verglichen:

  • Wenn der Typ eines Felds mit dem Typ des Index übereinstimmt, werden die Daten dem Index unverändert hinzugefügt.
  • Wenn sich der Typ des Felds vom Typ des Index unterscheidet, wird versucht, ihn in den Typ des Index zu zwingen (z. B. Ganzzahl in String).
    • Wenn die 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 werden in Logging Filtereinschränkungen auf Felder angewendet, die auf dem Datentyp der Daten in jedem zu bewertenden Logeintrag basieren. Wenn die Indexierung aktiviert ist, werden Filtereinschränkungen für ein Feld basierend auf dem Indextyp angewendet. Wenn Sie einem Feld einen Index hinzufügen, wird diesem Feld ein Schema auferlegt.

Wenn für einen Bucket ein benutzerdefinierter Index konfiguriert ist, unterscheiden sich die Schemaabgleichsmechanismen, wenn beide dieser Bedingungen erfüllt sind:

  • Der Quelldatentyp eines Felds 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 diesen Filter jetzt auf alle an:

jsonPayload.value > 20

Wenn für das Feld jsonPayoad.value keine benutzerdefinierte Indexierung vorhanden ist, wird bei der Protokollierung die flexible Typübereinstimmung 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 umgewandelt werden kann. Bei der Protokollierung wird dann 12345 > 20 ausgewertet und „wahr“ zurückgegeben, 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 „wahr“ zurückgegeben, da dies alphanumerisch der Fall ist.

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

  • Wenn der Index den Stringtyp hat, sind alle Vergleiche Stringvergleiche.
    • Der Eintrag „A“ stimmt nicht überein, da „12345“ nicht alphanumerisch 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 bei der Definition und Verwendung benutzerdefinierter Indexe berücksichtigt werden.

Grenzfall für Filter

Angenommen, für den Ganzzahlindex vom Typ jsonPayload.value 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 Stringindex einen Ganzzahlwert:

jsonPayload.value > 50

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