Melhore o tempo de consulta com a indexação personalizada

Este documento descreve como adicionar campos LogEntry indexados aos contentores do Cloud Logging para consultar os dados dos registos mais rapidamente.

Vista geral

O desempenho das consultas é fundamental para qualquer solução de registo. À medida que as cargas de trabalho são dimensionadas e os volumes de registos correspondentes aumentam, a indexação dos dados de registos mais usados pode reduzir o tempo de consulta.

Para melhorar o desempenho das consultas, o Logging indexa automaticamente os seguintes campos LogEntry:

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

Além dos campos que o registo indexa automaticamente, também pode direcionar um contentor de registos para indexar outros campos LogEntry criando um índice personalizado para o contentor.

Por exemplo, suponha que as suas expressões de consulta incluem frequentemente o campo jsonPayload.request.status. Pode configurar um índice personalizado para um contentor que inclua jsonPayload.request.status. Qualquer consulta subsequente aos dados desse contentor faria referência aos dados jsonPayload.request.status indexados se a expressão de consulta incluísse esse campo.

Ao usar a Google Cloud CLI ou a API Logging, pode adicionar índices personalizados a contentores de registos existentes ou novos. À medida que seleciona campos adicionais para incluir no índice personalizado, tenha em atenção as seguintes limitações:

• Pode adicionar até 20 campos por índice personalizado.
• Depois de configurar ou atualizar um índice personalizado de um grupo, tem de aguardar uma hora para que as alterações sejam aplicadas às suas consultas. Esta latência garante a correção dos resultados das consultas e aceita registos escritos no passado.
• O registo aplica a indexação personalizada aos dados armazenados em contentores de registos após a criação ou a alteração do índice. As alterações aos índices personalizados não se aplicam aos registos retroativamente.

Antes de começar

Antes de começar a configurar um índice personalizado, faça o seguinte:

• Verifique se está a usar a versão mais recente da CLI gcloud. Para mais informações, consulte o artigo Gerir componentes da CLI Google Cloud.

  .

• Verifique se tem uma função de gestão de identidade e acesso com as seguintes autorizações:

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

  Para ver detalhes sobre estas funções, consulte o artigo Controlo de acesso com a IAM.

Defina o índice personalizado

Para cada campo que adicionar ao índice personalizado de um grupo, define dois atributos: um caminho do campo e um tipo de campo:

• fieldPath: descreve o caminho específico para o campo LogEntry nas entradas do registo. Por exemplo, jsonPayload.req_status.
• type: indica se o campo é do tipo string ou inteiro. Os valores possíveis são INDEX_TYPE_STRING e INDEX_TYPE_INTEGER.

Pode adicionar um índice personalizado criando um novo contentor ou atualizando um contentor existente. Para mais informações sobre a configuração de contentores, consulte o artigo Configure contentores de registos.

Para configurar um índice personalizado ao criar um contentor, faça o seguinte:

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 atualizar um contentor existente de modo a incluir um índice personalizado, faça o seguinte:

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

Elimine um campo indexado personalizado

Para eliminar um campo do índice personalizado de um depósito, faça o seguinte:

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

Atualize o tipo de dados do campo indexado personalizado

Se precisar de corrigir o tipo de dados de um campo indexado personalizado, faça o seguinte:

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

Atualize o caminho de um campo indexado personalizado

Se precisar de corrigir o caminho do campo de um campo indexado personalizado, faça o seguinte:

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

Apresenta todos os campos indexados de um contentor

Para listar os detalhes de um contentor, incluindo os respetivos campos indexados personalizados, faça o seguinte:

gcloud logging buckets describe BUCKET_NAME \
--location=LOCATION

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

Limpe os campos personalizados indexados

Para remover todos os campos indexados personalizados de um contentor, faça o seguinte:

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

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

Consultar e ver dados indexados

Para consultar os dados incluídos em campos indexados personalizados, restrinja o âmbito da consulta ao contentor que contém os campos indexados personalizados e especifique a vista de registo adequada:

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

Para obter informações detalhadas sobre a sintaxe de filtragem, consulte o artigo Linguagem de consulta de registo.

Indexação e tipos de campos

A forma como configura a indexação de campos personalizados pode afetar a forma como os registos são armazenados em contentores de registos e como as consultas são processadas.

No momento da escrita

Registo de tentativas de utilização do índice personalizado em dados armazenados em contentores de registos após a criação do índice.

Os campos indexados são tipados, o que tem implicações para a data/hora na entrada do registo. Quando a entrada do registo é armazenada no contentor de registos, o campo de registo é avaliado em função do tipo de índice através destas regras:

• Se o tipo de um campo for igual ao tipo do índice, os dados são adicionados ao índice literalmente.
• Se o tipo do campo for diferente do tipo do índice, o Logging tenta forçá-lo a ser do tipo do índice (por exemplo, de número inteiro para string).
  • Se a coerção de tipo falhar, os dados não são indexados. Quando a coerção de tipo é bem-sucedida, os dados são indexados.

No momento da consulta

A ativação de um índice num campo altera a forma como tem de consultar esse campo. Por predefinição, o registo aplica restrições de filtro aos campos com base no tipo de dados em cada entrada de registo que está a ser avaliada. Quando a indexação está ativada, as restrições de filtro num campo são aplicadas com base no tipo de índice. A adição de um índice a um campo impõe um esquema nesse campo.

Quando um índice personalizado está configurado para um contentor, os comportamentos de correspondência de esquemas diferem quando ambas as condições seguintes são cumpridas:

• O tipo de dados de origem de um campo não corresponde ao tipo de índice desse campo.
• O utilizador aplica uma restrição nesse campo.

Considere os seguintes payloads JSON:

{"jsonPayload": {"name": "A", "value": 12345}}
{"jsonPayload": {"name": "B", "value": "3"}}

Agora, aplique este filtro a cada um dos seguintes elementos:

jsonPayload.value > 20

Se o campo jsonPayoad.value não tiver indexação personalizada, então: O registo aplica a correspondência de tipo flexível:

• Para "A", o registo observa que o valor da chave "value" é, na verdade, um número inteiro e que a restrição "20" pode ser convertida num número inteiro. O registo avalia então 12345 > 20 e devolve "true" porque é o caso numericamente.

• Para "B", o registo observa que o valor da chave "value" é, na verdade, uma string. Em seguida, avalia "3" > "20" e devolve "verdadeiro", uma vez que este é o caso alfanumericamente.

Se o campo jsonPayload.value estiver incluído no índice personalizado, o registo avalia esta restrição através do índice em vez da lógica de registo habitual. O comportamento muda:

• Se o índice for do tipo string, todas as comparações são comparações de strings.
  • A entrada "A" não corresponde, uma vez que "12345" não é superior a "20" alfanumericamente. A entrada "B" corresponde, uma vez que a string "3" é superior a "20".
• Se o índice for do tipo inteiro, todas as comparações são comparações de inteiros.
  • A entrada "B" não corresponde, uma vez que "3" não é numericamente superior a "20". A entrada "A" corresponde, uma vez que "12345" é superior a "20".

Esta diferença de comportamento é subtil e deve ser considerada quando definir e usar índices personalizados.

Caso extremo de filtragem

Para o índice do tipo inteiro jsonPayload.value, suponhamos que um valor de string é filtrado:

jsonPayload.value = "hello"

Se não for possível forçar o valor da consulta para o tipo de índice, o índice é ignorado.

No entanto, suponhamos que, para um índice do tipo string, passa um valor inteiro:

jsonPayload.value > 50

Nenhuma das opções A nem B corresponde, uma vez que nem "12345" nem "3" é alfanumericamente superior a "50".