1 /* 2 * Copyright (c) 2023 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 * @addtogroup Hitrace 18 * @{ 19 * 20 * @brief hiTraceMeter provides APIs for system performance trace. 21 * 22 * You can call the APIs provided by hiTraceMeter in your own service logic to effectively 23 * track service processes and check the system performance. 24 * 25 * @brief hitraceChain provides APIs for cross-thread and cross-process distributed tracing. 26 * hiTraceChain generates a unique chain ID for a service process and passes it to various information (including 27 * application events, system events, and logs) specific to the service process. 28 * During debugging and fault locating, you can use the unique chain ID to quickly correlate various information related 29 * to the service process. 30 * 31 * @syscap SystemCapability.HiviewDFX.HiTrace 32 * 33 * @since 10 34 */ 35 36 /** 37 * @file trace.h 38 * 39 * @kit PerformanceAnalysisKit 40 * 41 * @brief Defines APIs of the HiTraceMeter module for performance trace. 42 * 43 * @library libhitracechain.so 44 * @syscap SystemCapability.HiviewDFX.HiTrace 45 * @since 10 46 */ 47 48 #ifndef HIVIEWDFX_HITRACE_H 49 #define HIVIEWDFX_HITRACE_H 50 51 #include <stdint.h> 52 #include <stdbool.h> 53 54 #ifdef __cplusplus 55 extern "C" { 56 #endif 57 58 /** 59 * @brief Defines whether a <b>HiTraceId</b> instance is valid. 60 * 61 * @syscap SystemCapability.HiviewDFX.HiTrace 62 * 63 * @since 12 64 */ 65 typedef enum HiTraceId_Valid { 66 /** 67 * @brief Invalid <b>HiTraceId</b> instance. 68 * 69 * @syscap SystemCapability.HiviewDFX.HiTrace 70 * 71 * @since 12 72 */ 73 HITRACE_ID_INVALID = 0, 74 75 /** 76 * @brief Valid <b>HiTraceId</b> instance. 77 * 78 * @syscap SystemCapability.HiviewDFX.HiTrace 79 * 80 * @since 12 81 */ 82 HITRACE_ID_VALID = 1, 83 } HiTraceId_Valid; 84 85 /** 86 * @brief Enumerates the HiTrace version numbers. 87 * 88 * @syscap SystemCapability.HiviewDFX.HiTrace 89 * 90 * @since 12 91 */ 92 typedef enum HiTrace_Version { 93 /** 94 * @brief Version 1. 95 * 96 * @syscap SystemCapability.HiviewDFX.HiTrace 97 * 98 * @since 12 99 */ 100 HITRACE_VER_1 = 0, 101 } HiTrace_Version; 102 103 /** 104 * @brief Enumerates the HiTrace flags. 105 * 106 * @syscap SystemCapability.HiviewDFX.HiTrace 107 * 108 * @since 12 109 */ 110 typedef enum HiTrace_Flag { 111 /** 112 * @brief Default flag. 113 * 114 * @syscap SystemCapability.HiviewDFX.HiTrace 115 * 116 * @since 12 117 */ 118 HITRACE_FLAG_DEFAULT = 0, 119 120 /** 121 * @brief Both synchronous and asynchronous calls are traced. By default, only synchronous calls are traced. 122 * 123 * @syscap SystemCapability.HiviewDFX.HiTrace 124 * 125 * @since 12 126 */ 127 HITRACE_FLAG_INCLUDE_ASYNC = 1 << 0, 128 129 /** 130 * @brief No spans are created. By default, spans are created. 131 * 132 * @syscap SystemCapability.HiviewDFX.HiTrace 133 * 134 * @since 12 135 */ 136 HITRACE_FLAG_DONOT_CREATE_SPAN = 1 << 1, 137 138 /** 139 * @brief Trace points are automatically added to spans. By default, no trace point is added. 140 * 141 * @syscap SystemCapability.HiviewDFX.HiTrace 142 * 143 * @since 12 144 */ 145 HITRACE_FLAG_TP_INFO = 1 << 2, 146 147 /** 148 * @brief Information about the start and end of the trace task is not printed. By default, information about the 149 * start and end of the trace task is printed. 150 * 151 * @syscap SystemCapability.HiviewDFX.HiTrace 152 * 153 * @since 12 154 */ 155 HITRACE_FLAG_NO_BE_INFO = 1 << 3, 156 157 /** 158 * @brief The ID is not added to the log. By default, the ID is added to the log. 159 * 160 * @syscap SystemCapability.HiviewDFX.HiTrace 161 * 162 * @since 12 163 */ 164 HITRACE_FLAG_DONOT_ENABLE_LOG = 1 << 4, 165 166 /** 167 * @brief Tracing is triggered by faults. 168 * 169 * @syscap SystemCapability.HiviewDFX.HiTrace 170 * 171 * @since 12 172 */ 173 HITRACE_FLAG_FAULT_TRIGGER = 1 << 5, 174 175 /** 176 * @brief Trace points are added only for call chain trace between devices. 177 * By default, device-to-device trace points are not added. 178 * 179 * @syscap SystemCapability.HiviewDFX.HiTrace 180 * 181 * @since 12 182 */ 183 HITRACE_FLAG_D2D_TP_INFO = 1 << 6, 184 } HiTrace_Flag; 185 186 /** 187 * @brief Enumerates the HiTrace trace point types. 188 * 189 * @syscap SystemCapability.HiviewDFX.HiTrace 190 * 191 * @since 12 192 */ 193 typedef enum HiTrace_Tracepoint_Type { 194 /** 195 * @brief CS trace point. 196 * 197 * @syscap SystemCapability.HiviewDFX.HiTrace 198 * 199 * @since 12 200 */ 201 HITRACE_TP_CS = 0, 202 /** 203 * @brief CR trace point. 204 * 205 * @syscap SystemCapability.HiviewDFX.HiTrace 206 * 207 * @since 12 208 */ 209 HITRACE_TP_CR = 1, 210 /** 211 * @brief SS trace point. 212 * 213 * @syscap SystemCapability.HiviewDFX.HiTrace 214 * 215 * @since 12 216 */ 217 HITRACE_TP_SS = 2, 218 /** 219 * @brief SR trace point. 220 * 221 * @syscap SystemCapability.HiviewDFX.HiTrace 222 * 223 * @since 12 224 */ 225 HITRACE_TP_SR = 3, 226 /** 227 * @brief General trace point. 228 * 229 * @syscap SystemCapability.HiviewDFX.HiTrace 230 * 231 * @since 12 232 */ 233 HITRACE_TP_GENERAL = 4, 234 } HiTrace_Tracepoint_Type; 235 236 /** 237 * @brief Enumerates the HiTrace communication modes. 238 * 239 * @syscap SystemCapability.HiviewDFX.HiTrace 240 * 241 * @since 12 242 */ 243 typedef enum HiTrace_Communication_Mode { 244 /** 245 * @brief Default communication mode. 246 * 247 * @syscap SystemCapability.HiviewDFX.HiTrace 248 * 249 * @since 12 250 */ 251 HITRACE_CM_DEFAULT = 0, 252 /** 253 * @brief Inter-thread communication. 254 * 255 * @syscap SystemCapability.HiviewDFX.HiTrace 256 * 257 * @since 12 258 */ 259 HITRACE_CM_THREAD = 1, 260 /** 261 * @brief Inter-process communication. 262 * 263 * @syscap SystemCapability.HiviewDFX.HiTrace 264 * 265 * @since 12 266 */ 267 HITRACE_CM_PROCESS = 2, 268 /** 269 * @brief Inter-device communication. 270 * 271 * @syscap SystemCapability.HiviewDFX.HiTrace 272 * 273 * @since 12 274 */ 275 HITRACE_CM_DEVICE = 3, 276 } HiTrace_Communication_Mode; 277 278 /** 279 * @brief Enumerates the HiTrace output levels. The output level threshold system parameter determines 280 * the minimum output trace. 281 * 282 * @atomicservice 283 * 284 * @since 19 285 */ 286 typedef enum HiTrace_Output_Level { 287 /** 288 * @brief Output level only for debug usage. 289 * 290 * @atomicservice 291 * 292 * @since 19 293 */ 294 HITRACE_LEVEL_DEBUG = 0, 295 /** 296 * @brief Output level for log version usage. 297 * 298 * @atomicservice 299 * 300 * @since 19 301 */ 302 HITRACE_LEVEL_INFO = 1, 303 /** 304 * @brief Output level for log version usage, with higher priority than HITRACE_LEVEL_INFO. 305 * 306 * @atomicservice 307 * 308 * @since 19 309 */ 310 HITRACE_LEVEL_CRITICAL = 2, 311 /** 312 * @brief Output level for nolog version usage. 313 * 314 * @atomicservice 315 * 316 * @since 19 317 */ 318 HITRACE_LEVEL_COMMERCIAL = 3, 319 /** 320 * @brief Output level for range limit. 321 * 322 * @atomicservice 323 * 324 * @since 19 325 */ 326 HITRACE_LEVEL_MAX = HITRACE_LEVEL_COMMERCIAL, 327 } HiTrace_Output_Level; 328 329 /** 330 * @brief Defines a <b>HiTraceId</b> instance. 331 * 332 * @struct HiTraceId 333 * 334 * @syscap SystemCapability.HiviewDFX.HiTrace 335 * 336 * @since 12 337 */ 338 typedef struct HiTraceId { 339 #if __BYTE_ORDER == __LITTLE_ENDIAN 340 /** Whether the <b>HiTraceId</b> instance is valid. */ 341 uint64_t valid : 1; 342 /** Version number of the <b>HiTraceId</b> instance. */ 343 uint64_t ver : 3; 344 /** Chain ID of the <b>HiTraceId</b> instance. */ 345 uint64_t chainId : 60; 346 /** Flag of the <b>HiTraceId</b> instance. */ 347 uint64_t flags : 12; 348 /** Span ID of the <b>HiTraceId</b> instance. */ 349 uint64_t spanId : 26; 350 /** Parent span ID of the <b>HiTraceId</b> instance. */ 351 uint64_t parentSpanId : 26; 352 #elif __BYTE_ORDER == __BIG_ENDIAN 353 /** Chain ID of the <b>HiTraceId</b> instance. */ 354 uint64_t chainId : 60; 355 /** Version number of the <b>HiTraceId</b> instance. */ 356 uint64_t ver : 3; 357 /** Whether the <b>HiTraceId</b> instance is valid. */ 358 uint64_t valid : 1; 359 /** Parent span ID of the <b>HiTraceId</b> instance. */ 360 uint64_t parentSpanId : 26; 361 /** Span ID of the <b>HiTraceId</b> instance. */ 362 uint64_t spanId : 26; 363 /** Flag of the <b>HiTraceId</b> instance. */ 364 uint64_t flags : 12; 365 #else 366 #error "ERROR: No BIG_LITTLE_ENDIAN defines." 367 #endif 368 } HiTraceId; 369 370 /** 371 * @brief Starts tracing of a process. 372 * 373 * This API starts tracing, creates a <b>HiTraceId</b> instance, and sets it to the TLS of the calling thread. 374 * This API works only when it is called for the first time. 375 * 376 * @param name Pointer to a process name. 377 * @param flags Trace flag. 378 * @return Returns the created <b>HiTraceId</b> instance. 379 * 380 * @syscap SystemCapability.HiviewDFX.HiTrace 381 * 382 * @since 12 383 */ 384 HiTraceId OH_HiTrace_BeginChain(const char *name, int flags); 385 386 /** 387 * @brief Ends tracing and clears the <b>HiTraceId</b> instance of the calling thread from the TLS. 388 * 389 * 390 * @syscap SystemCapability.HiviewDFX.HiTrace 391 * 392 * @since 12 393 */ 394 void OH_HiTrace_EndChain(); 395 396 /** 397 * @brief Obtains the trace ID of the calling thread from the TLS. 398 * 399 * 400 * @return Returns the trace ID of the calling thread. If the calling thread does not have a trace ID, 401 * an invalid trace ID is returned. 402 * 403 * @syscap SystemCapability.HiviewDFX.HiTrace 404 * 405 * @since 12 406 */ 407 HiTraceId OH_HiTrace_GetId(); 408 409 /** 410 * @brief Sets the trace ID of the calling thread. If the ID is invalid, no operation is performed. 411 * 412 * This API sets a <b>HiTraceId</b> instance to the TLS of the calling thread. 413 * 414 * @param id Trace ID to set. 415 * 416 * @syscap SystemCapability.HiviewDFX.HiTrace 417 * 418 * @since 12 419 */ 420 void OH_HiTrace_SetId(const HiTraceId *id); 421 422 /** 423 * @brief Clears the trace ID of the calling thread and invalidates it. 424 * 425 * This API clears the <b>HiTraceId</b> instance in the TLS of the calling thread. 426 * 427 * @syscap SystemCapability.HiviewDFX.HiTrace 428 * 429 * @since 12 430 */ 431 void OH_HiTrace_ClearId(void); 432 433 /** 434 * @brief Creates a span ID based on the trace ID of the calling thread. 435 * 436 * This API generates a new span and corresponding <b>HiTraceId</b> instance based on the <b>HiTraceId</b> 437 * instance in the TLS of the calling thread. 438 * 439 * @return Returns a valid span ID. If span creation is not allowed, the ID of the calling thread is traced. 440 * 441 * @syscap SystemCapability.HiviewDFX.HiTrace 442 * 443 * @since 12 444 */ 445 HiTraceId OH_HiTrace_CreateSpan(void); 446 447 /** 448 * @brief Prints HiTrace information, including the trace ID. 449 * 450 * This API prints trace point information, including the communication mode, trace point type, timestamp, and span. 451 * 452 * @param mode Communication mode for the trace point. 453 * @param type Trace point type. 454 * @param id Trace ID. 455 * @param fmt Custom information to print. 456 * 457 * @syscap SystemCapability.HiviewDFX.HiTrace 458 * 459 * @since 12 460 */ 461 void OH_HiTrace_Tracepoint( 462 HiTrace_Communication_Mode mode, HiTrace_Tracepoint_Type type, const HiTraceId *id, const char *fmt, ...); 463 464 /** 465 * @brief Initializes a <b>HiTraceId</b> structure. 466 * 467 * @param id ID of the <b>HiTraceId</b> structure to be initialized. 468 * 469 * @syscap SystemCapability.HiviewDFX.HiTrace 470 * 471 * @since 12 472 */ 473 void OH_HiTrace_InitId(HiTraceId *id); 474 475 /** 476 * @brief Creates a <b>HiTraceId</b> structure based on a byte array. 477 * 478 * @param id ID of the <b>HiTraceId</b> structure to be created. 479 * @param pIdArray Byte array. 480 * @param len Length of the byte array. 481 * 482 * @syscap SystemCapability.HiviewDFX.HiTrace 483 * 484 * @since 12 485 */ 486 void OH_HiTrace_IdFromBytes(HiTraceId *id, const uint8_t *pIdArray, int len); 487 488 /** 489 * @brief Checks whether a <b>HiTraceId</b> instance is valid. 490 * 491 * 492 * @param id <b>HiTraceId</b> instance to check. 493 * @return Returns <b>true</b> if the <b>HiTraceId</b> instance is valid; returns <b>false</b> otherwise. 494 * 495 * @syscap SystemCapability.HiviewDFX.HiTrace 496 * 497 * @since 12 498 */ 499 bool OH_HiTrace_IsIdValid(const HiTraceId *id); 500 501 /** 502 * @brief Checks whether the specified trace flag in a <b>HiTraceId</b> instance is enabled. 503 * 504 * 505 * @param id <b>HiTraceId</b> instance to check. 506 * @param flag Specified trace flag. 507 * @return Returns <b>true</b> if the specified trace flag is enabled; returns <b>false</b> otherwise. 508 * 509 * @syscap SystemCapability.HiviewDFX.HiTrace 510 * 511 * @since 12 512 */ 513 bool OH_HiTrace_IsFlagEnabled(const HiTraceId *id, HiTrace_Flag flag); 514 515 /** 516 * @brief Enables the specified trace flag in a <b>HiTraceId</b> instance. 517 * 518 * 519 * @param id <b>HiTraceId</b> instance for which you want to enable the specified trace flag. 520 * @param flag Specified trace flag. 521 * 522 * @syscap SystemCapability.HiviewDFX.HiTrace 523 * 524 * @since 12 525 */ 526 void OH_HiTrace_EnableFlag(const HiTraceId *id, HiTrace_Flag flag); 527 528 /** 529 * @brief Obtains the trace flag set in a <b>HiTraceId</b> instance. 530 * 531 * @param id <b>HiTraceId</b> instance. 532 * 533 * @return Returns the trace flag set in the specified <b>HiTraceId</b> instance. 534 * 535 * @syscap SystemCapability.HiviewDFX.HiTrace 536 * 537 * @since 12 538 */ 539 int OH_HiTrace_GetFlags(const HiTraceId *id); 540 541 /** 542 * @brief Sets the trace flag for a <b>HiTraceId</b> instance. 543 * 544 * @param id <b>HiTraceId</b> instance. 545 * @param flags Trace flag to set. 546 * 547 * @syscap SystemCapability.HiviewDFX.HiTrace 548 * 549 * @since 12 550 */ 551 void OH_HiTrace_SetFlags(HiTraceId *id, int flags); 552 553 /** 554 * @brief Obtains the trace chain ID. 555 * 556 * @param id <b>HiTraceId</b> instance for which you want to obtain the trace chain ID. 557 * 558 * @return Returns the trace chain ID of the specified <b>HiTraceId</b> instance. 559 * 560 * @syscap SystemCapability.HiviewDFX.HiTrace 561 * 562 * @since 12 563 */ 564 uint64_t OH_HiTrace_GetChainId(const HiTraceId *id); 565 566 /** 567 * @brief Sets the trace chain ID to a <b>HiTraceId</b> instance 568 * 569 * @param id <b>HiTraceId</b> instance. 570 * @param chainId Trace chain ID to set. 571 * 572 * @syscap SystemCapability.HiviewDFX.HiTrace 573 * 574 * @since 12 575 */ 576 void OH_HiTrace_SetChainId(HiTraceId *id, uint64_t chainId); 577 578 /** 579 * @brief Obtains the span ID in a <b>HiTraceId</b> instance. 580 * 581 * @param id <b>HiTraceId</b> instance for which you want to obtain the span ID. 582 * 583 * @return Returns the span ID in the specified <b>HiTraceId</b> instance. 584 * 585 * @syscap SystemCapability.HiviewDFX.HiTrace 586 * 587 * @since 12 588 */ 589 uint64_t OH_HiTrace_GetSpanId(const HiTraceId *id); 590 591 /** 592 * @brief Sets the span ID in a <b>HiTraceId</b> instance. 593 * 594 * @param id <b>HiTraceId</b> instance for which you want to set the span ID. 595 * @param spanId Span ID to set. 596 * 597 * @syscap SystemCapability.HiviewDFX.HiTrace 598 * 599 * @since 12 600 */ 601 void OH_HiTrace_SetSpanId(HiTraceId *id, uint64_t spanId); 602 603 /** 604 * @brief Obtains the parent span ID in a <b>HiTraceId</b> instance. 605 * 606 * @param id <b>HiTraceId</b> instance for which you want to obtain the parent span ID. 607 * 608 * @return Returns the parent span ID in the specified <b>HiTraceId</b> instance. 609 * 610 * @syscap SystemCapability.HiviewDFX.HiTrace 611 * 612 * @since 12 613 */ 614 uint64_t OH_HiTrace_GetParentSpanId(const HiTraceId *id); 615 616 /** 617 * @brief Sets the parent span ID in a <b>HiTraceId</b> instance. 618 * 619 * @param id <b>HiTraceId</b> instance for which you want to set the parent span ID. 620 * @param parentSpanId Parent span ID to set. 621 * 622 * @syscap SystemCapability.HiviewDFX.HiTrace 623 * 624 * @since 12 625 */ 626 void OH_HiTrace_SetParentSpanId(HiTraceId *id, uint64_t parentSpanId); 627 628 /** 629 * @brief Converts a <b>HiTraceId</b> instance into a byte array for caching or communication. 630 * 631 * @param id <b>HiTraceId</b> instance to be converted. 632 * @param pIdArray Byte array. 633 * @param len Length of the byte array. 634 * 635 * @return Returns the length of the byte array after conversion. 636 * 637 * @syscap SystemCapability.HiviewDFX.HiTrace 638 * 639 * @since 12 640 */ 641 int OH_HiTrace_IdToBytes(const HiTraceId* id, uint8_t* pIdArray, int len); 642 643 /** 644 * @brief Marks the start of a synchronous trace task. 645 * 646 * The <b>OH_HiTrace_StartTrace</b> and <b>OH_HiTrace_FinishTrace</b> APIs must be used in pairs. 647 * The two APIs can be used in nested mode. The stack data structure is used for matching during trace data parsing. 648 * 649 * @param name Name of a trace task. 650 * 651 * @syscap SystemCapability.HiviewDFX.HiTrace 652 * @since 10 653 */ 654 void OH_HiTrace_StartTrace(const char *name); 655 656 /** 657 * @brief Marks the end of a synchronous trace task. 658 * 659 * This API must be used with <b>OH_HiTrace_StartTrace</b> in pairs. During trace data parsing, the system matches 660 * it with the <b>OH_HiTrace_StartTrace</b> API recently invoked in the service process. 661 * 662 * @syscap SystemCapability.HiviewDFX.HiTrace 663 * @since 10 664 */ 665 void OH_HiTrace_FinishTrace(void); 666 667 /** 668 * @brief Marks the start of an asynchronous trace task. 669 * 670 * This API is called to implement performance trace in asynchronous manner. The start and end of an asynchronous 671 * trace task do not occur in sequence. Therefore, a unique <b>taskId</b> is required to ensure proper data parsing. 672 * It is passed as an input parameter for the asynchronous API. 673 * This API is used with <b>OH_HiTrace_FinishAsyncTrace</b> in pairs. The two APIs that have the same name and 674 * task ID together form an asynchronous timeslice trace task. 675 * If multiple trace tasks with the same name need to be performed at the same time or a trace task needs to be 676 * performed multiple times concurrently, different task IDs must be specified in <b>OH_HiTrace_StartTrace</b>. 677 * If the trace tasks with the same name are not performed at the same time, the same taskId can be used. 678 * 679 * @param name Name of the asynchronous trace task. 680 * @param taskId ID of the asynchronous trace task. The start and end of an asynchronous trace task do not occur in 681 * sequence. Therefore, the start and end of an asynchronous trace need to be matched based on the task name and the 682 * unique task ID together. 683 * 684 * @syscap SystemCapability.HiviewDFX.HiTrace 685 * @since 10 686 */ 687 void OH_HiTrace_StartAsyncTrace(const char *name, int32_t taskId); 688 689 /** 690 * @brief Marks the end of an asynchronous trace task. 691 * 692 * This API is called in the callback function after an asynchronous trace is complete. 693 * It is used with <b>OH_HiTrace_StartAsyncTrace</b> in pairs. Its name and task ID must be the same as those of 694 * <b>OH_HiTrace_StartAsyncTrace</b>. 695 * 696 * @param name Name of the asynchronous trace task. 697 * @param taskId ID of the asynchronous trace task. The start and end of an asynchronous trace task do not occur in 698 * sequence. Therefore, the start and end of an asynchronous trace need to be matched based on the task name and the 699 * unique task ID together. 700 * 701 * @syscap SystemCapability.HiviewDFX.HiTrace 702 * @since 10 703 */ 704 void OH_HiTrace_FinishAsyncTrace(const char *name, int32_t taskId); 705 706 /** 707 * @brief Traces the value change of an integer variable based on its name. 708 * 709 * This API can be executed for multiple times to trace the value change of a given integer variable at different 710 * time points. 711 * 712 * @param name Name of the integer variable. It does not need to be the same as the real variable name. 713 * @param count Integer value. Generally, an integer variable can be passed. 714 * 715 * @syscap SystemCapability.HiviewDFX.HiTrace 716 * @since 10 717 */ 718 void OH_HiTrace_CountTrace(const char *name, int64_t count); 719 720 /** 721 * @brief Marks the start of a synchronous trace task with output level control. 722 * 723 * The <b>OH_HiTrace_StartTraceEx</b> and <b>OH_HiTrace_FinishTraceEx</b> APIs must be used in pairs. 724 * The two APIs can be used in nested mode. The stack data structure is used for matching during trace data parsing. 725 * 726 * @param level Trace output priority level. 727 * @param name Name of the synchronous trace task. 728 * @param customArgs key=value pair, multiple pairs use comma as separator. 729 * @atomicservice 730 * @since 19 731 */ 732 void OH_HiTrace_StartTraceEx(HiTrace_Output_Level level, const char* name, const char* customArgs); 733 734 /** 735 * @brief Marks the end of a synchronous trace task with output level control. 736 * 737 * This API must be used with <b>OH_HiTrace_StartTraceEx</b> in pairs. The two APIs, which have the same level, 738 * form an synchronous timeslice trace task. 739 * During trace data parsing, the system matches it with the most recent <b>OH_HiTrace_StartTraceEx</b> API 740 * invocation in the service process. 741 * 742 * @param level Trace output priority level. 743 * @atomicservice 744 * @since 19 745 */ 746 void OH_HiTrace_FinishTraceEx(HiTrace_Output_Level level); 747 748 /** 749 * @brief Marks the start of an asynchronous trace task with output level control. 750 * 751 * This API is called to implement performance trace in asynchronous manner. The start and end of an asynchronous 752 * trace task do not occur in sequence. Therefore, a unique <b>taskId</b> is required to ensure proper data parsing. 753 * It is passed as an input parameter for the asynchronous API. 754 * This API is used with <b>OH_HiTrace_FinishAsyncTraceEx</b> in pairs. The two APIs, which have the same level, 755 * name, and task ID, form an asynchronous timeslice trace task. 756 * If customCategory is specified, the trace slice will be grouped and displayed together with other trace slices 757 * with the same customCategory. 758 * If multiple trace tasks with the same name need to be performed at the same time or a trace task needs to be 759 * performed multiple times concurrently, different task IDs must be specified in <b>OH_HiTrace_StartAsyncTraceEx</b>. 760 * If the trace tasks with the same name are not performed at the same time, the same taskId can be used. 761 * Different processes's taskId do not interfere. 762 * 763 * @param level Trace output priority level. 764 * @param name Name of the asynchronous trace task. 765 * @param taskId ID of the asynchronous trace task. 766 * @param customCategory Label used to aggregate the asynchronous trace. 767 * @param customArgs key=value pair, multiple pairs use comma as separator. 768 * @atomicservice 769 * @since 19 770 */ 771 void OH_HiTrace_StartAsyncTraceEx(HiTrace_Output_Level level, const char* name, int32_t taskId, 772 const char* customCategory, const char* customArgs); 773 774 /** 775 * @brief Marks the end of an asynchronous trace task with output level control. 776 * 777 * This API is called in the callback function after an asynchronous trace is complete. 778 * It is used with <b>OH_HiTrace_StartAsyncTraceEx</b> in pairs. Its level, name, and task ID must be 779 * the same as those of <b>OH_HiTrace_StartAsyncTraceEx</b>. 780 * 781 * @param level Trace output priority level. 782 * @param name Name of the asynchronous trace task. 783 * @param taskId ID of the asynchronous trace task. 784 * @atomicservice 785 * @since 19 786 */ 787 void OH_HiTrace_FinishAsyncTraceEx(HiTrace_Output_Level level, const char* name, int32_t taskId); 788 789 /** 790 * @brief Traces the value change of an integer variable based on its name with output level control. 791 * 792 * This API can be executed for multiple times to trace the value change of a given integer variable at different 793 * time points. 794 * 795 * @param level Trace output priority level. 796 * @param name Name of the integer variable. It does not need to be the same as the real variable name. 797 * @param count Integer value. Generally, an integer variable can be passed. 798 * @atomicservice 799 * @since 19 800 */ 801 void OH_HiTrace_CountTraceEx(HiTrace_Output_Level level, const char* name, int64_t count); 802 803 /** 804 * @brief Get the trace output status of the calling process. 805 * 806 * @return Returns whether the calling process is allowed to output trace. 807 * @atomicservice 808 * @since 19 809 */ 810 bool OH_HiTrace_IsTraceEnabled(void); 811 812 #ifdef __cplusplus 813 } 814 #endif 815 /** @} */ 816 817 #endif // HIVIEWDFX_HITRACE_H 818