Mejorar el tiempo de consulta con la indexación personalizada

En este documento se describe cómo añadir campos indexados LogEntry a tus contenedores de Cloud Logging para que las consultas de tus datos de registro sean más rápidas.

Información general

El rendimiento de las consultas es fundamental para cualquier solución de registro. A medida que las cargas de trabajo se amplían y los volúmenes de registros correspondientes aumentan, indexar los datos de los 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
• gravedad
• 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 segmento de registro para que indexe otros campos de LogEntry creando un índice personalizado para el segmento.

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

Si usas la CLI de Google Cloud o la API Logging, puedes añadir índices personalizados a segmentos de registro nuevos o ya creados. Cuando seleccione campos adicionales para incluirlos en el índice personalizado, tenga en cuenta las siguientes limitaciones:

• Puedes añadir hasta 20 campos por índice personalizado.
• Después de configurar o actualizar el índice personalizado de un contenedor, debe esperar una hora para que los cambios se apliquen a sus consultas. Esta latencia asegura la corrección de los resultados de las consultas y acepta los registros que se escriben en el pasado.
• Logging aplica la indexación personalizada a los datos almacenados en segmentos de registros después de que se haya creado o cambiado el índice. Los cambios en los índices personalizados no se aplican a los registros de forma retroactiva.

Antes de empezar

Antes de empezar 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 Gestionar componentes de la CLI de Google Cloud.

  .

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

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

  Para obtener más información sobre estos roles, consulta el artículo sobre el control de acceso con gestión de identidades y accesos.

Definir el índice personalizado

Por cada campo que añadas al índice personalizado de un contenedor, debes definir dos atributos: una ruta de campo y un tipo de campo:

• fieldPath: describe la ruta específica al campo LogEntry de las entradas de registro. Por ejemplo, jsonPayload.req_status.
• type: indica si el campo es de tipo cadena o entero. Los valores posibles son INDEX_TYPE_STRING y INDEX_TYPE_INTEGER.

Puedes añadir un índice personalizado creando un nuevo contenedor o actualizando uno que ya tengas. Para obtener más información sobre cómo configurar los contenedores, consulta Configurar contenedores de registro.

Para configurar un índice personalizado al crear un contenedor, sigue estos pasos:

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 contenedor y añadirle un índice personalizado, siga estos pasos:

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

Eliminar un campo indexado personalizado

Para eliminar un campo del índice personalizado de un contenedor, siga estos pasos:

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

Actualizar 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

Actualizar la ruta de un campo indexado personalizado

Si necesitas corregir la ruta 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

Mostrar todos los campos indexados de un segmento

Para consultar los detalles de un contenedor, incluidos sus campos indexados personalizados, sigue estos pasos:

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 contenedor, haga lo siguiente:

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

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

Consultar y ver datos indexados

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

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

Para obtener información detallada sobre la sintaxis de filtrado, consulta el artículo Lenguaje de consultas de registro.

Indexación y tipos de campo

La forma en que configures la indexación de campos personalizados puede afectar a cómo se almacenan los registros en los contenedores de registro y a cómo se procesan las consultas.

En tiempo de escritura

Registra los intentos de usar el índice personalizado en los datos almacenados en los contenedores de registro después de que se haya creado el índice.

Los campos indexados tienen un tipo, lo que tiene implicaciones en la marca de tiempo de la entrada de registro. Cuando la entrada de registro se almacena en el segmento de registro, el campo de registro se evalúa con el tipo de índice mediante estas reglas:

• Si el tipo de un campo es el mismo que el del índice, los datos se añaden al índice tal cual.
• Si el tipo del campo es diferente del tipo del índice, Logging intenta convertirlo al tipo del índice (por ejemplo, de entero a cadena).
  • Si la conversión de tipo falla, los datos no se indexan. Cuando la conversión de tipo se realiza correctamente, los datos se indexan.

En el momento de la consulta

Si habilitas un índice en un campo, cambiará la forma en que debes consultar ese campo. De forma predeterminada, Logging aplica restricciones de filtro a los campos en función del tipo de datos de cada entrada de registro que se esté evaluando. Cuando la indexación está habilitada, las restricciones de filtro de un campo se aplican en función del tipo de índice. Al añadir un índice a un campo, se le impone un esquema.

Cuando se configura un índice personalizado para un contenedor, los comportamientos de coincidencia de esquemas son diferentes si 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 ellos:

jsonPayload.value > 20

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

• En el caso de "A", Logging 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. A continuación, el registro evalúa 12345 > 20 y devuelve "true" porque es el caso numéricamente.

• En el caso de "B", Logging observa que el valor de la clave "value" es en realidad una cadena. A continuación, evalúa "3" > "20" y devuelve "true" (verdadero), 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 mediante 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 debe tenerse en cuenta al definir y usar índices personalizados.

Filtrado de casos límite

Supongamos que se filtra un valor de cadena para el índice de tipo entero jsonPayload.value:

jsonPayload.value = "hello"

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

Sin embargo, supongamos que, en 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".