1/* 2 * Copyright (c) 2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit PerformanceAnalysisKit 19 */ 20 21import { AsyncCallback } from './@ohos.base'; 22 23/** 24 * Provides the system event logging function for applications to log the fault, statistical, security, 25 * and user behavior events reported during running. Based on event information, 26 * you will be able to analyze the running status of applications. 27 * 28 * @namespace hiSysEvent 29 * @syscap SystemCapability.HiviewDFX.HiSysEvent 30 * @systemapi hide for inner use 31 * @since 9 32 */ 33declare namespace hiSysEvent { 34 /** 35 * Enumerate system event types. 36 * 37 * @enum {number} 38 * @syscap SystemCapability.HiviewDFX.HiSysEvent 39 * @systemapi hide for inner use 40 * @since 9 41 */ 42 enum EventType { 43 /** 44 * Fault event 45 * 46 * @syscap SystemCapability.HiviewDFX.HiSysEvent 47 * @systemapi hide for inner use 48 * @since 9 49 */ 50 FAULT = 1, 51 52 /** 53 * Statistic event 54 * 55 * @syscap SystemCapability.HiviewDFX.HiSysEvent 56 * @systemapi hide for inner use 57 * @since 9 58 */ 59 STATISTIC = 2, 60 61 /** 62 * Security event 63 * 64 * @syscap SystemCapability.HiviewDFX.HiSysEvent 65 * @systemapi hide for inner use 66 * @since 9 67 */ 68 SECURITY = 3, 69 70 /** 71 * System behavior event 72 * 73 * @syscap SystemCapability.HiviewDFX.HiSysEvent 74 * @systemapi hide for inner use 75 * @since 9 76 */ 77 BEHAVIOR = 4 78 } 79 80 /** 81 * Definition of written system event information. 82 * 83 * @interface SysEventInfo 84 * @syscap SystemCapability.HiviewDFX.HiSysEvent 85 * @systemapi hide for inner use 86 * @since 9 87 */ 88 interface SysEventInfo { 89 /** 90 * The domain of the event. 91 * 92 * @type { string } 93 * @syscap SystemCapability.HiviewDFX.HiSysEvent 94 * @systemapi hide for inner use 95 * @since 9 96 */ 97 domain: string; 98 99 /** 100 * The name of the event. 101 * 102 * @type { string } 103 * @syscap SystemCapability.HiviewDFX.HiSysEvent 104 * @systemapi hide for inner use 105 * @since 9 106 */ 107 name: string; 108 109 /** 110 * The type of the event. 111 * 112 * @type { EventType } 113 * @syscap SystemCapability.HiviewDFX.HiSysEvent 114 * @systemapi hide for inner use 115 * @since 9 116 */ 117 eventType: EventType; 118 119 /** 120 * The params of the event. 121 * 122 * @type { ?object } 123 * @syscap SystemCapability.HiviewDFX.HiSysEvent 124 * @systemapi hide for inner use 125 * @since 9 126 */ 127 params?: object; 128 } 129 130 /** 131 * Write system event. 132 * 133 * @param {SysEventInfo} info - system event information to be written. 134 * @returns {Promise<void>} - Return Promise 135 * @throws {BusinessError} 401 - Parameter error. Possible causes: 136 * 1. Mandatory parameters are left unspecified. 137 * 2. Incorrect parameter types. 138 * 3. Parameter verification failed. 139 * @throws {BusinessError} 11200001 - Invalid event domain. 140 * @throws {BusinessError} 11200002 - Invalid event name. 141 * @throws {BusinessError} 11200003 - Abnormal environment. 142 * @throws {BusinessError} 11200004 - The event length exceeds the limit. 143 * @throws {BusinessError} 11200051 - Invalid event parameter. 144 * @throws {BusinessError} 11200052 - The size of the event parameter of the string type exceeds the limit. 145 * @throws {BusinessError} 11200053 - The number of event parameters exceeds the limit. 146 * @throws {BusinessError} 11200054 - The number of event parameters of the array type exceeds the limit. 147 * @syscap SystemCapability.HiviewDFX.HiSysEvent 148 * @systemapi hide for inner use 149 * @since 9 150 */ 151 function write(info: SysEventInfo): Promise<void>; 152 153 /** 154 * Write system event. 155 * 156 * @param {SysEventInfo} info - system event information to be written. 157 * @param {AsyncCallback<void>} callback - callback function. 158 * @throws {BusinessError} 401 - Parameter error. Possible causes: 159 * 1. Mandatory parameters are left unspecified. 160 * 2. Incorrect parameter types. 161 * 3. Parameter verification failed. 162 * @throws {BusinessError} 11200001 - Invalid event domain. 163 * @throws {BusinessError} 11200002 - Invalid event name. 164 * @throws {BusinessError} 11200003 - Abnormal environment. 165 * @throws {BusinessError} 11200004 - The event length exceeds the limit. 166 * @throws {BusinessError} 11200051 - Invalid event parameter. 167 * @throws {BusinessError} 11200052 - The size of the event parameter of the string type exceeds the limit. 168 * @throws {BusinessError} 11200053 - The number of event parameters exceeds the limit. 169 * @throws {BusinessError} 11200054 - The number of event parameters of the array type exceeds the limit. 170 * @syscap SystemCapability.HiviewDFX.HiSysEvent 171 * @systemapi hide for inner use 172 * @since 9 173 */ 174 function write(info: SysEventInfo, callback: AsyncCallback<void>): void; 175 176 /** 177 * Enumerate search system event rule type. 178 * 179 * @enum {number} 180 * @syscap SystemCapability.HiviewDFX.HiSysEvent 181 * @systemapi hide for inner use 182 * @since 9 183 */ 184 enum RuleType { 185 /** 186 * Whole word match 187 * 188 * @syscap SystemCapability.HiviewDFX.HiSysEvent 189 * @systemapi hide for inner use 190 * @since 9 191 */ 192 WHOLE_WORD = 1, 193 194 /** 195 * Prefix match 196 * 197 * @syscap SystemCapability.HiviewDFX.HiSysEvent 198 * @systemapi hide for inner use 199 * @since 9 200 */ 201 PREFIX = 2, 202 203 /** 204 * Regular match 205 * 206 * @syscap SystemCapability.HiviewDFX.HiSysEvent 207 * @systemapi hide for inner use 208 * @since 9 209 */ 210 REGULAR = 3 211 } 212 213 /** 214 * Definition listener rule for system event information. 215 * 216 * @interface WatchRule 217 * @syscap SystemCapability.HiviewDFX.HiSysEvent 218 * @systemapi hide for inner use 219 * @since 9 220 */ 221 interface WatchRule { 222 /** 223 * The domain of the event. 224 * 225 * @type { string } 226 * @syscap SystemCapability.HiviewDFX.HiSysEvent 227 * @systemapi hide for inner use 228 * @since 9 229 */ 230 domain: string; 231 232 /** 233 * The name of the event. 234 * 235 * @type { string } 236 * @syscap SystemCapability.HiviewDFX.HiSysEvent 237 * @systemapi hide for inner use 238 * @since 9 239 */ 240 name: string; 241 242 /** 243 * The tag of the event. 244 * 245 * @type { ?string } 246 * @syscap SystemCapability.HiviewDFX.HiSysEvent 247 * @systemapi hide for inner use 248 * @since 9 249 */ 250 tag?: string; 251 252 /** 253 * The rule of match system event 254 * 255 * @type { RuleType } 256 * @syscap SystemCapability.HiviewDFX.HiSysEvent 257 * @systemapi hide for inner use 258 * @since 9 259 */ 260 ruleType: RuleType; 261 } 262 263 /** 264 * Definition watcher for system event information. 265 * 266 * @interface Watcher 267 * @syscap SystemCapability.HiviewDFX.HiSysEvent 268 * @systemapi hide for inner use 269 * @since 9 270 */ 271 interface Watcher { 272 /** 273 * Rule of filter system event 274 * 275 * @syscap SystemCapability.HiviewDFX.HiSysEvent 276 * @systemapi hide for inner use 277 * @since 9 278 */ 279 rules: WatchRule[]; 280 281 /** 282 * Receive system event. 283 * 284 * @syscap SystemCapability.HiviewDFX.HiSysEvent 285 * @systemapi hide for inner use 286 * @since 9 287 */ 288 onEvent: (info: SysEventInfo) => void; 289 290 /** 291 * Hisysevent service shutdown. 292 * 293 * @syscap SystemCapability.HiviewDFX.HiSysEvent 294 * @systemapi hide for inner use 295 * @since 9 296 */ 297 onServiceDied: () => void; 298 } 299 300 /** 301 * Definition arguments for query system event information. 302 * 303 * @interface QueryArg 304 * @syscap SystemCapability.HiviewDFX.HiSysEvent 305 * @systemapi hide for inner use 306 * @since 9 307 */ 308 interface QueryArg { 309 /** 310 * Begin time 311 * 312 * @type { number } 313 * @syscap SystemCapability.HiviewDFX.HiSysEvent 314 * @systemapi hide for inner use 315 * @since 9 316 */ 317 beginTime: number; 318 319 /** 320 * End time 321 * 322 * @type { number } 323 * @syscap SystemCapability.HiviewDFX.HiSysEvent 324 * @systemapi hide for inner use 325 * @since 9 326 */ 327 endTime: number; 328 329 /** 330 * Max number of receive system event 331 * 332 * @type { number } 333 * @syscap SystemCapability.HiviewDFX.HiSysEvent 334 * @systemapi hide for inner use 335 * @since 9 336 */ 337 maxEvents: number; 338 339 /** 340 * Begin sequence 341 * 342 * @type { ?number } 343 * @syscap SystemCapability.HiviewDFX.HiSysEvent 344 * @systemapi hide for inner use 345 * @since 10 346 */ 347 fromSeq?: number; 348 349 /** 350 * End sequence 351 * 352 * @type { ?number } 353 * @syscap SystemCapability.HiviewDFX.HiSysEvent 354 * @systemapi hide for inner use 355 * @since 10 356 */ 357 toSeq?: number; 358 } 359 360 /** 361 * Definition event for query system event information 362 * 363 * @interface QueryRule 364 * @syscap SystemCapability.HiviewDFX.HiSysEvent 365 * @systemapi hide for inner use 366 * @since 9 367 */ 368 interface QueryRule { 369 /** 370 * The domain of the event 371 * 372 * @type { string } 373 * @syscap SystemCapability.HiviewDFX.HiSysEvent 374 * @systemapi hide for inner use 375 * @since 9 376 */ 377 domain: string; 378 379 /** 380 * List of event name 381 * 382 * @type { string[] } 383 * @syscap SystemCapability.HiviewDFX.HiSysEvent 384 * @systemapi hide for inner use 385 * @since 9 386 */ 387 names: string[]; 388 389 /** 390 * Extra parameter condition of event 391 * 392 * @type { ?string } 393 * @syscap SystemCapability.HiviewDFX.HiSysEvent 394 * @systemapi hide for inner use 395 * @since 10 396 */ 397 condition?: string; 398 } 399 400 /** 401 * Definition query result handler 402 * 403 * @interface Querier 404 * @syscap SystemCapability.HiviewDFX.HiSysEvent 405 * @systemapi hide for inner use 406 * @since 9 407 */ 408 interface Querier { 409 /** 410 * Handle query result, the query result will be send in several times. 411 * 412 * @syscap SystemCapability.HiviewDFX.HiSysEvent 413 * @systemapi hide for inner use 414 * @since 9 415 */ 416 onQuery: (infos: SysEventInfo[]) => void; 417 418 /** 419 * Notify querier execute query has finished. 420 * 421 * @syscap SystemCapability.HiviewDFX.HiSysEvent 422 * @systemapi hide for inner use 423 * @since 9 424 */ 425 onComplete: (reason: number, total: number) => void; 426 } 427 428 /** 429 * Add watcher to watch system event 430 * 431 * @permission ohos.permission.READ_DFX_SYSEVENT 432 * @param {Watcher} watcher watch system event 433 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 434 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 435 * @throws {BusinessError} 401 - Parameter error. Possible causes: 436 * 1. Mandatory parameters are left unspecified. 437 * 2. Incorrect parameter types. 438 * 3. Parameter verification failed. 439 * @throws {BusinessError} 11200101 - The number of watchers exceeds the limit. 440 * @throws {BusinessError} 11200102 - The number of watch rules exceeds the limit. 441 * @syscap SystemCapability.HiviewDFX.HiSysEvent 442 * @systemapi hide for inner use 443 * @since 9 444 */ 445 function addWatcher(watcher: Watcher): void; 446 447 /** 448 * Remove watcher 449 * 450 * @permission ohos.permission.READ_DFX_SYSEVENT 451 * @param {Watcher} watcher watch system event 452 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 453 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 454 * @throws {BusinessError} 401 - Parameter error. Possible causes: 455 * 1. Mandatory parameters are left unspecified. 456 * 2. Incorrect parameter types. 457 * 3. Parameter verification failed. 458 * @throws {BusinessError} 11200201 - The watcher does not exist. 459 * @syscap SystemCapability.HiviewDFX.HiSysEvent 460 * @systemapi hide for inner use 461 * @since 9 462 */ 463 function removeWatcher(watcher: Watcher): void; 464 465 /** 466 * Query system event 467 * 468 * @permission ohos.permission.READ_DFX_SYSEVENT 469 * @param {QueryArg} queryArg common arguments of query system event 470 * @param {QueryRule[]} rules rule of query system event 471 * @param {Querier} querier receive query result 472 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 473 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 474 * @throws {BusinessError} 401 - Parameter error. Possible causes: 475 * 1. Mandatory parameters are left unspecified. 476 * 2. Incorrect parameter types. 477 * 3. Parameter verification failed. 478 * @throws {BusinessError} 11200301 - The number of query rules exceeds the limit. 479 * @throws {BusinessError} 11200302 - Invalid query rule. 480 * @throws {BusinessError} 11200303 - The number of concurrent queriers exceeds the limit. 481 * @throws {BusinessError} 11200304 - The query frequency exceeds the limit. 482 * @syscap SystemCapability.HiviewDFX.HiSysEvent 483 * @systemapi hide for inner use 484 * @since 9 485 */ 486 function query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): void; 487 488 /** 489 * Export system event 490 * 491 * @permission ohos.permission.READ_DFX_SYSEVENT 492 * @param {QueryArg} queryArg common arguments of query system event 493 * @param {QueryRule[]} rules rule of query system event 494 * @returns {number} return hiview receive task time. 495 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 496 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 497 * @throws {BusinessError} 401 - Parameter error. Possible causes: 498 * 1. Mandatory parameters are left unspecified. 499 * 2. Incorrect parameter types. 500 * 3. Parameter verification failed. 501 * @throws {BusinessError} 11200301 - The number of query rules exceeds the limit. 502 * @throws {BusinessError} 11200302 - Invalid query rule. 503 * @throws {BusinessError} 11200304 – The query frequency exceeds the limit. 504 * @syscap SystemCapability.HiviewDFX.HiSysEvent 505 * @systemapi hide for inner use 506 * @since 10 507 */ 508 function exportSysEvents(queryArg: QueryArg, rules: QueryRule[]): number; 509 510 /** 511 * Subscribe system event 512 * 513 * @permission ohos.permission.READ_DFX_SYSEVENT 514 * @param {QueryRule[]} rules rule of subscribe system event 515 * @returns {number} return hiview receive task time. 516 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 517 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 518 * @throws {BusinessError} 401 - Parameter error. Possible causes: 519 * 1. Mandatory parameters are left unspecified. 520 * 2. Incorrect parameter types. 521 * 3. Parameter verification failed. 522 * @throws {BusinessError} 11200301 - The number of query rules exceeds the limit. 523 * @throws {BusinessError} 11200302 - Invalid query rule. 524 * @syscap SystemCapability.HiviewDFX.HiSysEvent 525 * @systemapi hide for inner use 526 * @since 10 527 */ 528 function subscribe(rules: QueryRule[]): number; 529 530 /** 531 * Unsubscribe system event 532 * 533 * @permission ohos.permission.READ_DFX_SYSEVENT 534 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 535 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 536 * @throws {BusinessError} 401 - Parameter error. Possible causes: 537 * 1. Mandatory parameters are left unspecified. 538 * 2. Incorrect parameter types. 539 * 3. Parameter verification failed. 540 * @throws {BusinessError} 11200305 – Unsubscription failed. 541 * @syscap SystemCapability.HiviewDFX.HiSysEvent 542 * @systemapi hide for inner use 543 * @since 10 544 */ 545 function unsubscribe(): void; 546} 547 548export default hiSysEvent; 549