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 * Sample code: \n 44 * Synchronous timeslice trace event: \n 45 * OH_HiTrace_StartTrace("hitraceTest");\n 46 * OH_HiTrace_FinishTrace();\n 47 * Output: \n 48 * <...>-1668 (-------) [003] .... 135.059377: tracing_mark_write: B|1668|H:hitraceTest \n 49 * <...>-1668 (-------) [003] .... 135.059415: tracing_mark_write: E|1668| \n 50 * Asynchronous timeslice trace event:\n 51 * OH_HiTrace_StartAsyncTrace("hitraceTest", 123); \n 52 * OH_HiTrace_FinishAsyncTrace("hitraceTest", 123); \n 53 * Output: \n 54 * <...>-2477 (-------) [001] .... 396.427165: tracing_mark_write: S|2477|H:hitraceTest 123 \n 55 * <...>-2477 (-------) [001] .... 396.427196: tracing_mark_write: F|2477|H:hitraceTest 123 \n 56 * Integer value trace event:\n 57 * OH_HiTrace_CountTrace("hitraceTest", 500); \n 58 * Output: \n 59 * <...>-2638 (-------) [002] .... 458.904382: tracing_mark_write: C|2638|H:hitraceTest 500 \n 60 * 61 * @library libhitracechain.so 62 * @syscap SystemCapability.HiviewDFX.HiTrace 63 * @since 10 64 */ 65 66 #ifndef HIVIEWDFX_HITRACE_H 67 #define HIVIEWDFX_HITRACE_H 68 69 #include <stdint.h> 70 #include <stdbool.h> 71 72 #ifdef __cplusplus 73 extern "C" { 74 #endif 75 76 /** 77 * @brief Defines whether a <b>HiTraceId</b> instance is valid. 78 * 79 * @syscap SystemCapability.HiviewDFX.HiTrace 80 * 81 * @since 12 82 */ 83 typedef enum HiTraceId_Valid { 84 /** 85 * @brief Invalid <b>HiTraceId</b> instance. 86 * 87 * @syscap SystemCapability.HiviewDFX.HiTrace 88 * 89 * @since 12 90 */ 91 HITRACE_ID_INVALID = 0, 92 93 /** 94 * @brief Valid <b>HiTraceId</b> instance. 95 * 96 * @syscap SystemCapability.HiviewDFX.HiTrace 97 * 98 * @since 12 99 */ 100 HITRACE_ID_VALID = 1, 101 } HiTraceId_Valid; 102 103 /** 104 * @brief Enumerates the HiTrace version numbers. 105 * 106 * @syscap SystemCapability.HiviewDFX.HiTrace 107 * 108 * @since 12 109 */ 110 typedef enum HiTrace_Version { 111 /** 112 * @brief Version 1. 113 * 114 * @syscap SystemCapability.HiviewDFX.HiTrace 115 * 116 * @since 12 117 */ 118 HITRACE_VER_1 = 0, 119 } HiTrace_Version; 120 121 /** 122 * @brief Enumerates the HiTrace flags. 123 * 124 * @syscap SystemCapability.HiviewDFX.HiTrace 125 * 126 * @since 12 127 */ 128 typedef enum HiTrace_Flag { 129 /** 130 * @brief Default flag. 131 * 132 * @syscap SystemCapability.HiviewDFX.HiTrace 133 * 134 * @since 12 135 */ 136 HITRACE_FLAG_DEFAULT = 0, 137 138 /** 139 * @brief Both synchronous and asynchronous calls are traced. By default, only synchronous calls are traced. 140 * 141 * @syscap SystemCapability.HiviewDFX.HiTrace 142 * 143 * @since 12 144 */ 145 HITRACE_FLAG_INCLUDE_ASYNC = 1 << 0, 146 147 /** 148 * @brief No spans are created. By default, spans are created. 149 * 150 * @syscap SystemCapability.HiviewDFX.HiTrace 151 * 152 * @since 12 153 */ 154 HITRACE_FLAG_DONOT_CREATE_SPAN = 1 << 1, 155 156 /** 157 * @brief Trace points are automatically added to spans. By default, no trace point is added. 158 * 159 * @syscap SystemCapability.HiviewDFX.HiTrace 160 * 161 * @since 12 162 */ 163 HITRACE_FLAG_TP_INFO = 1 << 2, 164 165 /** 166 * @brief Information about the start and end of the trace task is not printed. By default, information about the 167 * start and end of the trace task is printed. 168 * 169 * @syscap SystemCapability.HiviewDFX.HiTrace 170 * 171 * @since 12 172 */ 173 HITRACE_FLAG_NO_BE_INFO = 1 << 3, 174 175 /** 176 * @brief The ID is not added to the log. By default, the ID is added to the log. 177 * 178 * @syscap SystemCapability.HiviewDFX.HiTrace 179 * 180 * @since 12 181 */ 182 HITRACE_FLAG_DONOT_ENABLE_LOG = 1 << 4, 183 184 /** 185 * @brief Tracing is triggered by faults. 186 * 187 * @syscap SystemCapability.HiviewDFX.HiTrace 188 * 189 * @since 12 190 */ 191 HITRACE_FLAG_FAULT_TRIGGER = 1 << 5, 192 193 /** 194 * @brief Trace points are added only for call chain trace between devices. 195 * By default, device-to-device trace points are not added. 196 * 197 * @syscap SystemCapability.HiviewDFX.HiTrace 198 * 199 * @since 12 200 */ 201 HITRACE_FLAG_D2D_TP_INFO = 1 << 6, 202 } HiTrace_Flag; 203 204 /** 205 * @brief Enumerates the HiTrace trace point types. 206 * 207 * @syscap SystemCapability.HiviewDFX.HiTrace 208 * 209 * @since 12 210 */ 211 typedef enum HiTrace_Tracepoint_Type { 212 /** 213 * @brief CS trace point. 214 * 215 * @syscap SystemCapability.HiviewDFX.HiTrace 216 * 217 * @since 12 218 */ 219 HITRACE_TP_CS = 0, 220 /** 221 * @brief CR trace point. 222 * 223 * @syscap SystemCapability.HiviewDFX.HiTrace 224 * 225 * @since 12 226 */ 227 HITRACE_TP_CR = 1, 228 /** 229 * @brief SS trace point. 230 * 231 * @syscap SystemCapability.HiviewDFX.HiTrace 232 * 233 * @since 12 234 */ 235 HITRACE_TP_SS = 2, 236 /** 237 * @brief SR trace point. 238 * 239 * @syscap SystemCapability.HiviewDFX.HiTrace 240 * 241 * @since 12 242 */ 243 HITRACE_TP_SR = 3, 244 /** 245 * @brief General trace point. 246 * 247 * @syscap SystemCapability.HiviewDFX.HiTrace 248 * 249 * @since 12 250 */ 251 HITRACE_TP_GENERAL = 4, 252 } HiTrace_Tracepoint_Type; 253 254 /** 255 * @brief Enumerates the HiTrace communication modes. 256 * 257 * @syscap SystemCapability.HiviewDFX.HiTrace 258 * 259 * @since 12 260 */ 261 typedef enum HiTrace_Communication_Mode { 262 /** 263 * @brief Default communication mode. 264 * 265 * @syscap SystemCapability.HiviewDFX.HiTrace 266 * 267 * @since 12 268 */ 269 HITRACE_CM_DEFAULT = 0, 270 /** 271 * @brief Inter-thread communication. 272 * 273 * @syscap SystemCapability.HiviewDFX.HiTrace 274 * 275 * @since 12 276 */ 277 HITRACE_CM_THREAD = 1, 278 /** 279 * @brief Inter-process communication. 280 * 281 * @syscap SystemCapability.HiviewDFX.HiTrace 282 * 283 * @since 12 284 */ 285 HITRACE_CM_PROCESS = 2, 286 /** 287 * @brief Inter-device communication. 288 * 289 * @syscap SystemCapability.HiviewDFX.HiTrace 290 * 291 * @since 12 292 */ 293 HITRACE_CM_DEVICE = 3, 294 } HiTrace_Communication_Mode; 295 296 /** 297 * @brief Defines a <b>HiTraceId</b> instance. 298 * 299 * @struct HiTraceId 300 * 301 * @syscap SystemCapability.HiviewDFX.HiTrace 302 * 303 * @since 12 304 */ 305 typedef struct HiTraceId { 306 #if __BYTE_ORDER == __LITTLE_ENDIAN 307 /** Whether the <b>HiTraceId</b> instance is valid. */ 308 uint64_t valid : 1; 309 /** Version number of the <b>HiTraceId</b> instance. */ 310 uint64_t ver : 3; 311 /** Chain ID of the <b>HiTraceId</b> instance. */ 312 uint64_t chainId : 60; 313 /** Flag of the <b>HiTraceId</b> instance. */ 314 uint64_t flags : 12; 315 /** Span ID of the <b>HiTraceId</b> instance. */ 316 uint64_t spanId : 26; 317 /** Parent span ID of the <b>HiTraceId</b> instance. */ 318 uint64_t parentSpanId : 26; 319 #elif __BYTE_ORDER == __BIG_ENDIAN 320 /** Chain ID of the <b>HiTraceId</b> instance. */ 321 uint64_t chainId : 60; 322 /** Version number of the <b>HiTraceId</b> instance. */ 323 uint64_t ver : 3; 324 /** Whether the <b>HiTraceId</b> instance is valid. */ 325 uint64_t valid : 1; 326 /** Parent span ID of the <b>HiTraceId</b> instance. */ 327 uint64_t parentSpanId : 26; 328 /** Span ID of the <b>HiTraceId</b> instance. */ 329 uint64_t spanId : 26; 330 /** Flag of the <b>HiTraceId</b> instance. */ 331 uint64_t flags : 12; 332 #else 333 #error "ERROR: No BIG_LITTLE_ENDIAN defines." 334 #endif 335 } HiTraceId; 336 337 /** 338 * @brief Starts tracing of a process. 339 * 340 * This API starts tracing, creates a <b>HiTraceId</b> instance, and sets it to the TLS of the calling thread. 341 * This API works only when it is called for the first time. 342 * 343 * @param name Pointer to a process name. 344 * @param flags Trace flag. 345 * @return Returns the created <b>HiTraceId</b> instance. 346 * 347 * @syscap SystemCapability.HiviewDFX.HiTrace 348 * 349 * @since 12 350 */ 351 HiTraceId OH_HiTrace_BeginChain(const char *name, int flags); 352 353 /** 354 * @brief Ends tracing and clears the <b>HiTraceId</b> instance of the calling thread from the TLS. 355 * 356 * 357 * @syscap SystemCapability.HiviewDFX.HiTrace 358 * 359 * @since 12 360 */ 361 void OH_HiTrace_EndChain(); 362 363 /** 364 * @brief Obtains the trace ID of the calling thread from the TLS. 365 * 366 * 367 * @return Returns the trace ID of the calling thread. If the calling thread does not have a trace ID, 368 * an invalid trace ID is returned. 369 * 370 * @syscap SystemCapability.HiviewDFX.HiTrace 371 * 372 * @since 12 373 */ 374 HiTraceId OH_HiTrace_GetId(); 375 376 /** 377 * @brief Sets the trace ID of the calling thread. If the ID is invalid, no operation is performed. 378 * 379 * This API sets a <b>HiTraceId</b> instance to the TLS of the calling thread. 380 * 381 * @param id Trace ID to set. 382 * 383 * @syscap SystemCapability.HiviewDFX.HiTrace 384 * 385 * @since 12 386 */ 387 void OH_HiTrace_SetId(const HiTraceId *id); 388 389 /** 390 * @brief Clears the trace ID of the calling thread and invalidates it. 391 * 392 * This API clears the <b>HiTraceId</b> instance in the TLS of the calling thread. 393 * 394 * @syscap SystemCapability.HiviewDFX.HiTrace 395 * 396 * @since 12 397 */ 398 void OH_HiTrace_ClearId(void); 399 400 /** 401 * @brief Creates a span ID based on the trace ID of the calling thread. 402 * 403 * This API generates a new span and corresponding <b>HiTraceId</b> instance based on the <b>HiTraceId</b> 404 * instance in the TLS of the calling thread. 405 * 406 * @return Returns a valid span ID. If span creation is not allowed, the ID of the calling thread is traced. 407 * 408 * @syscap SystemCapability.HiviewDFX.HiTrace 409 * 410 * @since 12 411 */ 412 HiTraceId OH_HiTrace_CreateSpan(void); 413 414 /** 415 * @brief Prints HiTrace information, including the trace ID. 416 * 417 * This API prints trace point information, including the communication mode, trace point type, timestamp, and span. 418 * 419 * @param mode Communication mode for the trace point. 420 * @param type Trace point type. 421 * @param id Trace ID. 422 * @param fmt Custom information to print. 423 * 424 * @syscap SystemCapability.HiviewDFX.HiTrace 425 * 426 * @since 12 427 */ 428 void OH_HiTrace_Tracepoint( 429 HiTrace_Communication_Mode mode, HiTrace_Tracepoint_Type type, const HiTraceId *id, const char *fmt, ...); 430 431 /** 432 * @brief Initializes a <b>HiTraceId</b> structure. 433 * 434 * @param id ID of the <b>HiTraceId</b> structure to be initialized. 435 * 436 * @syscap SystemCapability.HiviewDFX.HiTrace 437 * 438 * @since 12 439 */ 440 void OH_HiTrace_InitId(HiTraceId *id); 441 442 /** 443 * @brief Creates a <b>HiTraceId</b> structure based on a byte array. 444 * 445 * @param id ID of the <b>HiTraceId</b> structure to be created. 446 * @param pIdArray Byte array. 447 * @param len Length of the byte array. 448 * 449 * @syscap SystemCapability.HiviewDFX.HiTrace 450 * 451 * @since 12 452 */ 453 void OH_HiTrace_IdFromBytes(HiTraceId *id, const uint8_t *pIdArray, int len); 454 455 /** 456 * @brief Checks whether a <b>HiTraceId</b> instance is valid. 457 * 458 * 459 * @param id <b>HiTraceId</b> instance to check. 460 * @return Returns <b>true</b> if the <b>HiTraceId</b> instance is valid; returns <b>false</b> otherwise. 461 * 462 * @syscap SystemCapability.HiviewDFX.HiTrace 463 * 464 * @since 12 465 */ 466 bool OH_HiTrace_IsIdValid(const HiTraceId *id); 467 468 /** 469 * @brief Checks whether the specified trace flag in a <b>HiTraceId</b> instance is enabled. 470 * 471 * 472 * @param id <b>HiTraceId</b> instance to check. 473 * @param flag Specified trace flag. 474 * @return Returns <b>true</b> if the specified trace flag is enabled; returns <b>false</b> otherwise. 475 * 476 * @syscap SystemCapability.HiviewDFX.HiTrace 477 * 478 * @since 12 479 */ 480 bool OH_HiTrace_IsFlagEnabled(const HiTraceId *id, HiTrace_Flag flag); 481 482 /** 483 * @brief Enables the specified trace flag in a <b>HiTraceId</b> instance. 484 * 485 * 486 * @param id <b>HiTraceId</b> instance for which you want to enable the specified trace flag. 487 * @param flag Specified trace flag. 488 * 489 * @syscap SystemCapability.HiviewDFX.HiTrace 490 * 491 * @since 12 492 */ 493 void OH_HiTrace_EnableFlag(const HiTraceId *id, HiTrace_Flag flag); 494 495 /** 496 * @brief Obtains the trace flag set in a <b>HiTraceId</b> instance. 497 * 498 * @param id <b>HiTraceId</b> instance. 499 * 500 * @return Returns the trace flag set in the specified <b>HiTraceId</b> instance. 501 * 502 * @syscap SystemCapability.HiviewDFX.HiTrace 503 * 504 * @since 12 505 */ 506 int OH_HiTrace_GetFlags(const HiTraceId *id); 507 508 /** 509 * @brief Sets the trace flag for a <b>HiTraceId</b> instance. 510 * 511 * @param id <b>HiTraceId</b> instance. 512 * @param flags Trace flag to set. 513 * 514 * @syscap SystemCapability.HiviewDFX.HiTrace 515 * 516 * @since 12 517 */ 518 void OH_HiTrace_SetFlags(HiTraceId *id, int flags); 519 520 /** 521 * @brief Obtains the trace chain ID. 522 * 523 * @param id <b>HiTraceId</b> instance for which you want to obtain the trace chain ID. 524 * 525 * @return Returns the trace chain ID of the specified <b>HiTraceId</b> instance. 526 * 527 * @syscap SystemCapability.HiviewDFX.HiTrace 528 * 529 * @since 12 530 */ 531 uint64_t OH_HiTrace_GetChainId(const HiTraceId *id); 532 533 /** 534 * @brief Sets the trace chain ID to a <b>HiTraceId</b> instance 535 * 536 * @param id <b>HiTraceId</b> instance. 537 * @param chainId Trace chain ID to set. 538 * 539 * @syscap SystemCapability.HiviewDFX.HiTrace 540 * 541 * @since 12 542 */ 543 void OH_HiTrace_SetChainId(HiTraceId *id, uint64_t chainId); 544 545 /** 546 * @brief Obtains the span ID in a <b>HiTraceId</b> instance. 547 * 548 * @param id <b>HiTraceId</b> instance for which you want to obtain the span ID. 549 * 550 * @return Returns the span ID in the specified <b>HiTraceId</b> instance. 551 * 552 * @syscap SystemCapability.HiviewDFX.HiTrace 553 * 554 * @since 12 555 */ 556 uint64_t OH_HiTrace_GetSpanId(const HiTraceId *id); 557 558 /** 559 * @brief Sets the span ID in a <b>HiTraceId</b> instance. 560 * 561 * @param id <b>HiTraceId</b> instance for which you want to set the span ID. 562 * @param spanId Span ID to set. 563 * 564 * @syscap SystemCapability.HiviewDFX.HiTrace 565 * 566 * @since 12 567 */ 568 void OH_HiTrace_SetSpanId(HiTraceId *id, uint64_t spanId); 569 570 /** 571 * @brief Obtains the parent span ID in a <b>HiTraceId</b> instance. 572 * 573 * @param id <b>HiTraceId</b> instance for which you want to obtain the parent span ID. 574 * 575 * @return Returns the parent span ID in the specified <b>HiTraceId</b> instance. 576 * 577 * @syscap SystemCapability.HiviewDFX.HiTrace 578 * 579 * @since 12 580 */ 581 uint64_t OH_HiTrace_GetParentSpanId(const HiTraceId *id); 582 583 /** 584 * @brief Sets the parent span ID in a <b>HiTraceId</b> instance. 585 * 586 * @param id <b>HiTraceId</b> instance for which you want to set the parent span ID. 587 * @param parentSpanId Parent span ID to set. 588 * 589 * @syscap SystemCapability.HiviewDFX.HiTrace 590 * 591 * @since 12 592 */ 593 void OH_HiTrace_SetParentSpanId(HiTraceId *id, uint64_t parentSpanId); 594 595 /** 596 * @brief Converts a <b>HiTraceId</b> instance into a byte array for caching or communication. 597 * 598 * @param id <b>HiTraceId</b> instance to be converted. 599 * @param pIdArray Byte array. 600 * @param len Length of the byte array. 601 * 602 * @return Returns the length of the byte array after conversion. 603 * 604 * @syscap SystemCapability.HiviewDFX.HiTrace 605 * 606 * @since 12 607 */ 608 int OH_HiTrace_IdToBytes(const HiTraceId* id, uint8_t* pIdArray, int len); 609 610 /** 611 * @brief Marks the start of a synchronous trace task. 612 * 613 * The <b>OH_HiTrace_StartTrace</b> and <b>OH_HiTrace_FinishTrace</b> APIs must be used in pairs. 614 * The two APIs can be used in nested mode. The stack data structure is used for matching during trace data parsing. 615 * 616 * @param name Name of a trace task. 617 * 618 * @syscap SystemCapability.HiviewDFX.HiTrace 619 * @since 10 620 */ 621 void OH_HiTrace_StartTrace(const char *name); 622 623 /** 624 * @brief Marks the end of a synchronous trace task. 625 * 626 * This API must be used with <b>OH_HiTrace_StartTrace</b> in pairs. During trace data parsing, the system matches 627 * it with the <b>OH_HiTrace_StartTrace</b> API recently invoked in the service process. 628 * 629 * @syscap SystemCapability.HiviewDFX.HiTrace 630 * @since 10 631 */ 632 void OH_HiTrace_FinishTrace(void); 633 634 /** 635 * @brief Marks the start of an asynchronous trace task. 636 * 637 * This API is called to implement performance trace in asynchronous manner. The start and end of an asynchronous 638 * trace task do not occur in sequence. Therefore, a unique <b>taskId</b> is required to ensure proper data parsing. 639 * It is passed as an input parameter for the asynchronous API. 640 * This API is used with <b>OH_HiTrace_FinishAsyncTrace</b> in pairs. The two APIs that have the same name and 641 * task ID together form an asynchronous timeslice trace task. 642 * If multiple trace tasks with the same name need to be performed at the same time or a trace task needs to be 643 * performed multiple times concurrently, different task IDs must be specified in <b>OH_HiTrace_StartTrace</b>. 644 * If the trace tasks with the same name are not performed at the same time, the same taskId can be used. 645 * 646 * @param name Name of the asynchronous trace task. 647 * @param taskId ID of the asynchronous trace task. The start and end of an asynchronous trace task do not occur in 648 * sequence. Therefore, the start and end of an asynchronous trace need to be matched based on the task name and the 649 * unique task ID together. 650 * 651 * @syscap SystemCapability.HiviewDFX.HiTrace 652 * @since 10 653 */ 654 void OH_HiTrace_StartAsyncTrace(const char *name, int32_t taskId); 655 656 /** 657 * @brief Marks the end of an asynchronous trace task. 658 * 659 * This API is called in the callback function after an asynchronous trace is complete. 660 * It is used with <b>OH_HiTrace_StartAsyncTrace</b> in pairs. Its name and task ID must be the same as those of 661 * <b>OH_HiTrace_StartAsyncTrace</b>. 662 * 663 * @param name Name of the asynchronous trace task. 664 * @param taskId ID of the asynchronous trace task. The start and end of an asynchronous trace task do not occur in 665 * sequence. Therefore, the start and end of an asynchronous trace need to be matched based on the task name and the 666 * unique task ID together. 667 * 668 * @syscap SystemCapability.HiviewDFX.HiTrace 669 * @since 10 670 */ 671 void OH_HiTrace_FinishAsyncTrace(const char *name, int32_t taskId); 672 673 /** 674 * @brief Traces the value change of an integer variable based on its name. 675 * 676 * This API can be executed for multiple times to trace the value change of a given integer variable at different 677 * time points. 678 * 679 * @param name Name of the integer variable. It does not need to be the same as the real variable name. 680 * @param count Integer value. Generally, an integer variable can be passed. 681 * 682 * @syscap SystemCapability.HiviewDFX.HiTrace 683 * @since 10 684 */ 685 void OH_HiTrace_CountTrace(const char *name, int64_t count); 686 687 #ifdef __cplusplus 688 } 689 #endif 690 /** @} */ 691 692 #endif // HIVIEWDFX_HITRACE_H 693