@ohos.hiTraceMeter (Performance Tracing)

The HiTraceMeter module provides the functions of tracing service processes and monitoring the system performance. It provides the data needed for HiTraceMeter to carry out performance analysis. For details about the development process, see Using HiTraceMeter.

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.

You are advised to use the performance tracing APIs of API version 19. The startTrace, finishTrace, and traceByValue APIs will be deprecated.

The trace output level cannot be specified in the startTrace, finishTrace and traceByValue APIs. By default, the trace output level is COMMERCIAL.

The vertical bar (|) is used as the separator in user-mode trace format. Therefore, the string parameters passed by the performance tracing APIs must exclude this character to avoid trace parsing exceptions.

The maximum length of a user-mode trace is 512 characters. Excess characters will be truncated.

Modules to Import

import { hiTraceMeter } from '@kit.PerformanceAnalysisKit';

hiTraceMeter.startTrace

startTrace(name: string, taskId: number): void

Starts an asynchronous trace.

If multiple trace tasks with the same name need to be performed at the same time or a trace 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 taskId can be used. For a specific example, see finishTrace.

Since API version 19, you are advised to use startAsyncTrace, which must be used together with finishAsyncTrace. In this way, you can specify the trace output level and category.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.HiviewDFX.HiTrace

Parameters

Example

hiTraceMeter.startTrace("myTestFunc", 1);

hiTraceMeter.finishTrace

finishTrace(name: string, taskId: number): void

Stops an asynchronous trace.

To stop a trace, the values of name and task ID in finishTrace must be the same as those in startTrace.

Since API version 19, you are advised to use finishAsyncTrace, which must be used together with startAsyncTrace.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.HiviewDFX.HiTrace

Parameters

Example

hiTraceMeter.finishTrace("myTestFunc", 1);

// Start trace tasks with the same name concurrently.
hiTraceMeter.startTrace("myTestFunc", 1);
// Service flow...
hiTraceMeter.startTrace("myTestFunc", 2);  // Start the second trace with the same name while the first task is still running. The tasks are running concurrently and therefore their taskId must be different.
// Service flow...
hiTraceMeter.finishTrace("myTestFunc", 1);
// Service flow...
hiTraceMeter.finishTrace("myTestFunc", 2);

// Start trace tasks with the same name in serial mode.
hiTraceMeter.startTrace("myTestFunc", 1);
// Service flow...
hiTraceMeter.finishTrace("myTestFunc", 1);  // End the first trace.
// Service flow...
hiTraceMeter.startTrace("myTestFunc", 1);   // Start the second trace with the same name in serial mode.
// Service flow...
hiTraceMeter.finishTrace("myTestFunc", 1);

hiTraceMeter.traceByValue

traceByValue(name: string, count: number): void

Traces the value changes of an integer variable.

Since API version 19, you are advised to use the traceByValue¹⁹⁺ API to specify the trace output level

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.HiviewDFX.HiTrace

Parameters

Example

let traceCount = 3;
hiTraceMeter.traceByValue("myTestCount", traceCount);
traceCount = 4;
hiTraceMeter.traceByValue("myTestCount", traceCount);
// Service flow...

HiTraceOutputLevel¹⁹⁺

Enumerates trace output levels.

The trace output level lower than the threshold does not take effect. The log version threshold is INFO, and the nolog version threshold is COMMERCIAL.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.HiviewDFX.HiTrace

hiTraceMeter.startAsyncTrace¹⁹⁺

startAsyncTrace(level: HiTraceOutputLevel, name: string, taskId: number, customCategory: string, customArgs?: string): void

Starts an asynchronous trace with the trace output level specified.

If multiple trace tasks with the same name need to be performed at the same time or a trace needs to be performed multiple times concurrently, different task IDs must be specified in startAsyncTrace.

If the trace tasks with the same name are not performed at the same time, the same taskId can be used. For details, see finishAsyncTrace.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.HiviewDFX.HiTrace

Parameters

Example

// If the customCategory parameter is not required, pass in an empty string.
// If the customArgs parameter is not required, do not pass in this parameter or pass in an empty string.
const COMMERCIAL = hiTraceMeter.HiTraceOutPutLevel.COMMERCIAL;
hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 1, "", "");
hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 2, "");
// Use commas (,) to separate multiple key-value pairs.
hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 3, "categoryTest", "key1=value");
hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 4, "categoryTest", "key1=value1,key2=value2");

hiTraceMeter.finishAsyncTrace¹⁹⁺

finishAsyncTrace(level: HiTraceOutputLevel, name: string, taskId: number): void

Stops an asynchronous trace with the trace output level specified.

The level, name, and taskId used in finishAsyncTrace must be the same as those of startAsyncTrace.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.HiviewDFX.HiTrace

Parameters

Example

const COMMERCIAL = hiTraceMeter.HiTraceOutPutLevel.COMMERCIAL;
hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 1);

const COMMERCIAL = hiTraceMeter.HiTraceOutPutLevel.COMMERCIAL;
// Start trace tasks with the same name concurrently.
// Start the first trace.
hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 1, "categoryTest", "key=value");
// Service flow...
// Start the second trace with the same name while the first trace is still running. The tasks are running concurrently and therefore their taskId must be different.
hiTraceMeter.startAsyncTrace(COMMERCIAL, "myTestFunc", 2, "categoryTest", "key=value");
// Service flow...
// Stop the first trace.
hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 1);
// Service flow...
// Stop the second trace.
hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 2);

const COMMERCIAL = hiTraceMeter.HiTraceOutPutLevel.COMMERCIAL;
// Start trace tasks with the same name in serial mode.
// Start the first trace.
hiTraceMeter.startTrace(COMMERCIAL, "myTestFunc", 1, "categoryTest", "key=value");
// Service flow...
// Stop the first trace.
hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 1);
// Service flow...
// Start the second trace with the same name. The traces with the same name are executed in serial mode.
hiTraceMeter.startTrace(COMMERCIAL, "myTestFunc", 1, "categoryTest", "key=value");
// Service flow...
// Stop the second trace with the same name.
hiTraceMeter.finishAsyncTrace(COMMERCIAL, "myTestFunc", 1);

hiTraceMeter.startSyncTrace¹⁹⁺

startSyncTrace(level: HiTraceOutputLevel, name: string, customArgs?: string): void

Starts a synchronous trace with the trace output level specified. For details, see finishSyncTrace.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.HiviewDFX.HiTrace

Parameters

Example

const COMMERCIAL = hiTraceMeter.HiTraceOutPutLevel.COMMERCIAL;
// If the customArgs parameter is not required, do not pass in this parameter or pass in an empty string.
hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc");
hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc", "");
// Use commas (,) to separate multiple key-value pairs.
hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc", "key=value");
hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc", "key1=value1,key2=value2");

hiTraceMeter.finishSyncTrace¹⁹⁺

finishSyncTrace(level: HiTraceOutputLevel): void

Stops a synchronous trace with the trace output level specified.

The level used in finishSyncTrace must be the same as that of startSyncTrace.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.HiviewDFX.HiTrace

Parameters

Example

const COMMERCIAL = hiTraceMeter.HiTraceOutPutLevel.COMMERCIAL;
hiTraceMeter.finishSyncTrace(COMMERCIAL);

const COMMERCIAL = hiTraceMeter.HiTraceOutPutLevel.COMMERCIAL;
// The startSyncTrace and finishSyncTrace APIs can be nested and they matched each other based on proximity.
// Start the first trace.
hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc1", "key=value");
// Service flow...
// Start the second trace.
hiTraceMeter.startSyncTrace(COMMERCIAL, "myTestFunc2", "key=value");
// Service flow...
// Stop the second trace.
hiTraceMeter.finishSyncTrace(COMMERCIAL);
// Service flow...
// Stop the first trace.
hiTraceMeter.finishSyncTrace(COMMERCIAL);

hiTraceMeter.traceByValue¹⁹⁺

traceByValue(level: HiTraceOutputLevel, name: string, count: number): void

Traces an integer with the trace output level specified. name and count are used to identify the name and value of an integer variable to be traced.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.HiviewDFX.HiTrace

Parameters

Example

const COMMERCIAL = hiTraceMeter.HiTraceOutPutLevel.COMMERCIAL;
let traceCount = 3;
hiTraceMeter.traceByValue(COMMERCIAL, "myTestCount", traceCount);
traceCount = 4;
hiTraceMeter.traceByValue(COMMERCIAL, "myTestCount", traceCount);
// Service flow...

hiTraceMeter.isTraceEnabled¹⁹⁺

isTraceEnabled(): boolean

Checks whether application trace capture is enabled.

You can use HiTrace commands to enable or disable trace capture.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.HiviewDFX.HiTrace

Returns

Example

if (hiTraceMeter.isTraceEnabled()) {
    // Service flow...
} else {
    // Service flow...
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Performance Analysis Kit

harmony 鸿蒙Performance Analysis Kit

harmony 鸿蒙HiAppEvent

harmony 鸿蒙HiAppEvent_AppEventGroup

harmony 鸿蒙HiAppEvent_AppEventInfo

harmony 鸿蒙HiCollie

harmony 鸿蒙HiCollie_DetectionParam

harmony 鸿蒙HiCollie_SetTimerParam

harmony 鸿蒙HiDebug

harmony 鸿蒙HiDebug_MemoryLimit