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

Para mejorar el rendimiento de las consultas, el registro 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 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 í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 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 los componentes de Google Cloud CLI.

• 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.

Define 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 la configuración de buckets, consulta Configura buckets de registros.

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

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

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

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

Borra un campo indexado personalizado

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

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

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 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

Actualiza la ruta de un campo indexado personalizado

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

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

Enumera todos los campos indexados de un bucket

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

gcloud logging buckets describe BUCKET_NAME\
--location=LOCATION

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

Borra los campos indexados personalizados

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

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

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

Consulta y visualiza datos indexados

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

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

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

El registro intenta usar el índice personalizado en los datos que se almacenan en los buckets de registro después de crear el índice.

Los campos indexados están escritos, lo que tiene consecuencias 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 al del índice, Logging intenta convertirlo en el tipo del índice (por 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

Si 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 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 a un campo impone un esquema en ese campo.

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

• 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 muestra “verdadero” porque este es el caso numéricamente.

• En “B”, el registro observa que el valor de la clave “value” 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 de la siguiente manera:

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

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 alfanuméricos más grandes que “50”.