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