Skip to content

Wonder233/tencentcloud-cls-uploader-sdk

Repository files navigation

tencentcloud-cls-uploader-sdk

日志服务(Cloud Log Service,CLS) 上传 SDK 封装。

  • 支持批量上传,多条日志可合并为一次请求
  • 支持调整并发
  • 支持匿名、永久密钥、临时密钥上报
  • 支持js、nodejs两个版本

注意: 在浏览器中使用本 SDK 时,目前暂时只支持匿名上报(不要传入永久密钥/获取临时密钥函数),并且需要在腾讯云 cls 日志服务控制台中将日志主题的匿名访问配置项开启。【匿名日志采集

new ClsClient(options) 构造函数参数说明

Property Type Description
region string 要上传的Cls地域
topicId string Cls 日志主题Id
sourceIp? string (可选) 日志来源,一般使用机器 IP 作为标识
credential? QCloudCredential (可选) 永久密钥
getAgent? () => any (可选) 获取代理函数
getAuthorization? GetAuthorizationFn (可选) 获取临时密钥函数
httpAdapter? 'xhr' | 'http' | AxiosAdapter (可选) http 请求适配器
maxRetainDuration? number (可选) 未上传的缓存日志超过该时间则上传(单位: s,默认 30s)
maxRetainSize? number (可选) 未上传的缓存日志数量超过该数值则上传(默认 20 条)
onError? (error: IClsSDKError) => void (可选) 生命周期:上传器发起请求发生错误(不影响上传器后续使用)
proxy? { host: string; port: number; protocol?: string; } (可选) 代理配置

使用示例

创建一个 Cls Client SDK 实例,SDK 支持以下格式创建:

  • 格式一(推荐):使用临时密钥进行日志上报。后端通过获取临时密钥给到前端,前端计算签名。
import ClsClient from 'tencentcloud-cls-uploader-sdk'

const clsClient = new ClsClient({
  topicId: 'xxxx',
  region: 'ap-guangzhou',
  maxRetainDuration: 30, // 默认 30s
  maxRetainSize: 20, // 默认20条
  getAuthorization: function (options, callback) {
    // 初始化时不会调用,只有调用 cos 方法(例如 cos.putObject)时才会进入
    // 异步获取临时密钥
    // 服务端 JS 和 PHP 例子:https://github.com/tencentyun/cos-js-sdk-v5/blob/master/server/
    // 服务端其他语言参考 COS STS SDK :https://github.com/tencentyun/qcloud-cos-sts-sdk
    // STS 详细文档指引看:https://cloud.tencent.com/document/product/436/14048

    const url = 'http://example.com/server/sts.php'; // url 替换成您自己的后端服务
    const xhr = new XMLHttpRequest();
    let data = null;
    let credentials = null;
    xhr.open('GET', url, true);
    xhr.onload = function (e) {
        try {
          data = JSON.parse(e.target.responseText);
          credentials = data.credentials;
        } catch (e) {
        }
        if (!data || !credentials) {
          return console.error('credentials invalid:\n' + JSON.stringify(data, null, 2))
        };
        callback({
          TmpSecretId: credentials.tmpSecretId,
          TmpSecretKey: credentials.tmpSecretKey,
          SecurityToken: credentials.sessionToken,
          // 建议返回服务器时间作为签名的开始时间,避免用户浏览器本地时间偏差过大导致签名错误
          StartTime: data.startTime, // 时间戳,单位秒,如:1580000000
          ExpiredTime: data.expiredTime, // 时间戳,单位秒,如:1580000000
      });
    };
    xhr.send();
  },
  onError(err) {
    console.log('onError:', err);
  },
});

const params = {
  hello: 'hello world',
  world: '2.1.0',
};

// 立即上传
clsClient.log(params, true);
  • 格式二:匿名上报。
import ClsClient from 'tencentcloud-cls-uploader-sdk'

const clsClient = new ClsClient({
  topicId: 'xxxx',
  region: 'ap-guangzhou',
  maxRetainDuration: 30, // 默认 30s
  maxRetainSize: 20, // 默认20条
  onError(err) {
    console.log('onError:', err);
  },
});

const params = {
  hello: 'hello world',
  world: '2.1.0',
};

// 立即上传
clsClient.log(params, true);
  • 格式三(不推荐):使用固定密钥计算签名进行日志上报
import ClsClient from 'tencentcloud-cls-uploader-sdk'

const clsClient = new ClsClient({
  topicId: 'xxxx',
  region: 'ap-guangzhou',
  maxRetainDuration: 30, // 默认 30s
  maxRetainSize: 20, // 默认20条
  credential: {
    SecretId: 'xxxx',
    SecretKey: 'xxxx',
  },
  onError(err) {
    console.log('onError:', err);
  },
});

const params = {
  hello: 'hello world',
  world: '2.1.0',
};

// 立即上传
clsClient.log(params, true);

API 文档

API 文档

About

日志服务(Cloud Log Service,CLS)上传客户端

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published