Configurar indexação personalizada

Neste documento, descrevemos como adicionar campos LogEntry indexados aos seus buckets do Cloud Logging para agilizar a consulta de dados de registros.

Informações gerais

O desempenho da consulta é fundamental para qualquer solução de geração de registros. À medida que as cargas de trabalho escalonar verticalmente e os volumes de registros correspondentes aumentam, a indexação dos dados de registros mais usados pode reduzir o tempo de consulta.

Para melhorar o desempenho da consulta, o Logging indexa automaticamente os seguintes campos LogEntry:

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

Além dos campos que o Logging indexa automaticamente, também é possível direcionar um bucket de registros para indexar outros campos LogEntry criando um índice personalizado para o bucket.

Por exemplo, suponha que suas expressões de consulta geralmente incluam o campo jsonPayload.request.status. É possível configurar um índice personalizado para um bucket que inclua jsonPayload.request.status. Qualquer consulta subsequente nos dados desse bucket referenciaria os dados jsonPayload.request.status indexados se a expressão de consulta incluir esse campo.

Ao usar a Google Cloud CLI ou a API Logging, é possível adicionar índices personalizados a buckets de registros novos ou atuais. Ao selecionar outros campos a serem incluídos no índice personalizado, observe as seguintes limitações:

• É possível adicionar até 20 campos por índice personalizado.
• Depois de configurar ou atualizar o índice personalizado de um bucket, aguarde uma hora para que as alterações sejam aplicadas às consultas. Essa latência garante a precisão do resultado da consulta e aceita registros gravados anteriormente.
• O Logging aplica a indexação personalizada aos dados armazenados em buckets de registros após a criação ou alteração do índice. As alterações em índices personalizados não se aplicam aos registros de maneira retroativa.

Antes de começar

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

• Verifique se você está usando a versão mais recente da CLI gcloud. Para mais informações, consulte Como gerenciar componentes da Google Cloud CLI.

• Verifique se você tem um papel do Identity and Access Management com as seguintes permissões:

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

  Para mais detalhes sobre esses papéis, consulte Controle de acesso com o IAM.

Definir o índice personalizado

Para cada campo adicionado ao índice personalizado de um bucket, você define dois atributos: um caminho e um tipo de campo:

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

Para adicionar um índice personalizado, crie um novo bucket ou atualize um bucket atual. Para mais informações sobre a configuração de buckets, consulte Configurar buckets de registros.

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

gcloud

Use o comando gcloud logging buckets create e defina a sinalização --index:

gcloud logging buckets create BUCKET_NAME\
--location=LOCATION\
--description="DESCRIPTION" \
--index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

Exemplo de comando:

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 criar um bucket, use projects.locations.buckets.create na API Logging. Prepare os argumentos do método da seguinte maneira:

1. Defina o parâmetro parent como o recurso em que o bucket será criado: projects/PROJECT_ID/locations/LOCATION.

   A variável LOCATION refere-se à região em que você quer que seus registros sejam armazenados.

   Por exemplo, se você quiser criar um bucket para o projeto my-project na região asia-east2, seu parâmetro parent será assim: projects/my-project/locations/asia-east2

2. Defina o parâmetro bucketId, por exemplo, my-bucket.

3. No corpo da solicitação LogBucket, configure o objeto IndexConfig para criar o índice personalizado.

4. Chame projects.locations.buckets.create para criar o bucket.

Para atualizar um bucket atual e incluir um índice personalizado, faça o seguinte:

gcloud

Use o comando gcloud logging buckets update e defina a sinalização --add-index:

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--add-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

Exemplo de comando:

gcloud logging buckets update \
int_index_test_bucket \
--location=global \ --add-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

Use projects.locations.buckets.patch na API Logging. No corpo da solicitação LogBucket, configure o objeto IndexConfig para incluir os campos LogEntry que você quer indexar.

Excluir um campo indexado personalizado

Para excluir um campo do índice personalizado de um bucket, faça o seguinte:

gcloud

Use o comando gcloud logging buckets update e defina a sinalização --remove-indexes :

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--remove-indexes=INDEX_FIELD_NAME

Exemplo de comando:

gcloud logging buckets update int_index_test_bucket \
--location=global \
--remove-indexes=jsonPayload.req_status

API

Use projects.locations.buckets.patch na API Logging. No corpo da solicitação LogBucket, remova os campos LogEntry do objeto IndexConfig.

Atualizar o tipo de dados do campo indexado personalizado

Se for necessário corrigir o tipo de dados de um campo indexado personalizado, faça o seguinte:

gcloud

Use o comando gcloud logging buckets update e defina a sinalização --update-index:

gcloud logging buckets update BUCKET_NAME\
--location=LOCATION\
--update-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

Exemplo de comando:

gcloud logging buckets update \
int_index_test_bucket \
--location=global \
--update-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

Use projects.locations.buckets.patch na API Logging. No corpo da solicitação LogBucket, atualize o objeto IndexConfig para fornecer o tipo de dados correto para um campo LogEntry.

Atualizar o caminho de um campo indexado personalizado

Se for necessário corrigir o caminho de um campo indexado personalizado, faça o seguinte:

gcloud

Use o comando gcloud logging buckets update e defina as sinalizações --remove-indexes e --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

Exemplo de comando:

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

Use projects.locations.buckets.patch na API Logging. No corpo da solicitação LogBucket, atualize o objeto IndexConfig para fornecer o caminho correto para um campo LogEntry.

Listar todos os campos indexados de um bucket

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

gcloud

Use o comando gcloud logging buckets describe:

gcloud logging buckets describe BUCKET_NAME\
--location=LOCATION

Exemplo de comando:

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

API

Use projects.locations.buckets.get na API Logging.

Limpar campos indexados personalizados

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

gcloud

Use o comando gcloud logging buckets update e adicione a sinalização --clear-indexes:

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

Exemplo de comando:

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

API

Use projects.locations.buckets.patch na API Logging. No corpo da solicitação LogBucket, exclua o objeto IndexConfig.

Consultar e visualizar dados indexados

Para consultar os dados incluídos nos campos indexados personalizados, restrinja o escopo da consulta ao bucket que contém os campos indexados personalizados e especifique a visualização de registro apropriada:

gcloud

Para ler registros de um bucket de registros, use o comando gcloud logging read e adicione um LOG_FILTER para incluir os dados indexados:

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

API

Para ler registros de um bucket de registros, use o método entries.list. Defina resourceNames para especificar o bucket e a visualização de registro apropriados e configure filter para selecionar os dados indexados.

Para informações detalhadas sobre a sintaxe de filtragem, consulte Linguagem de consulta do Logging.

Indexação e tipos de campo

A configuração da indexação de campo personalizado pode afetar a maneira como os registros são armazenados em buckets de registros e como as consultas são processadas.

No momento da gravação

O Logging tenta usar o índice personalizado nos dados armazenados em buckets de registros após a criação do índice.

Os campos indexados são digitados, o que tem implicações no carimbo de data/hora na entrada de registro. Quando a entrada de registro é armazenada no bucket de registros, o campo de registro é avaliado em relação ao tipo de índice usando estas regras:

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

No momento da consulta

Ativar um índice em um campo muda a forma como você precisa consultar esse campo. Por padrão, o Logging aplica restrições de filtro aos campos com base no tipo dos dados em cada entrada de registro que está sendo avaliada. Quando a indexação está ativada, as restrições de filtro em um campo são aplicadas com base no tipo do índice. Adicionar um índice a um campo impõe um esquema a ele.

Quando um índice personalizado é configurado para um bucket, os comportamentos de correspondência de esquema são diferentes quando as duas condições a seguir são atendidas:

• O tipo de dados de origem de um campo não corresponde ao tipo de índice dele.
• O usuário aplica uma restrição nesse campo.

Considere os seguintes payloads JSON:

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

Agora, aplique esse filtro a cada uma:

jsonPayload.value > 20

Se o campo jsonPayoad.value não tiver indexação personalizada, o Logging aplicará a correspondência de tipo flexível:

• Para "A", o Logging observa que o valor da chave "valor" é, na verdade, um número inteiro, e que a restrição, "20", pode ser convertida em um número inteiro. Em seguida, o Logging avalia 12345 > 20 e retorna "verdadeiro" porque esse é o caso numericamente.

• Para "B", o Logging observa que o valor da chave "valor" é, na verdade, uma string. Em seguida, ela avalia "3" > "20" e retorna "true", já que esse é o caso alfanumicamente.

Se o campo jsonPayload.value estiver incluído no índice personalizado, o Logging avaliará essa restrição usando o índice em vez da lógica normal do Logging. O comportamento muda:

• Se o índice for do tipo string, todas as comparações serão de strings.
  • A entrada "A" não corresponde, já que "12345" não é maior que "20" alfanuméricos. A entrada "B" corresponde, já que a string "3" é maior que "20".
• Se o índice for do tipo número inteiro, todas as comparações serão de números inteiros.
  • A entrada "B" não corresponde, já que "3" não é maior que "20" numericamente. A entrada "A" corresponde, já que "12345" é maior que "20".

Essa diferença de comportamento é sutil e precisa ser considerada ao definir e usar índices personalizados.

Caso extremo de filtragem

Para o índice de tipo inteiro jsonPayload.value, suponha que um valor de string seja filtrado:

jsonPayload.value = "hello"

Se não for possível converter o valor da consulta para o tipo de índice, o índice será ignorado.

No entanto, suponha que, para um índice do tipo string, você transmita um valor inteiro:

jsonPayload.value > 50

Nem A nem B corresponde, já que "12345" e "3" não são alfanuméricos maiores que "50".