# 云日志服务Web SDK 云日志服务Web SDK提供了Web SDK上报日志的一系列方法，如果您需要收集和分析用户在网站上的信息，例如用户的浏览器、浏览行为记录、终端设备记录，设备异常记录，网络使用记录等，可以直接使用Web SDK上报日志到LTS。 使用Web SDK上报日志到LTS的场景下，需要开启日志流的匿名写入功能，开启后上报日志没有经过有效鉴权，可能产生脏数据。详细操作请参考[管理日志流](https://support.huaweicloud.com/usermanual-lts/lts_04_0004.html)。 ![](https://support.huaweicloud.com/usermanual-lts/public_sys-resources/note_3.0-zh-cn.png) Web SDK支持跨云/本地上报日志，当前仅支持华北-北京四、华东-上海一、华南-广州的白名单用户，如有需要请[提交工单](https://support.huaweicloud.com/usermanual-ticket/zh-cn_topic_0127038618.html)申请。 #### 传输协议 HTTPS #### 使用前提 - 参考[注册华为账号并开通华为云](https://support.huaweicloud.com/usermanual-account/account_id_001.html)中操作，完成注册。 - 确认云日志服务的区域，请您根据所在区域，选择RegionName。 - 获取华为云账号的项目ID（project id），步骤请参见[API凭证](https://support.huaweicloud.com/usermanual-ca/ca_01_0002.html)。 - 获取需要上报到LTS的[日志组ID]和[日志流ID]。 #### 版本更新说明 表1版本更新说明 | 版本号 | 更新说明 | |:---|:---| | 1.0.25 | config中新增reportCallback参数，支持用户自定义回调函数，在日志上报成功或失败时，都会调用该回调函数。 | | 1.0.24 | 支持更多region：华东-上海一、华南-广州。 | | 1.0.21 | - 废弃config方法，优先使用new SDK创建一个新的实例。 - 去除代码中对三方包的依赖和存在的中文符号。 | | 1.0.19 | 修改时间阈值的范围从1-60改为1-1800，其默认值从30改为3。 | | 1.0.18 | - 调整日志级别等级。 - 支持labels嵌套。 | | 1.0.15 | 新增多实例。 | #### NPM方式安装SDK 1. 安装方法：在项目根目录下通过运行"npm i lts-web-sdk"命令，安装SDK软件包。您可以在[开源仓地址](https://www.npmjs.com/package/lts-web-sdk)下载最新的SDK。 2. 示例代码： ``` const LTS_WEB_SDK = require('lts-web-sdk').default; // import LTS_WEB_SDK from 'lts-web-sdk'; // 初始化 const weblog = new LTS_WEB_SDK({ // 上报region region: string, // 项目ID projectId: string, // 上报地址 url: string, // LTS日志组ID groupId: string, // LTS日志流ID streamId: string, // 调试日志等级 debug: string, // 上报条数阈值 cacheThreshold: number, // 上报时间阈值 timeInterval: number, // 回调函数 reportCallback: () => (result: { success: boolean; // 本次上报是否成功 labels?: object; // 本次上报的标签信息 content?: string[]; // 本次上报的日志信息 reason?: string; // 失败原因。仅上报失败时有该参数 }) => void, }); // 立即上报单条带标签 weblog.reportImmediately({ 'name': 'xiaoming', 'age': 18 }, { 'key': 'value' }); // 立即上报单条 不带标签 weblog.reportImmediately([{ key: 'value', number: 1, array: [], json: { json: 'json' } }, { 'key': 'value' }]); // 缓存上报多条 带标签 weblog.report([{ 'name': 'xiaohong', 'age': 18 }, { 'name': 'xiaobai', 'age': 20 }], { 'key': 'value' }); // 缓存上报多条 不带标签 weblog.report([{ 'name': 'xiaohong', 'age': 18 }, { key: 'value', number: 1, array: [], json: { json: 'json' } }]); // 缓存上报多条 带多个标签（最多50个） weblog.report([{ 'name': 'xiaohong', 'name': 'xiaolan' }], {'version': '1.0.0', 'render': 'web', 'link': '/', from: 'web'}); ``` #### CDN同步方式安装SDK 1. 安装方法： 在您的html文件中，通过以下方式引用SDK。 \ // 初始化 const weblog = new LTS_WEB_SDK({ // 上报region region: string, // 项目ID projectId: string, // 上报地址 url: string, // LTS日志组ID groupId: string, // LTS日志流ID streamId: string, // 调试开关，开启后可以看到输出的调试日志 debug: boolean, // 上报条数阈值 cacheThreshold: number, // 上报时间条数 timeInterval: number, // 回调函数 reportCallback: () => (result: { success: boolean; // 本次上报是否成功 labels?: object; // 本次上报的标签信息 content?: string[]; // 本次上报的日志信息 reason?: string; // 失败原因。仅上报失败时有该参数 }) => void, }); // 立即上报单条带标签 weblog.reportImmediately({ 'name': 'xiaoming', 'age': 18 }, { 'key': 'value' }); // 立即上报单条 不带标签 weblog.reportImmediately([{ key: 'value', number: 1, array: [], json: { json: 'json' } }, { 'key': 'value' }]); // 缓存上报多条 带标签 weblog.report([{ 'name': 'xiaohong', 'age': 18 }, { 'name': 'xiaobai', 'age': 20 }], { 'key': 'value' }); // 缓存上报多条 不带标签 weblog.report([{ 'name': 'xiaohong', 'age': 18 }, { key: 'value', number: 1, array: [], json: { json: 'json' } }]); // 缓存上报多条 带多个标签（最多50个） weblog.report([{ 'name': 'xiaohong', 'name': 'xiaolan' }], {'version': '1.0.0', 'render': 'web', 'link': '/', from: 'web'}); ``` #### 配置参数说明 - 配置参数说明 表2配置参数说明 | 字段 | 类型 | 是否必填 | 默认值 | 描述 | |---|---|---|---|---| | region | string | 必填 | - | 上报LTS所处的region。 | | projectId | string | 必填 | - | 账号的项目ID，128个字符上限。 | | groupId | string | 必填 | - | LTS日志组ID，128个字符上限。 | | streamId | string | 必填 | - | LTS日志流ID，128个字符上限。 | | url | string | 选填 | - | 用于上报日志的公网地址域名，支持指定端口号，比如：https://lts-access.cn-north-4.myhuaweicloud.com:443。如未设置url，将根据region自动生成链接，格式如下：https://lts-access.{region}.myhuaweicloud.com - 使用SDK在跨云或本地上报日志时，端口使用443。 - 使用华为云主机在华为云内网上报日志时，端口使用8102。 | | debug | string | 选填 | OFF | - 控制台调试信息的输出等级，有OFF、ERROR、WARN、INFO、DEBUG五个等级。 - 填入无效值会默认为OFF，最高等级为DEBUG，层级往下递减。 - 值为true时开启DEBUG等级的日志，值为false时日志等级为OFF。 | | cacheThreshold | int | 选填 | 30 | 默认30条上报条数阈值，当缓存到达阈值时上报缓存中的数据 30 \<= cacheThreshold \<= 1000 | | timeInterval | number | 选填 | 3 | 默认3s 上报阈值时间，当达到阈值时间上报缓存中的数据 1 \<= timeInterval \<= 1800 | | reportCallback | function | 选填 | - | 自定义回调函数，在日志上报成功或失败时，都会调用该回调函数。 | - 日志上报Report方法参数说明。 表3Report方法参数说明 | 字段 | 类型 | 是否必填 | 默认值 | 描述 | |:---|:---|:---|:---|:---| | content | Object \| Array\ | 必填 | - | 需要上报的日志对象或者对象数组，限制：Object：最多300个键值对，转成JSON字符串最大支持长度1024\*30个字节，超出部分将被截断。 array\：数组中的每条Object数据最多300个键值对，转成JSON字符串最大支持长度1024\*30个字节，超出部分将被截断。 用户的日志字段名称不允许包含双下划线（__）。 | | labels | Object | 选填 | 空 | 日志标签，最外层键值对50个以内，最外层key最大长度为64个字符，最外层key值只能由字母开头，字母、数字或下划线组成，标签转成JSON字符串最大支持长度1024\*30个字符，超出限制将不上报此条信息。 用户的日志字段名称不允许包含双下划线（__）。 | - 日志立即上报reportImmediately方法参数说明。 表4reportImmediately方法参数说明 | 字段 | 类型 | 是否必填 | 默认值 | 描述 | |:---|:---|:---|:---|:---| | content | Object \| Array\ | 选填 | - | 立即上报的日志对象或者对象数组，限制：Object：最多300个键值对，转成JSON字符串最大支持长度1024\*30个字节，超出部分将被截断。 array\：数组中的每条Object数据最多300个键值对，转成JSON字符串最大支持长度1024\*30个字节，超出部分将被截断。不填入内容时，将立即上报缓存中的日志。 用户的日志字段名称不允许包含双下划线（__）。 | | labels | Object | 选填 | 空 | 日志标签，最外层键值对50个以内，最外层key最大长度为64个字符，最外层key值只能由字母开头，字母、数字或下划线组成，标签转成JSON字符串最大支持长度1024\*30个字符，超出限制将不上报此条信息。 用户的日志字段名称不允许包含双下划线（__）。 | #### 参数获取方式 - 区域表 表5区域表 | 区域名称 | 区域 | |:---|:---| | 华北-北京四 | cn-north-4 | | 华东-上海一 | cn-east-3 | | 华南-广州 | cn-south-1 | - 日志组ID：在云日志服务控制台，选择"日志管理"，鼠标悬浮在日志组名称上，可查看日志组名称和日志组ID。 - 日志流ID：单击日志组名称对应的![](https://support.huaweicloud.com/usermanual-lts/zh-cn_image_0000001873666417.png)，鼠标悬浮在日志流名称上，可查看日志流名称和日志流ID。