Domain name for API request: cls.intl.tencentcloudapi.com.
To ensure the reliability of your log data and use the log service more efficiently, we recommend that you use the CLS-optimized API to upload structured logs (https://www.tencentcloud.com/document/product/614/16873?from_cn_redirect=1).
Meanwhile, we have specially optimized and customized SDKs in multiple languages for this API for you to choose from. The SDK provides unified async sending, resource control, automatic retry, graceful shutdown, perception reporting, and other features to improve the log reporting function. For details, refer to SDK Collection.
Meanwhile, the log upload API also supports synchronous log data upload. If you select to continue using this API, refer to the following text.
This API is used to write logs to the designated log topic.
| Field name | Data type | Location | Must | Description |
|---|---|---|---|---|
| logGroupList | message | pb | Yes | logGroup list, encapsulated content of the log group list. It is advisable not to exceed 5 logGroups. |
Group description:
| Field name | Required or optional | Description |
|---|---|---|
| logs | is | a log array, which means a set of multiple logs. One Log represents one log, and the number of logs in one LogGroup cannot exceed 10000 |
| contextFlow | No | The unique ID of LogGroup, which must be imported when using context features. Format: "{context ID}-{LogGroupID}". Context ID: A unique identifier for a context (a series of consecutively scrolled log files or a sequence of logs requiring order preservation), a 64-bit integer string in base 16. LogGroupID: A consecutively incremental integer string in base 16. Example: "102700A66102516A-59F59". |
| filename | No | Log file name |
| source | No | Log source, using machine IP as a label in general use |
| logTags | No | Log tag list |
Log description:
| field name | Required or optional | Description |
|---|---|---|
| time | is | log time (Unix timestamp), supports second, millisecond, microsecond, milliseconds is recommended |
| contents | No | Key-value formatted log content, representing multiple key-value composites in a log |
Content description:
| Field name | Required or optional | Description |
|---|---|---|
| key | Yes | The key value of a field group in a single-line log. It cannot start with _ |
| value | Yes | The value of a field group in a single-line log. The value of a single-line log must not exceed 1MB, and the sum of ALL values in a LogGroup cannot exceed 5MB. |
LogTag description:
| Field name | Required or optional | Description |
|---|---|---|
| key | Yes | Custom tag key |
| value | is | value corresponding to the custom tag key |
This example shows how to use the official protoc compiler to compile and generate a C++ language adjustable log upload API from a description file.
Currently protoc officially supports compilation for languages such as Java, C++, and Python. For details, see protoc.
Download Protocol Buffer, unzip and install. The example version is protobuf 2.6.1, and the environment is Centos 7.3 system. Decompress the protobuf-2.6.1.tar.gz compressed package to the /usr/local directory and enter the directory. Execute the command as follows:
tar -zxvf protobuf-2.6.1.tar.gz -C /usr/local/ && cd /usr/local/protobuf-2.6.1
Start compilation and installation, configure environment variables, execute the command as follows:
[root@VM_0_8_centos protobuf-2.6.1]# ./configure
[root@VM_0_8_centos protobuf-2.6.1]# make && make install
[root@VM_0_8_centos protobuf-2.6.1]# export PATH=$PATH:/usr/local/protobuf-2.6.1/bin
After successful compilation, view the version using the following command:
[root@VM_0_8_centos protobuf-2.6.1]# protoc --version
liprotoc 2.6.1
The PB description file is the data interchange format agreed by the communication parties. When uploading logs, compile the specified protocol format into the calling interface of the corresponding language version, then add to engineering code. For details, see protoc.
Create a local PB message description file cls.proto based on the PB data format specified by the log service.
!PB description file content immutable, and the file name must end with .proto.
The content of cls.proto (PB description file) is as follows:
package cls;
message Log
{
message Content
{
required string key = 1; // key for each group of fields
required string value = 2; // The value of the group field
}
required int64 time = 1; // A timestamp in UNIX time format
repeated Content contents = 2; // multiple kv combinations in a log
}
message LogTag
{
required string key = 1;
required string value = 2;
}
message LogGroup
{
repeated Log logs = 1; // log array composed of multiple logs
optional string contextFlow = 2; // Currently no utility
optional string filename = 3; // log file name
optional string source = 4; // log source, general use machine IP
repeated LogTag logTags = 5;
}
message LogGroupList
{
repeated LogGroup logGroupList = 1; // log group list
}
In this example, use the proto compiler to generate C++ language files under the same directory as the cls.proto file and execute the following compilation command:
protoc --cpp_out=./ ./cls.proto
--cpp_out=./ means compile to cpp format and output in the current directory. ./cls.proto refers to the cls.proto description file located in the current directory.
After successful compilation, it will output the code file in the corresponding language. This routine generates the cls.pb.h header file and the cls.pb.cc code implementation file, as shown below:
[root@VM_0_8_centos protobuf-2.6.1]# protoc --cpp_out=./ ./cls.proto
[root@VM_0_8_centos protobuf-2.6.1]# ls
cls.pb.cc cls.pb.h cls.proto
Import the generated cls.pb.h header file into the code and call the interface to encapsulate the data format.
A maximum of 100000 requests can be initiated per second for this API.
Note: this API can only use HTTP method POST with application/octet-stream content type.
The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.
Note: this API only supports the application/octet-stream type, and can only be called using the signature method V3, and the request parameters must be placed in the request header.
| Parameter Name | Required | Type | Description |
|---|---|---|---|
| X-TC-Action | Yes | String | Common Params. The value used for this API: UploadLog. |
| X-TC-Version | Yes | String | Common Params. The value used for this API: 2020-10-16. |
| X-TC-Region | Yes | String | Common Params. For more information, please see the list of regions supported by the product. |
| X-CLS-TopicId | Yes | String | Log topic id -Obtain the log topic Id through Get Log Topic List. |
| X-CLS-CompressType | No | String | Compression method. Currently supports - lz4 - zstd |
| Parameter Name | Type | Description |
|---|---|---|
| RequestId | String | The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem. |
upload log
POST / HTTP/1.1
{
"X-TC-Action": "UploadLog",
"Host": "cls.intl.tencentcloudapi.com",
"Content-Type": "application/x-protobuf",
"TopicId": "f6c4fa6f-xxxx-xxxx-8289-1ff6f77ed975",
"CompressType": "lz4"
}
<LogGroupList's PB format compression package content>
{
"Response": {
"RequestId": "6ef60bec-xxxx-xxxx-bb20-270359fb54a7"
}
}
TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.
The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.
| Error Code | Description |
|---|---|
| FailedOperation | Operation failed. |
| FailedOperation.MissingContent | Invalid Content. |
| FailedOperation.ReadQpsLimit | The read QPS exceeds the limit. |
| FailedOperation.Timeout | Operation timed out |
| FailedOperation.TopicClosed | The log topic has been disabled. |
| FailedOperation.TopicIsolated | The log topic has been isolated. |
| FailedOperation.WriteQpsLimit | The write QPS exceeds the limit. |
| FailedOperation.WriteTrafficLimit | The write traffic exceeds the limit. |
| InternalError | Internal error. |
| InvalidParameter | Incorrect parameter. |
| InvalidParameter.Content | Invalid Content. |
| LimitExceeded.LogSize | The log size exceeds the limit. |
| LimitExceeded.Tag | The number of tags exceeds the limit. |
| MissingParameter | Missing parameter. |
| OperationDenied | Operation denied. |
| OperationDenied.ACLFailed | ACL verification failed. |
| OperationDenied.AccountDestroy | The account has been terminated. |
| OperationDenied.AccountIsolate | The account has overdue payments. |
| OperationDenied.AccountNotExists | The account does not exist. |
| ResourceNotFound.PartitionNotExist | The partition does not exist. |
| ResourceNotFound.TopicNotExist | The log topic does not exist. |
| UnsupportedOperation | Unsupported operation. |
Apakah halaman ini membantu?
Anda juga dapat Menghubungi Penjualan atau Mengirimkan Tiket untuk meminta bantuan.
masukan