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:

• resource.type
• resource.labels.*
• logName
• severity
• timestamp
• insertId
• operation.id
• trace
• httpRequest.status
• labels.*
• split.uid

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:

  • roles/logging.admin
  • roles/logging.configWriter

  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 logging buckets create BUCKET_NAME\
--location=LOCATION\
--description="DESCRIPTION" \
--index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

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

So aktualisieren Sie einen vorhandenen Bucket, um einen benutzerdefinierten Index hinzuzufügen:

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

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

Benutzerdefiniertes indexiertes Feld löschen

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

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

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

Datentyp des benutzerdefinierten indexierten Felds aktualisieren

Wenn Sie den Datentyp eines benutzerdefinierten indexierten Felds korrigieren möchten, gehen Sie so vor:

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

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

Pfad eines benutzerdefinierten indexierten Felds aktualisieren

Wenn Sie den Feldpfad eines benutzerdefinierten indexierten Felds korrigieren möchten, gehen Sie so vor:

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

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

Alle indexierten Felder für einen Bucket auflisten

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

gcloud logging buckets describe BUCKET_NAME\
--location=LOCATION

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

Benutzerdefinierte indexierte Felder löschen

So entfernen Sie alle benutzerdefinierten indexierten Felder aus einem Bucket:

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

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

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 logging read LOG_FILTER --bucket=BUCKET_ID --location=LOCATION --view=VIEW_ID

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.