1# @ohos.hiviewdfx.hiAppEvent (应用事件打点) 2 3本模块提供了应用事件打点能力，包括应用事件落盘、应用事件订阅、应用事件清理、打点功能配置等功能。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10## 导入模块 11 12```ts 13import { hiAppEvent } from '@kit.PerformanceAnalysisKit'; 14``` 15 16## hiAppEvent.addProcessor<sup>11+</sup> 17 18addProcessor(processor: Processor): number 19 20开发者可添加数据处理者，该数据处理者用于提供事件上云功能，数据处理者的实现可预置在设备中，开发者可根据数据处理者的约束设置属性。 21 22Processor的配置信息需要由数据处理者提供，目前设备内暂未预置可供交互的数据处理者，因此当前事件上云功能不可用。 23 24**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 25 26**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 27 28**参数：** 29 30| 参数名 | 类型 | 必填 | 说明 | 31| --------- | ---------- | ---- | ------------- | 32| processor | [Processor](#processor11) | 是 | 上报事件的数据处理者。| 33 34**返回值：** 35 36| 类型 | 说明 | 37| ------ | ---------------------- | 38| number | 所添加上报事件数据处理者的ID。 添加失败返回-1，添加成功返回大于0的值。 | 39 40**错误码：** 41 42| 错误码ID | 错误信息 | 43| ------- | ----------------- | 44| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 45 46**示例：** 47 48```ts 49import { hilog } from '@kit.PerformanceAnalysisKit'; 50 51try { 52 let processor: hiAppEvent.Processor = { 53 name: 'analytics_demo' 54 }; 55 let id: number = hiAppEvent.addProcessor(processor); 56 hilog.info(0x0000, 'hiAppEvent', `addProcessor event was successful, id=${id}`); 57} catch (error) { 58 hilog.error(0x0000, 'hiAppEvent', `failed to addProcessor event, code=${error.code}`); 59} 60``` 61 62## Processor<sup>11+</sup> 63 64可以上报事件的数据处理者对象。 65 66**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 67 68| 名称 | 类型 | 必填 | 说明 | 69| ------------------- | ----------------------- | ---- | ---------------------------------------------------------------------------------------------------------- | 70| name | string | 是 | 数据处理者的名称。名称只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度非空且不超过256个字符。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 71| debugMode | boolean | 否 | 是否开启debug模式，默认值为false。配置值为true表示开启debug模式，false表示不开启debug模式。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 72| routeInfo | string | 否 | 服务器位置信息，默认为空字符串。传入字符串长度不能超过8KB，超过时会被置为默认值。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 73| appId | string | 否 | 应用id，默认为空字符串。传入字符串长度不能超过8KB，超过时会被置为默认值。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 74| onStartReport | boolean | 否 | 数据处理者在启动时是否上报事件，默认值为false。配置值为true表示上报事件，false表示不上报事件。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 75| onBackgroundReport | boolean | 否 | 当应用程序进入后台时是否上报事件，默认值为false。配置值为true表示上报事件，false表示不上报事件。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 76| periodReport | number | 否 | 事件定时上报时间周期，单位为秒。传入数值必须大于或等于0，小于0时会被置为默认值0，不进行定时上报。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 77| batchReport | number | 否 | 事件上报阈值，当事件条数达到阈值时上报事件。传入数值必须大于0且小于1000，不在数值范围内会被置为默认值0，不进行上报。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 78| userIds | string[] | 否 | 数据处理者可以上报的用户ID的name数组。name对应[setUserId](#hiappeventsetuserid11)接口的name参数。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 79| userProperties | string[] | 否 | 数据处理者可以上报的用户属性的name数组。name对应[setUserProperty](#hiappeventsetuserproperty11)接口的name参数。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 80| eventConfigs | [AppEventReportConfig](#appeventreportconfig11)[] | 否 | 数据处理者可以上报的事件数组。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 81| configId<sup>12+</sup> | number | 否 | 数据处理者配置id。传入数值必须大于或等于0，小于0时会被置为默认值0。传入的值大于0时，与数据处理者的名称name共同唯一标识数据处理者。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 82| customConfigs<sup>12+</sup> | Record\<string, string> | 否 | 自定义扩展参数。传入参数名和参数值不符合规格会默认不配置扩展参数，其规格定义如下：<br>- 参数名为string类型，首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过32个字符。<br>- 参数值为string类型，参数值长度需在1024个字符以内。<br>- 参数个数需在32个以内。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 83 84## AppEventReportConfig<sup>11+</sup> 85 86数据处理者可以上报事件的描述配置。 87 88**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 89 90**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 91 92| 名称 | 类型 | 必填 | 说明 | 93| ----------- | ------- | ---- | ------------------------------------------------------------ | 94| domain | string | 否 | 事件领域。事件领域名称支持数字、字母、下划线字符，需要以字母开头且不能以下划线结尾，长度非空且不超过32个字符。 | 95| name | string | 否 | 事件名称。首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过48个字符。 | 96| isRealTime | boolean | 否 | 是否实时上报事件。配置值为true表示实时上报事件，false表示不实时上报事件。 | 97 98## hiAppEvent.removeProcessor<sup>11+</sup> 99 100removeProcessor(id: number): void 101 102删除上报事件的数据处理者。 103 104**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 105 106**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 107 108**参数：** 109 110| 参数名 | 类型 | 必填 | 说明 | 111| ------| ------- | ---- | --------------------------- | 112| id | number | 是 | 上报事件数据处理者ID。值大于0。| 113 114**错误码：** 115 116| 错误码ID | 错误信息 | 117| ------- | ----------------- | 118| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 119 120**示例：** 121 122```ts 123import { hilog } from '@kit.PerformanceAnalysisKit'; 124 125try { 126 let processor: hiAppEvent.Processor = { 127 name: 'analytics_demo' 128 }; 129 let id: number = hiAppEvent.addProcessor(processor); 130 hiAppEvent.removeProcessor(id); 131} catch (error) { 132 hilog.error(0x0000, 'hiAppEvent', `failed to removeProcessor event, code=${error.code}`); 133} 134``` 135 136## hiAppEvent.write 137 138write(info: AppEventInfo, callback: AsyncCallback<void>): void 139 140应用事件打点方法，将事件写入到当天的事件文件中，可接收AppEventInfo类型的事件对象，使用callback方式作为异步回调。 141 142**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 143 144**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 145 146**参数：** 147 148| 参数名 | 类型 | 必填 | 说明 | 149| -------- | ------------------------------ | ---- | -------------- | 150| info | [AppEventInfo](#appeventinfo) | 是 | 应用事件对象。 | 151| callback | AsyncCallback<void> | 是 | 打点回调函数。 | 152 153**错误码：** 154 155以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 156 157| 错误码ID | 错误信息 | 158| -------- | --------------------------------------------- | 159| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 160| 11100001 | Function disabled. | 161| 11101001 | Invalid event domain. | 162| 11101002 | Invalid event name. | 163| 11101003 | Invalid number of event parameters. | 164| 11101004 | Invalid string length of the event parameter. | 165| 11101005 | Invalid event parameter name. | 166| 11101006 | Invalid array length of the event parameter. | 167 168**示例：** 169 170```ts 171import { BusinessError } from '@kit.BasicServicesKit'; 172import { hilog } from '@kit.PerformanceAnalysisKit'; 173 174let eventParams: Record<string, number | string> = { 175 "int_data": 100, 176 "str_data": "strValue", 177}; 178hiAppEvent.write({ 179 domain: "test_domain", 180 name: "test_event", 181 eventType: hiAppEvent.EventType.FAULT, 182 params: eventParams, 183}, (err: BusinessError) => { 184 if (err) { 185 hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); 186 return; 187 } 188 hilog.info(0x0000, 'hiAppEvent', `success to write event`); 189}); 190``` 191 192## hiAppEvent.write 193 194write(info: AppEventInfo): Promise<void> 195 196应用事件打点方法，将事件写入到当天的事件文件中，可接收AppEventInfo类型的事件对象，使用Promise方式作为异步回调。 197 198**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 199 200**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 201 202**参数：** 203 204| 参数名 | 类型 | 必填 | 说明 | 205| ------ | ------------------------------ | ---- | -------------- | 206| info | [AppEventInfo](#appeventinfo) | 是 | 应用事件对象。 | 207 208**返回值：** 209 210| 类型 | 说明 | 211| ------------------- | ------------- | 212| Promise<void> | Promise对象。 | 213 214**错误码：** 215 216以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 217 218| 错误码ID | 错误信息 | 219| -------- | --------------------------------------------- | 220| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 221| 11100001 | Function disabled. | 222| 11101001 | Invalid event domain. | 223| 11101002 | Invalid event name. | 224| 11101003 | Invalid number of event parameters. | 225| 11101004 | Invalid string length of the event parameter. | 226| 11101005 | Invalid event parameter name. | 227| 11101006 | Invalid array length of the event parameter. | 228 229**示例：** 230 231```ts 232import { BusinessError } from '@kit.BasicServicesKit'; 233import { hilog } from '@kit.PerformanceAnalysisKit'; 234 235let eventParams: Record<string, number | string> = { 236 "int_data": 100, 237 "str_data": "strValue", 238}; 239hiAppEvent.write({ 240 domain: "test_domain", 241 name: "test_event", 242 eventType: hiAppEvent.EventType.FAULT, 243 params: eventParams, 244}).then(() => { 245 hilog.info(0x0000, 'hiAppEvent', `success to write event`); 246}).catch((err: BusinessError) => { 247 hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); 248}); 249``` 250 251## AppEventInfo 252 253提供了应用事件信息的参数选项。 254 255**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 256 257**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 258 259| 名称 | 类型 | 必填 | 说明 | 260| --------- | ----------------------- | ---- | ------------------------------------------------------------ | 261| domain | string | 是 | 事件领域。事件领域名称支持数字、字母、下划线字符，需要以字母开头且不能以下划线结尾，长度非空且不超过32个字符。 | 262| name | string | 是 | 事件名称。首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过48个字符。 | 263| eventType | [EventType](#eventtype) | 是 | 事件类型。 | 264| params | object | 是 | 事件参数对象，每个事件参数包括参数名和参数值。**系统事件中params包含的字段已由各系统事件定义，具体字段含义在各类系统事件指南的介绍中，例如[崩溃事件介绍](../../dfx/hiappevent-watcher-crash-events.md)。** 针对应用事件，打点写入的参数由开发者定义，其规格如下：<br>- 参数名为string类型，首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过32个字符。<br>- 参数值支持string、number、boolean、数组类型，string类型参数长度需在8*1024个字符以内，超出会做丢弃处理；number类型参数取值需在Number.MIN_SAFE_INTEGER~Number.MAX_SAFE_INTEGER范围内，超出可能会产生不确定值；数组类型参数中的元素类型只能全为string、number、boolean中的一种，且元素个数需在100以内，超出会做丢弃处理。<br>- 参数个数需在32个以内，超出的参数会做丢弃处理。 | 265 266## hiAppEvent.setEventParam<sup>12+</sup> 267 268setEventParam(params: Record<string, ParamType>, domain: string, name?: string): Promise<void> 269 270事件自定义参数设置方法，使用Promise方式作为异步回调。在同一生命周期中，可以通过事件领域和事件名称关联系统事件和应用事件，系统事件仅支持崩溃和卡死事件。 271 272**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 273 274**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 275 276**参数：** 277 278| 参数名 | 类型 | 必填 | 说明 | 279| ------ | ------------------------------ | ---- | -------------- | 280| params | Record<string, [ParamType](#paramtype12)> | 是 | 事件自定义参数对象。参数名和参数值规格定义如下：<br>- 参数名为string类型，首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过32个字符。<br>- 参数值为[ParamType](#paramtype12)类型，参数值长度需在1024个字符以内。<br>- 参数个数需在64个以内。 | 281| domain | string | 是 | 事件领域。事件领域可支持关联应用事件和系统事件（hiAppEvent.domain.OS）。 | 282| name | string | 否 | 事件名称。默认为空字符串，空字符串表示关联事件领域下的所有事件名称。事件名称可支持关联应用事件和系统事件，其中系统事件仅支持关联崩溃事件（hiAppEvent.event.APP_CRASH）和卡死事件（hiAppEvent.event.APP_FREEZE）。 | 283 284**返回值：** 285 286| 类型 | 说明 | 287| ------------------- | ------------- | 288| Promise<void> | Promise对象。 | 289 290**错误码：** 291 292以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 293 294| 错误码ID | 错误信息 | 295| -------- | --------------------------------------------- | 296| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 297| 11101007 | The number of parameter keys exceeds the limit. | 298 299**示例：** 300 301```ts 302import { BusinessError } from '@kit.BasicServicesKit'; 303import { hilog } from '@kit.PerformanceAnalysisKit'; 304 305let params: Record<string, hiAppEvent.ParamType> = { 306 "int_data": 100, 307 "str_data": "strValue", 308}; 309// 给应用事件追加自定义参数 310hiAppEvent.setEventParam(params, "test_domain", "test_event").then(() => { 311 hilog.info(0x0000, 'hiAppEvent', `success to set event param`); 312}).catch((err: BusinessError) => { 313 hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); 314}); 315``` 316 317## hiAppEvent.setEventConfig<sup>15+</sup> 318 319setEventConfig(name: string, config: Record<string, ParamType>): Promise<void> 320 321事件自定义门限触发条件的参数设置方法，使用Promise方式作为异步回调。在同一生命周期中，可以通过事件名称，自定义事件门限触发条件相关的参数。**现在仅支持MAIN_THREAD_JANK事件。参数配置详见：[主线程超时事件检测](../../dfx/hiappevent-watcher-mainthreadjank-events.md#自定义采样栈参数介绍)**。 322 323**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 324 325**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 326 327**参数：** 328 329| 参数名 | 类型 | 必填 | 说明 | 330| ------ | ------------------------------ | ---- | -------------- | 331| name | string | 是 | 事件名称。 | 332| config | Record<string, ParamType> | 是 | 事件自定义参数对象。参数名和参数值规格定义如下：<br>- 参数名为string类型，要求非空，且参数名长度需在1024个字符以内。<br>- 参数值为ParamType类型，参数值长度需在1024个字符以内。 | 333 334**返回值：** 335 336| 类型 | 说明 | 337| ------------------- | ------------- | 338| Promise<void> | Promise对象。 | 339 340**错误码：** 341 342以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 343 344| 错误码ID | 错误信息 | 345| -------- | --------------------------------------------- | 346| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3.Parameter verification failed. | 347 348**示例：** 349 350该步骤用于模拟自定义MAIN_THREAD_JANK事件参数，以log_type的三种类型为例： 351 352log_type=0，采样栈或者采样trace。 353```ts 354import { BusinessError } from '@kit.BasicServicesKit'; 355import { hilog } from '@kit.PerformanceAnalysisKit'; 356 357let params: Record<string, hiAppEvent.ParamType> = { 358 "log_type": "0" 359}; 360 361hiAppEvent.setEventConfig(hiAppEvent.event.MAIN_THREAD_JANK, params).then(() => { 362 hilog.info(0x0000, 'hiAppEvent', `success to set event config`); 363}).catch((err: BusinessError) => { 364 hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); 365}); 366``` 367 368log_type=1，仅采集调用栈。 369```ts 370import { BusinessError } from '@kit.BasicServicesKit'; 371import { hilog } from '@kit.PerformanceAnalysisKit'; 372 373let params: Record<string, hiAppEvent.ParamType> = { 374 "log_type": "1", 375 "sample_interval": "100", 376 "ignore_startup_time": "11", 377 "sample_count": "21", 378 "report_times_per_app": "3" 379}; 380hiAppEvent.setEventConfig(hiAppEvent.event.MAIN_THREAD_JANK, params).then(() => { 381 hilog.info(0x0000, 'hiAppEvent', `success to set event config`); 382}).catch((err: BusinessError) => { 383 hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); 384}); 385``` 386 387log_type=2，仅收集trace。 388```ts 389import { BusinessError } from '@kit.BasicServicesKit'; 390import { hilog } from '@kit.PerformanceAnalysisKit'; 391 392let params: Record<string, hiAppEvent.ParamType> = { 393 "log_type": "2" 394}; 395hiAppEvent.setEventConfig(hiAppEvent.event.MAIN_THREAD_JANK, params).then(() => { 396 hilog.info(0x0000, 'hiAppEvent', `success to set event config`); 397}).catch((err: BusinessError) => { 398 hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); 399}); 400``` 401 402## ParamType<sup>12+</sup> 403 404type ParamType = number | string | boolean | Array<string> 405 406事件自定义参数值的类型。 407 408**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 409 410**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 411 412| 类型 | 说明 | 413|--------------------------|-------------------| 414| number | 表示值类型为数字。 | 415| string | 表示值类型为字符串。 | 416| boolean | 表示值类型为布尔值。 | 417| Array<string> | 表示值类型为字符串类型的数组。 | 418 419## hiAppEvent.configure 420 421configure(config: ConfigOption): void 422 423应用事件打点配置方法，可用于配置打点开关、目录存储配额大小等功能。 424 425**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 426 427**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 428 429**参数：** 430 431| 参数名 | 类型 | 必填 | 说明 | 432| ------ | ----------------------------- | ---- | ------------------------ | 433| config | [ConfigOption](#configoption) | 是 | 应用事件打点配置项对象。 | 434 435**错误码：** 436 437以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 438 439| 错误码ID | 错误信息 | 440| -------- | -------------------------------- | 441| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 442| 11103001 | Invalid max storage quota value. | 443 444**示例：** 445 446```ts 447// 配置打点开关为关闭状态 448let config1: hiAppEvent.ConfigOption = { 449 disable: true, 450}; 451hiAppEvent.configure(config1); 452 453// 配置文件目录存储配额为100M 454let config2: hiAppEvent.ConfigOption = { 455 maxStorage: '100M', 456}; 457hiAppEvent.configure(config2); 458``` 459 460## ConfigOption 461 462提供了对应用事件打点功能的配置选项。 463 464**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 465 466**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 467 468| 名称 | 类型 | 必填 | 说明 | 469| ---------- | ------- | ---- | ------------------------------------------------------------ | 470| disable | boolean | 否 | 打点功能开关，默认值为false。true：关闭打点功能，false：不关闭打点功能。 | 471| maxStorage | string | 否 | 打点数据存放目录的配额大小，默认值为“10M”。<br>在目录大小超出配额后，下次打点会触发对目录的清理操作：按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出配额时结束。<br>配额值字符串规格如下：<br>- 配额值字符串只由数字字符和大小单位字符（单位字符支持[b\|k\|kb\|m\|mb\|g\|gb\|t\|tb]，不区分大小写）构成。<br>- 配额值字符串必须以数字开头，后面可以选择不传单位字符（默认使用byte作为单位），或者以单位字符结尾。 | 472 473## hiAppEvent.setUserId<sup>11+</sup> 474 475setUserId(name: string, value: string): void 476 477设置用户ID。 478 479**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 480 481**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 482 483**参数：** 484 485| 参数名 | 类型 | 必填 | 说明 | 486| --------- | ------------------------- | ---- | ------------- | 487| name | string | 是 | 用户ID的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度非空且不超过256个字符。 | 488| value | string | 是 | 用户ID的值。长度不超过256，当值为null或空字符串时，则清除用户ID。 | 489 490**错误码：** 491 492| 错误码ID | 错误信息 | 493| ------- | ----------------- | 494| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 495 496**示例：** 497 498```ts 499import { hilog } from '@kit.PerformanceAnalysisKit'; 500 501try { 502 hiAppEvent.setUserId('key', 'value'); 503} catch (error) { 504 hilog.error(0x0000, 'hiAppEvent', `failed to setUserId event, code=${error.code}`); 505} 506``` 507 508## hiAppEvent.getUserId<sup>11+</sup> 509 510getUserId(name: string): string 511 512获取之前通过setUserId接口设置的value值。 513 514**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 515 516**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 517 518**参数：** 519 520| 参数名 | 类型 | 必填 | 说明 | 521| --------- | ----------------------- | ---- | ---------- | 522| name | string | 是 | 用户ID的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度不超过256。| 523 524**返回值：** 525 526| 类型 | 说明 | 527| ------ | ------------------------------- | 528| string | 用户ID的值。没有查到返回空字符串。 | 529 530**错误码：** 531 532| 错误码ID | 错误信息 | 533| ------- | ----------------- | 534| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 535 536**示例：** 537 538```ts 539import { hilog } from '@kit.PerformanceAnalysisKit'; 540 541hiAppEvent.setUserId('key', 'value'); 542try { 543 let value: string = hiAppEvent.getUserId('key'); 544 hilog.info(0x0000, 'hiAppEvent', `getUserId event was successful, userId=${value}`); 545} catch (error) { 546 hilog.error(0x0000, 'hiAppEvent', `failed to getUserId event, code=${error.code}`); 547} 548``` 549 550## hiAppEvent.setUserProperty<sup>11+</sup> 551 552setUserProperty(name: string, value: string): void 553 554设置用户属性。 555 556**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 557 558**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 559 560**参数：** 561 562| 参数名 | 类型 | 必填 | 说明 | 563| --------- | ------------------------- | ---- | -------------- | 564| name | string | 是 | 用户属性的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度非空且不超过256个字符。 | 565| value | string | 是 | 用户属性的值。长度不超过1024，当值为null或空字符串时，则清除用户属性。 | 566 567**错误码：** 568 569| 错误码ID | 错误信息 | 570| ------- | ----------------- | 571| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 572 573**示例：** 574 575```ts 576import { hilog } from '@kit.PerformanceAnalysisKit'; 577 578try { 579 hiAppEvent.setUserProperty('key', 'value'); 580} catch (error) { 581 hilog.error(0x0000, 'hiAppEvent', `failed to setUserProperty event, code=${error.code}`); 582} 583``` 584 585## hiAppEvent.getUserProperty<sup>11+</sup> 586 587getUserProperty(name: string): string 588 589获取之前通过setUserProperty接口设置的value值。 590 591**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 592 593**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 594 595**参数：** 596 597| 参数名 | 类型 | 必填 | 说明 | 598| --------- | ----------------------- | ---- | ---------- | 599| name | string | 是 | 用户属性的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度不超过256。| 600 601**返回值：** 602 603| 类型 | 说明 | 604| ------ | -------------------------------- | 605| string | 用户属性的值。 没有查到返回空字符串。 | 606 607**错误码：** 608 609| 错误码ID | 错误信息 | 610| ------- | ----------------- | 611| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 612 613**示例：** 614 615```ts 616import { hilog } from '@kit.PerformanceAnalysisKit'; 617 618hiAppEvent.setUserProperty('key', 'value'); 619try { 620 let value: string = hiAppEvent.getUserProperty('key'); 621 hilog.info(0x0000, 'hiAppEvent', `getUserProperty event was successful, userProperty=${value}`); 622} catch (error) { 623 hilog.error(0x0000, 'hiAppEvent', `failed to getUserProperty event, code=${error.code}`); 624} 625``` 626 627## hiAppEvent.addWatcher 628 629addWatcher(watcher: Watcher): AppEventPackageHolder 630 631添加应用事件观察者方法，可用于订阅应用事件。 632 633**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 634 635**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 636 637**参数：** 638 639| 参数名 | 类型 | 必填 | 说明 | 640| ------- | -------------------- | ---- | ---------------- | 641| watcher | [Watcher](#watcher) | 是 | 应用事件观察者。 | 642 643**返回值：** 644 645| 类型 | 说明 | 646| ------------------------------------------------ | ------------------------------------ | 647| [AppEventPackageHolder](#appeventpackageholder) | 订阅数据持有者，订阅失败时返回null。 | 648 649**错误码：** 650 651以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 652 653| 错误码ID | 错误信息 | 654| -------- | ------------------------------- | 655| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 656| 11102001 | Invalid watcher name. | 657| 11102002 | Invalid filtering event domain. | 658| 11102003 | Invalid row value. | 659| 11102004 | Invalid size value. | 660| 11102005 | Invalid timeout value. | 661 662**示例：** 663 664```ts 665import { hilog } from '@kit.PerformanceAnalysisKit'; 666 667// 1. 如果观察者传入了回调的相关参数，则可以选择在自动触发的回调函数中对订阅事件进行处理 668hiAppEvent.addWatcher({ 669 name: "watcher1", 670 appEventFilters: [ 671 { 672 domain: "test_domain", 673 eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR] 674 } 675 ], 676 triggerCondition: { 677 row: 10, 678 size: 1000, 679 timeOut: 1 680 }, 681 onTrigger: (curRow: number, curSize: number, holder: hiAppEvent.AppEventPackageHolder) => { 682 if (holder == null) { 683 hilog.error(0x0000, 'hiAppEvent', "holder is null"); 684 return; 685 } 686 hilog.info(0x0000, 'hiAppEvent', `curRow=${curRow}, curSize=${curSize}`); 687 let eventPkg: hiAppEvent.AppEventPackage | null = null; 688 while ((eventPkg = holder.takeNext()) != null) { 689 hilog.info(0x0000, 'hiAppEvent', `eventPkg.packageId=${eventPkg.packageId}`); 690 hilog.info(0x0000, 'hiAppEvent', `eventPkg.row=${eventPkg.row}`); 691 hilog.info(0x0000, 'hiAppEvent', `eventPkg.size=${eventPkg.size}`); 692 for (const eventInfo of eventPkg.data) { 693 hilog.info(0x0000, 'hiAppEvent', `eventPkg.data=${eventInfo}`); 694 } 695 } 696 } 697}); 698 699// 2. 如果观察者未传入回调的相关参数，则可以选择使用返回的holder对象手动去处理订阅事件 700// 针对异常退出时产生的崩溃事件（hiAppEvent.event.APP_CRASH）和卡死事件（hiAppEvent.event.APP_FREEZE），系统捕获维测日志有一定耗时，典型情况下30s内完成，极端情况下2min左右完成。在手动处理订阅事件的方法中，建议在进程启动后延时重试调用takeNext()获取此类事件。 701let holder = hiAppEvent.addWatcher({ 702 name: "watcher2", 703}); 704if (holder != null) { 705 let eventPkg: hiAppEvent.AppEventPackage | null = null; 706 while ((eventPkg = holder.takeNext()) != null) { 707 hilog.info(0x0000, 'hiAppEvent', `eventPkg.packageId=${eventPkg.packageId}`); 708 hilog.info(0x0000, 'hiAppEvent', `eventPkg.row=${eventPkg.row}`); 709 hilog.info(0x0000, 'hiAppEvent', `eventPkg.size=${eventPkg.size}`); 710 for (const eventInfo of eventPkg.data) { 711 hilog.info(0x0000, 'hiAppEvent', `eventPkg.data=${eventInfo}`); 712 } 713 } 714} 715 716// 3. 观察者可以在实时回调函数onReceive中处理订阅事件 717hiAppEvent.addWatcher({ 718 name: "watcher3", 719 appEventFilters: [ 720 { 721 domain: "test_domain", 722 eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR] 723 } 724 ], 725 onReceive: (domain: string, appEventGroups: Array<hiAppEvent.AppEventGroup>) => { 726 hilog.info(0x0000, 'hiAppEvent', `domain=${domain}`); 727 for (const eventGroup of appEventGroups) { 728 hilog.info(0x0000, 'hiAppEvent', `eventName=${eventGroup.name}`); 729 for (const eventInfo of eventGroup.appEventInfos) { 730 hilog.info(0x0000, 'hiAppEvent', `event=${JSON.stringify(eventInfo)}`, ); 731 } 732 } 733 } 734}); 735``` 736 737## hiAppEvent.removeWatcher 738 739removeWatcher(watcher: Watcher): void 740 741移除应用事件观察者方法，可用于取消订阅应用事件。 742 743**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 744 745**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 746 747**参数：** 748 749| 参数名 | 类型 | 必填 | 说明 | 750| ------- | -------------------- | ---- | ---------------- | 751| watcher | [Watcher](#watcher) | 是 | 应用事件观察者。 | 752 753**错误码：** 754 755以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 756 757| 错误码ID | 错误信息 | 758| -------- | --------------------- | 759| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 760| 11102001 | Invalid watcher name. | 761 762**示例：** 763 764```ts 765// 1. 定义一个应用事件观察者 766let watcher: hiAppEvent.Watcher = { 767 name: "watcher1", 768} 769 770// 2. 添加一个应用事件观察者来订阅事件 771hiAppEvent.addWatcher(watcher); 772 773// 3. 移除该应用事件观察者以取消订阅事件 774hiAppEvent.removeWatcher(watcher); 775``` 776 777## Watcher 778 779提供了应用事件观察者的参数选项。 780 781**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 782 783**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 784 785| 名称 | 类型 | 必填 | 说明 | 786| ---------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 787| name | string | 是 | 观察者名称，用于唯一标识观察者。 | 788| triggerCondition | [TriggerCondition](#triggercondition) | 否 | 订阅回调触发条件，需要与回调函数onTrigger一同传入才会生效。 | 789| appEventFilters | [AppEventFilter](#appeventfilter)[] | 否 | 订阅过滤条件，在需要对订阅事件进行过滤时传入。 | 790| onTrigger | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder)) => void | 否 | 订阅回调函数，需要与回调触发条件triggerCondition一同传入才会生效，函数入参说明如下：<br>curRow：在本次回调触发时的订阅事件总数量； <br>curSize：在本次回调触发时的订阅事件总大小，单位为byte； <br/>holder：订阅数据持有者对象，可以通过其对订阅事件进行处理。 | 791| onReceive<sup>11+</sup> | (domain: string, appEventGroups: Array<[AppEventGroup](#appeventgroup11)>) => void | 否 | 订阅实时回调函数，与回调函数onTrigger同时存在时，只触发此回调，函数入参说明如下：<br>domain：回调事件的领域名称； <br>appEventGroups：回调事件集合。 | 792 793## TriggerCondition 794 795提供了回调触发条件的参数选项，只要满足任一条件就会触发订阅回调。 796 797**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 798 799**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 800 801| 名称 | 类型 | 必填 | 说明 | 802| ------- | ------ | ---- | -------------------------------------- | 803| row | number | 否 | 满足触发回调的事件总数量，正整数。默认值0，不触发回调。传入负值时，会被置为默认值。 | 804| size | number | 否 | 满足触发回调的事件总大小，正整数，单位为byte。默认值0，不触发回调。传入负值时，会被置为默认值。 | 805| timeOut | number | 否 | 满足触发回调的超时时长，正整数，单位为30s。默认值0，不触发回调。传入负值时，会被置为默认值。 | 806 807## AppEventFilter 808 809提供了过滤应用事件的参数选项。 810 811**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 812 813**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 814 815| 名称 | 类型 | 必填 | 说明 | 816| ---------- | ------------------------- | ---- | ------------------------ | 817| domain | string | 是 | 需要订阅的事件领域。 | 818| eventTypes | [EventType](#eventtype)[] | 否 | 需要订阅的事件类型集合。 | 819| names<sup>11+</sup> | string[] | 否 | 需要订阅的事件名称集合。 | 820 821## AppEventPackageHolder 822 823订阅数据持有者类，用于对订阅事件进行处理。 824 825### constructor 826 827constructor(watcherName: string) 828 829类构造函数，创建订阅数据持有者实例，通过观察者名称关联到应用内已添加的观察者对象。 830 831**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 832 833**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 834 835**参数：** 836 837| 参数名 | 类型 | 必填 | 说明 | 838| ------ | ----------------- | ---- | ------------------------ | 839| watcherName | string | 是 | 观察者名称。 | 840 841**示例：** 842 843```ts 844let holder1: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher1"); 845``` 846 847### setSize 848 849setSize(size: number): void 850 851设置每次取出的应用事件包的数据大小阈值。 852 853**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 854 855**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 856 857**参数：** 858 859| 参数名 | 类型 | 必填 | 说明 | 860| ------ | ------ | ---- | -------------------------------------------- | 861| size | number | 是 | 数据大小阈值，单位为byte，取值范围是大于等于0的数，超出范围会抛异常。 | 862 863**错误码：** 864 865以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 866 867| 错误码ID | 错误信息 | 868| -------- | ------------------- | 869| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 870| 11104001 | Invalid size value. | 871 872**示例：** 873 874```ts 875let holder2: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher2"); 876holder2.setSize(1000); 877``` 878 879### setRow<sup>12+</sup> 880 881setRow(size: number): void 882 883设置每次取出的应用事件包的数据条数，优先级高于setSize，和setSize同时调用时仅setRow生效。 884 885**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 886 887**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 888 889**参数：** 890 891| 参数名 | 类型 | 必填 | 说明 | 892| ------ | ------ | ---- | -------------------------------------------- | 893| size | number | 是 | 应用事件条数，单位为条，取值范围是大于0的数，超出范围会抛异常。 | 894 895**错误码：** 896 897以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 898 899| 错误码ID | 错误信息 | 900| -------- | ------------------- | 901| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 902| 11104001 | Invalid size value. | 903 904**示例：** 905 906```ts 907let holder3: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher3"); 908holder3.setRow(1000); 909``` 910 911### takeNext 912 913takeNext(): AppEventPackage 914 915根据设置的数据大小阈值或条数来取出订阅事件数据，当订阅事件数据全部被取出时返回null作为标识。 9161、应用仅调用setSize不调用setRow时，根据数据大小限制取订阅事件。 9172、应用调用setRow，无论是否调用setSize，都根据setRow设置的条数取订阅事件。 9183、setSize和setRow都没被调用时，默认取1条订阅事件。 919 920**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 921 922**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 923 924**返回值：** 925 926| 类型 | 说明 | 927| ----------------------------------- | ------------------------------------------------------ | 928| [AppEventPackage](#appeventpackage) | 取出的事件包对象，订阅事件数据被全部取出后会返回null。 | 929 930**示例：** 931 932```ts 933let holder4: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher4"); 934let eventPkg = holder4.takeNext(); 935``` 936 937## AppEventPackage 938 939提供了订阅返回的应用事件包的参数定义。 940 941**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 942 943| 名称 | 类型 | 必填 | 说明 | 944| --------- | -------- | ---- | ------------------------------ | 945| packageId | number | 是 | 事件包ID，从0开始自动递增。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 946| row | number | 是 | 事件包的事件数量。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 947| size | number | 是 | 事件包的事件大小，单位为byte。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 948| data | string[] | 是 | 事件包的事件信息。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 949| appEventInfos<sup>12+</sup> | Array<[AppEventInfo](#appeventinfo)> | 是 | 事件对象集合。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 950 951## AppEventGroup<sup>11+</sup> 952 953提供了订阅返回的事件组的参数定义。 954 955**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 956 957**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 958 959| 名称 | 类型 | 必填 | 说明 | 960| ------------- | ------------------------------- | ---- | ------------- | 961| name | string | 是 | 事件名称。 | 962| appEventInfos | Array<[AppEventInfo](#appeventinfo)> | 是 | 事件对象集合。 | 963 964## hiAppEvent.clearData 965 966clearData(): void 967 968应用事件打点数据清理方法，将应用存储在本地的打点数据进行清除。 969 970**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 971 972**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 973 974**示例：** 975 976```ts 977hiAppEvent.clearData(); 978``` 979 980 981## EventType 982 983事件类型枚举。 984 985**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 986 987**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 988 989| 名称 | 值 | 说明 | 990| --------- | ---- | -------------- | 991| FAULT | 1 | 故障类型事件。 | 992| STATISTIC | 2 | 统计类型事件。 | 993| SECURITY | 3 | 安全类型事件。 | 994| BEHAVIOR | 4 | 行为类型事件。 | 995 996 997## hiappevent.domain<sup>11+</sup> 998 999提供了所有预定义事件的领域名称常量。 1000 1001**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1002 1003**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 1004 1005| 名称 | 类型 | 只读 | 说明 | 1006| --- | ------ | ------ | ---------- | 1007| OS | string | 是 | 系统领域。 | 1008 1009 1010## hiappevent.event 1011 1012提供了所有预定义事件的事件名称常量。 1013 1014**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 1015 1016| 名称 | 类型 | 只读 | 说明 | 1017| ------------------------- | ------ | ------ | -------------------- | 1018| USER_LOGIN | string | 是 | 用户登录事件。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1019| USER_LOGOUT | string | 是 | 用户登出事件。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1020| DISTRIBUTED_SERVICE_START | string | 是 | 分布式服务启动事件。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1021| APP_CRASH<sup>11+</sup> | string | 是 | 应用崩溃事件。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1022| APP_FREEZE<sup>11+</sup> | string | 是 | 应用卡死事件。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 1023| APP_LAUNCH<sup>12+</sup> | string | 是 | 应用启动耗时事件。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1024| SCROLL_JANK<sup>12+</sup> | string | 是 | 应用滑动丢帧事件。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1025| CPU_USAGE_HIGH<sup>12+</sup> | string | 是 | 应用CPU高负载事件。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1026| BATTERY_USAGE<sup>12+</sup> | string | 是 | 应用24h功耗器件分解统计事件。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1027| RESOURCE_OVERLIMIT<sup>12+</sup> | string | 是 | 应用资源泄露事件。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1028| ADDRESS_SANITIZER<sup>12+</sup> | string | 是 | 应用踩内存事件。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1029| MAIN_THREAD_JANK<sup>12+</sup> | string | 是 | 应用主线程超时事件。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 1030 1031 1032## hiappevent.param 1033 1034提供了所有预定义参数的参数名称常量。 1035 1036**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1037 1038**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 1039 1040| 名称 | 类型 | 只读 | 说明 | 1041| ------------------------------- | ------ | ------ | ------------------ | 1042| USER_ID | string | 是 | 用户自定义ID。 | 1043| DISTRIBUTED_SERVICE_NAME | string | 是 | 分布式服务名称。 | 1044| DISTRIBUTED_SERVICE_INSTANCE_ID | string | 是 | 分布式服务实例ID。 |