Configura la indexación personalizada

En este documento, se describe cómo agregar campos LogEntry indexados a tus buckets de Cloud Logging para acelerar las consultas de datos de registros.

Descripción general

El rendimiento de las consultas es fundamental para cualquier solución de registro. A medida que las cargas de trabajo se escalan verticalmente y los volúmenes de registros correspondientes aumentan, indexar los datos de registros más usados puede reducir el tiempo de consulta.

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

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

Además de esos campos que Logging indexa de forma automática, también puedes crear un índice personalizado para el bucket a fin de indicarle a un bucket de registros que indexe otros campos LogEntry.

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 en los datos de ese bucket hará referencia a los datos jsonPayload.request.status indexados si la expresión de consulta incluye ese campo.

Con Google Cloud CLI o la API de Logging, puedes agregar índices personalizados a buckets de registros nuevos o existentes. Cuando 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 consultas. Esta latencia garantiza la precisión del resultado de la consulta y acepta registros escritos en el pasado.
• Logging aplica la indexación personalizada a los datos almacenados en buckets de registro después de crear o cambiar 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 tienes un rol de Identity and Access Management con los siguientes permisos:

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

  Para obtener detalles sobre estas funciones, consulta Control de acceso con la IAM.

Define el índice personalizado

Para cada campo que agregas 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 string o número entero. Los valores posibles son INDEX_TYPE_STRING y INDEX_TYPE_INTEGER.

Para agregar un índice personalizado, crea un bucket nuevo o actualiza un bucket 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 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á 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 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 quieres 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 a fin de proporcionar el tipo de datos correcto para un campo LogEntry.

Actualiza la ruta de acceso de un campo indexado personalizado

Si necesitas corregir la ruta de 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 a fin de proporcionar la ruta de campo correcta para un campo LogEntry.

Enumera todos los campos indexados de un bucket

Para mostrar 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, 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 indexados personalizados, restringe el alcance de la consulta al bucket que contiene los campos indexados personalizados 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=VIEW_ID

API

Para leer registros de un bucket de registros, usa el método entries.list. Configura resourceNames para especificar el bucket y la vista de registro apropiados, y establece filter para seleccionar tus datos indexados.

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

Indexación y tipos de campos

La forma en que configuras la indexación de campos personalizada puede afectar la forma en que se almacenan los registros en los buckets de registros y cómo se procesan las consultas.

A la hora de la escritura

Logging intenta usar el índice personalizado en los datos que se almacenan en buckets de registros después de que se crea el índice.

Los campos indexados están escritos, lo que repercute en 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 según el tipo de índice mediante estas reglas:

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

A la hora de la consulta

Cuando habilitas un índice en un campo, cambia la forma en que debes consultarlo. De forma predeterminada, Logging aplica restricciones de filtro a los campos según el tipo de datos en cada entrada de registro que se evalúa. Cuando la indexación está habilitada, las restricciones de filtros de 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 esquemas 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, aplique este filtro a cada uno:

jsonPayload.value > 20

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

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

• Para “B”, Logging observa que el valor de la clave “value” es en realidad una string. Luego, evalúa "3" > "20" y muestra "true", ya que este es el caso de forma alfanumérica.

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

• Si el índice es de tipo string, todas las comparaciones son de tipo string.
  • La entrada "A" no coincide, ya que "12345" no es mayor que "20" en caracteres alfanuméricos. La entrada "B" coincide, ya que la string "3" es mayor que "20".
• Si el índice es de tipo número entero, todas las comparaciones son comparaciones de números 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 debe tenerse en cuenta cuando se definen y usan índices personalizados.

Filtrado de mayúsculas y minúsculas

Para el índice de tipo de número entero jsonPayload.value, supongamos que se filtra un valor de string:

jsonPayload.value = "hello"

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

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

jsonPayload.value > 50

Ni A ni B coinciden, ya que ni “12345” ni “3” son valores alfanuméricos mayores que “50”.