1. 前言

安装使用node.js SDK可以帮助开发者快速接入使用天翼云的日志服务相关功能，目前支持同步上传功能。

2. 使用条件

2.1. 先决条件

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

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

2、已获取AccessKey 和 SecretKey。

3、已安装node.js运行环境,推荐node16以上环境。

2.2. 下载及安装

从官方渠道下载ctyun_lts_nodejs_sdk.zip压缩包，放到相应位置后并解压。“ctyun_lts_nodejs_sdk/src”目录中index.ts为SDK的使用示例代码。

2.2.1. 编译使用

1、node,js sdk 使用前需安装node.js运行环境。

2、打开项目，执行以下命令安装依赖。如果失败，可以加上镜像源，比如天翼云：npm install --registry=xxx

npm install

3、安装ts-node，ts-node是用于编译并执行TypeScript文件的工具。

npm  i ts-node -g

4、将ts文件编译为js文件。它会将js文件输出到dist目录下。（可在tsconfig.json里面进行修改）

tsc

5、运行测试用例。

ts-node ./src/index.js

3. SDK使用设置

3.1. 基本使用

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

• 云日志服务访问地址。详情请查看访问地址（Endpoint）。
• key凭证：accessKey和secretKey 。详情请查看如何获取访问密钥（AK/SK）。
• 日志项目编码：logProject，在使用SDK前，需要确保您有至少一个已经存在的日志项目。
• 日志单元编码：logUnit，在使用SDK前，需要确保日志项目中有至少一个已经存在的日志单元。
• 待上传的日志：logItem，在使用SDK前，需要确保日志已按照特定格式组织。

参数	参数类型	描述	是否必须
endpoint	string	域名	是
accessKey	string	AccessKey，简称ak	是
secretKey	string	SecretKey ，简称sk	是
logProject	string	日志项目编码	是
logUnit	string	日志单元编码	是

示例代码：SDK使用示例

import Client from './client'
import LogItem from './logItem'
   
async function testPutlog() {
    const ak = 'your accessKey'
    const sk = 'your secretKey'
    const logProject = 'your logProject'   //日志项目编码
    const logUnit = 'your logUnit'         //日志单元编码
    const endpoint = 'your endpoint'       //不同资源池endpoint不同,请参考文档  

    const logItems = new Array();
    for (let i = 0; i < 10; i++) {  //一次请求上传10条日志
        const logItem =  new LogItem('node.js sdk test');
        logItem.setLogTimestamp(Date.now()*1000*1000)   //可省略,默认为当前时间
        logItem.addContent('contentString', 'contents test string')  //增加分词内容,也可不加
        logItem.addContent('contentDouble', 3.1415926)  //增加分词内容,也可不加
        logItems.push(logItem)
    }
    try {
        const client = new Client(ak,sk,endpoint)
        //初始化更新一次token,后续自动更新
        await client.getToken()        

        //上传日志，100次，总计100*10 = 1000条日志
        for (let i = 0; i < 100; i++) {
            const res = await client.putLogs(logProject, logUnit, logItems)
            console.log('statusCode:',logResponse.statusCode,', message:',logResponse.message,', error:',logResponse.error);

        }
    } catch (e) {
        console.log(e)
    }

}

//执行测试
testPutlog()

4. LTS服务代码示例

4.1. 关于Client的操作

4.1.1. Client()

此操作是初始化client，client包含的配置信息如下：

参数	参数类型	描述	是否必须
endpoint	string	域名	是
accessKey	string	AccessKey，简称ak	是
secretKey	string	SecretKey ，简称sk	是
compressType	string	日志压缩方式 ，默认lz4	否
securityToken	ITokenInfo	token信息	否
httpClient	HttpClient	用于http请求	否

示例代码：初始化创建Client

const client = new Client(ak,sk,endpoint)

4.1.2. getToken()

此操作是为client注入token信息，这一步需要使用ak和sk信息换取临时凭证TokenInfo，其中包含了token随机串和过期时间两个参数。这一步需要去访问CTIAM的api接口，调用api接口，返回token信息。

TokenInfo信息如下：

参数	类型	描述
token	string	token 随机串
expireTime	number	过期时间，默认30分钟

示例代码：初始化Token

 await client.getToken()        

4.2. 关于Log的操作

4.2.1. logItem()

此操作用于生成待上传的日志，其中LogItem格式如下，日志上传默认只支持Array,如果只上传一条也需要加入到Array中。

参数	类型	描述	是否必须
logTimestamp	number	时间戳，单位纳秒	是
originMsg	string	原始日志内容	是
contents	Map<string, any>	kv类型，日志分词，可用于索引	否
labels	Map<string, any>	kv类型，自定义label	否

注意：其中Contents和Labels的key的长度不超过64字符，仅支持数字、字母、下划线、连字符(-)、点(.),且必须以字母开头。value类型最好使用字符串（string）和数字类型（number），其他类型建议先转为字符串类型，并且value值不能为空或空字符串。

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

const logItems = new Array();
for (let i = 0; i < 10; i++) {  
    const logItem =  new LogItem('node.js sdk test');
    logItem.setLogTimestamp(Date.now()*1000*1000)   //省略,则默认为当前时间
    logItem.addContent('contentString', 'contents test string')  //分词内容,可不加
    logItem.addContent('contentDouble', 3.1415926)   
    logItem.addLabel('labelString','tag')     
    logItems.push(logItem)
}

//常用方式
 const logItems = new Array();
for (let i = 0; i < 10; i++) {  
    const logItem =  new LogItem('node.js sdk test');
    logItems.push(logItem)
}

4.3. 关于日志上传的操作

4.3.1. putLogs()

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

参数	类型	描述	是否必须
logProject	string	日志项目编码	是
logUnit	string	日志单元编码	是
logItems	Array	日志信息	是

示例代码：上传日志

const logResponse = await client.putLogs(logProject, logUnit, logItems)
console.log("res:",logResponse)

4.3.2. logResponse

logResponse 是putlogs方法的返回响应体，如下表格式：

参数	类型	描述	示例
statusCode	string	返回码，取值范围：0：-正常、-1：严重错误,其他自定义
message	string	状态描述	SUCCESS
error	string	参考错误编码列表

示例代码：获取返回结果

logResponse.statusCode
logResponse.message
logResponse.error

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

statusCode	error	message
-1	LTS_8000	请求失败，请稍候重试，或提交工单反馈
-1	LTS_8001	内容不合法，无法解析
-1	LTS_8004	日志内容包含的日志必须小于[x] MB和[y]条
-1	LTS_8006	日志内容解压失败
-1	LTS_8007	Token失效，请重新获取
-1	LTS_8009	无云日志服务产品实例，请先开通云日志服务
-1	LTS_8010	日志项目不存在
-1	LTS_8011	日志单元不存在
-1	LTS_8013	在1个日志项目下,写入流量最大限制:200MB/s
-1	LTS_8014	在1个日志项目下,写入次数最大限制:1000次/s
-1	LTS_8015	在1个日志单元下,写入流量最大限制:100MB/s
-1	LTS_8016	在1个日志单元下,写入次数最大限制:500次/s
-1	LTS_18000	调用ITIAM的接口失败