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:

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:

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

Usa el comando gcloud logging buckets create y define 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 segmento, usa projects.locations.buckets.create en la API Logging. Prepara los argumentos del método de la siguiente manera:

  1. En el parámetro parent, defina el recurso en el que se va a crear el segmento: projects/PROJECT_ID/locations/LOCATION

    La variable LOCATION hace referencia a la región en la que quieres que se almacenen tus registros.

    Por ejemplo, si quieres crear un segmento para el proyecto my-project en la región asia-east2, el parámetro parent sería el siguiente: projects/my-project/locations/asia-east2.

  2. Define 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 segmento.

Para actualizar un contenedor y añadirle un índice personalizado, siga estos pasos:

gcloud

Usa el comando gcloud logging buckets update y define 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 Logging. En el cuerpo de la solicitud LogBucket, configura el objeto IndexConfig para incluir los campos LogEntry que quieras indexar.

Eliminar un campo indexado personalizado

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

gcloud

Usa el comando gcloud logging buckets update y define 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 Logging. En el cuerpo de la solicitud LogBucket, elimina los campos LogEntry del objeto IndexConfig.

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

Usa el comando gcloud logging buckets update y define 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 Logging. En el cuerpo de la solicitud LogBucket, actualice el objeto IndexConfig para proporcionar el tipo de datos correcto para el campo LogEntry.

Actualizar la ruta de un campo indexado personalizado

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

gcloud

Usa el comando gcloud logging buckets update y define 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 Logging. En el cuerpo de la solicitud LogBucket, actualiza el objeto IndexConfig para proporcionar la ruta de campo correcta de un campo LogEntry.

Mostrar todos los campos indexados de un segmento

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

gcloud

Usa el comando 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 Logging.

Borrar campos indexados personalizados

Para quitar todos los campos indexados personalizados de un contenedor, haga lo siguiente:

gcloud

Usa el comando gcloud logging buckets update y añade 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 Logging. En el cuerpo de la solicitud LogBucket, elimina el objeto IndexConfig.

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

Para leer los registros de un segmento de registro, usa el comando gcloud logging read y añade un LOG_FILTER para incluir los datos indexados:

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

API

Para leer los registros de un segmento de registro, utiliza el método entries.list. Define resourceNames para especificar el segmento y la vista de registro adecuados, y define filter para seleccionar los datos indexados.

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