1# Working with Trace Using JSVM-API
2
3## Introduction
4
5You can use the trace-related APIs in JSVM-API to collect and output various types of runtime information. This capability can be used for fault location and performance analysis in the JSVM module.
6
7## Basic Concepts
8
9With the trace-related APIs, you can specify the categories for data collecting, collect information about JSVM internal events related to the specified categories, and return the collected information in JSON format via the specified callback.
10
11The trace capabilities provided by JSVM-API allow seamless integration of the JSVM module with the JavaScript environment, facilitating the identification of complex problems and system profiling.
12
13## Available APIs
14
15| API                      | Description                      |
16|----------------------------|--------------------------------|
17| OH_JSVM_TraceStart           | Starts collecting runtime information based on the specified event type and event count limit. |
18| OH_JSVM_TraceStop        | Stops collecting information and returns the collected information in JSON format via the specified callback. |
19
20## Example
21
22If you are just starting out with JSVM-API, see [JSVM-API Development Process](use-jsvm-process.md). The following demonstrates only the C++ code involved in trace development.
23
24### Collecting Data
25
26CPP code:
27
28```cpp
29#include <vector>
30#include <string>
31
32bool OutputStream(const char *data, int size, void *streamData) {
33    std::string value(data, size);
34    *(std::string *)streamData = std::string(data, size);
35    return true;
36}
37
38// OH_JSVM_TraceStart/OH_JSVM_TraceStop methods.
39static JSVM_Value Trace(JSVM_Env env, JSVM_CallbackInfo info) {
40    // Start trace based on the specified categories.
41    std::vector<JSVM_TraceCategory> categories = {JSVM_TRACE_VM};
42    JSVM_CALL(OH_JSVM_TraceStart(categories.size(), categories.data(), "trace test", 0));
43
44    // Run the code and trace data.
45    JSVM_Script script;
46    JSVM_Value jsSrc;
47    JSVM_Value result;
48    const char* trace_js = R"JS(
49      function map(x, y) {
50        return {"a": x, "b": y};
51      }
52      for (var i = 0; i < 80000; ++i) {
53        var x = map(i, i);
54      }
55    )JS";
56    JSVM_CALL(OH_JSVM_CreateStringUtf8(env, trace_js, JSVM_AUTO_LENGTH, &jsSrc));
57    JSVM_CALL(OH_JSVM_CompileScript(env, jsSrc, nullptr, 0, true, nullptr, &script));
58    JSVM_CALL(OH_JSVM_RunScript(env, script, &result));
59
60    // Stop tracing and write file.
61    std::string data;
62    JSVM_CALL(OH_JSVM_TraceStop(OutputStream, (void *)&data));
63
64    OH_LOG_INFO(LOG_APP, "JSVM Trace success:%{public}s", data.c_str());
65    return nullptr;
66}
67// Register the trace callback.
68static JSVM_CallbackStruct param[] = {
69    {.data = nullptr, .callback = Trace},
70};
71static JSVM_CallbackStruct *method = param;
72// Set a property descriptor named trace and associate it with a callback. This allows the Trace callback to be called from JS.
73static JSVM_PropertyDescriptor descriptor[] = {
74    {"trace", nullptr, method, nullptr, nullptr, nullptr, JSVM_DEFAULT},
75};
76// Call the C++ code from JS.
77const char *srcCallNative = R"JS(trace())JS";
78```
79