Benutzerdefinierte Indexierung konfigurieren

In diesem Dokument wird beschrieben, wie Sie indexierte LogEntry-Felder zu Ihrem Cloud Logging-Buckets zum Erstellen Logdaten schneller abfragen.

Übersicht

Die Abfrageleistung ist für jede Logging-Lösung von entscheidender Bedeutung. Wenn Arbeitslasten hochskaliert und das entsprechende Logvolumen wächst, kann die Indexierung Ihrer am häufigsten verwendeten Logdaten die Abfragezeit zu reduzieren.

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

Neben den Feldern, die Logging automatisch indexiert, kann einen Log-Bucket auch so anweisen, dass er andere LogEntry-Felder indexiert, indem ein benutzerdefinierten Index für den Bucket erstellen.

Angenommen, Ihre Abfrageausdrücke enthalten häufig das Feld jsonPayload.request.status Sie könnten einen benutzerdefinierten Index für einen Bucket konfigurieren einschließlich jsonPayload.request.status; jede nachfolgende Abfrage zu würden die Daten dieses Buckets auf die indexierten jsonPayload.request.status-Daten, wenn der Abfrageausdruck dieses Feld enthält.

Mit der Google Cloud CLI oder Logging API können Sie benutzerdefinierte in vorhandene oder neue Log-Buckets. Wenn Sie zusätzliche Felder auswählen die Sie in den benutzerdefinierten Index aufnehmen möchten, beachten Sie 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 warten eine Stunde lang, bis die Änderungen auf Ihre Abfragen angewendet werden. Diese Latenz sorgt für korrekte Abfrageergebnisse und akzeptiert Protokolle, die in der Vergangenheit geschrieben wurden.
  • Logging wendet die benutzerdefinierte Indexierung auf Daten an, die in Log-Buckets, nachdem der Index erstellt oder geändert wurde; Änderungen am benutzerdefinierten gelten Indexe nicht rückwirkend.

Hinweise

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

Benutzerdefinierten Index definieren

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

  • fieldPath: Beschreibt den Pfad zum LogEntry in der Datei Logeinträge. Beispiel: jsonPayload.req_status
  • type: Gibt an, ob das Feld vom Typ „String“ oder „Ganzzahl“ ist. Die Mögliche 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 Siehe Log-Buckets konfigurieren.

So konfigurieren Sie beim Erstellen eines Buckets einen benutzerdefinierten Index:

gcloud

Verwenden Sie die Methode 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 um den Bucket zu erstellen: 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 in der Region asia-east2 würde Ihr parent-Parameter so aussehen: dies: 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 mit einem benutzerdefinierten Index:

gcloud

Verwenden Sie die Methode 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 Im LogBucket erstellt haben, konfigurieren Sie das Objekt IndexConfig so, Fügen Sie die LogEntry ein, 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 die Methode 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 Anfragetext von LogBucket die Felder LogEntry 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. Im LogBucket-Anfragetext, aktualisieren Sie das IndexConfig-Objekt, um Den richtigen Datentyp für ein LogEntry-Feld.

Pfad eines benutzerdefinierten indexierten Felds aktualisieren

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

gcloud

Verwenden Sie die Methode 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 Im LogBucket-Anfragetext, aktualisieren Sie das IndexConfig-Objekt, um Den richtigen Feldpfad für ein LogEntry-Feld.

Alle indexierten Felder für einen Bucket auflisten

Um die Details eines Buckets einschließlich seiner benutzerdefinierten indexierten Felder aufzulisten, führen Sie die Folgendes:

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 in der Logging API projects.locations.buckets.get.

Benutzerdefinierte indexierte Felder löschen

So entfernen Sie alle benutzerdefinierten indexierten Felder aus einem Bucket:

gcloud

Verwenden Sie die Methode 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 in der Logging API projects.locations.buckets.patch. Im LogBucket erstellt haben, löschen Sie 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 die Methode gcloud logging read und fügen Sie einen LOG_FILTER zum Einbeziehen Ihre indexierten Daten an:

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

API

Verwenden Sie zum Lesen von Logs aus einem Log-Bucket die Methode entries.list-Methode. Festlegen resourceNames, um die entsprechende Bucket- und Logansicht anzugeben, und legen Sie filter wählen Sie die indexierten Daten aus.

Detaillierte Informationen zur Filtersyntax finden Sie unter Logging-Abfragesprache:

Indexierung und Feldtypen

Die Konfiguration der Indexierung für benutzerdefinierte Felder kann sich auf das Speichern von Logs auswirken und wie Abfragen verarbeitet werden.

Beim Schreiben

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

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

  • Wenn der Typ eines Felds mit dem Indextyp übereinstimmt, werden die Daten den Index wörtlich zu erstellen.
  • Wenn sich der Feldtyp vom Indextyp unterscheidet, gilt Folgendes: Logging versucht, sie in den Indextyp (für Beispiel: Ganzzahl in String).
    • Wenn die Typerzwingung fehlschlägt, werden die Daten nicht indexiert. Bei Typ erzwingen 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. Von werden in Logging Filtereinschränkungen auf Felder angewendet, Der Typ der Daten in jedem Logeintrag, der ausgewertet wird. Wenn die Indexierung werden Filtereinschränkungen auf ein Feld basierend auf dem Typ des -Index. Wenn Sie einem Feld einen Index hinzufügen, wird diesem Feld ein Schema auferlegt.

Wenn ein benutzerdefinierter Index für einen Bucket konfiguriert ist, unterscheiden sich, wenn diese beiden 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 nun auf jede Gruppe an:

jsonPayload.value > 20

Wenn im Feld jsonPayoad.value keine benutzerdefinierte Indexierung vorhanden ist, gilt Folgendes: Logging wendet den flexiblen Abgleich an:

  • Bei „A“ wird in Logging festgestellt, dass der Wert des Werts Schlüssel ist und dass die Einschränkung "20" in eine Integer Logging wertet dann 12345 > 20 aus und gibt „wahr“ weil dies numerisch der Fall ist.

  • Bei „B“ wird in Logging festgestellt, dass der Wert des Werts Taste ist eigentlich eine Zeichenfolge. Dann wird "3" > "20" ausgewertet und „true“ zurückgegeben, da dies alphanumerisch ist.

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

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

Dieser Verhaltensunterschied ist minimal und sollte beim Definieren und mit benutzerdefinierten Indexen.

Grenzfall filtern

Angenommen, ein Stringwert für den Ganzzahlindex jsonPayload.value ist Gefiltert:

jsonPayload.value = "hello"

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

Nehmen wir jedoch an, dass Sie für einen String-Index einen ganzzahligen Wert übergeben:

jsonPayload.value > 50

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