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 APIs to implement call chain tracing throughout a service process. 23 * With HiTrace, you can quickly obtain the run log for the call chain of a 24 * specified service process and locate faults in cross-device, cross-process, 25 * or cross-thread communications. 26 * 27 * @namespace hiTraceChain 28 * @syscap SystemCapability.HiviewDFX.HiTrace 29 * @since arkts {'1.1':'8','1.2':'20'} 30 * @arkts 1.1&1.2 31 */ 32declare namespace hiTraceChain { 33 /** 34 * Enumerate trace flag 35 * 36 * @enum { number } 37 * @syscap SystemCapability.HiviewDFX.HiTrace 38 * @since arkts {'1.1':'8','1.2':'20'} 39 * @arkts 1.1&1.2 40 */ 41 enum HiTraceFlag { 42 /** 43 * Default value 44 * 45 * @syscap SystemCapability.HiviewDFX.HiTrace 46 * @since arkts {'1.1':'8','1.2':'20'} 47 * @arkts 1.1&1.2 48 */ 49 DEFAULT = 0, 50 51 /** 52 * Trace sync and async call. default: trace sync call only. 53 * 54 * @syscap SystemCapability.HiviewDFX.HiTrace 55 * @since arkts {'1.1':'8','1.2':'20'} 56 * @arkts 1.1&1.2 57 */ 58 INCLUDE_ASYNC = 1, 59 60 /** 61 * Do not create child span. default: create child span. 62 * 63 * @syscap SystemCapability.HiviewDFX.HiTrace 64 * @since arkts {'1.1':'8','1.2':'20'} 65 * @arkts 1.1&1.2 66 */ 67 DONOT_CREATE_SPAN = 1 << 1, 68 69 /** 70 * Output tracepoint info in span. default: do not output tracepoint info. 71 * 72 * @syscap SystemCapability.HiviewDFX.HiTrace 73 * @since arkts {'1.1':'8','1.2':'20'} 74 * @arkts 1.1&1.2 75 */ 76 TP_INFO = 1 << 2, 77 78 /** 79 * Do not output begin and end info. default: output begin and end info. 80 * 81 * @syscap SystemCapability.HiviewDFX.HiTrace 82 * @since arkts {'1.1':'8','1.2':'20'} 83 * @arkts 1.1&1.2 84 */ 85 NO_BE_INFO = 1 << 3, 86 87 /** 88 * Do not add id to log. default: add id to log. 89 * 90 * @syscap SystemCapability.HiviewDFX.HiTrace 91 * @since arkts {'1.1':'8','1.2':'20'} 92 * @arkts 1.1&1.2 93 */ 94 DISABLE_LOG = 1 << 4, 95 96 /** 97 * The trace is triggered by fault. 98 * 99 * @syscap SystemCapability.HiviewDFX.HiTrace 100 * @since arkts {'1.1':'8','1.2':'20'} 101 * @arkts 1.1&1.2 102 */ 103 FAILURE_TRIGGER = 1 << 5, 104 105 /** 106 * Output device-to-device tracepoint info in span only. default: do not output device-to-device tracepoint info. 107 * 108 * @syscap SystemCapability.HiviewDFX.HiTrace 109 * @since arkts {'1.1':'8','1.2':'20'} 110 * @arkts 1.1&1.2 111 */ 112 D2D_TP_INFO = 1 << 6 113 } 114 115 /** 116 * Enumerate trace point type 117 * 118 * @enum { number } 119 * @syscap SystemCapability.HiviewDFX.HiTrace 120 * @since arkts {'1.1':'8','1.2':'20'} 121 * @arkts 1.1&1.2 122 */ 123 enum HiTraceTracepointType { 124 /** 125 * Client send 126 * 127 * @syscap SystemCapability.HiviewDFX.HiTrace 128 * @since arkts {'1.1':'8','1.2':'20'} 129 * @arkts 1.1&1.2 130 */ 131 CS = 0, 132 133 /** 134 * Client receive 135 * 136 * @syscap SystemCapability.HiviewDFX.HiTrace 137 * @since arkts {'1.1':'8','1.2':'20'} 138 * @arkts 1.1&1.2 139 */ 140 CR = 1, 141 142 /** 143 * Server send 144 * 145 * @syscap SystemCapability.HiviewDFX.HiTrace 146 * @since arkts {'1.1':'8','1.2':'20'} 147 * @arkts 1.1&1.2 148 */ 149 SS = 2, 150 151 /** 152 * Server receive 153 * 154 * @syscap SystemCapability.HiviewDFX.HiTrace 155 * @since arkts {'1.1':'8','1.2':'20'} 156 * @arkts 1.1&1.2 157 */ 158 SR = 3, 159 160 /** 161 * General info 162 * 163 * @syscap SystemCapability.HiviewDFX.HiTrace 164 * @since arkts {'1.1':'8','1.2':'20'} 165 * @arkts 1.1&1.2 166 */ 167 GENERAL = 4 168 } 169 170 /** 171 * Enumerate trace communication mode 172 * 173 * @enum { number } 174 * @syscap SystemCapability.HiviewDFX.HiTrace 175 * @since arkts {'1.1':'8','1.2':'20'} 176 * @arkts 1.1&1.2 177 */ 178 enum HiTraceCommunicationMode { 179 /** 180 * Unspecified 181 * 182 * @syscap SystemCapability.HiviewDFX.HiTrace 183 * @since arkts {'1.1':'8','1.2':'20'} 184 * @arkts 1.1&1.2 185 */ 186 DEFAULT = 0, 187 188 /** 189 * Thread-to-thread 190 * 191 * @syscap SystemCapability.HiviewDFX.HiTrace 192 * @since arkts {'1.1':'8','1.2':'20'} 193 * @arkts 1.1&1.2 194 */ 195 THREAD = 1, 196 197 /** 198 * Process-to-process 199 * 200 * @syscap SystemCapability.HiviewDFX.HiTrace 201 * @since arkts {'1.1':'8','1.2':'20'} 202 * @arkts 1.1&1.2 203 */ 204 PROCESS = 2, 205 206 /** 207 * Device-to-device 208 * 209 * @syscap SystemCapability.HiviewDFX.HiTrace 210 * @since arkts {'1.1':'8','1.2':'20'} 211 * @arkts 1.1&1.2 212 */ 213 DEVICE = 3 214 } 215 216 /** 217 * Trace id, for tracing process. 218 * 219 * @interface HiTraceId 220 * @syscap SystemCapability.HiviewDFX.HiTrace 221 * @since arkts {'1.1':'8','1.2':'20'} 222 * @arkts 1.1&1.2 223 */ 224 interface HiTraceId { 225 /** 226 * Chain id. 227 * 228 * @type { bigint } 229 * @syscap SystemCapability.HiviewDFX.HiTrace 230 * @since arkts {'1.1':'8','1.2':'20'} 231 * @arkts 1.1&1.2 232 */ 233 chainId: bigint; 234 235 /** 236 * Span id. 237 * 238 * @type { ?number } 239 * @syscap SystemCapability.HiviewDFX.HiTrace 240 * @since arkts {'1.1':'8','1.2':'20'} 241 * @arkts 1.1&1.2 242 */ 243 spanId?: number; 244 245 /** 246 * Parent span id. 247 * 248 * @type { ?number } 249 * @syscap SystemCapability.HiviewDFX.HiTrace 250 * @since arkts {'1.1':'8','1.2':'20'} 251 * @arkts 1.1&1.2 252 */ 253 parentSpanId?: number; 254 255 /** 256 * Trace flag. 257 * 258 * @type { ?number } 259 * @syscap SystemCapability.HiviewDFX.HiTrace 260 * @since arkts {'1.1':'8','1.2':'20'} 261 * @arkts 1.1&1.2 262 */ 263 flags?: number; 264 } 265 266 /** 267 * Start tracing a process impl. 268 * 269 * @param { string } name Process name. 270 * @param { number } flags Trace function flag. 271 * @returns { HiTraceId } Valid if first call, otherwise invalid. 272 * @syscap SystemCapability.HiviewDFX.HiTrace 273 * @since arkts {'1.1':'8','1.2':'20'} 274 * @arkts 1.1&1.2 275 */ 276 function begin(name: string, flags?: number): HiTraceId; 277 278 /** 279 * Stop process tracing and clear trace id of current thread if the given trace 280 * id is valid, otherwise do nothing. 281 * 282 * @param { HiTraceId } id The trace id that need to stop. 283 * @syscap SystemCapability.HiviewDFX.HiTrace 284 * @since arkts {'1.1':'8','1.2':'20'} 285 * @arkts 1.1&1.2 286 */ 287 function end(id: HiTraceId): void; 288 289 /** 290 * Get trace id of current thread, and return a invalid trace id if no 291 * trace id belong to current thread 292 * 293 * @returns { HiTraceId } Valid if current thread have a trace id, otherwise invalid. 294 * @syscap SystemCapability.HiviewDFX.HiTrace 295 * @since arkts {'1.1':'8','1.2':'20'} 296 * @arkts 1.1&1.2 297 */ 298 function getId(): HiTraceId; 299 300 /** 301 * Set id as trace id of current thread. Do nothing if id is invalid. 302 * 303 * @param { HiTraceId } id Set id as trace id of current thread. 304 * @syscap SystemCapability.HiviewDFX.HiTrace 305 * @since arkts {'1.1':'8','1.2':'20'} 306 * @arkts 1.1&1.2 307 */ 308 function setId(id: HiTraceId): void; 309 310 /** 311 * Clear trace id of current thread and set it invalid. 312 * 313 * @syscap SystemCapability.HiviewDFX.HiTrace 314 * @since arkts {'1.1':'8','1.2':'20'} 315 * @arkts 1.1&1.2 316 */ 317 function clearId(): void; 318 319 /** 320 * Create a new span id according to the trace id of current thread. 321 * 322 * @returns { HiTraceId } A valid span trace id. Otherwise trace id of current thread if do not allow create span. 323 * @syscap SystemCapability.HiviewDFX.HiTrace 324 * @since arkts {'1.1':'8','1.2':'20'} 325 * @arkts 1.1&1.2 326 */ 327 function createSpan(): HiTraceId; 328 329 /** 330 * Print hitrace info, include trace id info. 331 * 332 * @param { HiTraceCommunicationMode } mode Trace communication mode. 333 * @param { HiTraceTracepointType } type Trace info type. 334 * @param { HiTraceId } id Trace id that need to print. 335 * @param { string } msg Customized info that need to print. 336 * @syscap SystemCapability.HiviewDFX.HiTrace 337 * @since arkts {'1.1':'8','1.2':'20'} 338 * @arkts 1.1&1.2 339 */ 340 function tracepoint(mode: HiTraceCommunicationMode, type: HiTraceTracepointType, id: HiTraceId, msg?: string): void; 341 342 /** 343 * Judge whether the trace id is valid or not. 344 * 345 * @param { HiTraceId } id Trace id that need to judge. 346 * @returns { boolean } True for a valid trace id, otherwise false. 347 * @syscap SystemCapability.HiviewDFX.HiTrace 348 * @since arkts {'1.1':'8','1.2':'20'} 349 * @arkts 1.1&1.2 350 */ 351 function isValid(id: HiTraceId): boolean; 352 353 /** 354 * Judge whether the trace id has enabled a trace flag or not. 355 * 356 * @param { HiTraceId } id Trace id that need to judge. 357 * @param { HiTraceFlag } flag Trace flag that need to judge. 358 * @returns { boolean } true if the trace id has enabled the flag. 359 * @syscap SystemCapability.HiviewDFX.HiTrace 360 * @since arkts {'1.1':'8','1.2':'20'} 361 * @arkts 1.1&1.2 362 */ 363 function isFlagEnabled(id: HiTraceId, flag: HiTraceFlag): boolean; 364 365 /** 366 * Enable the designative trace flag for the trace id. 367 * 368 * @param { HiTraceId } id Trace id that need to enable a flag. 369 * @param { HiTraceFlag } flag the designative trace flag that need to be enabled in the trace id. 370 * @syscap SystemCapability.HiviewDFX.HiTrace 371 * @since arkts {'1.1':'8','1.2':'20'} 372 * @arkts 1.1&1.2 373 */ 374 function enableFlag(id: HiTraceId, flag: HiTraceFlag): void; 375} 376 377export default hiTraceChain; 378