Docs

Torch Log Service

Log management API

WebTracks

Call the WebTracks interface to batch upload logs to the specified log topic.

Instructions for use

This interface is used to upload multiple structured logs to the specified log topic.

Data upload requirements:

A request cannot exceed 5MiB, the maximum size of the original log that can be written each time is 5MiB, each log in the log group cannot exceed 1MiB, and the number of logs in a LogGroup cannot exceed 10000.

The server level will check the length of the log data written to each WebTracks request. If the limit is exceeded, the entire request fails and no log data is successfully written.

Log upload related interfaces (PutLogs, WebTracks) share a call frequency and traffic limit amount, the specific limit is as follows:

The total request frequency limit of the interface is 500 times/Shard/second. ExceedQPSLimit will be an error if the request frequency limit is exceeded.

The total traffic limit of the interface is 5MiB/Shard/s, and the traffic limit after log decompression in each Shard is 30MiB/s. ExceedRateLimit will be reported if the traffic limit is exceeded. In large traffic scenarios, it is recommended to turn on Shard automatic splitting to avoid affecting data writing efficiency.

tip

Before calling this interface, you need to enable the Web Tracking function for the log topic. For detailed instructions, please refer to Use web tracking to collect logs.

There is no need for authentication when writing data through the API interface WebTracks, which is equivalent to opening the anonymous write permission to the public network, which may generate dirty data.

URI

Request method	POST
URI	https://{tls-endpoint}/WebTracks?TopicId={TopicId}&ProjectId={ProjectId}
transport protocol	HTTPS

Request header

Name	Type	Required	Example	Description
Content-Type	String	Required	Application/json	Format of log content. Fixed as application/json.
x-tls-bodyrawsize	String	Required	1024	The original size (before compression) of the request body, in bytes.
X-tls-compresstype	String	Optional	LZ4	The compressed format of the request body. Not compressed by default. Support is set to lz4, indicating that the compression format is lz4. At this time, the compressed data needs to be passed in the request body.

URI request parameter

Body request parameter

Name	Type	Required	Example	Description
Logs	Array of Log	Required	[ { "tap1": "person-A", "tap2": "action-A" } ]	LogGroup (LogGroup), which represents a collection of multiple logs, and one log represents one log. tip The number of logs in a LogGroup cannot exceed 10000.
Source	String	optional	Mail carrier	Log source, typically identified by the machine IP.

Log instructions:

Name	Type	Required	Example	Description
Key	String	Required	Tap1	The field name (key) of a field in a single log. Key is a UTF-8 encoded string, supporting letters, numbers, spaces, underscores (_), hyphens (-) and slash (/), and does not support underlining (_) begins, begins or ends with a whitespace. The string size is 1 to 128 bytes.
Value	String	Required	Person-A	The field content (value) of a field in a single log.

Response parameter

None

Example

Request example

Response example

Error code

Error Code	HTTP status code	Message	Description
InvalidArgument	400	Invalid argument key% s, value% s, please check argument.	Parameter is invalid.
DeserializeFailed	400	Deserialization failed, please check argument.	Deserialization failed.
InvalidArgument	400	Parameter count is less than 2	In addition to ProjectID and TopicID, the Get request cannot have fewer than two keys.
TopicNotExist	404	Topic does not exist.	The journal topic does not exist.
InternalServerError	500	We encountered an unexpected server error, please try again later.	Internal server error.

For more information, see Common error codes.

Last updated: 2025.10.29 14:35:21