You need to enable JavaScript to run this app.
导航
日志服务
  • 文档首页
    • /
  • 日志服务

WebTracks

最近更新时间：2023.11.13 16:31:31

首次发布时间：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 写入数据时无需经过鉴权，相当于面向公网开放了匿名写入权限，可能产生脏数据。

URI

请求方法
POST

URI

https://tls-{Region}.ivolces.com/WebTracks?TopicId={TopicId}&ProjectId={ProjectId}

传输协议

HTTPS

请求头

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

Content-Type

String

必选

application/json

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

x-tls-bodyrawsize

String

必选

1024

请求体的原始大小（压缩前），单位为 Byte。

x-tls-compresstype

String

可选

lz4

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

URI请求参数

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

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 作为标识。

Log 说明：

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

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.

服务器内部错误。

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