Mejora el tiempo de consulta con 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 de 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 verticalmente y aumentan los volúmenes de registros correspondientes, indexar los datos de registros que más se usan puede reducir el tiempo de consulta.

Para mejorar el rendimiento de las consultas, Logging indexa automáticamente los siguientes campos 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 registros para que indexe otros campos LogEntry creando un índice personalizado para el bucket.

Por ejemplo, supongamos que tus expresiones de búsqueda suelen incluir el campo jsonPayload.request.status. Podrías configurar un índice personalizado para un bucket que incluya jsonPayload.request.status; cualquier consulta posterior sobre los datos de ese bucket haría referencia a los datos indexados de jsonPayload.request.status si la expresión de la consulta incluye ese campo.

Con Google Cloud CLI o la API de Logging, puedes agregar índices personalizados a 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.
• Después de configurar o actualizar el índice personalizado de un bucket, debes esperar una hora para que los cambios se apliquen a tus búsquedas. Esta latencia garantiza la corrección de los resultados de la búsqueda y acepta los registros que se escribieron en el pasado.
• El registro aplica la indexación personalizada a los datos que se almacenan en los buckets de registros después de que se creó o cambió 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 los componentes de Google Cloud CLI.

  Nota: En los ejemplos de gcloud CLI de este documento, se supone que configuraste gcloud CLI para actualizar el proyecto correcto. Si deseas especificar el proyecto en el comando, incluye la marca --project y especifica un Google Cloud ID del proyecto.

• Verifica que tengas un rol de Identity and Access Management con los siguientes permisos:

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

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

Cómo definir el índice personalizado

Para cada campo que agregues al índice personalizado de un bucket, debes definir dos atributos: una ruta de campo y un tipo de campo:

• fieldPath: Describe la ruta de acceso específica al campo LogEntry en tus entradas de registro. Por ejemplo, jsonPayload.req_status.
• type: Indica si el campo es de tipo cadena o número entero. Los 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 cómo configurar buckets, consulta Configura buckets de registros.

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

gcloud

Usa el comando gcloud logging buckets create y establece 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 para que sea 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.

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

gcloud

Usa el comando gcloud logging buckets update y establece 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 comando gcloud logging buckets update y establece 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 el cuerpo de la solicitud LogBucket, quita los campos LogEntry del objeto 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 personalizado indexado

Si necesitas corregir la ruta de acceso del campo 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 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.

Borra los campos personalizados indexados

Para quitar todos los campos indexados personalizados de un bucket, haz lo siguiente:

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 personalizados indexados, restringe el alcance de tu consulta al bucket que contiene los campos personalizados indexados y especifica la vista de registro adecuada:

gcloud

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

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

API

Para leer registros de un bucket de registros, usa el método 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 la indexación 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

Se registran los intentos de usar el índice personalizado en los datos almacenados en los buckets de registros después de que se creó el índice.

Los campos indexados se escriben, lo que tiene implicaciones para la marca de tiempo en la entrada de registro. Cuando la entrada de registro se almacena en el bucket de registros, el campo de registro se evalúa en función del tipo de índice con 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, el registro intenta forzarlo al tipo del índice (por ejemplo, de número entero a cadena).
  • Si falla la coerción de tipos, los datos no se indexan. Cuando la conversión de tipo se realiza correctamente, 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 la indexación está habilitada, las restricciones de filtro en un campo se aplican según el tipo de índice. Agregar un índice a un campo impone un esquema en ese campo.

Cuando se configura un índice personalizado para un bucket, los comportamientos de coincidencia de 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:

jsonPayload.value > 20

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

• Para "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 devuelve "verdadero" porque este es el caso numéricamente.

• En el caso de "B", el registro observa que el valor de la clave "value" es, en realidad, una cadena. Luego, evalúa "3" > "20" y devuelve "true", ya que este es el caso alfanumérico.

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

• Si el índice es de tipo cadena, todas las comparaciones son comparaciones de cadenas.
  • La entrada "A" 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 comparaciones de enteros.
  • La entrada "B" no coincide, ya que "3" no es mayor que "20" numéricamente. 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 entero jsonPayload.value, supongamos que se filtra un valor de cadena:

jsonPayload.value = "hello"

Si el valor de la búsqueda no se puede coercionar al tipo de índice, se ignora el índice.

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

jsonPayload.value > 50

Ni A ni B coinciden, ya que ni "12345" ni "3" son alfanuméricamente mayores que "50".