操作指南

API 文档

诚邀爱技术、爱分享的你,成为文档内容共建者> HOT

概述

日志服务提供日志检索及分析能力,可通过检索分析语句检索匹配特定条件的日志,或针对匹配的日志使用 SQL 进行统计分析,获取日志条数、平均响应时间和错误日志占比等统计结果。

检索分析语句由检索条件和 SQL 语句组成,两者通过竖线|分割:

[检索条件] | [SQL语句]

  • 检索条件:指定日志需要匹配的条件,返回符合该条件的日志。例如使用status:404检索响应状态码为404的应用请求日志。语法规则可参见 检索条件语法规则
  • SQL语句:针对符合检索条件的日志进行统计分析,返回统计分析结果。例如使用status:404 | select count(*) as logCounts统计响应状态码为404的应用请求日志数量。SQL 语句符合 SQL-92规范,语法规则可参见 SQL 语句语法规则
说明:

  • 只需要检索日志,不需要统计分析时,可省略其中的管道符|及 SQL 语句。
  • 检索分析语句为空时代表检索指定时间范围内的所有日志。

检索条件根据其是否指定了日志字段,分为全文检索和键值检索两种形式:

  • 全文检索:无需指定字段名称,日志内任意字段的值符合检索条件即匹配,例如使用error检索所有出现过 error 的日志。
  • 键值检索:需指定字段名称,日志内指定字段的值符合检索条件即匹配,例如使用level:error检索日志级别为 error 的日志。

前提条件

  • 使用检索条件
    • 全文检索:在索引配置中开启了全文索引
    • 键值检索:
      • 采集日志时按字段对日志进行了提取,即 日志结构化
      • 配置索引 时为需要检索的字段开启了键值索引。
  • 使用 SQL 语句
    • 采集日志时按字段对日志进行了提取,即 日志结构化
    • 配置索引 时为需要检索的字段开启了键值索引且开启统计

检索条件语法规则

语法规则

语法 说明
AND “与”逻辑操作符,例如 level:ERROR AND pid:1234
OR “或”逻辑操作符,例如 level:ERROR OR level:WARNING
NOT “非”逻辑操作符,例如 level:ERROR NOT pid:1234
() 分组操作符,控制逻辑运算优先级,例如 (ERROR OR WARNING) AND pid:1234
冒号,表示作用于的 key 字段,即键值检索,例如 level:ERROR
"" 双引号,引用一个短语,日志需包含短语内的各个词,且各个词的顺序保持不变,例如 name:"john Smith"
* 通配符查询,匹配零个、单个、多个字符,例如 host:www.test*.com
不支持前缀模糊查询,详情请参见 模糊检索
还可以通过 key:* 的方式查询字段(key)存在的日志,等价于 _exists_:key
? 通配符查询,匹配单个字符,例如 host:www.te?t.com
*类似,不支持前缀模糊查询
> 范围操作符,表示大于某个数值,例如 status:>400
>= 范围操作符,表示大于等于某个数值,例如 status:>=400
< 范围操作符,表示小于某个数值,例如 status:<400
<= 范围操作符,表示小于等于某个数值,例如 status:<=400
TO “范围”逻辑操作符,例如 request_time:[0.1 TO 1.0]
[] 范围操作符,包含边界值的范围,例如 age:[20 TO 30]
{} 范围操作符,不包含边界值的范围,例如 age:{20 TO 30}
\ 转义符号,转义后的字符表示符号本身,例如 url:\/images\/favicon.ico
如不想使用转义符,可使用""包裹,例如url:"/images/favicon.ico",但需注意,双引号内的词会被当作一个短语,日志需包含短语内的各个词,且各个词的顺序保持不变
_exists_ _exists_:key,返回 key 存在的日志,例如 _exists_:userAgent 表示搜索存在 userAgent 字段的日志
注意:

  • 语法区分大小写,例如 AND、OR 表示检索逻辑操作符,而 and、or 视为普通文本。
  • 多个检索条件使用空格连接时,视为”或“逻辑,例如 warning error 等价于 warning OR error
  • 检索关键字中存在特殊字符时,需使用转义符进行转义,特殊字符包括 + - && || ! ( ) { } [ ] ^ " ~ * ? : \。
  • 同时使用 AND 和 OR 逻辑运算符时,请使用()对检索条件进行分组,以明确逻辑优先级,例如(ERROR OR WARNING) AND pid:1234

示例

场景 语句
检索来源为某台机器的日志 __SOURCE__:127.0.0.1__SOURCE__:192.168.0.*
检索来源为某个文件的日志 __FILENAME__:"/var/log/access.log"__FILENAME__:\/var\/log\/*.log
检索包含 ERROR 的日志 ERROR
检索失败的日志(状态码大于400) status:>400
检索 GET 请求中失败(状态码大于400)的日志 method:GET AND status:>400
检索 ERRORWARNING 级别的日志 level:ERROR OR level:WARNING
检索非 INFO 级别 的日志 NOT level:INFO
检索192.168.10.10主机上非 INFO 级别的日志 __SOURCE__:192.168.10.10 NOT level:INFO
检索192.168.10.10主机上/var/log/access.log 文件中不包含 INFO 级别的日志 (__SOURCE__:192.168.10.10 AND __FILENAME__:"/var/log/access.log") NOT level:INFO
检索192.168.10.10主机上 ERRORWARNING 级别的日志 __SOURCE__:192.168.10.10 AND (level:ERROR OR level:WARNING)
检索 4XX 状态码的日志 status:[400 TO 500}
检索元数据中容器名为 nginx 的日志 __TAG__.container_name:nginx
检索元数据中容器名为 nginx,且请求延时大于1s 的日志 __TAG__.container_name:nginx AND request_time:>1
检索包含 message 字段的日志 message:*_exists_:message
检索不包含 message 字段的日志 NOT _exists_:message

模糊检索

在日志服务中进行模糊检索,需要在词的中间或末尾加上通配符,可使用*匹配零个、单个、多个字符,或?匹配单个字符,例如:

  • IP:192.168.1.* 表示在日志中查找 IP 为192. 168.1开头的日志,例如192. 168.1.1192. 168.1.34等。
  • host:www.te?t.com 表示在日志中查找 host 为 www.te 开头、t.com 结尾且中间包含1个字符的日志,例如 www.test.comwww.telt.com 等。
注意:

  • *?不能用在词的开头,即不支持前缀模糊检索。
  • long 和 double 类型字段不支持使用*?进行模糊检索,可以使用数值范围进行检索,例如 status:[400 TO 500}

如果您需要使用前缀模糊查询,可使用如下方法替代:

  • 添加分词符:例如日志为 host:www.test.comhost:m.test.com,需要查询字段中间包含 test 的日志,可为该字段添加分词符.,便可以直接使用 host:test 对日志进行检索。
  • 使用 SQL中的 LIKE 语法:例如 * | select * where host like '%test%',但这种方式相比检索条件性能较差,不适合日志数据量过大的场景。

SQL 语句语法规则

语法规则

语法 说明
SELECT 用于从表中选取数据,默认从当前日志主题中获取符合检索条件的数据,例如level:ERROR | select *,非嵌套子查询不需要 from 子句
AS 为列名称(KEY)指定别名,例如level:ERROR | select level as log_level
GROUP BY 用于结合聚合函数,根据一个或多个列(KEY)对结果集进行分组,例如 level:* | select count(*) as logCounts,level group by level
ORDER BY 用于根据指定的 KEY 对结果集进行排序,例如 level:* | select count(*) as logCounts,level group by level order by logCounts desc
LIMIT 用于限制由 SELECT 语句返回的数据数量,例如 level:* | select count(*) as logCounts,level group by level order by logCounts desc limit 5
注意:默认limit 100,最大支持10000
WHERE 用于对查询到的原始数据进行过滤,例如level:ERROR | select * where host like '%test%'
注意:
1. SQL 中的过滤功能相比检索条件性能较差,建议尽可能的使用检索条件满足数据过滤需求,例如使用status:>400 | select count(*) as logCounts代替* | select count(*) as logCounts where status>400 以更快的获得统计结果
2. WHERE 中不能使用 AS 别名,例如level:* | select level as log_level where log_level='ERROR',该语句执行会报错,因为其不符合 SQL-92规范
HAVING 用于对分组聚合后的数据进行过滤,与WHERE的区别在于其作用于分组(GROUP BY)之后,排序(ORDER BY)之前,而WHERE作用于聚合前的原始数据,例如level:* | select count(*) as logCounts,level group by level having count(*) > 100
嵌套子查询 针对一些复杂的统计分析场景,需要先对原始数据进行一次统计分析,再针对该分析结果进行二次统计分析,这时候需要在一个 SELECT 语句中嵌套另一个 SELECT 语句,这种查询方式称为嵌套子查询。例如* | select compare(PV, 86400) from (select count(*) as PV)
注意:

  • SQL 语句对大小写不敏感,SELECT 等效于 select
  • 字符串必须使用单引号''包裹,无符号包裹或被双引号""包裹的字符表示字段或列名。例如'status'表示字符串 status,status"status"表示日志字段 status。
  • 字符串内本身包含单引号'时,需使用''(两个单引号)代表单引号本身。例如'{''version'': ''1.0''}'表示原始字符串{'version': '1.0'}。字符串内本身包含双引号"时无需特殊处理。
  • 不需要在末尾加分号表示 SQL 结束。

SQL 函数

日志服务支持大量的 SQL 函数,全部函数详见 SQL 函数,此处列举一些常用的函数:

语法 说明
字符串函数 支持字符串连接、分割、长度计算和大小写转换等
日期和时间函数 支持时间格式转换、按时间分组统计和时间间隔计算等
IP 地理函数 支持从 IP 解析地理信息等
URL 函数 支持从 URL 获取域名、参数和编解码等
通用聚合函数 支持统计日志条数、数值最大值、最小值和平均值等
估算函数 支持统计唯一值个数、数值 P95/P90 分位值等
类型转换函数 支持转换变量类型,常用于对参数的变量类型有特殊要求的函数内
逻辑函数 AND、OR 和 NOT 等逻辑运算
运算符 +、-、*、/等算术运算和>、<等比较运算
条件表达式 CASE WHEN、IF 等条件判断
数组函数 获取数组元素等
同环比函数 对比当前时间周期内的计算结果与 n 秒之前时间周期内的计算结果
JSON 函数 获取 JSON 对象、JSON 类型转换等

示例

场景 语句
统计 GET 请求中失败(状态码大于400)的日志条数 method:GET AND status:>400 | select count(*) as logCounts
按分钟统计 GET 请求中失败(状态码大于400)的日志条数 method:GET AND status:>400 | select histogram( cast(__TIMESTAMP__ as timestamp),interval 1 minute) as analytic_time, count(*) as log_count group by analytic_time order by analytic_time limit 1000
统计请求数量最大的5个 URL * | select count(*) as PV,URL group by URL order by count(*) desc limit 5
统计平均响应耗时大于1000ms的 URL,并按耗时倒排 * | select avg(responseTime) as time_avg,URL group by URL having avg(responseTime)>1000 order by avg(responseTime) desc limit 10000
统计失败请求百分比 * | select count_if(status>400)*100.00/count(*) as "失败请求百分比"
统计每个 URL 失败请求百分比,并按占比倒排 * | select count_if(status>400)*100.00/count(*) as "失败请求百分比",URL group by URL order by count_if(status>400)*100.00/count(*) desc limit 10000

* | select "失败请求百分比",URL from (select count_if(status>400)*100.00/count(*) as "失败请求百分比",URL group by URL) order by "失败请求百分比" desc limit 10000
统计每个省份的请求数量 * | select ip_to_province(ip) as province, count(*) as PV group by province order by PV desc limit 100

限制说明

指标 限制说明 备注
SQL 结果条数 SQL 返回结果条数最大10000条 默认返回100条结果,可通过 LIMIT 最大返回10000条结果
内存占用量 每次 SQL 执行占用的服务端内存不能超过3GB 通常在使用 group by、distinct()、count(distinct()) 时可能触发该限制,是由于被统计的字段在通过 group by 或 distinct() 去重后值过多导致的。建议优化查询语句,使用值更少的字段对数据进行分组统计;或使用 approx_distinct() 替代count(distinct())。

操作步骤

  1. 登录 日志服务控制台
  2. 在左侧导航栏中,选择检索分析,进入检索分析页面。
  3. 选择待检索的日志集日志主题
  4. 输入检索分析语句,选择时间范围,可以选择近1小时、近4小时、近1天、近3天和自定义时间范围等
  5. 单击检索分析
  6. 当检索分析语句仅包含检索条件时:可在原始数据中查看匹配检索条件的日志,默认按日志时间倒排。
  7. 当检索分析语句包含SQL语句时:可在图表分析中查看分析结果,并可更改图表类型,以更加直观的查看统计结果。同时还会在“原始数据”中查看符合分析语句中检索条件的日志,以便于对比分析统计结果及原始日志。
说明:

  • 在图表分析中,可单击添加至仪表盘将当前图表添加至新的或已有的仪表盘。
  • 在检索分析语句输入框中,可点击输入框右侧的收藏快速添加告警图标收藏当前语句,或新增一条告警策略。

常见问题

目录