Configura la indexación personalizada

En este documento, se describe cómo agregar campos LogEntry indexados a tu los buckets de Cloud Logging para crear consultar tus datos de registro con mayor rapidez.

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 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, puedes también puede indicarle a un bucket de registros que indexe otros campos LogEntry creando un índice personalizado para el bucket.

Por ejemplo, imagina 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 sobre los datos de ese bucket harían referencia al jsonPayload.request.status 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 seleccionas campos adicionales para incluirlos 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 precisión de los resultados de la consulta y acepta registros escritos en el pasado.
• Logging aplica la indexación personalizada a los datos que se almacenan en buckets de registros después de crear o cambiar el índice; cambios a la acción personalizada 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 del gcloud CLI Para obtener más información, consulta Administra los 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 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. Los valores posibles son INDEX_TYPE_STRING y INDEX_TYPE_INTEGER.

Para agregar un índice personalizado, crea un bucket nuevo o usa actualizar 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 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

Si deseas actualizar un bucket existente para 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 acceso 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

Genera una lista de todos los campos indexados de un bucket

Para enumerar los detalles de un bucket, incluidos los campos indexados personalizados, sigue estos pasos: lo siguiente:

gcloud logging buckets describe BUCKET_NAME\
--location=LOCATION

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

Borrar campos indexados personalizados

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

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 al bucket que contiene los campos indexados personalizados y especifica el vista de registro apropiada:

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.

A la hora 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 registro, el campo de registro se evalúa en función del tipo de índice con estas reglas:

• Si el tipo de un campo es igual al tipo de índice, los datos se agregan a el índice literalmente.
• 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 se escribe coerción tenga éxito, 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 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 es las restricciones del 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 a 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 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”, Logging observa que el valor del “value” la clave es un número entero y que la restricción, “20”, se puede convertir en 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 "true", 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 del la lógica habitual de Logging. El comportamiento cambia:

• Si el índice es de tipo string, todas las comparaciones son de string.
  • La entrada "A" no coincide, ya que "12345" no es mayor que "20" alfabéticamente. La "B" coincide con la entrada, ya que la cadena “3” es mayor que 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 "A" coincide de entrada, desde “12345” es mayor que "20".

Esta diferencia de comportamiento es sutil y debe tenerse en cuenta al definir y con índices personalizados.

Filtra las mayúsculas y minúsculas

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