You need to enable JavaScript to run this app.
导航
SearchLogs
最近更新时间:2024.09.12 15:05:12首次发布时间:2022.05.11 11:26:48

调用 SearchLogs 接口检索日志。

使用说明

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

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

说明

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

注意事项

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

请求说明

  • 请求方式:POST
  • 请求地址:https://tls-{Region}.ivolces.com/SearchLogs

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数

Body

参数类型是否必选示例值描述
TopicIdString4a********要检索的日志主题 ID。

Query

String

error

查询分析语句,语句长度最大为 4 KiB。

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

StartTimeInteger1346457600000查询开始时间点,精确到毫秒。Unix 时间戳格式,表示从 1970-1-1 00:00:00 UTC 开始计算的毫秒数。如果指定为秒级别,服务端会自动转换精度为毫秒。
EndTimeInteger1630454400000查询结束时间点,精确到毫秒。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 中只有检索语句,没有分析语句时生效。

HighLight

Boolean

false

搜索的关键字在查询结果中是否高亮显示。
AccurateQuery

AccurateQuery

Boolean

true

是否使用纳秒精度查询日志。

  • true:使用纳秒精度查询日志。
  • false:使用毫秒精度查询日志。

返回参数

下表仅列出本接口特有的返回参数。更多信息请参见返回结构

参数类型示例值描述

ResultStatus

String

complete

查询的状态。

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

HitCount

Integer

9527

  • 在 1.0 架构中,HitCount 表示搜索匹配的总条目数,总匹配条数小于 10000 条时返回准确数目,大于或等于 10000 条时返回值为 10000。
  • 在 2.0 架构中,该参数无意义,请勿使用。

ListOver

Boolean

true

是否已返回全部结果。

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

说明

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

Analysis

Boolean

false

返回结果的类型。

  • true:返回的是分析结果。
  • false :返回的是查询结果。
CountInteger0分析请求命中的条目数。

Limit

Integer

0

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

  • 仅检索时,透传请求参数 limit 指定的值。
  • 检索分析时,透传SQL语句中指定的limit。
ContextString[1650349469000,130,9,null]用于在二次查询时指定继续查询的位点,通常在上下文查询等场景中使用。每次调用 SearchLogs 时,此接口会同时返回数据结尾位点 Context,如果需要查看后续的日志信息,可以再次调用 SearchLogs 接口,并在请求中传入上次响应中获取的 Context。

Logs

Array of JSON Map

/

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

  • __path__:日志所在的路径及文件名。
  • __source__:日志的来源 IP。
  • __time__:日志产生的时间。
  • __content__:日志全文。
  • __context_flow__:起始日志所在的 LogGroup 的 ID。
  • __package_offset__:起始日志在 LogGroup 的序号。
AnalysisResultObject of AnalysisResult/分析结果。
HighLightArray of JSON Map/高亮显示的关键字。

AnalysisResult

参数类型示例值描述
DataArray of JSON Map[{ "KeyInfo": "key:000000000940", "KeyType": "string", "ValueLen": "1", }]分析结果返回的键值对。
TypeJSON Map{ "KeyInfo": "text", "KeyType": "text", "ValueLen": "long", }日志分析列对应的属性。
SchemaArray of String["KeyType","ValueLen","KeyInfo"]日志分析列的名称。

请求示例 1

全文检索

{
    "TopicId":"c1***********",
    "Query":"error",
    "StartTime":1346457600000,
    "EndTime":1630454400000,
    "Limit":30,
    "Sort":"desc"
}

返回示例 1

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": []
    }
}

请求示例 2

键值检索

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"
}

返回示例 2

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",
                "__context_flow__": "e61050c909dcccc3-f7b3a4bfaf6af941-2",
                "__package_offset__": "3",
                "age": "xxx",
                "class": "xxx"
            },
        ],
        "AnalysisResult": {
            "Schema": [],
            "Type": {},
            "Data": []
        }
    }

请求示例 3

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"
}

返回示例 3

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length:  0
{
    "ResultStatus": "complete",
    "Analysis": true,
    "ListOver": true,
    "HitCount": 5924,
    "Count": 1, // sql检索的结果命中行数
    "Limit": 1, // sql检索的limit条数
    "Logs": [],
    "AnalysisResult": {
        "Schema": [
            "name",
            "age",
            "address"
        ],
        "Type": {
            "name": "text",
            "age": "long",
            "address": "text"
        },
        "Data": [
            {
                "name": "zhangsan",
                "age": "29",
                "address": "zhengjiang"
            }
        ]
    },
    "Context": ""
}

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

HTTP 状态码错误码错误信息说明
400InvalidArgumentInvalid argument key %s, value %s, please check argument.参数不合法。
400SqlSyntaxErrorSql syntax Error,details: Function [%s] cannot work with [%s]. Usage: SUM(NUMBER T) -\u003e TSQL 格式或语法错误。
404TopicNotExistTopic does not exist.日志主题不存在。
500InternalServerErrorWe encountered an unexpected server error, please try again later.服务器内部错误。
400SearchSyntaxErrorThe key-value index for field (%s) is not configured.未对查询字段配置键值索引。