本文档包含对存储在日志存储分区(已升级为使用 Log Analytics)中的日志条目的查询示例。在这些存储分区中,您可以从 Google Cloud 控制台的 Log Analytics 页面运行 SQL 查询。如需查看更多示例,请参阅 logging-analytics-samples
和 security-analytics
GitHub 代码库。
本文档不介绍 SQL 或如何路由和存储日志条目。如需了解这些主题,请参阅后续步骤部分。
准备工作
要在 Log Analytics 页面上使用本文档中显示的查询,请将 TABLE 替换为与您要查询的视图对应的表的名称。表名称的格式为
project_ID.region.bucket_ID.view_ID
。您可以在 Log Analytics 页面上找到视图的表名称;日志视图的默认查询会在FROM
语句中列出表名称。如需了解如何访问默认查询,请参阅查询日志视图。如需使用 BigQuery Studio 页面上本文档中显示的查询,请将 TABLE 替换为关联数据集内的表的路径。 例如,如需查询项目
myproject
中的关联数据集mydataset
的视图_AllLogs
,请将此字段设置为myproject.mydataset._AllLogs
:在 Google Cloud 控制台的导航面板中,选择 BigQuery:
如需打开日志分析页面,请执行以下操作:
-
在 Google Cloud 控制台的导航面板中,选择 Logging,然后选择 Log Analytics:
可选:如需确定日志视图的表架构,请在日志视图列表中找到该视图,然后选择该视图的名称。
系统随即会显示表的架构。您可以使用过滤条件字段来查找特定字段。您无法修改架构。
-
过滤日志
SQL 查询确定要处理表的哪些行,然后对这些行进行分组并执行聚合操作。如果未列出分组和聚合操作,则查询结果包含过滤操作选择的行。本部分中的示例说明了如何过滤。
按时间过滤
如需设置查询的时间范围,我们建议您使用时间范围选择器。当查询未在 WHERE
子句中指定 timestamp
字段时,系统会自动使用此选择器。例如,如需查看过去一周的数据,请从时间范围选择器中选择过去 7 天。您还可以使用时间范围选择器指定开始和结束时间、指定查看周围环境的时间以及更改时区。
如果您在 WHERE
子句中包含 timestamp
字段,则不会使用时间范围选择器设置。以下示例使用 TIMESTAMP_SUB
函数过滤数据,该函数可让您指定相对于当前时间的回溯期:
WHERE
timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
按资源过滤
如需按资源过滤,请添加 resource.type
限制。
例如,以下查询会读取最近一个小时的数据,并保留资源类型与 gce_instance
匹配的行,然后排序并显示最多 100 个条目:
SELECT
timestamp, log_name, severity, json_payload, resource, labels
FROM
`TABLE`
WHERE
resource.type = "gce_instance"
ORDER BY timestamp ASC
LIMIT 100
按严重程度过滤
您可以使用 severity = 'ERROR'
等限制按特定严重程度进行过滤。另一种方法是使用 IN
语句并指定一组有效值。
例如,以下查询会读取最近一个小时的数据,然后仅保留包含 severity
字段(其值为 'INFO'
或 'ERROR'
)的行:
SELECT
timestamp, log_name, severity, json_payload, resource, labels
FROM
`TABLE`
WHERE
severity IS NOT NULL AND
severity IN ('INFO', 'ERROR')
ORDER BY timestamp ASC
LIMIT 100
上一个查询按 severity
字段的值进行过滤。但是,您也可以编写按日志严重性数值进行过滤的查询。例如,如果将 severity
行替换为以下行,查询将返回严重级别至少为 NOTICE
的所有日志条目:
severity_number IS NOT NULL AND
severity_number > 200
如需了解枚举值,请参阅 LogSeverity
。
按日志名称过滤
如需按日志名称进行过滤,您可以对 log_name
或 log_id
字段的值添加限制。log_name
字段包含资源路径。也就是说,此字段的值类似于 projects/myproject/logs/mylog
。log_id
字段仅存储日志名称,例如 mylog
。
例如,以下查询会读取最近一个小时的数据,并保留 log_id
字段中值为 cloudaudit.googleapis.com/data_access
的行,然后排序并显示结果:
SELECT
timestamp, log_id, severity, json_payload, resource, labels
FROM
`TABLE`
WHERE
log_id = "cloudaudit.googleapis.com/data_access"
ORDER BY timestamp ASC
LIMIT 100
按资源标签过滤
大多数受监控的资源描述符都定义了用于标识特定资源的标签。例如,Compute Engine 实例的描述符包括可用区、项目 ID 和实例 ID 的标签。写入日志条目时,系统会为每个字段分配值。以下是此类示例:
{
type: "gce_instance"
labels: {
instance_id: "1234512345123451"
project_id: "my-project"
zone: "us-central1-f"
}
}
由于 labels
字段的数据类型是 JSON,因此在查询中包含 resource.labels.zone = "us-centra1-f"
等限制会导致语法错误。如需获取数据类型为 JSON 的字段的值,请使用函数 JSON_VALUE
。
例如,以下查询会读取最近的数据,如果资源是位于 us-central1-f
地区的 Compute Engine 实例,则保留这些行:
SELECT
timestamp, log_name, severity, JSON_VALUE(resource.labels.zone) AS zone, json_payload, resource, labels
FROM
`TABLE`
WHERE
resource.type = "gce_instance" AND
JSON_VALUE(resource.labels.zone) = "us-central1-f"
ORDER BY timestamp ASC
LIMIT 100
如需了解可检索和转换 JSON 数据的所有函数,请参阅 JSON 函数。
按 HTTP 请求过滤
如需过滤表以仅包含与 HTTP 请求或回复对应的行,请添加 http_request IS NOT NULL
限制:
SELECT
timestamp, log_name, severity, http_request, resource, labels
FROM
`TABLE`
WHERE
http_request IS NOT NULL
ORDER BY timestamp
LIMIT 100
以下查询仅包含与 GET
或 POST
请求对应的行:
SELECT
timestamp, log_name, severity, http_request, resource, labels
FROM
`TABLE`
WHERE
http_request IS NOT NULL AND
http_request.request_method IN ('GET', 'POST')
ORDER BY timestamp ASC
LIMIT 100
按 HTTP 状态过滤
如需按 HTTP 状态进行过滤,请修改 WHERE
子句以要求定义 http_request.status
字段:
SELECT
timestamp, log_name, http_request.status, http_request, resource, labels
FROM
`TABLE`
WHERE
http_request IS NOT NULL AND
http_request.status IS NOT NULL
ORDER BY timestamp ASC
LIMIT 100
如需确定存储在字段中的数据类型,请查看架构或显示该字段。上一个查询的结果显示,http_request.status
字段存储的是整数值。
按 JSON 类型的字段过滤
如需从数据类型为 JSON 的列中提取值,请使用函数 JSON_VALUE
。
请考虑以下查询:
SELECT
json_payload
FROM
`TABLE`
WHERE
json_payload.status IS NOT NULL
和
SELECT
json_payload
FROM
`TABLE`
WHERE
JSON_VALUE(json_payload.status) IS NOT NULL
前面的查询测试 json_payload
列的值;此列的内容由日志条目的内容决定。这两个查询都会舍弃不包含标记为 json_payload
的列的行。这两个查询之间的区别是最后一行,它定义了要针对 NULL
进行测试的内容。现在,假设一个表有两行。一行中,json_payload
列采用以下格式:
{
status: {
measureTime: "1661517845"
}
}
在其他行中,json_payload
列的结构有所不同:
{
@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"
}
前两行都满足 json_payload.status IS NOT NULL
限制。也就是说,查询结果包含这两行数据。
但是,如果限制为 JSON_VALUE(json_payload.status) IS NOT NULL
,则结果中仅包含第二行。
按正则表达式过滤
如需返回与正则表达式匹配的子字符串,请使用函数 REGEXP_EXTRACT
。此函数的返回类型是 STRING
或 BYTES
。
以下查询会显示最近收到的日志条目,使用 json_payload.jobName
字段保留这些条目,然后显示以 test
开头的部分名称:
SELECT
timestamp, REGEXP_EXTRACT(JSON_VALUE(json_payload.jobName), r".*(test.*)$") AS name,
FROM
`TABLE`
WHERE
json_payload.jobName IS NOT NULL
ORDER BY timestamp DESC
LIMIT 20
如需查看其他示例,请参阅 REGEXP_EXTRACT
文档。如需查看您可以使用的其他正则表达式的示例,请参阅函数、运算符和条件。
此示例中显示的查询效率低下。对于子字符串匹配(如图所示),请使用 CONTAINS_SUBSTR
函数。
对日志条目进行分组和汇总
本部分以前面的示例为基础,说明了如何对表行进行分组和汇总。如果未指定分组,但指定了聚合,则会输出单个结果,因为 SQL 会将满足 WHERE
子句的所有行视为单个组。
每个 SELECT
表达式都必须包含在组字段中,或者进行汇总。
按时间分组
如需按时间对数据进行分组,请使用函数 TIMESTAMP_TRUNC
,该函数会将时间戳截断为指定的粒度(如 MINUTE
)。例如,当粒度设置为 MINUTE
时,格式为 hours:minutes:seconds
的 15:30:11
时间戳会变为 15:30:00
。
以下查询会读取在时间范围选择器指定的时间间隔内接收的数据,然后保留 json_payload.status
字段的值不为 NULL 的那些行。该查询会按小时截断每行的时间戳,然后按截断的时间戳和状态对行进行分组:
SELECT
TIMESTAMP_TRUNC(timestamp, HOUR) AS hour,
JSON_VALUE(json_payload.status) AS status,
COUNT(*) AS count
FROM
`TABLE`
WHERE
json_payload IS NOT NULL AND
JSON_VALUE(json_payload.status) IS NOT NULL
GROUP BY hour,status
ORDER BY hour ASC
如需查看其他示例,请参阅 TIMESTAMP_TRUNC
文档。如需了解其他基于时间的函数,请参阅日期时间函数。
按资源分组
以下查询会读取最近一个小时的数据,然后按资源类型对行进行分组。然后,它会计算每种类型的行数,并返回一个包含两个列的表。第一列列出资源类型,而第二列是该资源类型的行数:
SELECT
resource.type, COUNT(*) AS count
FROM
`TABLE`
GROUP BY resource.type
LIMIT 100
按严重程度分组
以下查询会读取最近一小时的数据,然后保留具有严重级别字段的行。然后,查询按严重性对行进行分组,并计算每个组的行数:
SELECT
severity, COUNT(*) AS count
FROM
`TABLE`
WHERE
severity IS NOT NULL
GROUP BY severity
ORDER BY severity
LIMIT 100
按log_id
分组
以下查询的结果是一个包含两个列的表。第一列列出日志名称,第二列列出最近一小时内写入该日志的日志条目数。该查询按条目数对结果进行排序:
SELECT
log_id, COUNT(*) AS count
FROM
`TABLE`
GROUP BY log_id
ORDER BY count DESC
LIMIT 100
计算 HTTP 请求的平均延迟时间
以下查询说明了如何按多列进行分组,以及如何计算平均值。该查询按 HTTP 请求中包含的网址和 labels.checker_location
字段的值对行进行分组。对行进行分组后,查询会计算每组的平均延迟时间:
SELECT
JSON_VALUE(labels.checker_location) AS location,
AVG(http_request.latency.seconds) AS secs, http_request.request_url
FROM
`TABLE`
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
在前面的表达式中,需要 JSON_VALUE
才能提取 labels.checker_location
字段的值,因为 labels
的数据类型是 JSON。但是,您不能使用此函数从 http_request.latency.seconds
字段中提取值。后一个字段的数据类型为整数。
计算为子网测试发送的平均字节数
以下查询说明了如何显示按位置发送的平均字节数。
该查询会读取最近一个小时的数据,然后仅保留资源类型列为 gce_subnetwork
且 json_payload
列不为 NULL 的行。接下来,查询按资源位置对行进行分组。与之前将数据存储为数值的示例不同,bytes_sent
字段的值是字符串,因此您必须先将该值转换为 FLOAT64
,然后才能计算平均值:
SELECT JSON_VALUE(resource.labels.location) AS location,
AVG(CAST(JSON_VALUE(json_payload.bytes_sent) AS FLOAT64)) AS bytes
FROM
`TABLE`
WHERE
resource.type = "gce_subnetwork" AND
json_payload IS NOT NULL
GROUP BY location
LIMIT 100
上一次查询的结果是一个表,其中的每一行都列出了一个位置以及发送到该位置的平均字节数。
如需了解可检索和转换 JSON 数据的所有函数,请参阅 JSON 函数。
如需了解 CAST
和其他转换函数,请参阅转换函数。
计算包含与某种模式匹配的字段的日志条目数
如需返回与正则表达式匹配的子字符串,请使用函数 REGEXP_EXTRACT
。此函数的返回类型是 STRING
或 BYTES
。
以下查询会保留 json_payload.jobName
字段的值不为 NULL 的日志条目。然后,它会按以 test
开头的名称后缀对条目进行分组。最后,该查询会计算每个组中条目的数量:
SELECT
REGEXP_EXTRACT(JSON_VALUE(json_payload.jobName), r".*(test.*)$") AS name,
COUNT(*) AS count
FROM
`TABLE`
WHERE
json_payload.jobName IS NOT NULL
GROUP BY name
ORDER BY count
LIMIT 20
如需查看其他示例,请参阅 REGEXP_EXTRACT
文档。如需查看您可以使用的其他正则表达式的示例,请参阅函数、运算符和条件。
跨列搜索
本部分介绍了可用于搜索表的多列的两种不同方法。
基于令牌的搜索
如需在表中搜索与一组搜索字词匹配的条目,请使用函数 SEARCH
。此函数需要两个参数:搜索位置和搜索查询。由于 SEARCH
函数对数据的搜索方式有特定的规则,因此我们建议您阅读 SEARCH
文档。
以下查询仅保留字段与“35.193.12.15”完全匹配的行:
SELECT
timestamp, log_id, proto_payload, severity, resource.type, resource, labels
FROM
`TABLE` 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
在上一个查询中,反引号封装了要搜索的值。这可确保 SEARCH
函数搜索字段值与反引号之间的值之间的完全匹配项。
如果查询字符串中省略了反引号,则系统会根据 SEARCH
文档中定义的规则拆分查询字符串。例如,当以下语句运行时,查询字符串会拆分为四个词法单元:“35”“193”“12”和“15”:
SEARCH(t,"35.193.12.15")
当单个字段与所有四个词元匹配时,前面的 SEARCH
语句将匹配一行。令牌的顺序无关紧要。
您可以在一个查询中包含多个 SEARCH
语句。例如,在上一个查询中,您可以将针对日志 ID 的过滤条件替换为如下语句:
SEARCH(t,"`cloudaudit.googleapis.com/data_access`")
上一个语句搜索整个表,而原始语句仅搜索 log_id
列。
要对某一列执行多次搜索,请使用空格分隔各个字符串。例如,以下语句匹配字段包含“Hello World”“happy”和“days”的行:
SEARCH(t,"`Hello World` happy days")
最后,您可以搜索表的特定列,而不是搜索整个表。例如,以下语句仅搜索名为 text_payload
和 json_payload
的列:
SEARCH((text_payload, json_payload) ,"`35.222.132.245`")
如需了解如何处理 SEARCH
函数的参数,请参阅 BigQuery 参考页面搜索函数。
子字符串搜索
如需执行不区分大小写的测试以确定表达式中是否存在某个值,请使用函数 CONTAINS_SUBSTR
。当值存在时,此函数返回 TRUE
,否则返回 FALSE
。搜索值必须是 STRING
字面量,但不能是字面量 NULL
。
例如,以下查询会提取具有特定 IP 地址且时间戳在特定时间范围内的所有数据访问审核日志条目。最后,该查询会对结果进行排序,然后显示时间最早的 20 条结果:
SELECT
timestamp, log_id, proto_payload, severity, resource.type, resource, labels
FROM
`TABLE` 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
上一个查询执行子字符串测试。因此,包含“35.193.12.152”的行与 CONTAINS_SUBSTR
语句匹配。
合并来自多个来源的数据
查询语句可扫描一个或多个表或表达式,并返回计算结果行。例如,您可以使用查询语句以各种方式合并不同表或数据集上 SELECT
语句的结果,然后从组合数据中选择列。
使用联接合并两个表中的数据
如需组合两个表中的信息,请使用其中一个 join 运算符。您使用的联接类型和条件子句决定了行的组合和舍弃方式。
以下查询为您提供了由同一跟踪 span 写入的两个不同表中的行的 json_payload
字段。该查询对两个表中的 span_id
和 trace
列值均匹配的行执行内部 JOIN
。然后,查询会根据此结果选择来自 TABLE_1 的 timestamp
、severity
和 json_payload
字段、来自 TABLE_2 的 json_payload
字段以及两个表联接的 span_id
和 trace
字段的值,并最多返回 100 行:
SELECT
a.timestamp, a.severity, a.json_payload, b.json_payload, a.span_id, a.trace
FROM `TABLE_1` a
JOIN `TABLE_2` b
ON
a.span_id = b.span_id AND
a.trace = b.trace
LIMIT 100
使用并集组合多项选择
如需合并两个或更多 SELECT
语句的结果并舍弃重复行,请使用 UNION
运算符。如需保留重复行,请使用 UNION ALL
运算符。
以下查询从 TABLE_1 读取最近一个小时的数据,将结果与 TABLE_2 中最近一个小时的数据合并,通过增加时间戳对合并的数据进行排序,然后显示最早的 100 个条目:
SELECT
timestamp, log_name, severity, json_payload, resource, labels
FROM(
SELECT * FROM `TABLE_1`
UNION ALL
SELECT * FROM `TABLE_2`
)
ORDER BY timestamp ASC
LIMIT 100
后续步骤
如需了解如何路由和存储日志条目,请参阅以下文档:
如需获取 SQL 参考文档,请参阅以下文档: