diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index 1caec073b4827d78cd75f8238251af09edee81a0..4f22a8bf7269083ffad5538d06cf85ce92fbfcb7 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -5,7 +5,6 @@ - [ParticleAbility Module](js-apis-particleAbility.md) - [DataAbilityHelper Module](js-apis-dataAbilityHelper.md) - [DataUriUtils Module](js-apis-DataUriUtils.md) - - [Bundle Module](js-apis-Bundle.md) - [Context Module](js-apis-Context.md) - Event Notification - [CommonEvent Module](js-apis-commonEvent.md) @@ -21,16 +20,14 @@ - Security - [User Authentication](js-apis-useriam-userauth.md) - Data Management + - [File Management](js-apis-fileio.md) - [Lightweight Storage](js-apis-data-storage.md) - [Distributed Data Management](js-apis-distributed-data.md) - [Relational Database](js-apis-data-rdb.md) - [Result Set](js-apis-data-resultset.md) - [DataAbilityPredicates](js-apis-data-ability.md) -- File Management - - [File Management](js-apis-fileio.md) - Account Management - [Distributed Account Management](js-apis-distributed-account.md) - - [Application Account Management](js-apis-appAccount.md) - Telephony Service - [Call](js-apis-call.md) - [SMS](js-apis-sms.md) @@ -38,7 +35,6 @@ - [Radio](js-apis-radio.md) - Network and Connectivity - [WLAN](js-apis-wifi.md) - - [Bluetooth](js-apis-bluetooth.md) - Device Management - [Sensors](js-apis-sensor.md) - [Vibration](js-apis-vibrator.md) @@ -63,10 +59,10 @@ - [Setting the System Time](js-apis-system-time.md) - [Animation](js-apis-basic-features-animator.md) - [HiAppEvent](js-apis-hiappevent.md) - - [Performance Tracing](js-apis-bytrace.md) + - [Performance Tracing](js-apis-hitracemeter.md) - [Fault Logger](js-apis-faultLogger.md) - - [WebGL](js-apis-webgl.md) - - [WebGL2](js-apis-webgl2.md) + - [Distributed Call Chain Tracing](js-apis-hitracechain.md) + - [HiLog](js-apis-hilog.md) - Language Base Class Library - [Obtaining Process Information](js-apis-process.md) - [URL String Parsing](js-apis-url.md) diff --git a/en/application-dev/reference/apis/js-apis-bytrace.md b/en/application-dev/reference/apis/js-apis-bytrace.md index fc9713b4a69cc469e096111f27e25f39115e2ef0..a79e890d2a29af43852f76653150048c23f84c4a 100644 --- a/en/application-dev/reference/apis/js-apis-bytrace.md +++ b/en/application-dev/reference/apis/js-apis-bytrace.md @@ -1,7 +1,8 @@ # Performance Tracing >![](../../public_sys-resources/icon-note.gif) **NOTE:** ->The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> - The APIs of this module are no longer maintained since API version 8. It is recommended that you use the APIs of [hiTraceMeter](js-apis-hitracemeter.md) instead. +> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import @@ -9,9 +10,9 @@ import bytrace from '@ohos.bytrace'; ``` -## System Capabilities +## Required Permissions -SystemCapability.Developtools.Bytrace +None ## bytrace.startTrace @@ -194,5 +195,3 @@ Traces the value changes of a variable. traceCount = 5; bytrace.traceByValue("myTestCount", traceCount); ``` - - diff --git a/en/application-dev/reference/apis/js-apis-hitracechain.md b/en/application-dev/reference/apis/js-apis-hitracechain.md new file mode 100644 index 0000000000000000000000000000000000000000..370e48bd2a3bca058451d15a2b4f42ab77dd9b05 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-hitracechain.md @@ -0,0 +1,253 @@ +# Distributed Call Chain Tracing + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **Note:** +> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +``` +import hiTraceChain from '@ohos.hiTraceChain'; +``` + +## System Capabilities + +SystemCapability.HiviewDFX.HiTrace + +## HiTraceFlag + +Enumerates trace flag types. + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| DEFAULT | 0 | Default flag| +| INCLUDE_ASYNC | 1 | Asynchronous call flag| +| DONOT_CREATE_SPAN | 1 << 1 | No span flag| +| TP_INFO | 1 << 2 | Trace point flag| +| NO_BE_INFO | 1 << 3 | No begin/end flag| +| DISABLE_LOG | 1 << 4 | Log association flag| +| FAILURE_TRIGGER | 1 << 5 | Failure trigger flag| +| D2D_TP_INFO | 1 << 6 | Device-to-device trace point flag| + +## HiTraceTracepointType + +Enumerates trace point types. + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| CS | 0 | Client Send| +| CR | 1 | Client Receive| +| SS | 2 | Server Send| +| SR | 3 | Server Receive| +| GENERAL | 4 | General| + +## HiTraceCommunicationMode + +Enumerates communication modes. + +| Name| Default Value| Description| +| -------- | -------- | -------- | +| DEFAULT | 0 | Default mode| +| THREAD | 1 | Inter-thread communication| +| PROCESS | 2 | Inter-process communication| +| DEVICE | 3 | Inter-device communication| + +## HiTraceId + +Defines a **HiTraceId** object. + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| chainId | bigint | Yes| Call chain ID.| +| spandId | number | No| Span ID.| +| parentSpanId | number | No| Parent span ID.| +| flags | number | No| Trace flag combination.| + +## hiTraceChain.begin + +begin(name: string, flags: number = HiTraceFlag.DEFAULT): HiTraceId + +Starts call chain tracing. This API works in synchronous manner. + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | name | string | Yes| Traced service name.| + | flags | number | Yes| [Trace flag combination](#hitraceflag).| +- Return value + | Type| Description| + | -------- | -------- | + | [HiTraceId](#hitraceid) | **HiTraceId** instance.| + +- Example + ``` + let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); + ``` + +## hiTraceChain.end + +end(id: HiTraceId): void + +Stops call chain tracing. This API works in synchronous manner. + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| + +- Example + ``` + let asyncTraceId = hiTraceChain.begin("business"); + // End the call chain tracing after the service logic is executed for several times. + hiTraceChain.end(asyncTraceId); + ``` + +## hiTraceChain.getId + +getId(): HiTraceId + +Obtains the trace ID. This API works in synchronous manner. + +- Return value + | Type| Description| + | -------- | -------- | + | [HiTraceId](#hitraceid) | **HiTraceId** instance.| + +- Example + ``` + let traceId = hiTraceChain.begin("business"); + // Obtain the current trace ID after the service logic is executed for several times. + let curTraceId = hiTraceChain.getId(); + ``` + +## hiTraceChain.setId + +setId(id: HiTraceId): void + +Sets a trace ID. This API works in synchronous manner. + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| + +- Example + ``` + let traceId = hiTraceChain.begin("business"); + // Set the current trace ID after the service logic is executed for several times. + hiTraceChain.setId(asyncTraceId); + ``` + +## hiTraceChain.clearId + +clearId(): void + +Clears the trace ID. This API works in synchronous manner. + +- Example + ``` + let traceId = hiTraceChain.begin("business"); + // Clear the current trace ID after the service logic is executed for several times. + hiTraceChain.clearId(); + ``` + +## hiTraceChain.createSpan + +createSpan(): HiTraceId + +Creates a trace span. This API works in synchronous manner. + +- Return value + | Type| Description| + | -------- | -------- | + | [HiTraceId](#hitraceid) | **HiTraceId** instance.| + +- Example + ``` + let traceId = hiTraceChain.begin("business"); + // Create a trace span after the service logic is executed for several times. + let spanTraceId = hiTraceChain.createSpan(); + ``` + +## hiTraceChain.tracepoint + +tracepoint(mode: HiTraceCommunicationMode, type: HiTraceTracepointType, id: HiTraceId, msg?: string): void + +Triggers a trace point. This API works in synchronous manner. + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | mode | [HiTraceCommunicationMode](#hitracecommunicationmode) | Yes| Communication mode for the trace point.| + | type | [HiTraceTracepointType](#hitracetracepointtype)| Yes| Trace point type.| + | id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance for trace point triggering.| + | msg | string | No| Trace description passed for trace point triggering.| + +- Example + ``` + let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC | hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); + // Trigger the trace point after the service logic is executed for several times. + hiTraceChain.tracepoint(hiTraceChain.HiTraceCommunicationMode.THREAD, hiTraceChain.HiTraceTracepointType.SS, asyncTraceId, "Just a example"); + ``` + +## hiTraceChain.isValid + +isValid(id: HiTraceId): boolean + +Checks whether a **HiTraceId** instance is valid. This API works in synchronous manner. + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| +- Return value + | Type| Description| + | -------- | -------- | + | boolean | Returns **true** if the **HiTraceId** instance is valid; returns **false** otherwise.| + +- Example + ``` + let traceId = hiTraceChain.begin("business"); + let traceIdIsvalid = hiTraceChain.isValid(traceId); + ``` + +## hiTraceChain.isFlagEnabled + +isFlagEnabled(id: HiTraceId, flag: HiTraceFlag): boolean + +Checks whether the specified trace flag in the **HiTraceId** instance is enabled. This API works in synchronous manner. + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| + | flag | [HiTraceFlag](#hitraceflag) | Yes| Specified trace flag.| +- Return value + | Type| Description| + | -------- | -------- | + | boolean | Returns **true** if the specified trace flag in the **HiTraceId** instance is enabled; returns **false** otherwise.| +- Example + ``` + let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); + // The value of enabledDoNotCreateSpanFlag is true. + let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(asyncTraceId, hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); + ``` + +## hiTraceChain.enableFlag + +enableFlag(id: HiTraceId, flag: HiTraceFlag): void + +Enables the specified trace flag in the **HiTraceId** instance. This API works in synchronous manner. + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | id | [HiTraceId](#hitraceid) | Yes| **HiTraceId** instance.| + | flag | [HiTraceFlag](#hitraceflag) | Yes| Specified trace flag.| + +- Example + ``` + let asyncTraceId = hiTraceChain.begin("business", hiTraceChain.HiTraceFlag.INCLUDE_ASYNC); + hiTraceChain.enable(asyncTraceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); + // The value of enabledDoNotCreateSpanFlag is true. + let enabledDoNotCreateSpanFlag = hiTraceChain.isFlagEnabled(asyncTraceId, hiTraceChain.HiTraceFlag.DONOT_CREATE_SPAN); + ``` diff --git a/en/application-dev/reference/apis/js-apis-hitracemeter.md b/en/application-dev/reference/apis/js-apis-hitracemeter.md new file mode 100644 index 0000000000000000000000000000000000000000..fc8599f907aeaa7f0e0314f704b84d2139ba9a96 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-hitracemeter.md @@ -0,0 +1,107 @@ +# Performance Tracing + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **Note:** +> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. + + +## Modules to Import + +``` +import hiTraceMeter from '@ohos.hiTraceMeter'; +``` + + +## System Capabilities + +SystemCapability.HiviewDFX.HiTrace + + +## hiTraceMeter.startTrace + +startTrace(name: string, taskId: number, expectedTime?: number): void + +Starts a trace task. **expectedTime** is an optional parameter, which specifies the expected duration of the trace. + + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | name | string | Yes| Name of the trace task to start.| + | taskId | number | Yes| Task ID.| + | expectedTime | number | No| Expected duration of the trace, in ms.| + + > ![icon-note.gif](public_sys-resources/icon-note.gif) **Note:** + > If multiple trace tasks with the same name need to be performed at the same time or a trace task needs to be performed multiple times concurrently, different task IDs must be specified in **startTrace**. If the trace tasks with the same name are not performed at the same time, the same task ID can be used. For details, see the **hiTraceMeter.finishTrace** example. + +- Example + ``` + hiTraceMeter.startTrace("myTestFunc", 1); + hiTraceMeter.startTrace("myTestFunc", 1, 5); // The expected duration of the trace task is 5 ms. + ``` + + +## hiTraceMeter.finishTrace + +finishTrace(name: string, taskId: number): void + +Stops a trace task. + + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | name | string | Yes| Name of the trace task to start.| + | taskId | number | Yes| Task ID.| + + > ![icon-note.gif](public_sys-resources/icon-note.gif) **Note:** + > To stop a trace task, the values of name and task ID in **finishTrace** must be the same as those in **startTrace**. + +- Example + ``` + hiTraceMeter.finishTrace("myTestFunc", 1); + ``` + + ``` + // Start track tasks with the same name concurrently. + hiTraceMeter.startTrace("myTestFunc", 1); + // Service flow + hiTraceMeter.startTrace("myTestFunc", 2); // The second trace task starts while the first task is still running. The first and second tasks have the same name but different task IDs. + // Service flow + hiTraceMeter.finishTrace("myTestFunc", 1); + // Service flow + hiTraceMeter.finishTrace("myTestFunc", 2); + ``` + + ``` + // Start track tasks with the same name at different times. + hiTraceMeter.startTrace("myTestFunc", 1); + // Service flow + hiTraceMeter.finishTrace("myTestFunc", 1); // The first trace task ends. + // Service flow + hiTraceMeter.startTrace("myTestFunc", 1); // The second trace task starts after the first task ends. The two tasks have the same name and task ID. + // Service flow + hiTraceMeter.finishTrace("myTestFunc", 1); + ``` + + +## hiTraceMeter.traceByValue + +traceByValue(name: string, value: number): void + +Traces the value changes of a variable. + + +- Parameters + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | name | string | Yes| Name of the variable.| + | value | number | Yes| Value of the variable.| + +- Example + ``` + let traceCount = 3; + hiTraceMeter.traceByValue("myTestCount", traceCount); + traceCount = 4; + hiTraceMeter.traceByValue("myTestCount", traceCount); + // Service flow + ```