You need to enable JavaScript to run this app.
导航
WebTracks
最近更新时间:2024.05.20 11:32:00首次发布时间:2022.09.15 14:39:25

调用 WebTracks 接口批量上传日志到指定的日志主题中。

使用说明

本接口用于将多条结构化日志上传到指定的日志主题中。
数据上传要求:

  • 一次请求不可超过 5MiB,每次可以写入的原始日志大小上限为 5MiB,日志组中每条日志不超过 1MiB,一个 LogGroup 中日志个数不能超过 10000 条。
  • 服务端会对每次 WebTracks 请求写入的日志数据进行长度检查,如果超出限制则整个请求失败且无任何日志数据成功写入。

日志上传相关的接口(PutLogs、WebTracks)共用一个调用频率和流量限制的额度,具体限制如下:

  • 接口的总请求频率限制为 500 次/Shard/秒,超出请求频率限制会报错 ExceedQPSLimit。
  • 接口的总流量限制为 5MiB/Shard/s,每个 Shard 中日志解压后的流量限制为 30MiB/s,超出流量限制会报错 ExceedRateLimit。大流量场景下建议开启 Shard 自动分裂,以免影响数据写入效率。

说明

  • 调用此接口之前,需要先为日志主题开启 Web Tracking 功能,详细说明请参考通过 WebTracking 采集日志
  • 通过 API 接口 WebTracks 写入数据时无需经过鉴权,相当于面向公网开放了匿名写入权限,可能产生脏数据。

请求说明

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

请求头

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

Content-Type

String

必选

application/json

日志内容的格式。固定为 application/json。

x-tls-bodyrawsize

String

必选

1024

请求体的原始大小(压缩前),单位为 Byte。

x-tls-compresstype

String

可选

lz4

请求体的压缩格式。默认不压缩。
支持设置为 lz4,表示压缩格式为 lz4。此时需要在请求体中传入压缩后的数据。

请求参数

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

Query

参数
类型
是否必选
示例值
描述

ProjectId

String

5b*********

日志项目 ID。

TopicId

String

4a*********

日志主题 ID。

Body

参数
类型
是否必选
示例值
描述

Logs

Array of Log

必选

[
{
"tap1": "person-A",
"tap2": "action-A"
}
]

日志组(LogGroup),表示由多个 Log 组成的集合,一个 Log 表示一条日志。

说明

一个 LogGroup 中 Log 个数不能超过 10000。

Source

String

可选

postman

日志来源,一般使用机器 IP 作为标识。

Logs 说明

参数
类型
是否必选
示例值
描述

Key

String

必选

tap1

单条日志里某个字段的字段名(key)。
Key 为 UTF-8 编码字符串,支持字母、数字、空格、下划线(_)、连字符(-)和斜线(/),并且不支持以下划线(_)开头、以空格开头或结尾。字符串大小为 1~128 字节。

Value

String

必选

person-A

单条日志里某个字段的字段内容(value)。value 需满足上传要求

返回参数

本接口无特有的返回参数。更多信息请见返回结构

请求示例

POST https://tls-{Region}.ivolces.com/WebTracks?TopicId=c1******&ProjectId=c2******
<公共请求头>
Content-Type: application/json
x-tls-bodyrawsize: 1024
{
    "Source": "postman",
    "Logs": [
        {
            "tap1": "person-A",
            "tap2": "action-A"
        },
        {
            "tap1": "person-B",
            "tap2": "action-B"
        }
    ]
}

返回示例

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

错误码

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

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

InvalidArgument

400

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

参数不合法。

DeserializeFailed

400

Deserialization failed, please check argument.

反序列化失败。

InvalidArgument

400

Parameter count is less than 2

Get 请求除去 ProjectID 和 TopicID 外,key 不能少于 2 个。

TopicNotExist

404

Topic does not exist.

日志主题不存在。

InternalServerError

500

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

服务器内部错误。