diff --git a/api/@ohos.bytrace.d.ts b/api/@ohos.bytrace.d.ts index dcc5ba1bf0bf811d192ad06bacfcab6f5903b14f..1acc5cc2a9348e4203abc8591c17073217725c79 100644 --- a/api/@ohos.bytrace.d.ts +++ b/api/@ohos.bytrace.d.ts @@ -34,9 +34,9 @@ *
Each {@code startTrace} matches one {@code finishTrace}, and they must have the same name * and taskId. * - * @SysCap SystemCapability.Developtools.Bytrace - * @devices phone, tablet + * @deprecated * @since 7 + * @SysCap SystemCapability.Developtools.Bytrace */ declare namespace bytrace { /** @@ -47,10 +47,12 @@ declare namespace bytrace { * is specified by {@code name}, and the taskId is used to distinguish the tasks. It must be followed by * {@link #finishTrace}, the name and taskId need to be the same. * + * @deprecated + * @since 7 + * @SysCap SystemCapability.Developtools.Bytrace * @param name Indicates the task name. * @param taskId The unique id used to distinguish the tasks and match with the id in follow finishTrace. * @param expectedTime Indicates the expected time required for completing the task, in milliseconds. - * @since 7 */ function startTrace(name: string, taskId: number, expectedTime?: number): void; @@ -60,19 +62,23 @@ declare namespace bytrace { * This method is invoked at the end of a transaction to indicate that a task has ended, whose name * is specified by {@code name}. This method must be invoked after the the startTrace. * + * @deprecated + * @since 7 + * @SysCap SystemCapability.Developtools.Bytrace * @param name Indicates the task name. It must be the same whith the {@code name} of startTrace. * @param taskId The unique id used to distinguish the tasks and must be the same whith the . * {@code taskId} of startTrace. - * @since 7 */ function finishTrace(name: string, taskId: number): void; /** * Records a trace for generating a count, such as clock pulse and the number of layers. * + * @deprecated + * @since 7 + * @SysCap SystemCapability.Developtools.Bytrace * @param name Indicates the name used to identify the count. * @param count Indicates the number of the count. - * @since 7 */ function traceByValue(name: string, count: number): void; } diff --git a/api/@ohos.hiTraceChain.d.ts b/api/@ohos.hiTraceChain.d.ts new file mode 100644 index 0000000000000000000000000000000000000000..cd0b78fc536099fb38a62ea71b749cd2d37f53ab --- /dev/null +++ b/api/@ohos.hiTraceChain.d.ts @@ -0,0 +1,249 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * Provides APIs to implement call chain tracing throughout a service process. + * With HiTrace, you can quickly obtain the run log for the call chain of a + * specified service process and locate faults in cross-device, cross-process, + * or cross-thread communications. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + */ +declare namespace hiTraceChain { + /** + * Enumerate trace flag + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + */ + enum HiTraceFlag { + /** + * default value + */ + DEFAULT = 0, + + /** + * trace sync and async call. default: trace sync call only. + */ + INCLUDE_ASYNC = 1, + + /** + * do not create child span. default: create child span. + */ + DONOT_CREATE_SPAN = 1 << 1, + + /** + * output tracepoint info in span. default: do not output tracepoint info. + */ + TP_INFO = 1 << 2, + + /** + * do not output begin and end info. default: output begin and end info. + */ + NO_BE_INFO = 1 << 3, + + /** + * do not add id to log. default: add id to log. + */ + DISABLE_LOG = 1 << 4, + + /** + * the trace is triggered by fault. + */ + FAILURE_TRIGGER = 1 << 5, + + /** + * output device-to-device tracepoint info in span only. default: do not output device-to-device tracepoint info. + */ + D2D_TP_INFO = 1 << 6, + } + + /** + * Enumerate trace point type + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + */ + enum HiTraceTracepointType { + /** + * client send + */ + CS = 0, + + /** + * client receive + */ + CR = 1, + + /** + * server send + */ + SS = 2, + + /** + * server receive + */ + SR = 3, + + /** + * general info + */ + GENERAL = 4, + } + + /** + * Enumerate trace communication mode + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + */ + enum HiTraceCommunicationMode { + /** + * unspecified + */ + DEFAULT = 0, + + /** + * thread-to-thread + */ + THREAD = 1, + + /** + * process-to-process + */ + PROCESS = 2, + + /** + * device-to-device + */ + DEVICE = 3, + } + + /** + * Trace id, for tracing process. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + */ + interface HiTraceId { + chainId: bigint; /* 0n: invalid */ + spanId?: number; + parentSpanId?: number; + flags?: number; + } + + /** + * Start tracing a process impl. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + * @param {string} name Process name. + * @param {number} flags Trace function flag. + * @return {HiTraceId} Valid if first call, otherwise invalid. + */ + function begin(name: string, flags: number = HiTraceFlag.DEFAULT): HiTraceId; + + /** + * Stop process tracing and clear trace id of current thread if the given trace + * id is valid, otherwise do nothing. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + * @param {HiTraceId} id The trace id that need to stop. + */ + function end(id: HiTraceId): void; + + /** + * Get trace id of current thread, and return a invalid trace id if no + * trace id belong to current thread + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + * @return {HiTraceId} Valid if current thread have a trace id, otherwise invalid. + */ + function getId(): HiTraceId; + + /** + * Set id as trace id of current thread. Do nothing if id is invalid. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + * @param {HiTraceId} id Set id as trace id of current thread. + */ + function setId(id: HiTraceId): void; + + /** + * Clear trace id of current thread and set it invalid. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + */ + function clearId(): void; + + /** + * Create a new span id according to the trace id of current thread. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + * @return {HiTraceId} A valid span trace id. Otherwise trace id of current thread if do not allow create span. + */ + function createSpan(): HiTraceId; + + /** + * Print hitrace info, include trace id info. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + * @param {HiTraceCommunicationMode} mode Trace communication mode. + * @param {HiTraceTracepointType} type Trace info type. + * @param {HiTraceId} id Trace id that need to print. + * @param {string} msg Customized info that need to print. + */ + function tracepoint(mode: HiTraceCommunicationMode, type: HiTraceTracepointType, id: HiTraceId, msg?: string): void; + + /** + * Judge whether the trace id is valid or not. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + * @param {HiTraceId} id Trace id that need to judge. + * @return {boolean} True for a valid trace id, otherwise false. + */ + function isValid(id: HiTraceId): boolean; + + /** + * Judge whether the trace id has enabled a trace flag or not. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + * @param {HiTraceId} id Trace id that need to judge. + * @param {HiTraceFlag} flag Trace flag that need to judge. + * @return {boolean} true if the trace id has enabled the flag. + */ + function isFlagEnabled(id: HiTraceId, flag: HiTraceFlag): boolean; + + /** + * Enable the designative trace flag for the trace id. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + * @param {HiTraceId} id Trace id that need to enable a flag. + * @param {HiTraceFlag} flag the designative trace flag that need to be enabled in the trace id. + */ + function enableFlag(id: HiTraceId, flag: HiTraceFlag): void; +} + +export default hiTraceChain; diff --git a/api/@ohos.hiTraceMeter.d.ts b/api/@ohos.hiTraceMeter.d.ts new file mode 100644 index 0000000000000000000000000000000000000000..1d624ced5b9a1ef297399313d46712e1698c9c62 --- /dev/null +++ b/api/@ohos.hiTraceMeter.d.ts @@ -0,0 +1,81 @@ +/* + * Copyright (C) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * Provides interfaces to trace a task for performance measure, the logs can be capture by the + * bytrace cmdline available on the device. + * + *
This interfaces trace the start, end, and value changes of key processes that last for at least 3 ms. + * + *
Example: + * To trace a name verification that is expected to complete within 5 ms: + *
{@code + * bytrace.startTrace("checkName", 111, 5); + * //your process + * bytrace.finishTrace("checkName", 111); + * }+ * To trace the number of layers, which is 3: + *
{@code + * bytrace.traceByValue("curLayer", 3); + * }+ * + *
Each {@code startTrace} matches one {@code finishTrace}, and they must have the same name + * and taskId. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + */ +declare namespace hiTraceMeter { + /** + * Records a trace marking it as the start of a task, can with the expected completion time between + * startTrace and finishTrace. + * + * This method is invoked at the start of a transaction to indicate that a task has started, whose name + * is specified by {@code name}, and the taskId is used to distinguish the tasks. It must be followed by + * {@link #finishTrace}, the name and taskId need to be the same. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + * @param name Indicates the task name. + * @param taskId The unique id used to distinguish the tasks and match with the id in follow finishTrace. + */ + function startTrace(name: string, taskId: number): void; + + /** + * Records a trace and marks it as the end of a task. + * + * This method is invoked at the end of a transaction to indicate that a task has ended, whose name + * is specified by {@code name}. This method must be invoked after the the startTrace. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + * @param name Indicates the task name. It must be the same whith the {@code name} of startTrace. + * @param taskId The unique id used to distinguish the tasks and must be the same whith the . + * {@code taskId} of startTrace. + */ + function finishTrace(name: string, taskId: number): void; + + /** + * Records a trace for generating a count, such as clock pulse and the number of layers. + * + * @since 8 + * @SysCap SystemCapability.HiviewDFX.HiTrace + * @param name Indicates the name used to identify the count. + * @param count Indicates the number of the count. + */ + function traceByValue(name: string, count: number): void; +} + +export default hiTraceMeter; \ No newline at end of file