1/* 2 * Copyright (C) 2021 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 21/** 22 * Provides interfaces to trace a task for performance measure, the logs can be capture by the 23 * bytrace cmdline available on the device. 24 * 25 * <p>This interfaces trace the start, end, and value changes of key processes that last for at least 3 ms. 26 * 27 * <p>Example: 28 * Track the beginning of a context: 29 * <pre>{@code 30 * hiTraceMeter.startTrace("checkName", 111); 31 * }</pre> 32 * Track the end of a context: 33 * <pre>{@code 34 * hiTraceMeter.finishTrace("checkName", 111); 35 * }</pre> 36 * To trace the number of layers, which is 3: 37 * <pre>{@code 38 * hiTraceMeter.traceByValue("curLayer", 3); 39 * }</pre> 40 * 41 * <p>Each {@code startTrace} matches one {@code finishTrace}, and they must have the same name 42 * and taskId. 43 * 44 * @namespace hiTraceMeter 45 * @syscap SystemCapability.HiviewDFX.HiTrace 46 * @since 8 47 */ 48/** 49 * Provides interfaces to trace a task for performance measure, the logs can be capture by the 50 * hitrace cmdline on the device. 51 * 52 * <p>This interfaces trace the start, end, and value changes of key processes that last for at least 3 ms. 53 * 54 * <p>Example: 55 * Track the beginning of a context: 56 * <pre>{@code 57 * hiTraceMeter.startAsyncTrace(hiTraceMeter.HiTraceOutputLevel.COMMERCIAL, "checkName", 111, "test", "key=value"); 58 * }</pre> 59 * Track the end of a context: 60 * <pre>{@code 61 * hiTraceMeter.finishAsyncTrace(hiTraceMeter.HiTraceOutputLevel.COMMERCIAL, "checkName", 111); 62 * }</pre> 63 * To trace the number of layers, which is 3: 64 * <pre>{@code 65 * hiTraceMeter.traceByValue(hiTraceMeter.HiTraceOutputLevel.COMMERCIAL, "curLayer", 3); 66 * }</pre> 67 * 68 * <p>Each {@code startTrace} matches one {@code finishTrace}, and they must have the same name 69 * and taskId. 70 * 71 * <p>Each {@code startSyncTrace} matches one {@code finishSyncTrace}, and they must have the same 72 * level and name. 73 * 74 * <p>Each {@code startAsyncTrace} matches one {@code finishAsyncTrace}, and they must have the same 75 * level, name and taskId. 76 * 77 * @namespace hiTraceMeter 78 * @syscap SystemCapability.HiviewDFX.HiTrace 79 * @atomicservice 80 * @since 19 81 */ 82/** 83 * Provides interfaces to trace a task for performance measure, the logs can be capture by the 84 * hitrace cmdline on the device. 85 * 86 * <p>This interfaces trace the start, end, and value changes of key processes that last for at least 3 ms. 87 * 88 * <p>Example: 89 * Track the beginning of a context: 90 * <pre>{@code 91 * hiTraceMeter.startAsyncTrace(hiTraceMeter.HiTraceOutputLevel.COMMERCIAL, "checkName", 111, "test", "key=value"); 92 * }</pre> 93 * Track the end of a context: 94 * <pre>{@code 95 * hiTraceMeter.finishAsyncTrace(hiTraceMeter.HiTraceOutputLevel.COMMERCIAL, "checkName", 111); 96 * }</pre> 97 * To trace the number of layers, which is 3: 98 * <pre>{@code 99 * hiTraceMeter.traceByValue(hiTraceMeter.HiTraceOutputLevel.COMMERCIAL, "curLayer", 3); 100 * }</pre> 101 * 102 * <p>Each {@code startTrace} matches one {@code finishTrace}, and they must have the same name 103 * and taskId. 104 * 105 * <p>Each {@code startSyncTrace} matches one {@code finishSyncTrace}, and they must have the same 106 * level and name. 107 * 108 * <p>Each {@code startAsyncTrace} matches one {@code finishAsyncTrace}, and they must have the same 109 * level, name and taskId. 110 * 111 * @namespace hiTraceMeter 112 * @syscap SystemCapability.HiviewDFX.HiTrace 113 * @crossplatform 114 * @atomicservice 115 * @since 20 116 * @arkts 1.1&1.2 117 */ 118declare namespace hiTraceMeter { 119 120 /** 121 * Enumerates the HiTrace output levels. The output level threshold system parameter determines 122 * the minimum output trace. 123 * 124 * @enum { number } 125 * @syscap SystemCapability.HiviewDFX.HiTrace 126 * @atomicservice 127 * @since 19 128 */ 129 /** 130 * Enumerates the HiTrace output levels. The output level threshold system parameter determines 131 * the minimum output trace. 132 * 133 * @enum { number } 134 * @syscap SystemCapability.HiviewDFX.HiTrace 135 * @crossplatform 136 * @atomicservice 137 * @since 20 138 * @arkts 1.1&1.2 139 */ 140 enum HiTraceOutputLevel { 141 /** 142 * Ouput level only for debug usage. 143 * 144 * @syscap SystemCapability.HiviewDFX.HiTrace 145 * @atomicservice 146 * @since 19 147 */ 148 /** 149 * Ouput level only for debug usage. 150 * 151 * @syscap SystemCapability.HiviewDFX.HiTrace 152 * @crossplatform 153 * @atomicservice 154 * @since 20 155 * @arkts 1.1&1.2 156 */ 157 DEBUG = 0, 158 159 /** 160 * Output level for log version usage. 161 * 162 * @syscap SystemCapability.HiviewDFX.HiTrace 163 * @atomicservice 164 * @since 19 165 */ 166 /** 167 * Output level for log version usage. 168 * 169 * @syscap SystemCapability.HiviewDFX.HiTrace 170 * @crossplatform 171 * @atomicservice 172 * @since 20 173 * @arkts 1.1&1.2 174 */ 175 INFO = 1, 176 177 /** 178 * Output level for log version usage, with higher priority than INFO. 179 * 180 * @syscap SystemCapability.HiviewDFX.HiTrace 181 * @atomicservice 182 * @since 19 183 */ 184 /** 185 * Output level for log version usage, with higher priority than INFO. 186 * 187 * @syscap SystemCapability.HiviewDFX.HiTrace 188 * @crossplatform 189 * @atomicservice 190 * @since 20 191 * @arkts 1.1&1.2 192 */ 193 CRITICAL = 2, 194 195 /** 196 * Output level for nolog version usage. 197 * 198 * @syscap SystemCapability.HiviewDFX.HiTrace 199 * @atomicservice 200 * @since 19 201 */ 202 /** 203 * Output level for nolog version usage. 204 * 205 * @syscap SystemCapability.HiviewDFX.HiTrace 206 * @crossplatform 207 * @atomicservice 208 * @since 20 209 * @arkts 1.1&1.2 210 */ 211 COMMERCIAL = 3, 212 213 /** 214 * Output level range limit. 215 * 216 * @syscap SystemCapability.HiviewDFX.HiTrace 217 * @atomicservice 218 * @since 19 219 */ 220 /** 221 * Output level range limit. 222 * 223 * @syscap SystemCapability.HiviewDFX.HiTrace 224 * @crossplatform 225 * @atomicservice 226 * @since 20 227 * @arkts 1.1&1.2 228 */ 229 MAX = COMMERCIAL 230 } 231 232 /** 233 * Records a trace marking it as the start of a task, can with the expected completion time between 234 * startTrace and finishTrace. 235 * 236 * This method is invoked at the start of a transaction to indicate that a task has started, whose name 237 * is specified by {@code name}, and the taskId is used to distinguish the tasks. It must be followed by 238 * {@link #finishTrace}, the name and taskId need to be the same. 239 * 240 * @param { string } name Indicates the task name. 241 * @param { number } taskId The unique id used to distinguish the tasks and match with the id in follow finishTrace. 242 * @syscap SystemCapability.HiviewDFX.HiTrace 243 * @since 8 244 */ 245 /** 246 * Records a trace marking it as the start of a task, can with the expected completion time between 247 * startTrace and finishTrace. 248 * 249 * This method is invoked at the start of a transaction to indicate that a task has started, whose name 250 * is specified by {@code name}, and the taskId is used to distinguish the tasks. It must be followed by 251 * {@link #finishTrace}, the name and taskId need to be the same. 252 * 253 * @param { string } name Indicates the task name. 254 * @param { number } taskId The unique id used to distinguish the tasks and match with the id in follow finishTrace. 255 * @syscap SystemCapability.HiviewDFX.HiTrace 256 * @atomicservice 257 * @since 19 258 */ 259 /** 260 * Records a trace marking it as the start of a task, can with the expected completion time between 261 * startTrace and finishTrace. 262 * 263 * This method is invoked at the start of a transaction to indicate that a task has started, whose name 264 * is specified by {@code name}, and the taskId is used to distinguish the tasks. It must be followed by 265 * {@link #finishTrace}, the name and taskId need to be the same. 266 * 267 * @param { string } name Indicates the task name. 268 * @param { number } taskId The unique id used to distinguish the tasks and match with the id in follow finishTrace. 269 * @syscap SystemCapability.HiviewDFX.HiTrace 270 * @crossplatform 271 * @atomicservice 272 * @since 20 273 * @arkts 1.1&1.2 274 */ 275 function startTrace(name: string, taskId: number): void; 276 277 /** 278 * Records a trace and marks it as the end of a task. 279 * 280 * This method is invoked at the end of a transaction to indicate that a task has ended, whose name 281 * is specified by {@code name}. This method must be invoked after the the startTrace. 282 * 283 * @param { string } name Indicates the task name. It must be the same with the {@code name} of startTrace. 284 * @param { number } taskId The unique id used to distinguish the tasks and must be the same with the . 285 * {@code taskId} of startTrace. 286 * @syscap SystemCapability.HiviewDFX.HiTrace 287 * @since 8 288 */ 289 /** 290 * Records a trace and marks it as the end of a task. 291 * 292 * This method is invoked at the end of a transaction to indicate that a task has ended, whose name 293 * is specified by {@code name}. This method must be invoked after {@link #startTrace}. 294 * 295 * @param { string } name Indicates the task name. It must be the same with the {@code name} of startTrace. 296 * @param { number } taskId The unique id used to distinguish the tasks and must be the same with the 297 * {@code taskId} of startTrace. 298 * @syscap SystemCapability.HiviewDFX.HiTrace 299 * @atomicservice 300 * @since 19 301 */ 302 /** 303 * Records a trace and marks it as the end of a task. 304 * 305 * This method is invoked at the end of a transaction to indicate that a task has ended, whose name 306 * is specified by {@code name}. This method must be invoked after {@link #startTrace}. 307 * 308 * @param { string } name Indicates the task name. It must be the same with the {@code name} of startTrace. 309 * @param { number } taskId The unique id used to distinguish the tasks and must be the same with the 310 * {@code taskId} of startTrace. 311 * @syscap SystemCapability.HiviewDFX.HiTrace 312 * @crossplatform 313 * @atomicservice 314 * @since 20 315 * @arkts 1.1&1.2 316 */ 317 function finishTrace(name: string, taskId: number): void; 318 319 /** 320 * Records a trace for generating a count, such as clock pulse and the number of layers. 321 * 322 * @param { string } name Indicates the name used to identify the count. 323 * @param { number } count Indicates the number of the count. 324 * @syscap SystemCapability.HiviewDFX.HiTrace 325 * @since 8 326 */ 327 /** 328 * Records a trace for generating a count, such as clock pulse and the number of layers. 329 * 330 * @param { string } name Indicates the name used to identify the count. 331 * @param { number } count Indicates the number of the count. 332 * @syscap SystemCapability.HiviewDFX.HiTrace 333 * @atomicservice 334 * @since 19 335 */ 336 /** 337 * Records a trace for generating a count, such as clock pulse and the number of layers. 338 * 339 * @param { string } name Indicates the name used to identify the count. 340 * @param { number } count Indicates the number of the count. 341 * @syscap SystemCapability.HiviewDFX.HiTrace 342 * @crossplatform 343 * @atomicservice 344 * @since 20 345 * @arkts 1.1&1.2 346 */ 347 function traceByValue(name: string, count: number): void; 348 349 /** 350 * Records a trace marking it as the start of a task. 351 * 352 * This method is invoked at the start of a transaction to indicate that a task has started, whose name 353 * is specified by {@code name}, and the taskId is used to distinguish the tasks. It must be followed by 354 * {@link #finishSyncTrace}, called by the same thread with the same level. 355 * 356 * @param { HiTraceOutputLevel } level Indicates trace output priority level. 357 * @param { string } name Indicates the task name. 358 * @param { string } [customArgs] Indicates key=value pair to be output in trace; multiple pairs should use comma 359 * as separator. 360 * @syscap SystemCapability.HiviewDFX.HiTrace 361 * @atomicservice 362 * @since 19 363 */ 364 /** 365 * Records a trace marking it as the start of a task. 366 * 367 * This method is invoked at the start of a transaction to indicate that a task has started, whose name 368 * is specified by {@code name}, and the taskId is used to distinguish the tasks. It must be followed by 369 * {@link #finishSyncTrace}, called by the same thread with the same level. 370 * 371 * @param { HiTraceOutputLevel } level Indicates trace output priority level. 372 * @param { string } name Indicates the task name. 373 * @param { string } [customArgs] Indicates key=value pair to be output in trace; multiple pairs should use comma 374 * as separator. 375 * @syscap SystemCapability.HiviewDFX.HiTrace 376 * @crossplatform 377 * @atomicservice 378 * @since 20 379 * @arkts 1.1&1.2 380 */ 381 function startSyncTrace(level: HiTraceOutputLevel, name: string, customArgs?: string): void; 382 383 /** 384 * Records a trace and marks it as the end of a task. 385 * 386 * This method is invoked at the end of a transaction to indicate that the nearest running task tracked by 387 * startSyncTrace that has yet to be marked by finishSyncTrace, has ended. 388 * This method must be invoked after {@link #startSyncTrace}, called by the same thread with the same level. 389 * 390 * @param { HiTraceOutputLevel } level Indicates trace output priority level. 391 * @syscap SystemCapability.HiviewDFX.HiTrace 392 * @atomicservice 393 * @since 19 394 */ 395 /** 396 * Records a trace and marks it as the end of a task. 397 * 398 * This method is invoked at the end of a transaction to indicate that the nearest running task tracked by 399 * startSyncTrace that has yet to be marked by finishSyncTrace, has ended. 400 * This method must be invoked after {@link #startSyncTrace}, called by the same thread with the same level. 401 * 402 * @param { HiTraceOutputLevel } level Indicates trace output priority level. 403 * @syscap SystemCapability.HiviewDFX.HiTrace 404 * @crossplatform 405 * @atomicservice 406 * @since 20 407 * @arkts 1.1&1.2 408 */ 409 function finishSyncTrace(level: HiTraceOutputLevel): void; 410 411 /** 412 * Records a trace marking it as the start of a task. 413 * 414 * This method is invoked at the start of a transaction to indicate that a task has started, whose name 415 * is specified by {@code name}, and the taskId is used to distinguish the tasks. It must be followed by a 416 * corresponding {@link #finishAsyncTrace}, with the same level, name, and taskId. 417 * 418 * @param { HiTraceOutputLevel } level Indicates trace output priority level. 419 * @param { string } name Indicates the task name. 420 * @param { number } taskId The unique id used to distinguish the task and match with the id of the 421 * corresponding finishAsyncTrace. 422 * @param { string } customCategory Indicates the label to aggregate asynchronous task display. 423 * @param { string } [customArgs] Indicates key=value pair to be output in trace; multiple pairs should use comma 424 * as Separator. 425 * @syscap SystemCapability.HiviewDFX.HiTrace 426 * @atomicservice 427 * @since 19 428 */ 429 /** 430 * Records a trace marking it as the start of a task. 431 * 432 * This method is invoked at the start of a transaction to indicate that a task has started, whose name 433 * is specified by {@code name}, and the taskId is used to distinguish the tasks. It must be followed by a 434 * corresponding {@link #finishAsyncTrace}, with the same level, name, and taskId. 435 * 436 * @param { HiTraceOutputLevel } level Indicates trace output priority level. 437 * @param { string } name Indicates the task name. 438 * @param { number } taskId The unique id used to distinguish the task and match with the id of the 439 * corresponding finishAsyncTrace. 440 * @param { string } customCategory Indicates the label to aggregate asynchronous task display. 441 * @param { string } [customArgs] Indicates key=value pair to be output in trace; multiple pairs should use comma 442 * as Separator. 443 * @syscap SystemCapability.HiviewDFX.HiTrace 444 * @crossplatform 445 * @atomicservice 446 * @since 20 447 * @arkts 1.1&1.2 448 */ 449 function startAsyncTrace(level: HiTraceOutputLevel, name: string, taskId: number, customCategory: string, 450 customArgs?: string): void; 451 452 /** 453 * Records a trace and marks it as the end of a task. 454 * 455 * This method is invoked at the end of a transaction to indicate that a task has ended, whose name is specified 456 * by {@code name}. This method must be invoked after {@link #startAsyncTrace}, with the same level, name, 457 * and taskId. It is not required to be invoked by the same thread calling startAsyncTrace. 458 * 459 * @param { HiTraceOutputLevel } level Indicates trace output priority level. 460 * @param { string } name Indicates the task name. 461 * @param { number } taskId The unique id used to distinguish the task and match with the id of the corresponding 462 * startAsyncTrace. 463 * @syscap SystemCapability.HiviewDFX.HiTrace 464 * @atomicservice 465 * @since 19 466 */ 467 /** 468 * Records a trace and marks it as the end of a task. 469 * 470 * This method is invoked at the end of a transaction to indicate that a task has ended, whose name is specified 471 * by {@code name}. This method must be invoked after {@link #startAsyncTrace}, with the same level, name, 472 * and taskId. It is not required to be invoked by the same thread calling startAsyncTrace. 473 * 474 * @param { HiTraceOutputLevel } level Indicates trace output priority level. 475 * @param { string } name Indicates the task name. 476 * @param { number } taskId The unique id used to distinguish the task and match with the id of the corresponding 477 * startAsyncTrace. 478 * @syscap SystemCapability.HiviewDFX.HiTrace 479 * @crossplatform 480 * @atomicservice 481 * @since 20 482 * @arkts 1.1&1.2 483 */ 484 function finishAsyncTrace(level: HiTraceOutputLevel, name: string, taskId: number): void; 485 486 /** 487 * Records a trace for generating a count, such as clock pulse and the number of layers. 488 * 489 * @param { HiTraceOutputLevel } level Indicates trace output priority level. 490 * @param { string } name Indicates the name used to identify the count. 491 * @param { number } count Indicates the number of the count. 492 * @syscap SystemCapability.HiviewDFX.HiTrace 493 * @atomicservice 494 * @since 19 495 */ 496 /** 497 * Records a trace for generating a count, such as clock pulse and the number of layers. 498 * 499 * @param { HiTraceOutputLevel } level Indicates trace output priority level. 500 * @param { string } name Indicates the name used to identify the count. 501 * @param { number } count Indicates the number of the count. 502 * @syscap SystemCapability.HiviewDFX.HiTrace 503 * @crossplatform 504 * @atomicservice 505 * @since 20 506 * @arkts 1.1&1.2 507 */ 508 function traceByValue(level: HiTraceOutputLevel, name: string, count: number): void; 509 510 /** 511 * Return whether the current process is allowed to output trace. 512 * 513 * @returns { boolean } The status of whether the current process is allowed to output trace. 514 * @syscap SystemCapability.HiviewDFX.HiTrace 515 * @atomicservice 516 * @since 19 517 */ 518 /** 519 * Return whether the current process is allowed to output trace. 520 * 521 * @returns { boolean } The status of whether the current process is allowed to output trace. 522 * @syscap SystemCapability.HiviewDFX.HiTrace 523 * @crossplatform 524 * @atomicservice 525 * @since 20 526 * @arkts 1.1&1.2 527 */ 528 function isTraceEnabled(): boolean; 529} 530 531export default hiTraceMeter; 532