Este documento contém exemplos de consultas sobre entradas de registro armazenadas em
buckets de registros que são atualizados para usar a Análise de dados de registros.
Nesses buckets, você pode executar consultas SQL do
Página Análise de dados de registros no console do Google Cloud. Para mais amostras, consulte a
logging-analytics-samples
e as
security-analytics
repositórios do GitHub.
Este documento não descreve o SQL nem como rotear e armazenar entradas de registro. Para informações sobre esses tópicos, consulte a seção Próximas etapas.
Antes de começar
Para usar as consultas mostradas na página Análise de dados de registros neste documento, faça o seguinte: substituir TABLE_NAME_OF_LOG_VIEW pelo nome da tabela na visualização de registros que você quer consultar. Este nome tem o formato
project_ID.region.bucket_ID.view_ID
:Para identificar esse nome, acesse a lista Visualizações de registros na Análise de dados de registros, localize a visualização de registros e selecione Consulta. O painel Consulta é preenchido com uma consulta padrão, inclui o nome da tabela da visualização de registro que é consultada. Para informações sobre como acessar a consulta padrão, consulte Consultar uma visualização de registro.
Para usar as consultas mostradas neste documento sobre página do BigQuery Studio, substitua TABLE_NAME_OF_LOG_VIEW pelo caminho para a tabela. no conjunto de dados vinculado. Por exemplo, para consultar a visualização
_AllLogs
no conjunto de dados vinculadomydataset
. que está no projetomyproject
, defina esse campo comomyproject.mydataset._AllLogs
:No console do Google Cloud, acesse a página do BigQuery:
Também é possível encontrar essa página usando a barra de pesquisa.
Para abrir a página Análise de dados de registros, faça o seguinte:
-
No console do Google Cloud, acesse a página Análise de dados de registros:
Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.
Opcional: para identificar o esquema da visualização de registros, Na lista Visualizações de registro, encontre a visualização e selecione o da visualização.
O esquema é exibido. Use o campo Filtro. para localizar campos específicos. Não é possível modificar o esquema.
-
Filtrar registros
As consultas SQL determinam quais entradas na visualização de registros serão processadas e agrupam essas entradas e realizar operações agregadas. Quando não há agrupamento e agregação operação estiverem listadas, o resultado da consulta incluirá as linhas selecionadas pelo operação de filtro. Os exemplos nesta seção ilustram a filtragem.
Filtrar por horário
Para definir o período da consulta, recomendamos que você
use o seletor de intervalo de tempo. Esse seletor é usado automaticamente quando uma consulta
não especifica um campo timestamp
na cláusula WHERE
.
Por exemplo, para visualizar os dados da semana passada, selecione Últimos sete dias de
o seletor de intervalo de tempo. Também é possível usar o intervalo de tempo
para especificar um horário de início e de término, especificar um horário para a visualização e
alterar os fusos horários.
Se você incluir um campo timestamp
na cláusula WHERE
, o intervalo de tempo
configuração do seletor não é usada. O exemplo a seguir filtra os dados por
usando a função TIMESTAMP_SUB
, que permite especificar um lookback
a partir do horário atual:
WHERE
timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
Para mais informações sobre como filtrar por tempo, consulte Funções de hora e funções de carimbo de data/hora.
Filtrar por recurso
Para filtrar por recurso, adicione uma restrição resource.type
.
Por exemplo, a consulta a seguir lê a hora mais recente dos dados e
retém as linhas cujo tipo de recurso corresponde a gce_instance
e, em seguida, classifica as
e exibe até 100 entradas:
SELECT
timestamp, log_name, severity, json_payload, resource, labels
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
resource.type = "gce_instance"
ORDER BY timestamp ASC
LIMIT 100
Filtrar por gravidade
É possível filtrar por gravidade específica com uma restrição como
severity = 'ERROR'
: Outra opção é usar a instrução IN
e especificar um conjunto de valores válidos.
Por exemplo, a consulta a seguir lê a hora mais recente dos dados e
em seguida, retém apenas as linhas que contêm um campo severity
cujo valor é
'INFO'
ou 'ERROR'
:
SELECT
timestamp, log_name, severity, json_payload, resource, labels
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
severity IS NOT NULL AND
severity IN ('INFO', 'ERROR')
ORDER BY timestamp ASC
LIMIT 100
A consulta anterior filtra pelo valor do campo severity
. No entanto,
também é possível escrever consultas que filtram pelo valor numérico da gravidade do registro.
Por exemplo, se você substituir as linhas severity
pelas seguintes linhas:
a consulta retorna todas as entradas de registro com nível de gravidade de pelo menos NOTICE
:
severity_number IS NOT NULL AND
severity_number > 200
Para informações sobre os valores enumerados, consulte
LogSeverity
Filtrar por nome do registro
Para filtrar por um nome de registro, adicione uma restrição no valor do
log_name
ou o campo log_id
. O campo log_name
inclui o recurso
caminho. Ou seja, esse campo tem valores como projects/myproject/logs/mylog
.
O campo log_id
armazena apenas o nome do registro, como mylog
.
Por exemplo, a consulta a seguir lê a hora mais recente dos dados e
mantém as linhas em que o valor no campo log_id
é
cloudaudit.googleapis.com/data_access
e classifica e exibe os
resultados:
SELECT
timestamp, log_id, severity, json_payload, resource, labels
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
log_id = "cloudaudit.googleapis.com/data_access"
ORDER BY timestamp ASC
LIMIT 100
Filtrar por rótulo de recurso
A maioria dos descritores de recursos monitorados define rótulos que são usados para identificar um recurso específico. Por exemplo, o descritor de uma instância do Compute Engine inclui rótulos para a zona, o ID do projeto e o ID da instância. Quando o quando uma entrada de registro é gravada, os valores são atribuídos a cada campo. Confira a seguir exemplo:
{
type: "gce_instance"
labels: {
instance_id: "1234512345123451"
project_id: "my-project"
zone: "us-central1-f"
}
}
Como o tipo de dados do campo labels
é JSON, a inclusão de uma restrição
como resource.labels.zone = "us-centra1-f"
em uma consulta resulta em uma sintaxe
erro. Para conseguir o valor de um campo com um tipo de dados JSON, use a função
JSON_VALUE
Por exemplo, a consulta a seguir lê os dados mais recentes e retém
as linhas em que o recurso é uma instância do Compute Engine
localizados na zona us-central1-f
:
SELECT
timestamp, log_name, severity, JSON_VALUE(resource.labels.zone) AS zone, json_payload, resource, labels
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
resource.type = "gce_instance" AND
JSON_VALUE(resource.labels.zone) = "us-central1-f"
ORDER BY timestamp ASC
LIMIT 100
Para informações sobre todas as funções que podem recuperar e transformar arquivos JSON dados, consulte Funções JSON.
Filtrar por solicitação HTTP
Para filtrar a visualização de registros para incluir apenas entradas de registro que correspondam a uma solicitação
solicitação ou resposta, adicione uma restrição http_request IS NOT NULL
:
SELECT
timestamp, log_name, severity, http_request, resource, labels
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
http_request IS NOT NULL
ORDER BY timestamp
LIMIT 100
A consulta a seguir inclui apenas linhas que correspondem a GET
ou POST
solicitações:
SELECT
timestamp, log_name, severity, http_request, resource, labels
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
http_request IS NOT NULL AND
http_request.request_method IN ('GET', 'POST')
ORDER BY timestamp ASC
LIMIT 100
Filtrar por status HTTP
Para filtrar por status HTTP, modifique a cláusula WHERE
para exigir a
http_request.status
seja definido:
SELECT
timestamp, log_name, http_request.status, http_request, resource, labels
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
http_request IS NOT NULL AND
http_request.status IS NOT NULL
ORDER BY timestamp ASC
LIMIT 100
Para determinar o tipo de dados armazenados em um campo, confira o esquema ou exiba
campo. Os resultados da consulta anterior mostram que
O campo http_request.status
armazena valores inteiros.
Filtrar por um campo com um tipo JSON
Para extrair um valor de uma coluna com dados do tipo JSON, use a função
JSON_VALUE
Considere as seguintes consultas:
SELECT
json_payload
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
json_payload.status IS NOT NULL
e
SELECT
json_payload
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
JSON_VALUE(json_payload.status) IS NOT NULL
As consultas anteriores testam o valor do campo json_payload
no
a uma entrada de registro. Ambas as consultas
Descarte as entradas de registro que não contêm um campo rotulado como json_payload
.
A diferença entre as duas consultas é a linha final, que define
o que é testado em relação a NULL
. Agora, considere uma visualização de registros
duas entradas de registro. Para uma entrada de registro, o campo json_payload
tem o seguinte
formulário:
{
status: {
measureTime: "1661517845"
}
}
Para a outra entrada de registro, o campo json_payload
tem uma estrutura diferente:
{
@type: "type.googleapis.com/google.cloud.scheduler.logging.AttemptFinished"
jobName: "projects/my-project/locations/us-central1/jobs/test1"
relativeUrl: "/food=cake"
status: "NOT_FOUND"
targetType: "APP_ENGINE_HTTP"
}
As duas entradas de registro anteriores atendem à restrição
json_payload.status IS NOT NULL
:
Ou seja, o resultado da primeira consulta inclui as duas entradas de registro.
No entanto, quando a restrição for JSON_VALUE(json_payload.status) IS NOT NULL
,
apenas a segunda entrada de registro
é incluída no resultado da consulta.
Filtrar por expressão regular
Para retornar a substring que corresponde a uma expressão regular, use a função
REGEXP_EXTRACT
O tipo de retorno dessa função é
um STRING
ou um BYTES
.
A consulta a seguir exibe as entradas de registro mais recentes recebidas e mantém
essas entradas com um campo json_payload.jobName
e, em seguida, exibe a
do nome que começa com test
:
SELECT
timestamp, REGEXP_EXTRACT(JSON_VALUE(json_payload.jobName), r".*(test.*)$") AS name,
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
json_payload.jobName IS NOT NULL
ORDER BY timestamp DESC
LIMIT 20
Para mais exemplos, consulte a
Documentação do REGEXP_EXTRACT
.
Para exemplos de outras expressões regulares que
que você pode usar, consulte Funções, operadores e condicionais.
A consulta mostrada neste exemplo não é eficiente. Para uma correspondência de substring, como
com o ilustrado, use a função CONTAINS_SUBSTR
.
Agrupar e agregar entradas de registro
Esta seção se baseia nos exemplos anteriores e ilustra como é possível
agrupar e agregar entradas de registro. Se você não especificar um agrupamento, mas
especificarem uma agregação, um único resultado será mostrado, porque o SQL trata todas
linhas que satisfazem a cláusula WHERE
como um único grupo.
Cada expressão SELECT
precisa ser incluída ou agregada nos campos do grupo.
Agrupar por tempo
Para agrupar os dados por horário, use a função TIMESTAMP_TRUNC
,
que trunca um carimbo de data/hora para uma granularidade especificada, como MINUTE
. Para
exemplo, um carimbo de data/hora de 15:30:11
, que é formatado como
hours:minutes:seconds
, torna-se 15:30:00
quando a granularidade é definida como
MINUTE
.
A consulta a seguir lê os dados recebidos no intervalo especificado por
o seletor de intervalo de tempo e, em seguida, mantém
as linhas em que o valor do campo json_payload.status
não é NULL.
A consulta trunca o carimbo de data/hora de cada linha por hora e agrupa as
pelo carimbo de data/hora e status truncados:
SELECT
TIMESTAMP_TRUNC(timestamp, HOUR) AS hour,
JSON_VALUE(json_payload.status) AS status,
COUNT(*) AS count
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
json_payload IS NOT NULL AND
JSON_VALUE(json_payload.status) IS NOT NULL
GROUP BY hour,status
ORDER BY hour ASC
Para mais exemplos, consulte a
Documentação do TIMESTAMP_TRUNC
.
Para informações sobre outras funções baseadas em tempo, consulte
Funções de data e hora.
Agrupar por recurso
A consulta a seguir lê a hora mais recente dos dados e agrupa as entradas de registro por tipo de recurso. Em seguida, ela conta o número de linhas para cada tipo de recurso e retorna uma tabela com duas colunas. A primeira coluna lista tipo de recurso, enquanto a segunda coluna é o número de linhas para esse tipo de recurso:
SELECT
resource.type, COUNT(*) AS count
FROM
`TABLE_NAME_OF_LOG_VIEW`
GROUP BY resource.type
LIMIT 100
Agrupar por gravidade
A consulta a seguir lê a hora mais recente dos dados e retém as linhas. com um campo "severity". A consulta agrupa as linhas por gravidade e conta o número de linhas de cada grupo:
SELECT
severity, COUNT(*) AS count
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
severity IS NOT NULL
GROUP BY severity
ORDER BY severity
LIMIT 100
Agrupar por log_id
O resultado da consulta a seguir é uma tabela com duas colunas. A primeira lista os nomes dos registros e a segunda coluna lista o número de que foram gravadas no registro. O classifica os resultados pela contagem de entradas:
SELECT
log_id, COUNT(*) AS count
FROM
`TABLE_NAME_OF_LOG_VIEW`
GROUP BY log_id
ORDER BY count DESC
LIMIT 100
Calcular a latência média da solicitação HTTP
A consulta a seguir ilustra o agrupamento por várias colunas e o cálculo
um valor médio. A consulta agrupa as linhas pelo URL contido na
solicitação e pelo valor do campo labels.checker_location
. Depois
agrupando as linhas, a consulta calcula a latência média de cada grupo:
SELECT
JSON_VALUE(labels.checker_location) AS location,
AVG(http_request.latency.seconds) AS secs, http_request.request_url
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
http_request IS NOT NULL AND
http_request.request_method IN ('GET')
GROUP BY http_request.request_url, location
ORDER BY location
LIMIT 100
Na expressão anterior, JSON_VALUE
é necessário para extrair o valor
do campo labels.checker_location
porque o tipo de dados para
labels
é JSON.
No entanto, essa função não é usada para extrair o valor da função
http_request.latency.seconds
. O último campo tem um tipo de dados de
inteiro.
Calcular a média de bytes enviados para um teste de sub-rede
A consulta a seguir ilustra como exibir o número médio de bytes enviados por local.
A consulta lê a hora mais recente dos dados e retém apenas essas linhas.
cuja coluna de tipo de recurso é gce_subnetwork
e com json_payload
não é NULL. Em seguida, a consulta agrupa as linhas pelo local
recurso. Ao contrário do exemplo anterior, em que os dados são armazenados como valores
valor, o valor do campo bytes_sent
é uma string e, portanto,
converta o valor em FLOAT64
antes de calcular a média:
SELECT JSON_VALUE(resource.labels.location) AS location,
AVG(CAST(JSON_VALUE(json_payload.bytes_sent) AS FLOAT64)) AS bytes
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
resource.type = "gce_subnetwork" AND
json_payload IS NOT NULL
GROUP BY location
LIMIT 100
O resultado da consulta anterior é uma tabela em que cada linha lista um local e a média de bytes enviados para esse local.
Para informações sobre todas as funções que podem recuperar e transformar arquivos JSON dados, consulte Funções JSON.
Para informações sobre CAST
e outras funções de conversão, consulte
Funções de conversão.
Contar as entradas de registro com um campo que corresponda a um padrão
Para retornar a substring que corresponde a uma expressão regular, use a função
REGEXP_EXTRACT
O tipo de retorno dessa função é
um STRING
ou um BYTES
.
A consulta a seguir retém as entradas de registro para as quais o valor
do campo json_payload.jobName
não é NULL.
Em seguida, agrupa as entradas pelo sufixo do nome que começa
com test
. Por fim, a consulta conta o número de entradas em cada grupo:
SELECT
REGEXP_EXTRACT(JSON_VALUE(json_payload.jobName), r".*(test.*)$") AS name,
COUNT(*) AS count
FROM
`TABLE_NAME_OF_LOG_VIEW`
WHERE
json_payload.jobName IS NOT NULL
GROUP BY name
ORDER BY count
LIMIT 20
Para mais exemplos, consulte a
Documentação do REGEXP_EXTRACT
.
Para exemplos de outras expressões regulares que
que você pode usar, consulte Funções, operadores e condicionais.
Pesquisa entre colunas
Esta seção descreve duas abordagens diferentes que podem ser usadas para pesquisar várias colunas de uma tabela.
Pesquisa baseada em token
Para pesquisar entradas de registro em uma visualização de registro que correspondam a um conjunto de termos de pesquisa,
use a função SEARCH
. Essa função requer dois parâmetros:
onde pesquisar e a consulta de pesquisa.
Como a função SEARCH
tem regras específicas sobre como os dados são pesquisados,
recomendamos a leitura da documentação do SEARCH
.
A consulta a seguir retém apenas as linhas que têm um campo que corresponda exatamente a "35.193.12.15":
SELECT
timestamp, log_id, proto_payload, severity, resource.type, resource, labels
FROM
`TABLE_NAME_OF_LOG_VIEW` AS t
WHERE
proto_payload IS NOT NULL AND
log_id = "cloudaudit.googleapis.com/data_access" AND
SEARCH(t,"`35.193.12.15`")
ORDER BY timestamp ASC
LIMIT 20
Na consulta anterior, os acentos graves envolvem o valor a ser pesquisado. Isso
garante que a função SEARCH
busque uma correspondência exata entre
um valor de campo e o valor entre os acentos graves.
Quando os acentos graves são omitidos na string de consulta, a string de consulta é dividida
com base nas regras definidas na documentação do SEARCH
.
Por exemplo, quando a instrução a seguir é executada,
a string de consulta será dividida em quatro tokens: "35", "193", "12" e "15":
SEARCH(t,"35.193.12.15")
A instrução SEARCH
anterior corresponde a uma linha quando um único campo
corresponde aos quatro tokens. A ordem deles não importa.
É possível incluir várias instruções SEARCH
em uma consulta. Por exemplo, na
da consulta anterior, substitua o filtro no ID do registro por uma
declaração como a seguinte:
SEARCH(t,"`cloudaudit.googleapis.com/data_access`")
A instrução anterior pesquisa todos os campos das entradas de registro na visualização de registros
enquanto a instrução original pesquisa apenas o campo log_id
da
as entradas de registro.
Para realizar várias pesquisas em diversos campos, separe as strings individuais com um espaço. Por exemplo, a instrução a seguir corresponde a linhas em que um campo contém "Hello World", "happy" e "days":
SEARCH(t,"`Hello World` happy days")
Por fim, você pode pesquisar campos específicos em vez de pesquisar um
tabela inteira. Por exemplo, a instrução a seguir pesquisa apenas
as colunas chamadas text_payload
e json_payload
:
SEARCH((text_payload, json_payload) ,"`35.222.132.245`")
Para informações sobre como os parâmetros da função SEARCH
são processados,
consulte a página de referência do BigQuery Funções de pesquisa.
Pesquisa de substring
Para executar um teste que não diferencia maiúsculas de minúsculas para determinar se um valor existe em um
expressão, use a função CONTAINS_SUBSTR
.
Essa função retorna TRUE
quando o valor existe e
Caso contrário, FALSE
. O valor da pesquisa precisa ser um literal STRING
, mas não o
NULL
literal.
Por exemplo, a consulta a seguir busca todas as entradas de registro de auditoria de acesso a dados por um endereço IP específico com carimbos de data/hora de um intervalo de tempo específico. Por fim, a consulta classifica os resultados e mostra os 20 resultados mais antigos:
SELECT
timestamp, log_id, proto_payload, severity, resource.type, resource, labels
FROM
`TABLE_NAME_OF_LOG_VIEW` AS t
WHERE
proto_payload IS NOT NULL AND
log_id = "cloudaudit.googleapis.com/data_access" AND
CONTAINS_SUBSTR(t,"35.193.12.15")
ORDER BY timestamp ASC
LIMIT 20
A consulta anterior executa um teste de substring. Portanto, uma linha que contém
“35.193.12.152” corresponde à instrução CONTAINS_SUBSTR
.
Combine dados de várias fontes
As instruções de consulta verificam uma ou mais tabelas ou expressões e retornam o
de resultados computadas. Por exemplo, você pode usar instruções de consulta para mesclar o
resultados de instruções SELECT
em diferentes tabelas ou conjuntos de dados em uma
de várias maneiras e, em seguida, selecionar as colunas dos dados combinados.
Combinar dados de duas tabelas com mesclagens
Para combinar informações de duas tabelas, use o método join operadores. O tipo de junção e a cláusula condicional que você usa determinam como as linhas são combinadas e descartadas.
A consulta a seguir fornece os campos json_payload
das linhas na
duas tabelas diferentes escritas pelo mesmo período de trace. A consulta executa uma
JOIN
interno em duas tabelas para linhas em que os valores de
as colunas span_id
e trace
nas duas tabelas correspondem. A partir desse resultado,
a consulta seleciona os campos timestamp
, severity
e json_payload
de TABLE_NAME_OF_LOG_VIEW_1, o campo json_payload
do
ABLE_NAME_OF_LOG_VIEW_2, e os valores de span_id
e trace
em que as duas tabelas foram mescladas, e retorna até 100
linhas:
SELECT
a.timestamp, a.severity, a.json_payload, b.json_payload, a.span_id, a.trace
FROM `TABLE_NAME_OF_LOG_VIEW_1` a
JOIN `ABLE_NAME_OF_LOG_VIEW_2` b
ON
a.span_id = b.span_id AND
a.trace = b.trace
LIMIT 100
Combinar várias seleções com uniões
Para combinar os resultados de duas ou mais instruções SELECT
e descartar
linhas duplicadas, use o operador UNION
. Para manter cópias
de linhas, use o operador UNION ALL
.
A consulta a seguir lê a hora mais recente de dados de TABLE_NAME_OF_LOG_VIEW_1, mescla o resultado com a hora mais recente de dados de ABLE_NAME_OF_LOG_VIEW_2, classifica os dados mesclados aumentando e exibe as 100 entradas mais antigas:
SELECT
timestamp, log_name, severity, json_payload, resource, labels
FROM(
SELECT * FROM `TABLE_NAME_OF_LOG_VIEW_1`
UNION ALL
SELECT * FROM `ABLE_NAME_OF_LOG_VIEW_2`
)
ORDER BY timestamp ASC
LIMIT 100
Limitações
As consultas usadas na página Análise de dados de registros são compatíveis com funções do GoogleSQL com algumas exceções.
Os comandos SQL a seguir não são suportados para consultas SQL emitidas usando o Página Análise de dados de registros:
- Comandos DDL e DML
- Funções JavaScript definidas pelo usuário
- Funções do BigQuery ML
- Variáveis SQL
As opções a seguir são suportadas apenas quando você está consultando um conjunto de dados vinculado usando as páginas do BigQuery Studio e do Looker Studio, e as Ferramenta de linha de comando bq:
- Funções JavaScript definidas pelo usuário
- Funções do BigQuery ML
- Variáveis SQL
A seguir
Para saber como rotear e armazenar entradas de registro, consulte os seguintes documentos:
- Crie um bucket de registros
- Fazer upgrade de um bucket para usar a Análise de dados de registros
- Vincular um bucket de registros a um conjunto de dados do BigQuery
- Configurar e gerenciar coletores
Para documentação de referência do SQL, consulte os documentos a seguir: