You need to enable JavaScript to run this app.
导航

SearchLogs

最近更新时间2024.01.25 17:43:09

首次发布时间2022.05.11 11:26:48

调用 SearchLogs 接口检索日志。

使用说明

检索相关的接口(SearchLogs、DescribeLogContext 和 DescribeHistogram)共用一个调用频率和并发限制的额度,具体限制如下:

  • 针对单个火山引擎账号或 IAM 用户,日志检索的请求频率限制为 100 次/秒,否则会收到报错 ExceedQPSLimit。
  • 针对单个日志主题,日志检索并发数限制为 15,否则会收到报错ExceedCountLimit。

说明

  • 调用此接口前,建议阅读检索概述分析概述,了解日志检索分析功能的能力与限制、支持的检索语法与 SQL 分析语法。
  • 检索日志前,请确认已开启了索引。如果需要统计日志,应已为参与统计的日志字段开启了字段索引和统计。
  • 日志数据在日志服务中的存储时间由日志项目的日志保存时间决定,已经过期删除的日志无法进行查询。

请求头

SearchLogs 接口的请求头中,“X-Tls-Apiversion” 应指定为“0.3.0”。其他请求头参数说明请参考公共参数

URI

请求方法
POST

URI

https://tls-{Region}.ivolces.com/SearchLogs

传输协议

HTTPS

请求参数

参数
参数类型
是否必选
示例值
说明

TopicId

String

必选

4a********

要检索的日志主题 ID。

Query

String

必选

error

查询分析语句,语句长度最大为 4 KiB。
日志服务查询分析语句结构请参考分析概述。其中检索语句的语法请参考检索语法,支持的 SQL 分析语法与函数列表请参考分析语法

StartTime

Long

必选

1346457600000

查询开始时间点,精确到毫秒。Unix 时间戳格式,表示从 1970-1-1 00:00:00 UTC 开始计算的毫秒数。如果指定为秒级别,服务端会自动转换精度为毫秒。

EndTime

Long

必选

1630454400000

查询结束时间点,精确到毫秒。Unix 时间戳格式,表示从 1970-1-1 00:00:00 UTC 开始计算的毫秒数。如果指定为秒级别,服务端会自动转换精度为毫秒。

Limit

Integer

可选

30

查询结果分页展示时,此参数用于表示每页的数据量。最大值为 1000,单次最多返回 20MiB 日志数据,通过分页最多返回 100,000 条。

说明

  • 此参数在仅检索时生效,即参数 Query 中只有检索语句,没有分析语句时此参数生效。同时检索分析时,需要在参数 Query 中通过 limit 语法指定返回的日志条数。
  • 该参数用法相当于传统的分页参数 PageSize,不同于日志服务的 Limit 语法

Context

String

可选

[1650349469000,130,9,null]

用于在二次查询时指定继续查询的位点,通常在上下文查询等场景中使用。每次调用 SearchLogs 时,此接口会同时返回数据结尾位点 Context,如果需要查看后续的日志信息,可以再次调用 SearchLogs 接口,并在请求中传入上次响应中获取的 Context。

说明

此参数在仅检索时生效,即参数 Query 中只有检索语句,没有分析语句时此参数生效。同时检索分析时,暂不支持分页。

Sort

String

可选

desc

按日志时间戳顺序返回日志,精确到毫秒。

  • desc:(默认值)按照时间逆序返回日志,新的日志在前。
  • asc:按照时间顺序返回日志,旧的日志在前。

说明

仅当 Query 中只有检索语句,没有分析语句时生效。

响应参数

参数
类型
示例值
描述

ResultStatus

String

complete

查询的状态。

  • complete:查询完成,返回结果完整。
  • incomplete:查询完成,返回部分结果。
  • error:查询未完成,返回错误。
  • time_out :查询超时,返回的结果可能不完整。

HitCount

Integer

9527

搜索匹配的总条目数,总匹配条数小于 10000 条时返回准确数目,大于或等于 10000 条时返回值为 10000。

ListOver

Boolean

true

是否已返回全部的检索结果。

  • true:已返回全部的检索结果。
  • false:未返回全部的检索结果,可以传入 context 继续查询。

说明

仅当 Query 参数中只有检索语句,没有分析语句时,该参数有效。

Analysis

Boolean

false

返回结果的类型。

  • true:返回的是分析结果。
  • false :返回的是查询结果。

Count

Integer

0

分析请求命中的条目数。

Limit

Integer

0

请求中指定返回的 Limit 条目数。默认为 100。

  • 仅检索时,透传请求参数 limit 指定的值。
  • 检索分析时,透传SQL语句中指定的limit。

Context

String

[1650349469000,130,9,null]

用于在二次查询时指定继续查询的位点,通常在上下文查询等场景中使用。每次调用 SearchLogs 时,此接口会同时返回数据结尾位点 Context,如果需要查看后续的日志信息,可以再次调用 SearchLogs 接口,并在请求中传入上次响应中获取的 Context。

Logs

Array of Dictionary

/

返回的日志条目列表。其中:

  • __path__:日志所在的路径及文件名。
  • __source__:日志的来源 IP。
  • __time__:日志产生的时间。
  • __content__:日志全文。
  • __context_flow__:起始日志所在的 LogGroup 的 ID。
  • __package_offset__:起始日志在 LogGroup 的序号。

AnalysisResult

Struct of AnalysisResult

/

分析结果。详细信息请参考 AnalysisResult

示例

请求示例

全文检索

POST https://tls-{Region}.ivolces.com/SearchLogs HTTP/1.1
Content-Type: application/json
...
{
    "TopicId":"c1***********",
    "Query":"error",
    "StartTime":1346457600000,
    "EndTime":1630454400000,
    "Limit":30,
    "Sort":"desc"
}

键值检索

POST https://tls-{Region}.ivolces.com/SearchLogs HTTP/1.1
Content-Type: application/json
...
{
    "TopicId":"c1**********",
    "Query":"name:xiaoming",
    "StartTime":1346457600000,
    "EndTime":1630454400000,
    "Limit":30,
    "Sort":"desc"
}

SQL分析

POST https://tls-{Region}.ivolces.com/SearchLogs HTTP/1.1
Content-Type: application/json
...
{
    "TopicId":"c1***********",
    "Query":"* | select name, age, address",
    "StartTime":1346457600000,
    "EndTime":1630454400000,
    "Limit":30,
    "Sort":"desc"
}

响应示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length:  0

全文检索

{
    "ResultStatus": "complete",
    "HitCount": 20,  // 搜索匹配的总条目数
    "Count": 0,      // sql检索的结果命中行数
    "Limit": 0,      // sql检索的limit条数
    "ListOver":false,
    "Analysis":false,
    "Context":"[1650349469000,130,9,null]",
    "Logs": [
        {
            "__path__": "/root/my_script/tls-conf-master/input_logs/log/hashkey.log",    
            "__source__": "10.17.0.2",  
            "__time__": "1655788239654",    
            "__content__": "", 
            "__context_flow__":"e61050c909dcccc3-f7b3a4bfaf6af941-2",
            "__package_offset__":"3"
        },
        ...
    ],
    "AnalysisResult": {
        "Schema": [],
        "Type": {},
        "Data": []
    }
}

KV检索

{
    "ResultStatus": "complete",
    "HitCount": 20,  // 搜索匹配的总条目数
    "Count": 0,      // sql检索的结果命中行数
    "Limit": 0,      // sql检索的limit条数
    "ListOver":false,
    "Analysis":false,
    "Context":"[1650349469000,130,9,null]",
    "Logs": [
        [
        {
            "__path__": "/root/my_script/tls-conf-master/input_logs/log/hashkey.log",   
            "__source__": "10.17.0.2",  
            "__time__": "1655788239654", 
            "__context_flow__":"e61050c909dcccc3-f7b3a4bfaf6af941-2",
            "__package_offset__":"3",
            "age": "xxx", 
            "class": "xxx",
            ...
        },
        ...
    ],
    "AnalysisResult": {
        "Schema": [],
        "Type": {},
        "Data": []
    }
}

SQL 分析

{
    "ResultStatus": "complete",
    "Analysis": true,
    "ListOver": true,
    "HitCount": 5924,
    "Count": 1,       // sql检索的结果命中行数
    "Limit": 1,       // sql检索的limit条数
    "Logs": [],       
    "AnalysisResult": {
        "Schema": [
            "KeyType",
            "ValueLen",
            "KeyInfo",
            "ValueSize"
        ],
        "Type": {
            "KeyInfo": "text",
            "KeyType": "text",
            "ValueLen": "long",
            "ValueSize": "long"
        },
        "Data": [
            {
                "KeyInfo": "memtier-1",
                "KeyType": "string",
                "ValueLen": "1",
                "ValueSize": "11"
            }
        ]
    },
    "Context": ""
}

错误码

错误码(Code)
HTTP 状态码
错误信息(Message)
说明

InvalidArgument

400

Invalid argument key %s, value %s, please check argument.

参数不合法。

SqlSyntaxError

400

Sql syntax Error,details: Function [%s] cannot work with [%s]. Usage: SUM(NUMBER T) -\u003e T

SQL 格式或语法错误。

TopicNotExist

404

Topic does not exist.

日志主题不存在。

InternalServerError

500

We encountered an unexpected server error, please try again later.

服务器内部错误。

更多信息,请参考通用错误码