Configura la indexación personalizada

En este documento, se describe cómo agregar campos LogEntry indexados a tus buckets de Cloud Logging para que las consultas a tus datos de registros sean más rápidas.

Descripción general

El rendimiento de las consultas es fundamental para cualquier solución de registro. A medida que las cargas de trabajo escalan y aumentar el volumen de registro correspondiente, la indexación de tus datos de registro más usados puede reducir el tiempo de consulta.

Para mejorar el rendimiento de las consultas, Logging indexa automáticamente los siguientes campos de LogEntry:

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

Además de los campos que Logging indexa automáticamente, también puedes dirigir un bucket de registro para indexar otros campos LogEntry. Para ello, crea un índice personalizado para el bucket.

Por ejemplo, supongamos que tus expresiones de consulta suelen incluir el campo jsonPayload.request.status. Puedes configurar un índice personalizado para un bucket que incluya jsonPayload.request.status. Cualquier consulta posterior a los datos de ese bucket haría referencia a los datos de jsonPayload.request.status indexados si la expresión de consulta incluye ese campo.

Con Google Cloud CLI o la API de Logging, puedes agregar en buckets de registros existentes o nuevos. A medida que selecciones campos adicionales para incluir en el índice personalizado, ten en cuenta las siguientes limitaciones:

• Puedes agregar hasta 20 campos por índice personalizado.
• Luego de configurar o actualizar el índice personalizado de un bucket, debes esperar para que los cambios se apliquen a tus consultas. Esta latencia garantiza la exactitud de los resultados de la consulta y acepta registros que se escribieron en el pasado.
• El registro aplica el indexado personalizado a los datos que se almacenan en los buckets de registro después de que se crea o cambia el índice. Los cambios en los índices personalizados no se aplican a los registros de forma retroactiva.

Antes de comenzar

Antes de comenzar a configurar un índice personalizado, haz lo siguiente:

• Verifica que estés usando la versión más reciente de la CLI de gcloud. Para obtener más información, consulta Administra componentes de Google Cloud CLI.

• Verifica que tengas un rol de administración de identidades y accesos con los siguientes permisos:

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

  Para obtener detalles sobre estos roles, consulta Control de acceso con la IAM.

Define el índice personalizado

Para cada campo que agregas al índice personalizado de un bucket, defines dos atributos: una ruta de campo y un tipo de campo:

• fieldPath: Describe la ruta específica al campo LogEntry en tus entradas de registro. Por ejemplo, jsonPayload.req_status.
• type: Indica si el campo es de tipo string o número entero. El valores posibles son INDEX_TYPE_STRING y INDEX_TYPE_INTEGER.

Para agregar un índice personalizado, puedes crear un bucket nuevo o actualizar uno existente. Para obtener más información sobre la configuración de buckets, consulta Configura buckets de registros.

Para configurar un índice personalizado cuando creas un bucket, haz lo siguiente:

gcloud

Usa el gcloud logging buckets create y configura la marca --index:

gcloud logging buckets create BUCKET_NAME\
--location=LOCATION\
--description="DESCRIPTION" \
--index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

Comando de ejemplo:

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

Para crear un bucket, usa projects.locations.buckets.create en la API de Logging. Prepara los argumentos del método de la siguiente manera:

1. Establece el parámetro parent como el recurso en el que se creará el bucket: projects/PROJECT_ID/locations/LOCATION

   La variable LOCATION hace referencia a la región en la que deseas que se almacenen tus registros.

   Por ejemplo, si deseas crear un bucket para el proyecto my-project en la región asia-east2, tu parámetro parent se vería de la siguiente manera: projects/my-project/locations/asia-east2

2. Establece el parámetro bucketId, por ejemplo, my-bucket.

3. En el cuerpo de la solicitud LogBucket, configura el objeto IndexConfig para crear el índice personalizado.

4. Llama a projects.locations.buckets.create para crear el bucket.

Si deseas actualizar un bucket existente para que incluya un índice personalizado, haz lo siguiente:

gcloud

Usa el gcloud logging buckets update y configura la marca --add-index:

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

Comando de ejemplo:

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

API

Usa projects.locations.buckets.patch en la API de Logging En el cuerpo de la solicitud LogBucket, configura el objeto IndexConfig para incluir los campos LogEntry que deseas indexar.

Borra un campo indexado personalizado

Para borrar un campo del índice personalizado de un bucket, haz lo siguiente:

gcloud

Usa el gcloud logging buckets update y configura la marca --remove-indexes :

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

Comando de ejemplo:

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

API

Usa projects.locations.buckets.patch en la API de Logging. En la LogBucket, quita los campos LogEntry del IndexConfig.

Actualiza el tipo de datos del campo indexado personalizado

Si necesitas corregir el tipo de datos de un campo indexado personalizado, haz lo siguiente:

gcloud

Usa el comando gcloud logging buckets update y establece la marca --update-index:

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

Comando de ejemplo:

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

API

Usa projects.locations.buckets.patch en la API de Logging. En el cuerpo de la solicitud LogBucket, actualiza el objeto IndexConfig para proporcionar el tipo de datos correcto para un campo LogEntry.

Actualiza la ruta de un campo indexado personalizado

Si necesitas corregir la ruta de acceso de un campo indexado personalizado, haz lo siguiente:

gcloud

Usa el comando gcloud logging buckets update y establece las marcas --remove-indexes y --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

Comando de ejemplo:

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

Usa projects.locations.buckets.patch en la API de Logging En el cuerpo de la solicitud LogBucket, actualiza el objeto IndexConfig para proporcionar la ruta de acceso de campo correcta para un campo LogEntry.

Enumera todos los campos indexados de un bucket

Para enumerar los detalles de un bucket, incluidos sus campos indexados personalizados, haz lo siguiente:

gcloud

Usa el comando de gcloud logging buckets describe:

gcloud logging buckets describe BUCKET_NAME\
--location=LOCATION

Comando de ejemplo:

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

API

Usa projects.locations.buckets.get en la API de Logging.

Borrar campos indexados personalizados

Para quitar todos los campos indexados personalizados de un bucket, sigue estos pasos:

gcloud

Usa el comando gcloud logging buckets update y agrega la marca --clear-indexes:

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

Comando de ejemplo:

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

API

Usa projects.locations.buckets.patch en la API de Logging En el cuerpo de la solicitud LogBucket, borra el objeto IndexConfig.

Consulta y visualiza datos indexados

Para consultar los datos incluidos en los campos indexados personalizados, restringe el permiso de al bucket que contiene los campos indexados personalizados y especifica el vista de registro apropiada:

gcloud

Para leer registros de un bucket de registros, usa el gcloud logging read y agrega un LOG_FILTER para incluir tus datos indexados:

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

API

Para leer registros de un bucket de registros, usa el entries.list. Establece resourceNames para especificar el bucket y la vista de registro adecuados, y establece filter para seleccionar tus datos indexados.

Para obtener información detallada sobre la sintaxis de filtrado, consulta Lenguaje de consulta de Logging.

Indexación y tipos de campos

La forma en que configures el indexado de campos personalizados puede afectar la forma en que se almacenan los registros en los buckets de registros y cómo se procesan las consultas.

En el momento de la escritura

Logging intenta usar el índice personalizado en los datos almacenados en buckets de registros después de crear el índice.

Los campos indexados se escriben, lo que tiene implicaciones para la marca de tiempo en el entrada de registro. Cuando la entrada de registro se almacena en el bucket de registros, el campo de registro se evalúa con respecto al tipo de índice usando estas reglas:

• Si el tipo de un campo es el mismo que el del índice, los datos se agregan al índice de forma literal.
• Si el tipo del campo es diferente del tipo del índice, entonces Logging intenta forzarlo al tipo de índice (para ejemplo, de número entero a cadena).
  • Si la coerción de tipo falla, los datos no se indexan. Cuando la coerción de tipo es correcta, los datos se indexan.

En el momento de la consulta

Habilitar un índice en un campo cambia la forma en que debes consultar ese campo. De forma predeterminada, Logging aplica restricciones de filtro a los campos según el tipo de datos de cada entrada de registro que se evalúa. Cuando se habilita la indexación, las restricciones de filtro en un campo se aplican según el tipo de índice. Agregar un índice en un campo impone un esquema en ese campo.

Cuando se configura un índice personalizado para un bucket, los comportamientos de coincidencia del esquema difieren cuando se cumplen estas dos condiciones:

• El tipo de datos de origen de un campo no coincide con el tipo de índice de ese campo.
• El usuario aplica una restricción en ese campo.

Considera las siguientes cargas útiles de JSON:

{"jsonPayload": {"name": "A", "value": 12345}}
{"jsonPayload": {"name": "B", "value": "3"}}

Ahora aplica este filtro a cada uno de los siguientes elementos:

jsonPayload.value > 20

Si el campo jsonPayoad.value no tiene indexación personalizada, el registro aplica la coincidencia de tipo flexible:

• En el caso de "A", el registro observa que el valor de la clave "value" es, en realidad, un número entero y que la restricción, "20", se puede convertir en un número entero. Luego, el registro evalúa 12345 > 20 y muestra “verdadero” porque este es el caso numéricamente.

• Para “B”, Logging observa que el valor del “value” tecla es en realidad una cadena. Luego, evalúa "3" > "20" y muestra “verdadero”, ya que este es el caso alfanumérico.

Si el campo jsonPayload.value se incluye en el índice personalizado, Logging evalúa esta restricción con el índice en lugar de la lógica habitual de Logging. El comportamiento cambia:

• Si el índice es de tipo de cadena, todas las comparaciones son de cadenas.
  • La "A" entrada no coincide, ya que “12345” no es mayor que "20" alfanuméricamente. La entrada “B” coincide, ya que la cadena “3” es mayor que “20”.
• Si el índice es de tipo entero, todas las comparaciones son de números enteros.
  • La "B" entrada no coincide, ya que “3” no es mayor que "20" en forma numérica. La entrada "A" coincide, ya que "12345" es mayor que "20".

Esta diferencia de comportamiento es sutil y se debe tener en cuenta cuando se definen y usan índices personalizados.

Caso extremo de filtrado

Para el índice de tipo de número entero jsonPayload.value, supongamos que se filtrado:

jsonPayload.value = "hello"

Si el valor de la consulta no se puede forzar al tipo de índice, se ignora el índice.

Sin embargo, supongamos que, para un índice de tipo de cadena, pasas un valor de número entero:

jsonPayload.value > 50

Ni A ni B coinciden, ya que ni “12345” ni “3” son alfabéticamente mayores que “50”.