1. 前言

安装使用Python SDK可以帮助开发者快速接入并使用天翼云的云日志服务相关功能。

2. 使用条件

2.1. 先决条件

用户需要具备以下条件才能够使用LTS SDK Python 版本：

1、购买并订阅了天翼云的云日志服务，并创建了日志项目和日志单元，获取到相应编码（logProject、logUnit）。

2、已获取AccessKey 和 SecretKey。

3、已安装Python3.6或以上版本。

2.2. 下载及安装

下载压缩包，放到相应位置后并解压。“ctyun_lts_python_sdk”目录中“example”为SDK的使用示例代码。

在“ctyun_lts_python_sdk”目录下执行标准 python 包安装命令：

# python setup.py install

安装命令会安装SDK所需要的依赖包，并将整个SDK作为一个python包安装到您的python环境中。其中会同步安装lz4、six、protobuf>=3.5.2、requests。

如果上述命令安装不成功，也可以手动逐步安装这四个python包。

pip install requests==2.27.1
pip install lz4==3.1.10
pip install six
pip install protobuf==3.5.2

之后可以通过一下命令查看是否安装成功，安装后的python包名为ctyun-lts-python-sdk。

pip list    # 成功安装会出现 ctyun-lts-python-sdk

如果修改了SDK的源码，并希望重新安装使用，可以先卸载再安装。

pip uninstall ctyun-lts-python-sdk
python setup.py install

安装完python包之后，只需要引入lts的包就可以使用SDK的功能了。

from lts import LogItem, get_current_timestamp, LogClient, LogException

然后运行程序，以sample_putlogs举例:

python sample_putlogs.py

3. SDK使用设置

3.1. 基本设置

使用 SDK访问 LTS 的服务，需要设置正确的 AccessKey、SecretKey 和服务端 Endpoint，所有的服务可以使用同一 key 凭证来进行访问，但不同的服务需要使用不同的 endpoint 进行访问，详情参考天翼云官网-SDK接入概述。在调用前SDK，需要已知以下参数：

1、云日志服务访问地址。详情请查看访问地址（Endpoint）。

2、key凭证：accessKey和secretKey 。详情请查看如何获取访问密钥（AK/SK）。

3、日志项目编码：logProject，在使用SDK前，需要确保您有至少一个已经存在的日志项目，日志项目就是您要将日志上传到的地方。

4、日志单元编码：logUnit，在使用SDK前，需要确保日志项目中有至少一个已经存在的日志单元。

目前通过SDK将日志上传有两种上传形式：同步上传和异步批量上传，详细信息参考代码内README文档。

1、同步上传：当调用日志上传接口时，sdk会立即进行网络请求调用，并返回发送结果。这种方式结构简单，可用于发送频率不高的场景。

2、异步批量上传：当调用日志上传接口时，后台线程会将日志进行累积，当达到发送条件时，会进行一次合并发送。对于需要频繁调用发送接口的场景，这种方式性能更卓越，更高效。

示例代码：同步上传

from lts import LogItem, get_current_timestamp, LogClient

def main():
    access_key = "your accessKey"
    secret_key = "your secretKey"
    log_project = "log project Code"
    log_unit = "log unit Code"
    endpoint = "endpoint"

    log_items = []
    log_item = LogItem()
    curr_time = get_current_timestamp(3)  # 获取当前的时间戳，单位纳秒
    log_item.set_log_timestamp(curr_time)
    log_item.set_origin_msg("Python sdk test oriMessage")
    log_item.contents_push_back("level", "info")
    log_item.contents_push_back("area", 3.1415926)

    log_num = 10
    for i in range(0, log_num):
        log_items.append(log_item)

    try:
        log_client = LogClient(endpoint=endpoint, access_key=access_key, secret_key=secret_key)
        for i in range(0, 100):  # send 100 times
            putlogs_response = log_client.put_logs(log_project, log_unit, log_items)
            print("statusCode:", putlogs_response.status_code, ", message:", putlogs_response.messgae, ", error:",
                  putlogs_response.error)
    except Exception as ex:
        print(ex)


if __name__ == "__main__":
    main()

示例代码：异步批量上传

from lts.asynchronous.producer import Producer
from lts.asynchronous.producer_config import ProducerConfig
from lts import LogItem, get_current_timestamp, ClientConfig


# 异步批量多线程上传日志
def main():
    access_key = "your accessKey"
    secret_key = "your secretKey"
    log_project = "log project Code"
    log_unit = "log unit Code"
    endpoint = "endpoint"

    log_items = []
    log_item = LogItem()
    curr_time = get_current_timestamp(3)
    log_item.set_log_timestamp(curr_time)
    log_item.set_origin_msg("Python sdk test oriMessage")
    log_item.contents_push_back("level", "info")
    log_item.contents_push_back("area", 3.1415926)
    log_num = 10
    for i in range(0, log_num):
        log_items.append(log_item)

    # 初始化producer
    producer_config = ProducerConfig()
    producer = Producer(producer_config)
    try:
        client_config = ClientConfig(endpoint, access_key, secret_key)
        producer.build_clients(client_config)
        producer.start()

        # 发送日志,有回调结果
        for i in range(0, 10000):  # send 100 times
            producer.send_logs_callback(log_project, log_unit, log_item)

        # 发送日志,无回调结果
        # for i in range(0, 10000):
        #     producer.send_logs(log_project, log_unit, log_item)
        # time.sleep(5)

        # 安全关闭producer
        producer.safe_close()
    except Exception as ex:
        print(ex)


if __name__ == "__main__":
    main()

4. 服务代码示例-同步上传

同步上传每调用一次发送日志的方法，就会进行一次https请求发送日志，然后返回日志发送结果。同步上传对于需求简单，发送频率不高，发送量不大的场景比较适用。虽然是同步发送，但是可以将多条日志合在一起，一次性发送，减少API请求次数。

4.1. 关于Client的操作

client的默认配置，里面包含如下参数。

示例代码：初始化Client

client_config = ClientConfig(endpoint, access_key, secret_key)
# 可对默认配置进行变更
client_config.request_timeout = 30
Client_config.retries = 3

log_client = LogClient(client_config)

#或者使用默认配置
log_client = LogClient(endpoint=endpoint, access_key=access_key, secret_key=secret_key)

4.2. 关于Log的操作

日志上传只能上传LogItem格式的日志，log_items是一个数组类型，里面包含若干条LogItem日志，格式如下：

配置一个或多个log_item，然后放入log_items下的数组，作为参数传递，这就是要传入的日志信息，LogItem类型需要的参数如下。

注意：单条日志最大1MB，单个包最大5MB，其中contents和labels的key的长度不超过64字符，仅支持数字、字母、下划线、连字符(-)、点(.)，且必须以字母开头。value类型最好使用字符串（string）和数字类型（int,double），其他类型建议先转为字符串类型，并且value值不能为空或空字符串。

示例代码：组装生成10条日志

log_items = []
log_item = LogItem()
curr_time = get_current_timestamp(3)
log_item.set_log_timestamp(curr_time)
log_item.set_origin_msg("Python sdk test oriMessage")
log_item.contents_push_back("contentInt", curr_time)
log_item.contents_push_back("level", "info")
log_item.contents_push_back("area：", 3.1415926)
log_item.contents_push_back("unit_id", 123145)
for i in range(1, 10):
	log_items.append(log_item)

当然，对于dict 类型的contents 和labels 类型，也可以用set方法进行赋值，减少push_back()操作。

contents = {"contentInt": 123456,"contentString": "string content"}
log_item.set_contents(contents)

4.3. 关于日志上传的操作

此操作用于日志上传服务，需要传入的参数有三个，分别是log_project(日志项目编码)，unit_code(日志单元编码)，log_items（要上传的日志）。

示例代码：上传日志

try:
 	log_client = LogClient(endpoint=endpoint, access_key=access_key, secret_key=secret_key)
    for i in range(0, 100):  # send 100 times
        log_response = log_client.put_logs(log_project, log_unit, log_items)
    log_response.log_print_body()
except LogException as ex:
    print(ex)

resp_body有如下种类：

日志服务相关错误编码(部分):