检索和分析BLS日志 AsyncSearch
更新时间：2025-10-13
描述
检索和分析BLS日志
接口限制
- 只支持index路径查询，且必须不为空，不支持其他查询参数，如timeout等。对于结构体参数，目前只支持query，aggs, fields, sort, searchAfter, highlight, size
- 查询query和聚合aggs的语法支持参考下面的列表
- 目前不支持随机翻页，因此不支持from结构体参数，只能通过searchAfter的游标获取下一页
- searchAfter下一页字段只支持数组的第一个元素，也只返回一个元素的数组，作为BLS下一页的游标
- 返回结果中没有total参数，没有_score得分，如果需要数据总数，可以通过聚合语法ValueCountAggregation获取
- 目前该函数是同步返回，不支持异步，BLS会一直查询至到超时报错
目前BLS支持的elasticsearch检索语法如下：
- MatchAllQuery
- BoolQuery
- RangeQuery
- TermQuery
- MatchPhrase
- MatchQuery
- WildcardQuery
- MultiMatchQuery
- ExistQuery
- IdsQuery
- PrefixQuery
- QueryStringQuery
- SimpleQueryStringQuery
目前BLS支持的elasticsearch分析语法如下：
- DateHistogramAggregation
- HistogramAggregation
- TermsAggregation
- SamplerAggregation
- RandomSamplerBridgeAggregation
- ValueCountAggregation
- CardinalityAggregation
- MaxAggregation
- MinAggregation
- SumAggregation
- AverageAggregation
- PercentilesAggregation
- StatsAggregation
- FilterAggregation
- FiltersAggregation
请求
- 请求语法
Text
1POST /<name>/_async_search HTTP/1.1
2Host: <Endpoint>
3Authorization: <Authorization String>- 请求头域
除公共请求头域外，无其它特殊头域。
- 请求参数
| 参数名称 | 类型 | 是否必须 | 参数位置 | 描述 |
|---|---|---|---|---|
| name | String | Yes | Path | 索引名称，不支持模糊匹配 |
| query | Object | Yes | RequestBody | 语法同普通queryDSL，语法规则参考官网 |
| aggs | Object | No | RequestBody | 语法桶普通的Aggregations，语法规则参考官网 |
| fields | List<String> | No | RequestBody | 返回的字段列表，默认全部字段 |
| sort | Map<String, Map<String, String>> | No | RequestBody | 排序，目前仅支持按照@timestamp排序，默认按时间倒序 |
| searchAfter | List<String> | No | RequestBody | 下一页游标，目前只支持数组的第一个元素，默认从指定时间的第一个开始查询 |
| highlight | Highlight | No | RequestBody | 高亮配置 |
| size | Int | No | RequestBody | 查询返回多少条命中的日志，默认1000 |
其中 Highlight 对象的元素结构如下：
| 参数名称 | 类型 | 是否必须 | 参数位置 | 描述 |
|---|---|---|---|---|
| pre_tags | List<String> | No | RequestBody | 高亮的前置标识，默认@kibana-highlighted-field@ |
| post_tags | List<String> | No | RequestBody | 高亮的后置标识，默认@/kibana-highlighted-field@ |
成功响应
- 响应头域
除公共响应头域外，无其它特殊头域。
- 响应参数
| 字段 | 类型 | 描述 |
|---|---|---|
| start_time_in_millis | Int | 查询开始时间 |
| expiration_time_in_millis | Int | 查询结束时间 |
| response | Response | 响应体 |
上表中的 Response 对象的元素结构如下：
| 字段 | 类型 | 描述 |
|---|---|---|
| took | Int | 查询耗时 |
| timed_out | Boolean | 是否超时 |
| _shards | Shard | 查询分片情况 |
| hits | Map<String, List |
命中的文档 |
| aggregations | Aggregations | 聚合结果，参考官网 |
其中 Shard 对象的元素结构如下：
| 字段 | 类型 | 描述 |
|---|---|---|
| total | Int | 总共查询的分片数，目前固定为1 |
| successful | Int | 成功的分片数 |
| skipped | Int | 跳过的分片数 |
| failed | Int | 失败的分片数 |
其中 Hit 对象的元素结构如下：
| 字段 | 类型 | 描述 |
|---|---|---|
| _index | String | 项目和日志集信息 如何非default项目，使用 项目$日志集名称 的格式，defualt项目只有日志集名称 |
| _id | String | 日志集记录的ID 由offset和timestamp组成 |
| _score | Double | 得分，目前都是0 |
| sort | List<String> | 排序字段，用于查找下一页, 目前都是单个元素 |
| _version | Int | 版本，目前都是1 |
| fields | Map<String, []Any> | 日志集字段信息 |
| _version | Int | 版本，目前都是1 |
异常响应
- 响应头域
除公共响应头域外，无其它特殊头域。
- 响应参数
| 字段 | 类型 | 描述 |
|---|---|---|
| error | Error | 错误原因 |
| status | Int | http状态码，比如：500 |
上表中的 Error 对象的元素结构如下：
| 字段 | 类型 | 描述 |
|---|---|---|
| root_cause | List<Error> | 根原因 |
| caused_by | Error | 具体的原因 |
| type | String | 错误类型 |
| reason | String | 错误原因 |
示例
- 请求示例
Text
1POST /my-index/_async_search HTTP/1.1
2Host: bls-log.bj.baidubce.com
3Authorization:bce-auth-v1/18717522d39411e9b721df098b0b908c/2019-09-10T07:00:20Z/1800/content-type;host;x-bce-date;x-bce-request-id/6a7cb6c9ac7ec156c805e55e7d0bcfc443b47feee97cf099c1c0d93a0b4c8304
4Content-Type: application/json; charset=utf-8
5{
6 // 必须，es的查询语法，具体支持的语法参考下面的说明
7 "query": {
8 "bool": {
9 "filter": [
10 {
11 "range": {
12 "@timestamp": {
13 "format": "strict_date_optional_time",
14 "gte": "2025-08-01T04:18:44.642Z",
15 "lte": "2025-08-01T06:18:44.642Z"
16 }
17 }
18 }
19 ]
20 }
21 },
22 // 可选，es的聚合语法，具体支持的语法参考下面的说明
23 "aggs": {
24 "0": {
25 "terms": {
26 "field": "level",
27 "order": {
28 "_count": "desc"
29 },
30 "size": 3
31 },
32 "aggs": {
33 "1": {
34 "date_histogram": {
35 "field": "@timestamp",
36 "fixed_interval": "30m",
37 }
38 }
39 }
40 }
41 },
42 // 返回的字段列表，默认全部字段
43 "fields": [
44 {
45 "field": "*",
46 "include_unmapped": "true"
47 }
48 ],
49 // 可选，排序，目前仅支持按照timestamp排序，默认按时间倒序
50 "sort": [
51 {
52 "timestamp": {
53 "order": "desc",
54 }
55 }
56 ],
57 // 可选，下一页游标，目前只支持数组的第一个元素，默认从指定时间的第一个开始查询
58 "searchAfter": [
59 "CJPphaWXMxCMgNz4haWXMxj0Aw"
60 ]
61 // 高亮配置，可选
62 "highlight": {
63 // 可选，高亮的前置标识，默认@kibana-highlighted-field@
64 "pre_tags": [
65 "@kibana-highlighted-field@"
66 ],
67 // 可选，高亮的后置标识，默认@/kibana-highlighted-field@
68 "post_tags": [
69 "@/kibana-highlighted-field@"
70 ]
71 }
72 // 可选，查询返回多少条命中的日志，默认1000
73 "size": 20
74}- 响应示例
Text
1HTTP/1.1 204
2Content-Type: application/json; charset=utf-8
3X-Bce-Request-Id: 2eeba101-4cc7-4cfe-b5ac-a3be8d060e33
4Date: Fri, 10 Apr 2020 04:42:37 GMT
5
6// 成功示例
7{
8 // 查询开始时间
9 "start_time_in_millis": 1696324475123,
10 // 查询结束时间
11 "expiration_time_in_millis": 1696929275123,
12 // 响应体
13 "response": {
14 // 查询耗时
15 "took": 132,
16 // 是否超时
17 "timed_out": false,
18 // 查询分片情况
19 "_shards": {
20 // 总共查询的分片数，目前固定为1
21 "total": 1,
22 // 成功的分片数
23 "successful": 1,
24 // 跳过的分片数
25 "skipped": 0,
26 // 失败的分片数
27 "failed": 0
28 },
29 // 查询命中结果
30 "hits": {
31 // 具体的日志记录信息，一个元素一条日志记录
32 "hits": [
33 {
34 // 项目和日志集信息 如何非default项目，使用 项目$日志集名称 的格式，defualt项目只有日志集名称
35 "_index": "project$logstore",
36 // 日志集记录的ID 由offset和timestamp组成
37 "_id": "1758596174317#28812839737868314",
38 // 得分，目前都是0
39 "_score": 0,
40 // 排序字段，用于查找下一页
41 "sort": [
42 "CJPphaWXMxCMgNz4haWXMxj0Aw"
43 ],
44 // 版本，目前都是1
45 "_version": 1
46 // 日志集字段信息
47 "fields": {
48 // 时间字段
49 "@timestamp": [
50 "2025-09-23T03:32:48.750Z"
51 ],
52 // 索引字段caller
53 "caller": [
54 "middleware/log_request.go:47"
55 ],
56 // 索引字段ip
57 "ip": [
58 "10.164.105.42"
59 ],
60 }
61 }
62 ]
63 },
64 // 日志聚合信息
65 "aggregations": {
66 // 第一个桶聚合信息
67 "0": {
68 "buckets": [
69 {
70 // 第二个桶聚合信息
71 "1": {
72 "buckets": [
73 {
74 // 该桶的总日志数
75 "doc_count": 66626,
76 // 第一个桶的名称
77 "key": 1758508200000,
78 // 字符串信息
79 "key_as_string": "2025-09-22T02:30:00.000+00:00"
80 },
81 {
82 "doc_count": 189923,
83 "key": 1758510000000,
84 "key_as_string": "2025-09-22T03:00:00.000+00:00"
85 },
86 ]
87 },
88 // 第二通桶命中的日志数
89 "doc_count": 9185770,
90 // 第二个桶的名称
91 "key": "info"
92 },
93 {
94 "1": {
95 "buckets": [
96 {
97 "doc_count": 31945,
98 "key": 1758508200000,
99 "key_as_string": "2025-09-22T02:30:00.000+00:00"
100 },
101 {
102 "doc_count": 84637,
103 "key": 1758510000000,
104 "key_as_string": "2025-09-22T03:00:00.000+00:00"
105 }
106 ]
107 },
108 "doc_count": 4093518,
109 "key": "warn"
110 }
111 ],
112 // 错误文档数
113 "doc_count_error_upper_bound": 0,
114 // 其他文档数
115 "sum_other_doc_count": 565
116 }
117 }
118 }
119}
120
121// 异常实例
122{
123 "error": {
124 "root_cause": [
125 {
126 "type": "status_exception",
127 "reason": "exist stat aggregations syntax not support",
128 }
129 ],
130 "caused_by": {
131 "type": "search_phase_execution_exception",
132 "reason": "all shards failed"
133 "caused_by": {
134 "type": "parse_exception",
135 "reason": "exist stat aggregations syntax not support"
136 }
137 }
138 "type": "status_exception",
139 "reason": "error while executing search"
140 },
141 "status": 500
142}