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 * Provides APIs to implement call chain tracing throughout a service process. 18 * With HiTrace, you can quickly obtain the run log for the call chain of a 19 * specified service process and locate faults in cross-device, cross-process, 20 * or cross-thread communications. 21 * 22 * @since 8 23 * @syscap SystemCapability.HiviewDFX.HiTrace 24 */ 25declare namespace hiTraceChain { 26 /** 27 * Enumerate trace flag 28 * 29 * @since 8 30 * @syscap SystemCapability.HiviewDFX.HiTrace 31 */ 32 enum HiTraceFlag { 33 /** 34 * Default value 35 */ 36 DEFAULT = 0, 37 38 /** 39 * Trace sync and async call. default: trace sync call only. 40 */ 41 INCLUDE_ASYNC = 1, 42 43 /** 44 * Do not create child span. default: create child span. 45 */ 46 DONOT_CREATE_SPAN = 1 << 1, 47 48 /** 49 * Output tracepoint info in span. default: do not output tracepoint info. 50 */ 51 TP_INFO = 1 << 2, 52 53 /** 54 * Do not output begin and end info. default: output begin and end info. 55 */ 56 NO_BE_INFO = 1 << 3, 57 58 /** 59 * Do not add id to log. default: add id to log. 60 */ 61 DISABLE_LOG = 1 << 4, 62 63 /** 64 * The trace is triggered by fault. 65 */ 66 FAILURE_TRIGGER = 1 << 5, 67 68 /** 69 * Output device-to-device tracepoint info in span only. default: do not output device-to-device tracepoint info. 70 */ 71 D2D_TP_INFO = 1 << 6, 72 } 73 74 /** 75 * Enumerate trace point type 76 * 77 * @since 8 78 * @syscap SystemCapability.HiviewDFX.HiTrace 79 */ 80 enum HiTraceTracepointType { 81 /** 82 * Client send 83 */ 84 CS = 0, 85 86 /** 87 * Client receive 88 */ 89 CR = 1, 90 91 /** 92 * Server send 93 */ 94 SS = 2, 95 96 /** 97 * Server receive 98 */ 99 SR = 3, 100 101 /** 102 * General info 103 */ 104 GENERAL = 4, 105 } 106 107 /** 108 * Enumerate trace communication mode 109 * 110 * @since 8 111 * @syscap SystemCapability.HiviewDFX.HiTrace 112 */ 113 enum HiTraceCommunicationMode { 114 /** 115 * Unspecified 116 */ 117 DEFAULT = 0, 118 119 /** 120 * Thread-to-thread 121 */ 122 THREAD = 1, 123 124 /** 125 * Process-to-process 126 */ 127 PROCESS = 2, 128 129 /** 130 * Device-to-device 131 */ 132 DEVICE = 3, 133 } 134 135 /** 136 * Trace id, for tracing process. 137 * 138 * @since 8 139 * @syscap SystemCapability.HiviewDFX.HiTrace 140 */ 141 interface HiTraceId { 142 chainId: bigint; /* 0n: invalid */ 143 spanId?: number; 144 parentSpanId?: number; 145 flags?: number; 146 } 147 148 /** 149 * Start tracing a process impl. 150 * 151 * @since 8 152 * @syscap SystemCapability.HiviewDFX.HiTrace 153 * @param {string} name Process name. 154 * @param {number} flags Trace function flag. 155 * @returns {HiTraceId} Valid if first call, otherwise invalid. 156 */ 157 function begin(name: string, flags?: number): HiTraceId; 158 159 /** 160 * Stop process tracing and clear trace id of current thread if the given trace 161 * id is valid, otherwise do nothing. 162 * 163 * @since 8 164 * @syscap SystemCapability.HiviewDFX.HiTrace 165 * @param {HiTraceId} id The trace id that need to stop. 166 */ 167 function end(id: HiTraceId): void; 168 169 /** 170 * Get trace id of current thread, and return a invalid trace id if no 171 * trace id belong to current thread 172 * 173 * @since 8 174 * @syscap SystemCapability.HiviewDFX.HiTrace 175 * @returns {HiTraceId} Valid if current thread have a trace id, otherwise invalid. 176 */ 177 function getId(): HiTraceId; 178 179 /** 180 * Set id as trace id of current thread. Do nothing if id is invalid. 181 * 182 * @since 8 183 * @syscap SystemCapability.HiviewDFX.HiTrace 184 * @param {HiTraceId} id Set id as trace id of current thread. 185 */ 186 function setId(id: HiTraceId): void; 187 188 /** 189 * Clear trace id of current thread and set it invalid. 190 * 191 * @since 8 192 * @syscap SystemCapability.HiviewDFX.HiTrace 193 */ 194 function clearId(): void; 195 196 /** 197 * Create a new span id according to the trace id of current thread. 198 * 199 * @since 8 200 * @syscap SystemCapability.HiviewDFX.HiTrace 201 * @returns {HiTraceId} A valid span trace id. Otherwise trace id of current thread if do not allow create span. 202 */ 203 function createSpan(): HiTraceId; 204 205 /** 206 * Print hitrace info, include trace id info. 207 * 208 * @since 8 209 * @syscap SystemCapability.HiviewDFX.HiTrace 210 * @param {HiTraceCommunicationMode} mode Trace communication mode. 211 * @param {HiTraceTracepointType} type Trace info type. 212 * @param {HiTraceId} id Trace id that need to print. 213 * @param {string} msg Customized info that need to print. 214 */ 215 function tracepoint(mode: HiTraceCommunicationMode, type: HiTraceTracepointType, id: HiTraceId, msg?: string): void; 216 217 /** 218 * Judge whether the trace id is valid or not. 219 * 220 * @since 8 221 * @syscap SystemCapability.HiviewDFX.HiTrace 222 * @param {HiTraceId} id Trace id that need to judge. 223 * @returns {boolean} True for a valid trace id, otherwise false. 224 */ 225 function isValid(id: HiTraceId): boolean; 226 227 /** 228 * Judge whether the trace id has enabled a trace flag or not. 229 * 230 * @since 8 231 * @syscap SystemCapability.HiviewDFX.HiTrace 232 * @param {HiTraceId} id Trace id that need to judge. 233 * @param {HiTraceFlag} flag Trace flag that need to judge. 234 * @returns {boolean} true if the trace id has enabled the flag. 235 */ 236 function isFlagEnabled(id: HiTraceId, flag: HiTraceFlag): boolean; 237 238 /** 239 * Enable the designative trace flag for the trace id. 240 * 241 * @since 8 242 * @syscap SystemCapability.HiviewDFX.HiTrace 243 * @param {HiTraceId} id Trace id that need to enable a flag. 244 * @param {HiTraceFlag} flag the designative trace flag that need to be enabled in the trace id. 245 */ 246 function enableFlag(id: HiTraceId, flag: HiTraceFlag): void; 247} 248 249export default hiTraceChain; 250