@ohos-perf/core 0.1.0 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/index.d.ts +2687 -71
- package/dist/index.js +13442 -4189
- package/package.json +48 -40
package/dist/index.d.ts
CHANGED
|
@@ -26,6 +26,27 @@ declare class StreamerNotFoundError extends OhosPerfError {
|
|
|
26
26
|
code?: string;
|
|
27
27
|
});
|
|
28
28
|
}
|
|
29
|
+
declare class EmulatorCommandError extends OhosPerfError {
|
|
30
|
+
readonly output: string;
|
|
31
|
+
constructor(message: string, output: string, opts?: {
|
|
32
|
+
cause?: unknown;
|
|
33
|
+
code?: string;
|
|
34
|
+
});
|
|
35
|
+
}
|
|
36
|
+
declare class EmulatorImageMissingError extends OhosPerfError {
|
|
37
|
+
readonly installCommand: string;
|
|
38
|
+
constructor(message: string, installCommand: string, opts?: {
|
|
39
|
+
cause?: unknown;
|
|
40
|
+
code?: string;
|
|
41
|
+
});
|
|
42
|
+
}
|
|
43
|
+
declare class EmulatorNotFoundError extends OhosPerfError {
|
|
44
|
+
readonly searchedPaths: string[];
|
|
45
|
+
constructor(searchedPaths: string[], opts?: {
|
|
46
|
+
cause?: unknown;
|
|
47
|
+
code?: string;
|
|
48
|
+
});
|
|
49
|
+
}
|
|
29
50
|
declare class IngestError extends OhosPerfError {
|
|
30
51
|
readonly stderr: string;
|
|
31
52
|
constructor(message: string, stderr: string, code?: string, opts?: {
|
|
@@ -149,6 +170,23 @@ declare class Hdc {
|
|
|
149
170
|
* HDC_SHELL_FAILED.
|
|
150
171
|
*/
|
|
151
172
|
shell(target: string, cmd: string): Promise<HdcResult>;
|
|
173
|
+
/**
|
|
174
|
+
* Run a long-lived shell command and collect its stdout for `durationMs`.
|
|
175
|
+
*
|
|
176
|
+
* `hilog` never exits on its own, so the host clock bounds the capture and
|
|
177
|
+
* the child is killed at the end. Killing is the normal path, not an error:
|
|
178
|
+
* the result carries whatever was printed before the kill and `code` is the
|
|
179
|
+
* exit code only when the child exited on its own (`null` when killed).
|
|
180
|
+
*
|
|
181
|
+
* A command that fails immediately (non-zero exit before the deadline) is
|
|
182
|
+
* still returned rather than thrown: the collector decides whether the
|
|
183
|
+
* output is usable, and an empty result is what it must see.
|
|
184
|
+
*/
|
|
185
|
+
shellFor(target: string, cmd: string, durationMs: number): Promise<{
|
|
186
|
+
stdout: string;
|
|
187
|
+
stderr: string;
|
|
188
|
+
code: number | null;
|
|
189
|
+
}>;
|
|
152
190
|
recv(target: string, devicePath: string, localPath: string): Promise<void>;
|
|
153
191
|
send(target: string, localPath: string, devicePath: string): Promise<void>;
|
|
154
192
|
fport(target: string, local: number, remote: number): Promise<void>;
|
|
@@ -180,7 +218,7 @@ declare class Hdc {
|
|
|
180
218
|
* probe output that produced the verdict. Callers never have to infer "empty
|
|
181
219
|
* result" from "unsupported device".
|
|
182
220
|
*/
|
|
183
|
-
type CapabilityId = 'trace.frames' | 'trace.sched' | 'trace.binder' | 'trace.thread_state' | 'perf.samples' | 'perf.pmu' | 'mem.procfs' | 'mem.native_hook' | 'mem.gpu' | 'render.fps_live' | 'render.hitch' | 'render.vsync' | 'ui.tree' | 'ui.gesture' | 'power.xpower' | 'net.io' | 'disk.io' | 'js.heap' | 'coverage' | 'startup.app_startup';
|
|
221
|
+
type CapabilityId = 'trace.frames' | 'trace.sched' | 'trace.binder' | 'trace.thread_state' | 'trace.ark' | 'perf.samples' | 'perf.pmu' | 'mem.procfs' | 'mem.native_hook' | 'mem.gpu' | 'render.fps_live' | 'render.hitch' | 'render.vsync' | 'ui.tree' | 'ui.gesture' | 'ui.capture' | 'power.xpower' | 'net.io' | 'disk.io' | 'js.heap' | 'coverage' | 'hilog.stream' | 'startup.app_startup' | 'static.hap';
|
|
184
222
|
/**
|
|
185
223
|
* How directly a capability measures the thing it claims to measure.
|
|
186
224
|
*
|
|
@@ -322,12 +360,12 @@ declare class Streamer {
|
|
|
322
360
|
* without a fresh file all fail. Every filesystem failure is surfaced as an
|
|
323
361
|
* IngestError, never a raw fs error.
|
|
324
362
|
*/
|
|
325
|
-
convert(inputPath: string, outputDbPath: string): Promise<void>;
|
|
363
|
+
convert(inputPath: string, outputDbPath: string, soDir?: string): Promise<void>;
|
|
326
364
|
/**
|
|
327
365
|
* `shell: false` is mandatory: the DevEco install path contains spaces, and
|
|
328
366
|
* a shell would split `D:/Application/DevEco Studio/...` into pieces.
|
|
329
367
|
*/
|
|
330
|
-
spawnSpec(inputPath: string, outputDbPath: string): SpawnSpec;
|
|
368
|
+
spawnSpec(inputPath: string, outputDbPath: string, soDir?: string): SpawnSpec;
|
|
331
369
|
private spawnSpecFor;
|
|
332
370
|
/** Spawn without a shell so spaces in the executable path stay intact. */
|
|
333
371
|
protected spawnProcess(command: string, args: string[]): Promise<SpawnResult>;
|
|
@@ -350,6 +388,12 @@ interface SceneLayout {
|
|
|
350
388
|
hidumperFile: string;
|
|
351
389
|
/** `ui.json` from a `uitest dumpLayout` capture. */
|
|
352
390
|
uiFile: string;
|
|
391
|
+
/** `screenshot.png` from a `uitest screenCap` capture. */
|
|
392
|
+
screenshotFile: string;
|
|
393
|
+
/** `hilog.log` from a `--hilog` capture: the raw device log stream. */
|
|
394
|
+
hilogFile: string;
|
|
395
|
+
/** `hilog.jsonl` from the same capture: one typed row per log line. */
|
|
396
|
+
hilogJsonlFile: string;
|
|
353
397
|
metadataFile: string;
|
|
354
398
|
}
|
|
355
399
|
declare function createSceneLayout(root: string): SceneLayout;
|
|
@@ -635,6 +679,33 @@ declare class HidumperCollector implements Collector {
|
|
|
635
679
|
}, layout: SceneLayout): Promise<HidumperCapture>;
|
|
636
680
|
}
|
|
637
681
|
|
|
682
|
+
/** The command whose stdout is the log stream. */
|
|
683
|
+
declare const HILOG_COMMAND = "hilog";
|
|
684
|
+
/**
|
|
685
|
+
* Captures the device's hilog stream into the scene.
|
|
686
|
+
*
|
|
687
|
+
* The output is the raw log text, one line per record. Parsing happens
|
|
688
|
+
* offline (`parseHilogText`), so the artifact is exactly what the device
|
|
689
|
+
* printed and a parser change never requires a re-capture.
|
|
690
|
+
*/
|
|
691
|
+
declare class HilogCollector implements Collector {
|
|
692
|
+
readonly id = "hilog";
|
|
693
|
+
readonly provides: CapabilityId[];
|
|
694
|
+
collect(hdc: Hdc, target: string, opts: {
|
|
695
|
+
durationMs: number;
|
|
696
|
+
}, layout: SceneLayout): Promise<{
|
|
697
|
+
lines: number;
|
|
698
|
+
}>;
|
|
699
|
+
}
|
|
700
|
+
/**
|
|
701
|
+
* Read the captured log back.
|
|
702
|
+
*
|
|
703
|
+
* Returns `undefined` when the scene has no `hilog.log`: an absent artifact
|
|
704
|
+
* is a scene that never captured logs, and the analyzer turns that into a
|
|
705
|
+
* degraded reason rather than an empty measurement.
|
|
706
|
+
*/
|
|
707
|
+
declare function readHilogText(layout: SceneLayout): string | undefined;
|
|
708
|
+
|
|
638
709
|
/**
|
|
639
710
|
* hiperf collection driver.
|
|
640
711
|
*
|
|
@@ -822,7 +893,32 @@ interface UiNode {
|
|
|
822
893
|
readonly scrollable: boolean;
|
|
823
894
|
/** Direct child count. */
|
|
824
895
|
readonly children: number;
|
|
896
|
+
/**
|
|
897
|
+
* `bounds` parsed into a rect, or `undefined` when the string did not match
|
|
898
|
+
* the measured `"[l,t][r,b]"` form. The diff compares geometry edge by edge,
|
|
899
|
+
* so it needs numbers; a node whose bounds did not parse simply has none.
|
|
900
|
+
*/
|
|
901
|
+
readonly boundsRect?: {
|
|
902
|
+
readonly left: number;
|
|
903
|
+
readonly top: number;
|
|
904
|
+
readonly right: number;
|
|
905
|
+
readonly bottom: number;
|
|
906
|
+
};
|
|
907
|
+
/**
|
|
908
|
+
* Every string attribute the dump carried, for the UI diff's attribute
|
|
909
|
+
* comparison. Optional so a caller that only lists nodes does not pay for a
|
|
910
|
+
* copy of every field; `flattenUiTree` always fills it.
|
|
911
|
+
*/
|
|
912
|
+
readonly attributes?: Readonly<Record<string, string>>;
|
|
825
913
|
}
|
|
914
|
+
/**
|
|
915
|
+
* Parse a `bounds` string into a rect.
|
|
916
|
+
*
|
|
917
|
+
* The dump writes `"[0,0][1080,2340]"`. Anything else — a different separator,
|
|
918
|
+
* a float, a single corner — is `undefined` rather than a guess: the UI diff
|
|
919
|
+
* treats geometry as numbers, and a guessed rect would mark the wrong region.
|
|
920
|
+
*/
|
|
921
|
+
declare function parseBounds(bounds: string): UiNode['boundsRect'];
|
|
826
922
|
/**
|
|
827
923
|
* Flatten a `dumpLayout` document depth-first in document order.
|
|
828
924
|
*
|
|
@@ -834,16 +930,27 @@ interface UiNode {
|
|
|
834
930
|
* A document that is not a tree at all yields `[]` rather than throwing: the
|
|
835
931
|
* caller asked "what is on screen", and "nothing parseable" is a valid answer
|
|
836
932
|
* that the `ui.get` query can return as zero rows.
|
|
933
|
+
*
|
|
934
|
+
* `opts.full` adds `boundsRect` and the raw `attributes` map, which the UI diff
|
|
935
|
+
* needs and `ui.get` does not: a query row carries the documented subset, so an
|
|
936
|
+
* agent reading a screen does not get every renderer field with it.
|
|
837
937
|
*/
|
|
838
|
-
declare function flattenUiTree(root: unknown
|
|
938
|
+
declare function flattenUiTree(root: unknown, opts?: {
|
|
939
|
+
full?: boolean;
|
|
940
|
+
}): UiNode[];
|
|
839
941
|
/**
|
|
840
942
|
* Read a captured `ui.json` and flatten it.
|
|
841
943
|
*
|
|
842
944
|
* A missing file is not an error (the scene may have no uitest capture);
|
|
843
945
|
* invalid JSON is likewise `undefined`, because a truncated dump is not a
|
|
844
946
|
* screen with no nodes.
|
|
947
|
+
*
|
|
948
|
+
* `opts.full` is passed through to {@link flattenUiTree}: the UI diff reads a
|
|
949
|
+
* scene with it, the `ui.get` query does not.
|
|
845
950
|
*/
|
|
846
|
-
declare function readUiTree(path: string
|
|
951
|
+
declare function readUiTree(path: string, opts?: {
|
|
952
|
+
full?: boolean;
|
|
953
|
+
}): UiNode[] | undefined;
|
|
847
954
|
|
|
848
955
|
/** Fixed device-side path; removed before and after every dump. */
|
|
849
956
|
declare const DEVICE_UI_PATH = "/data/local/tmp/ohosperf_ui.json";
|
|
@@ -872,6 +979,199 @@ declare class UitestCollector implements Collector {
|
|
|
872
979
|
}, layout: SceneLayout): Promise<UiNode[]>;
|
|
873
980
|
}
|
|
874
981
|
|
|
982
|
+
/** Fixed device-side path; removed before and after every capture. */
|
|
983
|
+
declare const DEVICE_SCREENSHOT_PATH = "/data/local/tmp/ohosperf_screen.png";
|
|
984
|
+
/** What a successful capture produced, for `scene.json`. */
|
|
985
|
+
interface ScreenshotCapture {
|
|
986
|
+
readonly width: number;
|
|
987
|
+
readonly height: number;
|
|
988
|
+
readonly bytes: number;
|
|
989
|
+
}
|
|
990
|
+
/**
|
|
991
|
+
* Capture a screenshot into `screenshot.png`.
|
|
992
|
+
*
|
|
993
|
+
* `uitest screenCap -p <path>` writes the PNG on the device and prints
|
|
994
|
+
* `ScreenCap saved to <path>`. The marker is required for the same reason the
|
|
995
|
+
* UI dump requires its own: hdc exits 0 even when the device tool refuses, so
|
|
996
|
+
* an exit code proves nothing.
|
|
997
|
+
*
|
|
998
|
+
* The order mirrors the other collectors — remove the fixed device path, run,
|
|
999
|
+
* require the marker, require a non-empty file, `recv`, then verify. The
|
|
1000
|
+
* verification here is a full decode: a truncated transfer is the failure this
|
|
1001
|
+
* collector exists to catch, and a PNG whose dimensions cannot be read is not a
|
|
1002
|
+
* screenshot. A failed capture never leaves `screenshot.png` behind, so a later
|
|
1003
|
+
* analysis cannot mistake the previous screen for this capture's.
|
|
1004
|
+
*/
|
|
1005
|
+
declare class ScreenshotCollector implements Collector {
|
|
1006
|
+
readonly id = "screenshot";
|
|
1007
|
+
readonly provides: CapabilityId[];
|
|
1008
|
+
collect(hdc: Hdc, target: string, opts: {
|
|
1009
|
+
timeoutMs?: number;
|
|
1010
|
+
}, layout: SceneLayout): Promise<ScreenshotCapture>;
|
|
1011
|
+
}
|
|
1012
|
+
|
|
1013
|
+
/**
|
|
1014
|
+
* UI gesture injection.
|
|
1015
|
+
*
|
|
1016
|
+
* `uitest uiInput` is the device-side injector. Measured on the Mate 60
|
|
1017
|
+
* (OpenHarmony 7.0.0.111) over plain `hdc shell`:
|
|
1018
|
+
*
|
|
1019
|
+
* - a successful injection prints `No Error` on stdout;
|
|
1020
|
+
* - the host exit code is **always 0**, even when the tool refuses the
|
|
1021
|
+
* gesture and exits 1 inside the device shell — so the marker is the only
|
|
1022
|
+
* proof of acceptance;
|
|
1023
|
+
* - a swipe velocity outside 200..40000 prints a warning and silently uses
|
|
1024
|
+
* the default, so the request would not be what actually happened.
|
|
1025
|
+
*
|
|
1026
|
+
* The driver therefore validates everything it can before the shell call and
|
|
1027
|
+
* quotes text as one shell argument. Every text value is single-quoted;
|
|
1028
|
+
* control characters are rejected because they are not typable and would
|
|
1029
|
+
* smuggle separators into the command line.
|
|
1030
|
+
*/
|
|
1031
|
+
|
|
1032
|
+
type Gesture = {
|
|
1033
|
+
readonly action: 'click';
|
|
1034
|
+
readonly x: number;
|
|
1035
|
+
readonly y: number;
|
|
1036
|
+
} | {
|
|
1037
|
+
readonly action: 'swipe';
|
|
1038
|
+
readonly fromX: number;
|
|
1039
|
+
readonly fromY: number;
|
|
1040
|
+
readonly toX: number;
|
|
1041
|
+
readonly toY: number;
|
|
1042
|
+
readonly velocity?: number;
|
|
1043
|
+
} | {
|
|
1044
|
+
readonly action: 'key';
|
|
1045
|
+
readonly key: string | number;
|
|
1046
|
+
} | {
|
|
1047
|
+
readonly action: 'inputText';
|
|
1048
|
+
readonly x: number;
|
|
1049
|
+
readonly y: number;
|
|
1050
|
+
readonly text: string;
|
|
1051
|
+
} | {
|
|
1052
|
+
readonly action: 'text';
|
|
1053
|
+
readonly text: string;
|
|
1054
|
+
};
|
|
1055
|
+
interface GestureResult {
|
|
1056
|
+
/** The gesture as performed, echoed for logs and JSON consumers. */
|
|
1057
|
+
readonly gesture: Gesture;
|
|
1058
|
+
/** The tool's stdout, trimmed (`No Error`, or a warning plus `No Error`). */
|
|
1059
|
+
readonly output: string;
|
|
1060
|
+
}
|
|
1061
|
+
/**
|
|
1062
|
+
* Inject gestures through `uitest uiInput`.
|
|
1063
|
+
*
|
|
1064
|
+
* `perform` takes the transport method it needs rather than the whole `Hdc`,
|
|
1065
|
+
* so a caller (Device) can hand in the shared transport and a test can hand in
|
|
1066
|
+
* a three-line fake.
|
|
1067
|
+
*/
|
|
1068
|
+
declare class GestureDriver {
|
|
1069
|
+
perform(hdc: Pick<Hdc, 'shell'>, target: string, gesture: Gesture): Promise<GestureResult>;
|
|
1070
|
+
}
|
|
1071
|
+
|
|
1072
|
+
/**
|
|
1073
|
+
* The human- and machine-readable description of one captured scene.
|
|
1074
|
+
*
|
|
1075
|
+
* `startedAtNs` is device uptime in nanoseconds (read from `/proc/uptime`), the
|
|
1076
|
+
* same clock base as trace `ts` values — never host `Date.now()`. It is the
|
|
1077
|
+
* start marker the startup analyzer falls back to when `app_startup` is empty.
|
|
1078
|
+
* `capture.startedAtMs` is host wall-clock and exists for humans only.
|
|
1079
|
+
*/
|
|
1080
|
+
interface SceneStepRef {
|
|
1081
|
+
/** 1-based round within a scenario run. */
|
|
1082
|
+
readonly round: number;
|
|
1083
|
+
/** 0-based position of the step in the scenario's `steps` array. */
|
|
1084
|
+
readonly index: number;
|
|
1085
|
+
readonly id: string;
|
|
1086
|
+
}
|
|
1087
|
+
interface SceneMetadata {
|
|
1088
|
+
version: 1;
|
|
1089
|
+
app: {
|
|
1090
|
+
packageName: string;
|
|
1091
|
+
processNames: string[];
|
|
1092
|
+
};
|
|
1093
|
+
pids: number[];
|
|
1094
|
+
deviceId: string;
|
|
1095
|
+
startedAtNs?: number;
|
|
1096
|
+
/**
|
|
1097
|
+
* Present only when the scene was captured by a scenario step. A scene
|
|
1098
|
+
* copied out of a run therefore still says which step produced it, without
|
|
1099
|
+
* needing the run's `steps.json` beside it.
|
|
1100
|
+
*/
|
|
1101
|
+
step?: SceneStepRef;
|
|
1102
|
+
capture?: {
|
|
1103
|
+
startedAtMs: number;
|
|
1104
|
+
durationMs: number;
|
|
1105
|
+
collectors: string[];
|
|
1106
|
+
/**
|
|
1107
|
+
* Present only when a hiperf capture ran. `samples` may be 0: an idle app
|
|
1108
|
+
* yields no samples, which is a real capture, not a missing one.
|
|
1109
|
+
*/
|
|
1110
|
+
hiperf?: {
|
|
1111
|
+
samples: number;
|
|
1112
|
+
/**
|
|
1113
|
+
* Present only when the capture passed a symbol directory. `true` means
|
|
1114
|
+
* symbolization was *requested* — the converter was given `--So_dir` —
|
|
1115
|
+
* not that every frame came back named; a directory missing the app's
|
|
1116
|
+
* libraries still leaves addresses. Absent means the scene did not
|
|
1117
|
+
* record the attempt, which is not the same as "no".
|
|
1118
|
+
*/
|
|
1119
|
+
symbolized?: boolean;
|
|
1120
|
+
};
|
|
1121
|
+
/**
|
|
1122
|
+
* Present only when a hidumper capture ran. `frames` may be 0: a screen
|
|
1123
|
+
* that presented nothing is a measurement, not a missing capture.
|
|
1124
|
+
*/
|
|
1125
|
+
hidumper?: {
|
|
1126
|
+
frames: number;
|
|
1127
|
+
};
|
|
1128
|
+
/**
|
|
1129
|
+
* Present only when a uitest capture ran. `nodes` may be 0: a blank screen
|
|
1130
|
+
* is a measurement, not a missing capture.
|
|
1131
|
+
*/
|
|
1132
|
+
uitest?: {
|
|
1133
|
+
nodes: number;
|
|
1134
|
+
};
|
|
1135
|
+
/**
|
|
1136
|
+
* Present only when a screenshot capture ran. `bytes` is the size of
|
|
1137
|
+
* `screenshot.png`; a capture that produced a zero-byte or undecodable file
|
|
1138
|
+
* is a failure, so the counts here are always positive.
|
|
1139
|
+
*/
|
|
1140
|
+
screenshot?: {
|
|
1141
|
+
width: number;
|
|
1142
|
+
height: number;
|
|
1143
|
+
bytes: number;
|
|
1144
|
+
};
|
|
1145
|
+
/**
|
|
1146
|
+
* Present only when a hilog capture ran. `lines` may be 0 only if the
|
|
1147
|
+
* collector succeeded on an empty stream, which it treats as a failure;
|
|
1148
|
+
* the field records the count the collector reported.
|
|
1149
|
+
*/
|
|
1150
|
+
hilog?: {
|
|
1151
|
+
lines: number;
|
|
1152
|
+
};
|
|
1153
|
+
};
|
|
1154
|
+
}
|
|
1155
|
+
/**
|
|
1156
|
+
* Writes `scene.json` next to the other scene artifacts.
|
|
1157
|
+
*
|
|
1158
|
+
* The scene root is created when needed. The file is pretty-printed with two
|
|
1159
|
+
* spaces and ends with one newline so it is diff-friendly and byte-stable.
|
|
1160
|
+
*/
|
|
1161
|
+
declare function writeSceneMetadata(layout: SceneLayout, meta: SceneMetadata): void;
|
|
1162
|
+
/**
|
|
1163
|
+
* Reads a scene's `scene.json`, or `undefined` when it cannot be trusted.
|
|
1164
|
+
*
|
|
1165
|
+
* A missing file, invalid JSON, a non-object document, a `version` other than
|
|
1166
|
+
* `1`, or a document missing the required fields all yield `undefined`: a
|
|
1167
|
+
* partially valid description would be worse than none. `startedAtNs` is
|
|
1168
|
+
* optional, but a non-positive (including zero) or non-finite value is dropped
|
|
1169
|
+
* from the result (the file itself is never rewritten) so consumers can treat
|
|
1170
|
+
* "no marker" as one case. Uptime 0 addresses the trace origin, not the capture
|
|
1171
|
+
* start, so accepting it would only produce a nonsense startup duration.
|
|
1172
|
+
*/
|
|
1173
|
+
declare function readSceneMetadata(layout: SceneLayout): SceneMetadata | undefined;
|
|
1174
|
+
|
|
875
1175
|
/**
|
|
876
1176
|
* Device probe.
|
|
877
1177
|
*
|
|
@@ -977,10 +1277,40 @@ interface CollectOptions extends TraceCollectOptions {
|
|
|
977
1277
|
events?: readonly string[];
|
|
978
1278
|
callStacks?: boolean;
|
|
979
1279
|
};
|
|
1280
|
+
/**
|
|
1281
|
+
* A host directory of shared objects to symbolize the hiperf capture with.
|
|
1282
|
+
*
|
|
1283
|
+
* Passed to the perf conversion as `--So_dir`, so frames come out named
|
|
1284
|
+
* instead of `file+0xoffset`. Requires `hiperf`: without a perf capture
|
|
1285
|
+
* there is nothing to symbolize, and the request is refused before any
|
|
1286
|
+
* device call rather than silently ignored. The directory must exist on
|
|
1287
|
+
* this host, which is checked here too.
|
|
1288
|
+
*/
|
|
1289
|
+
soDir?: string;
|
|
980
1290
|
/** Also sample the RenderService fps/hitch counters for `durationMs`. */
|
|
981
1291
|
hidumper?: boolean;
|
|
982
1292
|
/** Also dump the on-screen UI tree. */
|
|
983
1293
|
uitest?: boolean;
|
|
1294
|
+
/**
|
|
1295
|
+
* Also capture a screenshot of the whole screen.
|
|
1296
|
+
*
|
|
1297
|
+
* Independent of `uitest`: a screenshot without a tree is a valid capture,
|
|
1298
|
+
* and the UI analyzer reports the half that is missing rather than zeros.
|
|
1299
|
+
*/
|
|
1300
|
+
screenshot?: boolean;
|
|
1301
|
+
/**
|
|
1302
|
+
* Also stream the device's `hilog` for `durationMs`.
|
|
1303
|
+
*
|
|
1304
|
+
* `hilog` is device-wide and needs no app, so this works on an app-less
|
|
1305
|
+
* capture. The raw log lands in `hilog.log`; parsing happens offline.
|
|
1306
|
+
*/
|
|
1307
|
+
hilog?: boolean;
|
|
1308
|
+
/**
|
|
1309
|
+
* Record this capture as one step of a scenario run. Written into
|
|
1310
|
+
* `scene.json`, so the scene names its own step after being copied out of
|
|
1311
|
+
* the run directory.
|
|
1312
|
+
*/
|
|
1313
|
+
step?: SceneStepRef;
|
|
984
1314
|
}
|
|
985
1315
|
interface CollectSession {
|
|
986
1316
|
/** Capture, then convert and open the scene. */
|
|
@@ -996,6 +1326,9 @@ interface DeviceDeps {
|
|
|
996
1326
|
hiperf?: HiperfCollector;
|
|
997
1327
|
hidumper?: HidumperCollector;
|
|
998
1328
|
uitest?: UitestCollector;
|
|
1329
|
+
screenshot?: ScreenshotCollector;
|
|
1330
|
+
hilog?: HilogCollector;
|
|
1331
|
+
gesture?: GestureDriver;
|
|
999
1332
|
}
|
|
1000
1333
|
/**
|
|
1001
1334
|
* A probed device.
|
|
@@ -1026,6 +1359,14 @@ declare class Device {
|
|
|
1026
1359
|
stderr: string;
|
|
1027
1360
|
code: number;
|
|
1028
1361
|
}>;
|
|
1362
|
+
/**
|
|
1363
|
+
* Inject a UI gesture through `uitest uiInput`.
|
|
1364
|
+
*
|
|
1365
|
+
* The capability gate is the same contract `collect` uses: an unavailable
|
|
1366
|
+
* `ui.gesture` throws before any device call, and the message carries the
|
|
1367
|
+
* matrix's reason (`uitest not present on device`).
|
|
1368
|
+
*/
|
|
1369
|
+
gesture(request: Gesture): Promise<GestureResult>;
|
|
1029
1370
|
/**
|
|
1030
1371
|
* Prepare a capture session. The capability gate runs here so a device that
|
|
1031
1372
|
* cannot produce frames fails before any device state is touched.
|
|
@@ -1047,6 +1388,331 @@ declare class Device {
|
|
|
1047
1388
|
*/
|
|
1048
1389
|
declare function connect(opts?: ConnectOptions): Promise<Device>;
|
|
1049
1390
|
|
|
1391
|
+
/**
|
|
1392
|
+
* HarmonyOS emulator lifecycle.
|
|
1393
|
+
*
|
|
1394
|
+
* DevEco Studio ships `Emulator.exe`, which owns the instance directory format,
|
|
1395
|
+
* the image signature check and the QEMU launch. This module drives it rather
|
|
1396
|
+
* than reproducing it: `EmulatorClient` spawns and parses, `EmulatorLifecycle`
|
|
1397
|
+
* proves state transitions with `hdc`.
|
|
1398
|
+
*
|
|
1399
|
+
* Two measured properties shape everything here:
|
|
1400
|
+
*
|
|
1401
|
+
* 1. **The exit code carries no information.** `Unable to start the emulator`,
|
|
1402
|
+
* `Emulator: Unknown option 'bogus'.` and a silently rejected `-create` all
|
|
1403
|
+
* exit 0. Success is proven by re-reading state, never by `$?`.
|
|
1404
|
+
* 2. **`-start` and `-stop` are fire-and-forget.** Both return in well under a
|
|
1405
|
+
* second while the instance is still booting or still shutting down, so a
|
|
1406
|
+
* caller that trusts their output reports the wrong state.
|
|
1407
|
+
*/
|
|
1408
|
+
|
|
1409
|
+
/** One instance as `-list -details` reports it. */
|
|
1410
|
+
interface EmulatorInstance {
|
|
1411
|
+
readonly name: string;
|
|
1412
|
+
readonly running: boolean;
|
|
1413
|
+
/** `os.apiVersion`, e.g. `"24"`. */
|
|
1414
|
+
readonly apiVersion?: string;
|
|
1415
|
+
/** `imageSubPath`, e.g. `system-image/HarmonyOS-6.1.1/phone_all_x86/`. */
|
|
1416
|
+
readonly imageDir?: string;
|
|
1417
|
+
/** Absolute instance directory. */
|
|
1418
|
+
readonly instancePath: string;
|
|
1419
|
+
readonly uuid?: string;
|
|
1420
|
+
/** `os.osVersion`, e.g. `HarmonyOS 6.1.1(24)`. */
|
|
1421
|
+
readonly osVersion?: string;
|
|
1422
|
+
/** The hdc target id; present only when it can be attributed unambiguously. */
|
|
1423
|
+
readonly target?: string;
|
|
1424
|
+
/** Why `target` is absent, when it is absent for a reason other than "not running". */
|
|
1425
|
+
readonly targetReason?: string;
|
|
1426
|
+
}
|
|
1427
|
+
/** One row of `-imageList -downloaded true`. */
|
|
1428
|
+
interface EmulatorImage {
|
|
1429
|
+
readonly deviceType: string;
|
|
1430
|
+
/** `osVersion`, e.g. `"HarmonyOS 6.1.1(24)"`. */
|
|
1431
|
+
readonly osVersion: string;
|
|
1432
|
+
readonly downloaded: boolean;
|
|
1433
|
+
/** `SoftWareVersion`, e.g. `"6.1.0.126"`. */
|
|
1434
|
+
readonly softwareVersion: string;
|
|
1435
|
+
readonly releaseType?: string;
|
|
1436
|
+
}
|
|
1437
|
+
/** What `create` needs; validated by the lifecycle layer before it is spawned. */
|
|
1438
|
+
interface CreateEmulatorRequest {
|
|
1439
|
+
readonly name: string;
|
|
1440
|
+
readonly deviceType: string;
|
|
1441
|
+
readonly osVersion: string;
|
|
1442
|
+
readonly screenProfile?: string;
|
|
1443
|
+
readonly memoryGb?: number;
|
|
1444
|
+
readonly storageGb?: number;
|
|
1445
|
+
}
|
|
1446
|
+
interface EmulatorClientOptions {
|
|
1447
|
+
/** Explicit `Emulator.exe`; checked first by {@link EmulatorClient.resolvePath}. */
|
|
1448
|
+
emulatorPath?: string;
|
|
1449
|
+
/** Environment used both for spawning and for the `OHOS_PERF_EMULATOR`/`PATH` lookup. */
|
|
1450
|
+
env?: Env;
|
|
1451
|
+
/**
|
|
1452
|
+
* Override the built-in install candidate list. Tests pass `[]` so the
|
|
1453
|
+
* search list is exactly the one they assert on.
|
|
1454
|
+
*/
|
|
1455
|
+
commonPaths?: string[];
|
|
1456
|
+
/** `-instancePath` for every command that accepts it. */
|
|
1457
|
+
instancePath?: string;
|
|
1458
|
+
/** `-imageRoot` for every command that accepts it. */
|
|
1459
|
+
imageRoot?: string;
|
|
1460
|
+
/**
|
|
1461
|
+
* Host platform, for the binary name and the install candidate list.
|
|
1462
|
+
* Defaults to `process.platform`; injectable so a test can exercise the
|
|
1463
|
+
* non-Windows branch on any host. Typed as `string` on purpose: `NodeJS`
|
|
1464
|
+
* types are not part of this package's published declarations.
|
|
1465
|
+
*/
|
|
1466
|
+
platform?: string;
|
|
1467
|
+
}
|
|
1468
|
+
/**
|
|
1469
|
+
* The `Emulator.exe` process surface.
|
|
1470
|
+
*
|
|
1471
|
+
* Every method here runs the binary and interprets its output; none of them
|
|
1472
|
+
* decides what a state *means*. That split is what lets the lifecycle layer be
|
|
1473
|
+
* tested with a plain object while this layer is tested against recorded output.
|
|
1474
|
+
*/
|
|
1475
|
+
declare class EmulatorClient {
|
|
1476
|
+
private readonly opts;
|
|
1477
|
+
private readonly env;
|
|
1478
|
+
private readonly platform;
|
|
1479
|
+
private resolvedPath?;
|
|
1480
|
+
private parsedVersion?;
|
|
1481
|
+
private configRoots?;
|
|
1482
|
+
constructor(opts?: EmulatorClientOptions);
|
|
1483
|
+
/**
|
|
1484
|
+
* The instance root, in the spec's discovery order: explicit option, then
|
|
1485
|
+
* `OHOS_PERF_EMULATOR_INSTANCE`, then `.emu_config`'s `emuPath`, then
|
|
1486
|
+
* `%LOCALAPPDATA%\Huawei\Emulator\deployed`.
|
|
1487
|
+
*
|
|
1488
|
+
* `undefined` only when none of those exist — off Windows there is no
|
|
1489
|
+
* `%LOCALAPPDATA%` default, and inventing one would pass the binary a
|
|
1490
|
+
* relative path. The resolved root is always passed explicitly rather than
|
|
1491
|
+
* left to the binary's own discovery, so the argv records where the answer
|
|
1492
|
+
* came from.
|
|
1493
|
+
*/
|
|
1494
|
+
private resolvedInstanceRoot;
|
|
1495
|
+
/** The image root, discovered the same way via `imagePath` and `%LOCALAPPDATA%\Huawei\Sdk`. */
|
|
1496
|
+
private resolvedImageRoot;
|
|
1497
|
+
/** Read `.emu_config` at most once per client. */
|
|
1498
|
+
private emuConfig;
|
|
1499
|
+
/**
|
|
1500
|
+
* Search order: explicit path -> OHOS_PERF_EMULATOR -> common DevEco
|
|
1501
|
+
* installs -> PATH. Throws {@link EmulatorNotFoundError} listing every
|
|
1502
|
+
* candidate in order, so a caller can see exactly what was tried.
|
|
1503
|
+
*/
|
|
1504
|
+
resolvePath(): Promise<string>;
|
|
1505
|
+
/**
|
|
1506
|
+
* Banner version, e.g. `6.1.1.200`. The real binary prints
|
|
1507
|
+
* `HarmonyOS Emulator :6.1.1.200` and exits 0.
|
|
1508
|
+
*/
|
|
1509
|
+
version(): Promise<string>;
|
|
1510
|
+
/**
|
|
1511
|
+
* `-list -details`, parsed and sorted by name.
|
|
1512
|
+
*
|
|
1513
|
+
* `[Empty]` is the real binary's answer when the instance root holds none;
|
|
1514
|
+
* it is success with zero instances, not a parse failure.
|
|
1515
|
+
*/
|
|
1516
|
+
listDetailed(): Promise<EmulatorInstance[]>;
|
|
1517
|
+
/** `-imageList -downloaded true`, parsed and sorted by type then version. */
|
|
1518
|
+
imageList(): Promise<EmulatorImage[]>;
|
|
1519
|
+
/**
|
|
1520
|
+
* `-start <name>`.
|
|
1521
|
+
*
|
|
1522
|
+
* Fire-and-forget by design: the real binary returns in well under a second
|
|
1523
|
+
* and the instance keeps running after it exits, so the caller must poll
|
|
1524
|
+
* {@link listDetailed} for the state change.
|
|
1525
|
+
*/
|
|
1526
|
+
/**
|
|
1527
|
+
* `-start <name>`.
|
|
1528
|
+
*
|
|
1529
|
+
* Measured on 6.1.1.200: a **valid** `-start` does not exit. The process
|
|
1530
|
+
* becomes the emulator (it holds ~1 GB and keeps running), so waiting for
|
|
1531
|
+
* its pipes to close waits forever. An **invalid** one prints `Unable to
|
|
1532
|
+
* start the emulator` and exits 1 in under 100 ms.
|
|
1533
|
+
*
|
|
1534
|
+
* So this settles: it collects output until the child exits or
|
|
1535
|
+
* {@link START_SETTLE_MS} passes, whichever comes first, then drops the
|
|
1536
|
+
* pipes and leaves the child running. The exit code is therefore not a
|
|
1537
|
+
* verdict on success — {@link EmulatorLifecycle.start} proves that by
|
|
1538
|
+
* re-reading state, which is the same rule the rest of this class follows.
|
|
1539
|
+
* Detaching keeps the emulator alive when this process exits.
|
|
1540
|
+
*/
|
|
1541
|
+
startInstance(name: string): Promise<void>;
|
|
1542
|
+
/** `-stop <name>`; fire-and-forget, see {@link startInstance}. */
|
|
1543
|
+
stopInstance(name: string): Promise<void>;
|
|
1544
|
+
/**
|
|
1545
|
+
* `-create`, with no validation.
|
|
1546
|
+
*
|
|
1547
|
+
* The binary silently ignores a bad device type, an unknown OS version or a
|
|
1548
|
+
* name that already exists — it prints nothing and exits 0. Deciding those
|
|
1549
|
+
* is {@link EmulatorLifecycle.create}'s job, before this runs.
|
|
1550
|
+
*/
|
|
1551
|
+
createInstance(req: CreateEmulatorRequest): Promise<void>;
|
|
1552
|
+
/**
|
|
1553
|
+
* Spawn without a shell so install paths with spaces stay one argv element.
|
|
1554
|
+
*
|
|
1555
|
+
* `opts.settleMs` exists for `-start`, which does not exit on success. When
|
|
1556
|
+
* set, the promise resolves once the child exits or the window elapses —
|
|
1557
|
+
* whichever is first — after which the pipes are destroyed and the child is
|
|
1558
|
+
* detached so it survives this process. Output captured so far is returned
|
|
1559
|
+
* with code 0, and failure-line classification still applies, so a fast
|
|
1560
|
+
* rejection is caught either way.
|
|
1561
|
+
*
|
|
1562
|
+
* `detach` is only set alongside `settleMs`: a child that outlives the
|
|
1563
|
+
* caller must not hold the caller's console or pipes open.
|
|
1564
|
+
*/
|
|
1565
|
+
protected spawnProcess(command: string, args: string[], opts?: {
|
|
1566
|
+
settleMs?: number;
|
|
1567
|
+
detach?: boolean;
|
|
1568
|
+
}): Promise<{
|
|
1569
|
+
stdout: string;
|
|
1570
|
+
stderr: string;
|
|
1571
|
+
code: number;
|
|
1572
|
+
}>;
|
|
1573
|
+
/** `-instancePath` when a root was resolved; no flag otherwise. */
|
|
1574
|
+
private instancePathArgs;
|
|
1575
|
+
/** `-imageRoot` when a root was resolved; no flag otherwise. */
|
|
1576
|
+
private imageRootArgs;
|
|
1577
|
+
/** Resolve the binary, spawn, and classify the output. */
|
|
1578
|
+
private run;
|
|
1579
|
+
/**
|
|
1580
|
+
* Classify a completed spawn.
|
|
1581
|
+
*
|
|
1582
|
+
* The exit code is 0 for every failure the binary reports through a failure
|
|
1583
|
+
* line, so a failure line outranks the code: an invalid `-start` prints
|
|
1584
|
+
* `Unable to start the emulator` **and** exits 1, and reporting only
|
|
1585
|
+
* `-start exited 1` would discard the one sentence that says what happened.
|
|
1586
|
+
*
|
|
1587
|
+
* The match is structural (`Emulator: `, `Unable to `) rather than a list of
|
|
1588
|
+
* known sentences: the binary uses its own name as a prefix for argument
|
|
1589
|
+
* errors and `Unable to …` for operational ones, and a future message of
|
|
1590
|
+
* either shape should fail loudly instead of being read as success.
|
|
1591
|
+
*/
|
|
1592
|
+
private assertOk;
|
|
1593
|
+
/** Parse a JSON array, naming the first line of output when it is not one. */
|
|
1594
|
+
private parseJson;
|
|
1595
|
+
}
|
|
1596
|
+
/** The client operations the lifecycle needs; `EmulatorClient` satisfies it structurally. */
|
|
1597
|
+
interface EmulatorBackend {
|
|
1598
|
+
listDetailed(): Promise<EmulatorInstance[]>;
|
|
1599
|
+
imageList(): Promise<EmulatorImage[]>;
|
|
1600
|
+
startInstance(name: string): Promise<void>;
|
|
1601
|
+
stopInstance(name: string): Promise<void>;
|
|
1602
|
+
createInstance(req: CreateEmulatorRequest): Promise<void>;
|
|
1603
|
+
}
|
|
1604
|
+
/** What a successful {@link EmulatorLifecycle.start} reports. */
|
|
1605
|
+
interface EmulatorStartResult {
|
|
1606
|
+
readonly name: string;
|
|
1607
|
+
/** The hdc target id, ready for `collect --target`. */
|
|
1608
|
+
readonly target: string;
|
|
1609
|
+
/** True when the instance was already running before this call. */
|
|
1610
|
+
readonly alreadyRunning: boolean;
|
|
1611
|
+
/** Wall-clock milliseconds this call spent waiting for boot. */
|
|
1612
|
+
readonly waitedMs: number;
|
|
1613
|
+
}
|
|
1614
|
+
/** What a successful {@link EmulatorLifecycle.stop} reports. */
|
|
1615
|
+
interface EmulatorStopResult {
|
|
1616
|
+
readonly name: string;
|
|
1617
|
+
/** False when the instance was not running; nothing was sent to `-stop`. */
|
|
1618
|
+
readonly wasRunning: boolean;
|
|
1619
|
+
}
|
|
1620
|
+
/** The `hdc` operations the lifecycle needs; `Hdc` satisfies it structurally. */
|
|
1621
|
+
interface HdcSlice {
|
|
1622
|
+
listTargets(): Promise<HdcTarget[]>;
|
|
1623
|
+
shell(target: string, cmd: string): Promise<{
|
|
1624
|
+
stdout: string;
|
|
1625
|
+
stderr: string;
|
|
1626
|
+
code: number;
|
|
1627
|
+
}>;
|
|
1628
|
+
}
|
|
1629
|
+
interface EmulatorLifecycleOptions {
|
|
1630
|
+
/** Defaults to a real {@link EmulatorClient}; tests inject a plain object. */
|
|
1631
|
+
client?: EmulatorBackend;
|
|
1632
|
+
/** Defaults to a real `Hdc`; tests inject a plain object. */
|
|
1633
|
+
hdc?: HdcSlice;
|
|
1634
|
+
/** Total budget for `start`, across all three phases. */
|
|
1635
|
+
startTimeoutMs?: number;
|
|
1636
|
+
/** Total budget for `stop`. */
|
|
1637
|
+
stopTimeoutMs?: number;
|
|
1638
|
+
/** Poll interval for every wait. */
|
|
1639
|
+
pollMs?: number;
|
|
1640
|
+
/** Injection point for tests; production leaves it unset. */
|
|
1641
|
+
now?: () => number;
|
|
1642
|
+
}
|
|
1643
|
+
/**
|
|
1644
|
+
* State and waiting, as distinct from spawning and parsing.
|
|
1645
|
+
*
|
|
1646
|
+
* `-start` and `-stop` both return before the state they report has settled,
|
|
1647
|
+
* and `-list -details` is the only authority on it. Every method here re-reads
|
|
1648
|
+
* that state rather than trusting a command's exit or its success line.
|
|
1649
|
+
*/
|
|
1650
|
+
declare class EmulatorLifecycle {
|
|
1651
|
+
private readonly client;
|
|
1652
|
+
private readonly hdc;
|
|
1653
|
+
private readonly startTimeoutMs;
|
|
1654
|
+
private readonly stopTimeoutMs;
|
|
1655
|
+
private readonly pollMs;
|
|
1656
|
+
private readonly now;
|
|
1657
|
+
constructor(opts?: EmulatorLifecycleOptions);
|
|
1658
|
+
/**
|
|
1659
|
+
* Instances with a `target` attached when it can be attributed.
|
|
1660
|
+
*
|
|
1661
|
+
* The port is not knowable from config — `hw.hdc.port` is `notset` by
|
|
1662
|
+
* default, and the same instance has been observed on different ports in
|
|
1663
|
+
* different sessions. So a target is reported only when there is exactly one
|
|
1664
|
+
* running instance and exactly one connected TCP target; guessing would
|
|
1665
|
+
* produce a plausible-looking wrong answer, which is worse than a reason.
|
|
1666
|
+
*/
|
|
1667
|
+
list(): Promise<EmulatorInstance[]>;
|
|
1668
|
+
/**
|
|
1669
|
+
* Start `name` and wait until its guest has finished booting.
|
|
1670
|
+
*
|
|
1671
|
+
* Three phases, one deadline: the instance reports `isRunning`, a new
|
|
1672
|
+
* connected TCP target appears, and `bootevent.boot.completed` turns true.
|
|
1673
|
+
* Each phase has its own timeout message because "it timed out" leaves the
|
|
1674
|
+
* caller unable to tell a slow boot from a broken start.
|
|
1675
|
+
*
|
|
1676
|
+
* A timeout never stops the emulator: a half-booted instance is the evidence
|
|
1677
|
+
* of what went wrong, and the message says how to remove it.
|
|
1678
|
+
*/
|
|
1679
|
+
start(name: string, opts?: {
|
|
1680
|
+
timeoutMs?: number;
|
|
1681
|
+
}): Promise<EmulatorStartResult>;
|
|
1682
|
+
/**
|
|
1683
|
+
* Stop `name` and wait until the instance reports `isRunning: false`.
|
|
1684
|
+
*
|
|
1685
|
+
* The real `-stop` prints `Stop emulator <name> successfully` and returns in
|
|
1686
|
+
* about 140 ms, while the instance keeps reporting `isRunning: true` for
|
|
1687
|
+
* several seconds. Trusting its output would report a stop that has not
|
|
1688
|
+
* happened, so this re-reads state.
|
|
1689
|
+
*/
|
|
1690
|
+
stop(name: string, opts?: {
|
|
1691
|
+
timeoutMs?: number;
|
|
1692
|
+
}): Promise<EmulatorStopResult>;
|
|
1693
|
+
/**
|
|
1694
|
+
* Create an instance, validating before anything is spawned.
|
|
1695
|
+
*
|
|
1696
|
+
* The binary is silent about every rejection measured — a bad device type, an
|
|
1697
|
+
* unknown OS version, a duplicate name and a missing image all print nothing
|
|
1698
|
+
* and exit 0. So the checks here are the only thing between the caller and a
|
|
1699
|
+
* create that did nothing, and the post-create re-read is the only proof that
|
|
1700
|
+
* it did something.
|
|
1701
|
+
*/
|
|
1702
|
+
create(req: CreateEmulatorRequest): Promise<EmulatorInstance>;
|
|
1703
|
+
/**
|
|
1704
|
+
* Poll `attempt` until it returns a value, or the deadline passes.
|
|
1705
|
+
*
|
|
1706
|
+
* The deadline is absolute so one budget covers every phase of `start`;
|
|
1707
|
+
* a per-phase budget would multiply the caller's timeout by three.
|
|
1708
|
+
*
|
|
1709
|
+
* `advice` is the caller's, because the cleanup differs: a start that timed
|
|
1710
|
+
* out left a half-booted instance, while a stop that timed out already ran
|
|
1711
|
+
* the one command that removes it.
|
|
1712
|
+
*/
|
|
1713
|
+
private waitUntil;
|
|
1714
|
+
}
|
|
1715
|
+
|
|
1050
1716
|
/**
|
|
1051
1717
|
* hiprofiler plugin templates.
|
|
1052
1718
|
*
|
|
@@ -1100,68 +1766,613 @@ declare function memoryPlugin(opts?: MemoryPluginOptions): HiprofilerPlugin;
|
|
|
1100
1766
|
declare const PLANE_A_PLUGINS: readonly HiprofilerPlugin[];
|
|
1101
1767
|
|
|
1102
1768
|
/**
|
|
1103
|
-
*
|
|
1769
|
+
* hilog line parsing.
|
|
1104
1770
|
*
|
|
1105
|
-
*
|
|
1106
|
-
*
|
|
1107
|
-
*
|
|
1108
|
-
*
|
|
1771
|
+
* A hilog line is:
|
|
1772
|
+
*
|
|
1773
|
+
* ```
|
|
1774
|
+
* MM-DD HH:MM:SS.mmm PID TID LEVEL DOMAIN/TAG message
|
|
1775
|
+
* ```
|
|
1776
|
+
*
|
|
1777
|
+
* The timestamp carries **no year**. The year comes from the scene's capture
|
|
1778
|
+
* metadata, and a month/day that would place the line after the capture is
|
|
1779
|
+
* read as the previous year: the alternative (this year) invents a future log,
|
|
1780
|
+
* which no real capture can contain.
|
|
1781
|
+
*
|
|
1782
|
+
* A line that does not match is kept as a raw row (`parsed: false`) rather
|
|
1783
|
+
* than dropped. A rule count computed over silently discarded lines is a
|
|
1784
|
+
* number nobody can check.
|
|
1109
1785
|
*/
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
|
|
1113
|
-
|
|
1114
|
-
|
|
1786
|
+
/** The five documented levels, plus whatever character the device printed. */
|
|
1787
|
+
type HilogLevel = 'D' | 'I' | 'W' | 'E' | 'F' | string;
|
|
1788
|
+
/** One log line, parsed or raw. `index` is the file order, 0-based. */
|
|
1789
|
+
interface HilogLine {
|
|
1790
|
+
readonly index: number;
|
|
1791
|
+
/** Nanoseconds since the Unix epoch; `0` on a raw row. */
|
|
1792
|
+
readonly ts: number;
|
|
1793
|
+
readonly level: HilogLevel;
|
|
1794
|
+
readonly pid: number;
|
|
1795
|
+
readonly tid: number;
|
|
1796
|
+
readonly domain: string;
|
|
1797
|
+
readonly tag: string;
|
|
1798
|
+
readonly message: string;
|
|
1799
|
+
readonly parsed: boolean;
|
|
1800
|
+
}
|
|
1801
|
+
/**
|
|
1802
|
+
* Parse one line.
|
|
1803
|
+
*
|
|
1804
|
+
* `year` is the capture year and `captureNs` the capture instant in
|
|
1805
|
+
* nanoseconds — the same clock base as trace `ts` and every query window. A
|
|
1806
|
+
* line later than the capture by more than half a year is moved to `year - 1`,
|
|
1807
|
+
* the only reading that cannot produce a future log from a year-less format.
|
|
1808
|
+
*/
|
|
1809
|
+
declare function parseHilogLine(line: string, year: number, captureNs: number): HilogLine;
|
|
1810
|
+
/**
|
|
1811
|
+
* How to place a year-less timestamp on the timeline.
|
|
1812
|
+
*
|
|
1813
|
+
* `year` comes from `scene.json`'s capture time and is **absent** for a scene
|
|
1814
|
+
* with no descriptor. A raw scene still has a log worth counting, so an absent
|
|
1815
|
+
* year yields raw rows (`parsed: false`, `ts: 0`) rather than a guess: 1970 or
|
|
1816
|
+
* the host clock would be a confident wrong instant, and every `hilog.around`
|
|
1817
|
+
* window built from it would be wrong too.
|
|
1818
|
+
*/
|
|
1819
|
+
interface HilogParseOptions {
|
|
1820
|
+
readonly year?: number;
|
|
1821
|
+
/** The capture instant, ns since epoch. `0` means unknown. */
|
|
1822
|
+
readonly captureNs: number;
|
|
1823
|
+
}
|
|
1824
|
+
/**
|
|
1825
|
+
* Parse a whole log.
|
|
1826
|
+
*
|
|
1827
|
+
* Splits on `\r?\n` and drops exactly one trailing empty element (the file's
|
|
1828
|
+
* final newline), so `lines.count` equals the number of lines a reader sees.
|
|
1829
|
+
* Interior blank lines stay as raw rows.
|
|
1830
|
+
*/
|
|
1831
|
+
declare function parseHilogText(text: string, opts: HilogParseOptions): HilogLine[];
|
|
1832
|
+
|
|
1833
|
+
/** One pattern rule, in the shape HapRay's `hilog.patterns` uses. */
|
|
1834
|
+
interface HilogRule {
|
|
1835
|
+
readonly name: string;
|
|
1836
|
+
readonly regex: string;
|
|
1837
|
+
/**
|
|
1838
|
+
* Which capture groups to extract, 1-based. `0` means the whole match.
|
|
1839
|
+
* Defaults to `[0]`, matching upstream's `groups` default.
|
|
1840
|
+
*/
|
|
1841
|
+
readonly groups?: readonly number[];
|
|
1842
|
+
/**
|
|
1843
|
+
* Either one comparison per extracted group (`['!=4', '>512']`) or one
|
|
1844
|
+
* expression over `$1`, `$2`, … (`'$1 * $2 > $3 * $4'`).
|
|
1845
|
+
*/
|
|
1846
|
+
readonly conditions?: string | readonly string[];
|
|
1847
|
+
/**
|
|
1848
|
+
* `message` (default) matches the log message only, so a rule cannot match
|
|
1849
|
+
* a tag by accident. `line` matches the whole raw line, with `^`/`$`
|
|
1850
|
+
* anchored per line.
|
|
1851
|
+
*/
|
|
1852
|
+
readonly scope?: 'message' | 'line';
|
|
1853
|
+
}
|
|
1854
|
+
/** One rule hit: which rule, which line, and the extracted group values. */
|
|
1855
|
+
interface HilogMatch {
|
|
1856
|
+
readonly ruleName: string;
|
|
1857
|
+
readonly lineIndex: number;
|
|
1858
|
+
readonly groups: readonly string[];
|
|
1859
|
+
}
|
|
1860
|
+
/** A compiled rule: the regex, the condition, and the extraction plan. */
|
|
1861
|
+
interface CompiledRule {
|
|
1862
|
+
readonly name: string;
|
|
1863
|
+
match(line: HilogLine): readonly string[] | undefined;
|
|
1864
|
+
}
|
|
1865
|
+
/**
|
|
1866
|
+
* HapRay's `hilog.patterns`, verbatim from `config.yaml` at `9386e4e`.
|
|
1867
|
+
*
|
|
1868
|
+
* The three `CreatePixelMap` rules share one regex and differ only in their
|
|
1869
|
+
* condition, so a single line can match more than one — upstream counts it
|
|
1870
|
+
* in each, and so does this port.
|
|
1871
|
+
*/
|
|
1872
|
+
declare const DEFAULT_HILOG_RULES: readonly HilogRule[];
|
|
1873
|
+
/**
|
|
1874
|
+
* Compile a rule set, sorted by name.
|
|
1875
|
+
*
|
|
1876
|
+
* Sorting is what makes evaluation order independent of the caller's array:
|
|
1877
|
+
* two rule files with the same rules in different orders produce the same
|
|
1878
|
+
* match list.
|
|
1879
|
+
*/
|
|
1880
|
+
declare function compileRules(rules: readonly HilogRule[]): CompiledRule[];
|
|
1881
|
+
/**
|
|
1882
|
+
* Every match over every line, ordered by `(lineIndex, ruleName)`.
|
|
1883
|
+
*
|
|
1884
|
+
* One rule's failure never stops another: a non-numeric group is a rule
|
|
1885
|
+
* authoring error, so it is thrown rather than swallowed, and the caller
|
|
1886
|
+
* decides whether to report the rule as broken.
|
|
1887
|
+
*/
|
|
1888
|
+
declare function matchRules(rules: readonly CompiledRule[], lines: readonly HilogLine[]): HilogMatch[];
|
|
1889
|
+
|
|
1890
|
+
/**
|
|
1891
|
+
* A decoded image: row-major RGBA, 4 bytes per pixel.
|
|
1892
|
+
*
|
|
1893
|
+
* Alpha is always present after decoding, whatever the source colour type was:
|
|
1894
|
+
* a grey or RGB PNG is expanded to opaque RGBA so every consumer (hashing, the
|
|
1895
|
+
* pixel diff, region marking) handles exactly one layout.
|
|
1896
|
+
*/
|
|
1897
|
+
interface RgbaImage {
|
|
1898
|
+
readonly width: number;
|
|
1899
|
+
readonly height: number;
|
|
1900
|
+
/** Row-major RGBA, 4 bytes per pixel, length = width*height*4. */
|
|
1901
|
+
readonly data: Uint8Array;
|
|
1902
|
+
}
|
|
1903
|
+
/**
|
|
1904
|
+
* Decode an 8-bit, non-interlaced PNG into RGBA.
|
|
1905
|
+
*
|
|
1906
|
+
* Deliberately narrow: the device writes 8-bit RGB/RGBA and nothing else, so
|
|
1907
|
+
* palette, 16-bit and interlaced images are refused by name rather than
|
|
1908
|
+
* half-decoded into a plausible-looking wrong image. The five row filters are
|
|
1909
|
+
* all implemented, because those do appear in real encoders.
|
|
1910
|
+
*
|
|
1911
|
+
* A length mismatch after inflation is the truncated-transfer check: the
|
|
1912
|
+
* expected size is exactly `height * (1 + bytesPerPixel * width)`, and any
|
|
1913
|
+
* other length means the IDAT stream ended early (or was padded). Neither is
|
|
1914
|
+
* a picture, so both fail rather than being resized.
|
|
1915
|
+
*/
|
|
1916
|
+
declare function decodePng(bytes: Uint8Array): RgbaImage;
|
|
1917
|
+
/**
|
|
1918
|
+
* Encode RGBA as an 8-bit RGBA PNG.
|
|
1919
|
+
*
|
|
1920
|
+
* No ancillary chunks are written — no `tIME`, no `tEXt` — so the bytes depend
|
|
1921
|
+
* only on the pixels. That is what lets a marked image be compared byte for
|
|
1922
|
+
* byte across runs (D5).
|
|
1923
|
+
*/
|
|
1924
|
+
declare function encodePng(image: RgbaImage): Uint8Array;
|
|
1925
|
+
|
|
1926
|
+
/** An axis-aligned rectangle in screenshot pixels. */
|
|
1927
|
+
interface Rect {
|
|
1928
|
+
readonly left: number;
|
|
1929
|
+
readonly top: number;
|
|
1930
|
+
readonly right: number;
|
|
1931
|
+
readonly bottom: number;
|
|
1932
|
+
}
|
|
1933
|
+
/**
|
|
1934
|
+
* The result of comparing two screenshots.
|
|
1935
|
+
*
|
|
1936
|
+
* `hamming`/`similarity` answer "is the structure the same" (a 64-bit gradient
|
|
1937
|
+
* hash is insensitive to small colour shifts); `changedRatio` answers "how much
|
|
1938
|
+
* of the picture differs". They can disagree — a solid colour change moves one
|
|
1939
|
+
* and not the other — so both are reported and neither is presented as *the*
|
|
1940
|
+
* answer.
|
|
1941
|
+
*/
|
|
1942
|
+
interface ImageComparison {
|
|
1943
|
+
readonly dhashA: string;
|
|
1944
|
+
readonly dhashB: string;
|
|
1945
|
+
/** 0..64, the bit distance between the two dHashes. */
|
|
1946
|
+
readonly hamming: number;
|
|
1947
|
+
/** `1 - hamming/64`. */
|
|
1948
|
+
readonly similarity: number;
|
|
1949
|
+
/** Fraction of compared pixels whose channels differ by more than `tolerance`. */
|
|
1950
|
+
readonly changedRatio: number;
|
|
1951
|
+
/** The per-channel threshold actually applied (0..255). */
|
|
1952
|
+
readonly tolerance: number;
|
|
1953
|
+
/** The downscaled size the pixel comparison ran at. */
|
|
1954
|
+
readonly comparedWidth: number;
|
|
1955
|
+
readonly comparedHeight: number;
|
|
1956
|
+
}
|
|
1957
|
+
/**
|
|
1958
|
+
* A 64-bit difference hash, as 16 hex characters.
|
|
1959
|
+
*
|
|
1960
|
+
* The image is box-averaged down to 9×8 greyscale and each row's 8 horizontal
|
|
1961
|
+
* gradients become 8 bits (`right > left`). Two identical pictures hash the
|
|
1962
|
+
* same; a uniform picture hashes to all zeros whatever its colour, because
|
|
1963
|
+
* every gradient is zero — a property worth knowing before reading a distance
|
|
1964
|
+
* of 0 as "visually identical".
|
|
1965
|
+
*/
|
|
1966
|
+
declare function dhash(image: RgbaImage): string;
|
|
1967
|
+
/**
|
|
1968
|
+
* Compare two screenshots.
|
|
1969
|
+
*
|
|
1970
|
+
* Refuses different dimensions: `bounds` from the UI tree and the pixels here
|
|
1971
|
+
* are in the same coordinate space, so a cross-resolution comparison would
|
|
1972
|
+
* silently compare different regions. Normalising sizes is a different feature
|
|
1973
|
+
* with its own honesty problem (layout differences would read as pixel
|
|
1974
|
+
* differences), and it is deliberately absent.
|
|
1975
|
+
*/
|
|
1976
|
+
declare function compareImages(a: RgbaImage, b: RgbaImage, opts?: {
|
|
1977
|
+
tolerance?: number;
|
|
1978
|
+
}): ImageComparison;
|
|
1979
|
+
/**
|
|
1980
|
+
* Draw a 1 px red rectangle on each region's edges, returning a new image.
|
|
1981
|
+
*
|
|
1982
|
+
* The rectangle marks the *edges*, not the fill: a filled block would hide the
|
|
1983
|
+
* very pixels the caller is being shown. Regions are clipped to the image, so
|
|
1984
|
+
* a node whose bounds run past the screen still marks its visible part.
|
|
1985
|
+
*/
|
|
1986
|
+
declare function markRegions(image: RgbaImage, regions: readonly Rect[]): RgbaImage;
|
|
1987
|
+
|
|
1988
|
+
/** One node-level difference between two captures. */
|
|
1989
|
+
interface UiTreeDifference {
|
|
1990
|
+
readonly change: 'added' | 'removed' | 'changed';
|
|
1991
|
+
/** Document path, e.g. `0.2.1` — the position in the *later* tree for added
|
|
1992
|
+
* and changed nodes, in the earlier tree for removed ones. */
|
|
1993
|
+
readonly path: string;
|
|
1994
|
+
/** The identity the match used, so a caller can find the node again. */
|
|
1995
|
+
readonly identity: string;
|
|
1996
|
+
readonly type: string;
|
|
1997
|
+
readonly bounds?: {
|
|
1998
|
+
readonly left: number;
|
|
1999
|
+
readonly top: number;
|
|
2000
|
+
readonly right: number;
|
|
2001
|
+
readonly bottom: number;
|
|
1115
2002
|
};
|
|
1116
|
-
|
|
1117
|
-
|
|
1118
|
-
|
|
1119
|
-
|
|
1120
|
-
|
|
1121
|
-
|
|
1122
|
-
|
|
1123
|
-
|
|
1124
|
-
|
|
1125
|
-
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
|
-
|
|
1135
|
-
|
|
1136
|
-
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1140
|
-
|
|
1141
|
-
|
|
1142
|
-
|
|
1143
|
-
|
|
2003
|
+
/** Attribute-level differences; absent for added and removed nodes. */
|
|
2004
|
+
readonly attributes?: Array<{
|
|
2005
|
+
name: string;
|
|
2006
|
+
before: string;
|
|
2007
|
+
after: string;
|
|
2008
|
+
}>;
|
|
2009
|
+
}
|
|
2010
|
+
interface UiTreeDiff {
|
|
2011
|
+
readonly added: UiTreeDifference[];
|
|
2012
|
+
readonly removed: UiTreeDifference[];
|
|
2013
|
+
readonly changed: UiTreeDifference[];
|
|
2014
|
+
/** Matched nodes with no reported difference. */
|
|
2015
|
+
readonly unchanged: number;
|
|
2016
|
+
}
|
|
2017
|
+
/**
|
|
2018
|
+
* Attributes excluded from the comparison.
|
|
2019
|
+
*
|
|
2020
|
+
* HapRay's list, kept for the same reason it exists: these are renderer
|
|
2021
|
+
* internals that change between two captures of an identical screen, so
|
|
2022
|
+
* reporting them would drown a real difference in noise.
|
|
2023
|
+
*/
|
|
2024
|
+
declare const IGNORED_ATTRIBUTES: readonly string[];
|
|
2025
|
+
/**
|
|
2026
|
+
* Geometry differences smaller than this are not differences.
|
|
2027
|
+
*
|
|
2028
|
+
* A node that moved by 3 px between two captures of the same screen is layout
|
|
2029
|
+
* jitter, not a UI change; 5 px is HapRay's measured threshold and the one the
|
|
2030
|
+
* diff reports in its own output.
|
|
2031
|
+
*/
|
|
2032
|
+
declare const GEOMETRY_TOLERANCE_PX = 5;
|
|
2033
|
+
/**
|
|
2034
|
+
* A node's identity for matching.
|
|
2035
|
+
*
|
|
2036
|
+
* `bundleName | type | id | text`, with an empty `id` or `text` omitted. Text
|
|
2037
|
+
* is part of the identity deliberately: a label *is* what that node is, so a
|
|
2038
|
+
* text change reads as one removed node plus one added one rather than a
|
|
2039
|
+
* "changed" node whose meaning is unclear. Matching by identity instead of by
|
|
2040
|
+
* index is what stops one inserted sibling from shifting every later
|
|
2041
|
+
* comparison.
|
|
2042
|
+
*/
|
|
2043
|
+
declare function nodeIdentity(node: UiNode): string;
|
|
2044
|
+
/**
|
|
2045
|
+
* Compare two flattened trees by node identity.
|
|
2046
|
+
*
|
|
2047
|
+
* Children are bucketed by identity and paired in document order within each
|
|
2048
|
+
* bucket, so an insertion consumes one slot instead of shifting the rest. A
|
|
2049
|
+
* node present only on the later side is `added`, only on the earlier side
|
|
2050
|
+
* `removed`, and a matched pair with attribute differences is `changed`.
|
|
2051
|
+
* Output arrays are sorted by path, so the result is byte-stable (D5).
|
|
2052
|
+
*/
|
|
2053
|
+
declare function diffTrees(before: readonly UiNode[], after: readonly UiNode[]): UiTreeDiff;
|
|
2054
|
+
|
|
2055
|
+
/** What one side of the comparison contained, as the page and JSON report it. */
|
|
2056
|
+
interface UiDiffSide {
|
|
2057
|
+
readonly dir: string;
|
|
2058
|
+
/** `scene.json`'s capture start, copied as an input; absent without metadata. */
|
|
2059
|
+
readonly startedAtMs?: number;
|
|
2060
|
+
readonly screenshot: {
|
|
2061
|
+
readonly width: number;
|
|
2062
|
+
readonly height: number;
|
|
2063
|
+
} | null;
|
|
2064
|
+
readonly tree: {
|
|
2065
|
+
readonly nodes: number;
|
|
2066
|
+
} | null;
|
|
2067
|
+
}
|
|
2068
|
+
/**
|
|
2069
|
+
* The result of comparing two captured scenes.
|
|
2070
|
+
*
|
|
2071
|
+
* `image` and `tree` are `null` only when neither side has that artifact — a
|
|
2072
|
+
* comparison of two tree-only captures has no image, and saying so in
|
|
2073
|
+
* `degraded` is more useful than failing. A missing artifact on *one* side is
|
|
2074
|
+
* an error, because a missing screen is not an unchanged screen.
|
|
2075
|
+
*/
|
|
2076
|
+
interface UiDiff {
|
|
2077
|
+
readonly schemaVersion: 1;
|
|
2078
|
+
readonly a: UiDiffSide;
|
|
2079
|
+
readonly b: UiDiffSide;
|
|
2080
|
+
readonly image: ImageComparison | null;
|
|
2081
|
+
readonly tree: UiTreeDiff | null;
|
|
2082
|
+
readonly regions: Rect[];
|
|
2083
|
+
readonly degraded: string[];
|
|
2084
|
+
}
|
|
2085
|
+
/** Where `compareSceneDirs` writes its artifacts. */
|
|
2086
|
+
interface UiCompareOptions {
|
|
2087
|
+
/** Output directory for the four files. */
|
|
2088
|
+
readonly outDir: string;
|
|
2089
|
+
/** Per-channel pixel tolerance, 0..255; defaults to the image diff's 8. */
|
|
2090
|
+
readonly tolerance?: number;
|
|
2091
|
+
}
|
|
2092
|
+
/**
|
|
2093
|
+
* Compare two scene directories by UI tree and screenshot.
|
|
2094
|
+
*
|
|
2095
|
+
* Both sides are read before anything is written, so a failure leaves no
|
|
2096
|
+
* half-written bundle. `ui-diff.json` carries no clock of its own — the two
|
|
2097
|
+
* `capture.startedAtMs` values are copied from each side's `scene.json` — so
|
|
2098
|
+
* two runs over the same inputs are byte-identical (D5), as are the marked
|
|
2099
|
+
* PNGs, whose encoder writes no ancillary chunks.
|
|
2100
|
+
*/
|
|
2101
|
+
declare function compareSceneDirs(a: string, b: string, opts: UiCompareOptions): Promise<UiDiff>;
|
|
2102
|
+
/** The artifact file names, for a caller reporting what was written. */
|
|
2103
|
+
declare const UI_DIFF_FILES: readonly string[];
|
|
2104
|
+
|
|
2105
|
+
/**
|
|
2106
|
+
* Render the UI comparison page.
|
|
2107
|
+
*
|
|
2108
|
+
* Self-contained except for the two marked PNGs beside it: no scripts, no
|
|
2109
|
+
* network access, inline CSS. The tolerance and the geometry threshold are
|
|
2110
|
+
* stated in the page, so a reader can tell how much difference the numbers
|
|
2111
|
+
* already forgive without opening the docs.
|
|
2112
|
+
*/
|
|
2113
|
+
declare function renderUiDiffHtml(diff: UiDiff): string;
|
|
2114
|
+
|
|
2115
|
+
/**
|
|
2116
|
+
* Declarative scenario documents.
|
|
2117
|
+
*
|
|
2118
|
+
* A scenario is data, not code: ordered steps, each with a setup phase that
|
|
2119
|
+
* runs before the capture, an action phase that runs inside it, and a cleanup
|
|
2120
|
+
* phase that runs after. This module is the whole trust boundary — every
|
|
2121
|
+
* field is checked here, before a device is touched, and an unknown key is an
|
|
2122
|
+
* error rather than a silently ignored typo.
|
|
2123
|
+
*
|
|
2124
|
+
* The validator is hand-written on purpose. A schema library would be the
|
|
2125
|
+
* first runtime dependency in `@ohos-perf/core`, and the property that makes
|
|
2126
|
+
* this file worth reading — every rejection names the JSON path that caused
|
|
2127
|
+
* it — is the one a generic validator reports least clearly.
|
|
2128
|
+
*/
|
|
2129
|
+
|
|
2130
|
+
/** One thing a step does. `wait` and `marker` touch no device. */
|
|
2131
|
+
type ScenarioAction = {
|
|
2132
|
+
readonly kind: 'launch';
|
|
2133
|
+
readonly ability: string;
|
|
2134
|
+
} | {
|
|
2135
|
+
readonly kind: 'forceStop';
|
|
2136
|
+
} | {
|
|
2137
|
+
readonly kind: 'click';
|
|
2138
|
+
readonly x: number;
|
|
2139
|
+
readonly y: number;
|
|
2140
|
+
} | {
|
|
2141
|
+
readonly kind: 'swipe';
|
|
2142
|
+
readonly fromX: number;
|
|
2143
|
+
readonly fromY: number;
|
|
2144
|
+
readonly toX: number;
|
|
2145
|
+
readonly toY: number;
|
|
2146
|
+
readonly velocity?: number;
|
|
2147
|
+
} | {
|
|
2148
|
+
readonly kind: 'key';
|
|
2149
|
+
readonly key: string | number;
|
|
2150
|
+
} | {
|
|
2151
|
+
readonly kind: 'text';
|
|
2152
|
+
readonly text: string;
|
|
2153
|
+
} | {
|
|
2154
|
+
readonly kind: 'inputText';
|
|
2155
|
+
readonly x: number;
|
|
2156
|
+
readonly y: number;
|
|
2157
|
+
readonly text: string;
|
|
2158
|
+
} | {
|
|
2159
|
+
readonly kind: 'wait';
|
|
2160
|
+
readonly ms: number;
|
|
2161
|
+
} | {
|
|
2162
|
+
readonly kind: 'marker';
|
|
2163
|
+
readonly name: string;
|
|
2164
|
+
};
|
|
2165
|
+
/** The collectors a step may ask for, by the name `Device.collect` understands. */
|
|
2166
|
+
declare const COLLECTOR_NAMES: readonly ["hitrace", "hiprofiler", "procfs", "hiperf", "hidumper", "uitest", "hilog"];
|
|
2167
|
+
type CollectorName = (typeof COLLECTOR_NAMES)[number];
|
|
2168
|
+
interface StepCapture {
|
|
2169
|
+
readonly durationMs: number;
|
|
2170
|
+
readonly collectors: readonly CollectorName[];
|
|
2171
|
+
readonly hiprofiler?: {
|
|
2172
|
+
readonly plugins: readonly HiprofilerPluginName[];
|
|
1144
2173
|
};
|
|
2174
|
+
readonly hiperf?: {
|
|
2175
|
+
readonly frequency?: number;
|
|
2176
|
+
};
|
|
2177
|
+
}
|
|
2178
|
+
interface ScenarioStep {
|
|
2179
|
+
readonly id: string;
|
|
2180
|
+
readonly name: string;
|
|
2181
|
+
readonly setup: readonly ScenarioAction[];
|
|
2182
|
+
readonly actions: readonly ScenarioAction[];
|
|
2183
|
+
readonly cleanup: readonly ScenarioAction[];
|
|
2184
|
+
readonly capture: StepCapture;
|
|
2185
|
+
}
|
|
2186
|
+
interface Scenario {
|
|
2187
|
+
readonly version: 1;
|
|
2188
|
+
readonly name: string;
|
|
2189
|
+
readonly description?: string;
|
|
2190
|
+
readonly app: string;
|
|
2191
|
+
readonly rounds: number;
|
|
2192
|
+
readonly steps: readonly ScenarioStep[];
|
|
1145
2193
|
}
|
|
1146
2194
|
/**
|
|
1147
|
-
*
|
|
2195
|
+
* Parse and validate a scenario document.
|
|
1148
2196
|
*
|
|
1149
|
-
*
|
|
1150
|
-
*
|
|
2197
|
+
* Throws `OhosPerfError` with code `SCENARIO_BAD_INPUT` for a document-level
|
|
2198
|
+
* problem (invalid JSON, wrong version, unknown key, missing field) and
|
|
2199
|
+
* `SCENARIO_BAD_STEP` for one inside a step. Both name the JSON path.
|
|
1151
2200
|
*/
|
|
1152
|
-
declare function
|
|
2201
|
+
declare function parseScenario(text: string): Scenario;
|
|
2202
|
+
|
|
1153
2203
|
/**
|
|
1154
|
-
*
|
|
2204
|
+
* Executing one scenario action against a device.
|
|
1155
2205
|
*
|
|
1156
|
-
*
|
|
1157
|
-
*
|
|
1158
|
-
*
|
|
1159
|
-
*
|
|
1160
|
-
*
|
|
1161
|
-
*
|
|
1162
|
-
*
|
|
2206
|
+
* The split with the runner is deliberate: this module performs exactly one
|
|
2207
|
+
* action and throws when it fails, while the runner owns the record — when it
|
|
2208
|
+
* happened, whether the step survived it, and what the trace says. That keeps
|
|
2209
|
+
* "did it work" in one place and "what do we remember about it" in another.
|
|
2210
|
+
*
|
|
2211
|
+
* Quoting lives in `GestureDriver`, not here: it already knows that the device
|
|
2212
|
+
* shell needs `'…'` and that a quote inside a text argument must be escaped.
|
|
2213
|
+
* Quoting again here would send the quote characters to the device.
|
|
1163
2214
|
*/
|
|
1164
|
-
|
|
2215
|
+
|
|
2216
|
+
/** The device surface actions need. `Device` satisfies it structurally. */
|
|
2217
|
+
interface ActionDevice {
|
|
2218
|
+
readonly id: string;
|
|
2219
|
+
shell(cmd: string): Promise<{
|
|
2220
|
+
stdout: string;
|
|
2221
|
+
stderr: string;
|
|
2222
|
+
code: number;
|
|
2223
|
+
}>;
|
|
2224
|
+
gesture(g: Gesture): Promise<GestureResult>;
|
|
2225
|
+
}
|
|
2226
|
+
/**
|
|
2227
|
+
* Perform one action and return what the device said.
|
|
2228
|
+
*
|
|
2229
|
+
* `launch` and `forceStop` use the scenario's app; a `wait` sleeps without a
|
|
2230
|
+
* device call. A `marker` is refused here — the runner records markers with a
|
|
2231
|
+
* device-uptime instant, and having two layers able to "execute" one would
|
|
2232
|
+
* let them disagree about whether it happened.
|
|
2233
|
+
*/
|
|
2234
|
+
declare function executeAction(device: ActionDevice, app: string, action: ScenarioAction): Promise<{
|
|
2235
|
+
output?: string;
|
|
2236
|
+
}>;
|
|
2237
|
+
|
|
2238
|
+
/**
|
|
2239
|
+
* The scenario runner: ordered steps, one capture window each.
|
|
2240
|
+
*
|
|
2241
|
+
* The shape that matters is the phase order. `setup` runs before the capture
|
|
2242
|
+
* so the state you want to measure is already on screen; `actions` run
|
|
2243
|
+
* *inside* the window so the gesture that causes the work is in the trace;
|
|
2244
|
+
* `cleanup` runs after, always. HapRay's DSL parses setup and cleanup and
|
|
2245
|
+
* never executes them — executing all three is why this exists.
|
|
2246
|
+
*
|
|
2247
|
+
* Nothing here analyzes. A step directory is a scene, so `ohos-perf analyze`,
|
|
2248
|
+
* `report` and `query` apply to it unchanged.
|
|
2249
|
+
*/
|
|
2250
|
+
|
|
2251
|
+
/** One action's outcome, as `steps.json` records it. */
|
|
2252
|
+
interface ActionOutcome {
|
|
2253
|
+
readonly action: ScenarioAction;
|
|
2254
|
+
/** Device uptime in ns, read immediately before the action; absent when the read failed. */
|
|
2255
|
+
readonly atNs?: number;
|
|
2256
|
+
/** Host clock at the action, ms. */
|
|
2257
|
+
readonly atMs: number;
|
|
2258
|
+
readonly ok: boolean;
|
|
2259
|
+
readonly output?: string;
|
|
2260
|
+
readonly error?: string;
|
|
2261
|
+
}
|
|
2262
|
+
interface RunStepResult {
|
|
2263
|
+
readonly round: number;
|
|
2264
|
+
readonly index: number;
|
|
2265
|
+
readonly id: string;
|
|
2266
|
+
readonly name: string;
|
|
2267
|
+
readonly status: 'ok' | 'failed';
|
|
2268
|
+
/** Present only when a scene exists on disk. */
|
|
2269
|
+
readonly sceneDir?: string;
|
|
2270
|
+
readonly startedAtMs: number;
|
|
2271
|
+
readonly durationMs: number;
|
|
2272
|
+
readonly actions: readonly ActionOutcome[];
|
|
2273
|
+
readonly error?: string;
|
|
2274
|
+
}
|
|
2275
|
+
interface RunResult {
|
|
2276
|
+
readonly scenario: string;
|
|
2277
|
+
readonly app: string;
|
|
2278
|
+
readonly device: {
|
|
2279
|
+
id: string;
|
|
2280
|
+
kind: string;
|
|
2281
|
+
};
|
|
2282
|
+
readonly rounds: number;
|
|
2283
|
+
readonly status: 'completed' | 'failed';
|
|
2284
|
+
readonly steps: readonly RunStepResult[];
|
|
2285
|
+
readonly startedAtMs: number;
|
|
2286
|
+
readonly durationMs: number;
|
|
2287
|
+
readonly pids: {
|
|
2288
|
+
pids: readonly number[];
|
|
2289
|
+
processNames: readonly string[];
|
|
2290
|
+
};
|
|
2291
|
+
/** Absent when the device would not report one. Never a fabricated `0.0.0`. */
|
|
2292
|
+
readonly appVersion?: string;
|
|
2293
|
+
}
|
|
2294
|
+
/** The collect request one step turns into. Mirrors `Device.collect`. */
|
|
2295
|
+
interface RunnerCollectOptions {
|
|
2296
|
+
app: string;
|
|
2297
|
+
durationMs: number;
|
|
2298
|
+
sceneRoot: string;
|
|
2299
|
+
step: SceneStepRef;
|
|
2300
|
+
procfs?: boolean;
|
|
2301
|
+
hiprofiler?: {
|
|
2302
|
+
plugins: readonly HiprofilerPluginName[];
|
|
2303
|
+
};
|
|
2304
|
+
hiperf?: {
|
|
2305
|
+
frequency?: number;
|
|
2306
|
+
};
|
|
2307
|
+
hidumper?: boolean;
|
|
2308
|
+
uitest?: boolean;
|
|
2309
|
+
hilog?: boolean;
|
|
2310
|
+
}
|
|
2311
|
+
/** The device surface the runner needs. `Device` satisfies it structurally. */
|
|
2312
|
+
interface RunnerDevice {
|
|
2313
|
+
readonly id: string;
|
|
2314
|
+
readonly kind: string;
|
|
2315
|
+
shell(cmd: string): Promise<{
|
|
2316
|
+
stdout: string;
|
|
2317
|
+
stderr: string;
|
|
2318
|
+
code: number;
|
|
2319
|
+
}>;
|
|
2320
|
+
gesture(g: Gesture): Promise<GestureResult>;
|
|
2321
|
+
collect(opts: RunnerCollectOptions): Promise<{
|
|
2322
|
+
ingest(): Promise<{
|
|
2323
|
+
close(): void;
|
|
2324
|
+
}>;
|
|
2325
|
+
}>;
|
|
2326
|
+
}
|
|
2327
|
+
interface RunOptions {
|
|
2328
|
+
readonly outDir: string;
|
|
2329
|
+
/** Overrides the scenario's own `rounds` when set. */
|
|
2330
|
+
readonly rounds?: number;
|
|
2331
|
+
/** Step ids to run; order in the scenario wins. */
|
|
2332
|
+
readonly only?: readonly string[];
|
|
2333
|
+
/** Continue after a failed step instead of stopping. */
|
|
2334
|
+
readonly keepGoing?: boolean;
|
|
2335
|
+
/** Injected clock, for tests. */
|
|
2336
|
+
readonly now?: () => number;
|
|
2337
|
+
}
|
|
2338
|
+
/**
|
|
2339
|
+
* Run a scenario: every selected (round, step) pair, one scene each.
|
|
2340
|
+
*
|
|
2341
|
+
* The returned result is what `steps.json` records; the files are written
|
|
2342
|
+
* before returning, on the success and the failure path alike, so a run that
|
|
2343
|
+
* stopped at step 2 still says what step 1 produced.
|
|
2344
|
+
*/
|
|
2345
|
+
declare class ScenarioRunner {
|
|
2346
|
+
private readonly device;
|
|
2347
|
+
private readonly opts;
|
|
2348
|
+
private readonly now;
|
|
2349
|
+
constructor(device: RunnerDevice, opts: RunOptions);
|
|
2350
|
+
run(scenario: Scenario): Promise<RunResult>;
|
|
2351
|
+
/**
|
|
2352
|
+
* The steps to run, in scenario order.
|
|
2353
|
+
*
|
|
2354
|
+
* `--only` is a filter, not an ordering: typing `scroll,open` still runs
|
|
2355
|
+
* `open` first, because a step may depend on the state a previous one left.
|
|
2356
|
+
*/
|
|
2357
|
+
private selectedSteps;
|
|
2358
|
+
private runStep;
|
|
2359
|
+
/**
|
|
2360
|
+
* Perform one action and record it; never throws.
|
|
2361
|
+
*
|
|
2362
|
+
* A `marker` is recorded here, not executed: it is an annotation with a
|
|
2363
|
+
* device-uptime instant — the thing that lets a later query line a tap up
|
|
2364
|
+
* with a trace row — and there is no trace event behind it. Recording it in
|
|
2365
|
+
* the runner is what keeps "it happened" in the same place as "when".
|
|
2366
|
+
*/
|
|
2367
|
+
private perform;
|
|
2368
|
+
}
|
|
2369
|
+
/**
|
|
2370
|
+
* Write `testInfo.json`, `steps.json` and `pids.json` into a run directory.
|
|
2371
|
+
*
|
|
2372
|
+
* Pretty-printed with two spaces and one trailing newline, like `scene.json`,
|
|
2373
|
+
* so a run is diff-friendly and byte-stable apart from its clock fields.
|
|
2374
|
+
*/
|
|
2375
|
+
declare function writeRunFiles(outDir: string, result: RunResult): void;
|
|
1165
2376
|
|
|
1166
2377
|
/**
|
|
1167
2378
|
* Frame status as stored in `frame_slice.flag`.
|
|
@@ -1677,19 +2888,28 @@ declare class CallstackQuery {
|
|
|
1677
2888
|
* quotes or a `--` comment is matched as text. The result is capped by
|
|
1678
2889
|
* `opts.limit` (default {@link DEFAULT_MATCH_LIMIT}), and `opts.range`
|
|
1679
2890
|
* restricts `ts` inclusively.
|
|
2891
|
+
*
|
|
2892
|
+
* `opts.ipids` restricts the result to rows emitted by a thread of one of
|
|
2893
|
+
* those processes. **An empty array matches nothing** — an empty app
|
|
2894
|
+
* identity means no process was identified, and widening to device-wide is
|
|
2895
|
+
* the attribution bug `MemoryMeasureAnalyzer` guards against. `undefined`
|
|
2896
|
+
* leaves the query unscoped.
|
|
1680
2897
|
*/
|
|
1681
2898
|
matching(pattern: string, opts?: {
|
|
1682
2899
|
range?: TimeRange;
|
|
1683
2900
|
limit?: number;
|
|
2901
|
+
ipids?: readonly number[];
|
|
1684
2902
|
}): CallstackEvent[];
|
|
1685
2903
|
/**
|
|
1686
2904
|
* Rows `matching()` would return without its `opts.limit` cap.
|
|
1687
2905
|
*
|
|
1688
2906
|
* Uses the same `WHERE` as `matching()`, so the pair can report a true
|
|
1689
|
-
* match count while the fetched rows stay bounded.
|
|
2907
|
+
* match count while the fetched rows stay bounded. An empty `opts.ipids`
|
|
2908
|
+
* counts zero, for the same reason `matching()` returns nothing.
|
|
1690
2909
|
*/
|
|
1691
2910
|
countMatching(pattern: string, opts?: {
|
|
1692
2911
|
range?: TimeRange;
|
|
2912
|
+
ipids?: readonly number[];
|
|
1693
2913
|
}): number;
|
|
1694
2914
|
/**
|
|
1695
2915
|
* Callstack rows with their arguments resolved through `args` + `data_dict`.
|
|
@@ -1740,6 +2960,58 @@ interface PerfCallchain {
|
|
|
1740
2960
|
callchainId: number;
|
|
1741
2961
|
functions: PerfFunction[];
|
|
1742
2962
|
}
|
|
2963
|
+
/**
|
|
2964
|
+
* Sample weight attributed to one leaf symbol.
|
|
2965
|
+
*
|
|
2966
|
+
* `event_count` is attributed to the deepest frame of the sample's callchain
|
|
2967
|
+
* (the "self" cost), so rows answer "which function was executing when the
|
|
2968
|
+
* sample was taken". A chain whose deepest frame has an empty symbol is not
|
|
2969
|
+
* attributable and contributes no row.
|
|
2970
|
+
*/
|
|
2971
|
+
interface PerfLeafAttribution {
|
|
2972
|
+
symbol: string;
|
|
2973
|
+
filePath: string;
|
|
2974
|
+
samples: number;
|
|
2975
|
+
/** True when `symbol` is a `file+0xoffset` reference, not a name. */
|
|
2976
|
+
unresolved: boolean;
|
|
2977
|
+
}
|
|
2978
|
+
/**
|
|
2979
|
+
* One row of summed sample weight per `(symbol, filePath, unresolved)`.
|
|
2980
|
+
*
|
|
2981
|
+
* This is the population {@link PerfQuery.leafAttribution} returns, plus the
|
|
2982
|
+
* frames no symbol resolves at all, so the rows sum to the window's weight.
|
|
2983
|
+
* `unresolved` separates "the recorder had no symbol" from "the lookup
|
|
2984
|
+
* missed": a `libfoo.so+0x1cce24` symbol is honest, and counting it as
|
|
2985
|
+
* resolved would make the numbers read better than the capture is.
|
|
2986
|
+
*/
|
|
2987
|
+
interface SymbolStat {
|
|
2988
|
+
symbol: string;
|
|
2989
|
+
filePath: string;
|
|
2990
|
+
samples: number;
|
|
2991
|
+
unresolved: boolean;
|
|
2992
|
+
}
|
|
2993
|
+
/**
|
|
2994
|
+
* True when a resolved symbol is a `file+0xoffset` reference or empty.
|
|
2995
|
+
*
|
|
2996
|
+
* The converter writes `libfoo.so+0x1cce24` when it has no symbol for an
|
|
2997
|
+
* address, so the text is honest but unnamed. A space means the text is a
|
|
2998
|
+
* sentence or a demangled signature, never that form. The file path is never
|
|
2999
|
+
* part of the test: an unresolved frame still names the library it ran in,
|
|
3000
|
+
* which is what makes the evidence actionable.
|
|
3001
|
+
*/
|
|
3002
|
+
declare function isUnresolvedSymbol(symbol: string): boolean;
|
|
3003
|
+
/**
|
|
3004
|
+
* One folded stack, in the format `flamegraph.pl` and every flamegraph viewer
|
|
3005
|
+
* understands: `a;b;c` with `samples` samples ending at `c`.
|
|
3006
|
+
*/
|
|
3007
|
+
interface FoldedStack {
|
|
3008
|
+
/** Semicolon-joined symbol path, root first. */
|
|
3009
|
+
stack: string;
|
|
3010
|
+
/** The last symbol on the stack — the frame the samples were taken in. */
|
|
3011
|
+
leaf: string;
|
|
3012
|
+
/** Summed `event_count` of every sample folded into this stack. */
|
|
3013
|
+
samples: number;
|
|
3014
|
+
}
|
|
1743
3015
|
/**
|
|
1744
3016
|
* Typed accessor over the optional `perf_*` tables.
|
|
1745
3017
|
*
|
|
@@ -1753,6 +3025,14 @@ declare class PerfQuery {
|
|
|
1753
3025
|
constructor(db: QueryHandle);
|
|
1754
3026
|
/** True when `perf_sample` exists and contains at least one row. */
|
|
1755
3027
|
hasSamples(): boolean;
|
|
3028
|
+
/**
|
|
3029
|
+
* True when `perf_files` exists, so a frame can carry a symbol at all.
|
|
3030
|
+
*
|
|
3031
|
+
* A capture without it has no symbol table to resolve against: every frame
|
|
3032
|
+
* is unnamed for that reason, not because its callchain was truncated. The
|
|
3033
|
+
* distinction matters to the wording a reader gets.
|
|
3034
|
+
*/
|
|
3035
|
+
hasSymbolTable(): boolean;
|
|
1756
3036
|
/**
|
|
1757
3037
|
* `perf_thread` rows whose `process_id` is one of `pids`, ordered by `id`.
|
|
1758
3038
|
*
|
|
@@ -1760,6 +3040,27 @@ declare class PerfQuery {
|
|
|
1760
3040
|
* table returns `[]`.
|
|
1761
3041
|
*/
|
|
1762
3042
|
threads(pids: number[]): PerfThread[];
|
|
3043
|
+
/**
|
|
3044
|
+
* The `thread_id`s of the threads named `threadName` in one of `pids`.
|
|
3045
|
+
*
|
|
3046
|
+
* Exists for the GC analyzer, which attributes samples to `OS_GC_Thread`.
|
|
3047
|
+
* Ordering is by `thread_id` so the result is byte-stable (D5); an empty
|
|
3048
|
+
* `pids` or an absent `perf_thread` table returns `[]`.
|
|
3049
|
+
*/
|
|
3050
|
+
threadIdsNamed(pids: readonly number[], threadName: string): number[];
|
|
3051
|
+
/**
|
|
3052
|
+
* The summed weight of the samples recorded by `threadIds`.
|
|
3053
|
+
*
|
|
3054
|
+
* `perf_sample.event_count` is the sample's weight — the number of events
|
|
3055
|
+
* the sample stands for — not 1. Summing rows instead of this column makes
|
|
3056
|
+
* every share computed from it wrong by the sampling period. `threadIds`
|
|
3057
|
+
* omitted sums the whole database; an empty array returns 0.
|
|
3058
|
+
*
|
|
3059
|
+
* `range` restricts the sum to samples whose `timestamp_trace` falls inside
|
|
3060
|
+
* it, which is what a windowed share needs: summing the whole table while the
|
|
3061
|
+
* stacks are windowed makes the share describe a different population.
|
|
3062
|
+
*/
|
|
3063
|
+
eventCount(threadIds?: readonly number[], range?: TimeRange): number;
|
|
1763
3064
|
/**
|
|
1764
3065
|
* Samples of `threadIds` whose `timestamp_trace` is in `[startNs, endNs]`.
|
|
1765
3066
|
*
|
|
@@ -1773,20 +3074,219 @@ declare class PerfQuery {
|
|
|
1773
3074
|
* Mirrors HapRay's `_query_callchains_batch`: per thread at most the first
|
|
1774
3075
|
* 50 distinct `callchain_id`s (in chain-id order) are considered and at most
|
|
1775
3076
|
* `maxChainsPerThread` (default 20) non-empty chains are returned. Frames
|
|
1776
|
-
* are ordered by `depth`;
|
|
1777
|
-
* `(file_id, serial_id)`
|
|
1778
|
-
*
|
|
1779
|
-
*
|
|
3077
|
+
* are ordered by `depth`; a symbol resolves through the exact
|
|
3078
|
+
* `(file_id, symbol_id → serial_id)` row of `perf_files`, then through the
|
|
3079
|
+
* `data_dict` text for `perf_callchain.name`, and never from a neighbouring
|
|
3080
|
+
* row of the same file. The file path still resolves from `file_id` alone,
|
|
3081
|
+
* so an unresolved frame names the library it ran in.
|
|
1780
3082
|
*
|
|
1781
3083
|
* If `perf_callchain` or `perf_files` is absent there is nothing to return,
|
|
1782
3084
|
* so the result is `[]` (HapRay does the same).
|
|
1783
3085
|
*/
|
|
1784
3086
|
callchains(threadIds: number[], range: TimeRange, maxChainsPerThread?: number): PerfCallchain[];
|
|
1785
|
-
|
|
1786
|
-
|
|
1787
|
-
|
|
1788
|
-
|
|
1789
|
-
|
|
3087
|
+
/**
|
|
3088
|
+
* Folds every sample of `threadIds` in `range` into semicolon-joined stacks.
|
|
3089
|
+
*
|
|
3090
|
+
* Deliberately **not** built on {@link callchains}: that method caps at 50
|
|
3091
|
+
* chain ids and 20 chains per thread (HapRay's UI budget), which would
|
|
3092
|
+
* silently drop samples from an aggregate. This reads every distinct
|
|
3093
|
+
* `callchain_id` the samples reference and weights each by `event_count` —
|
|
3094
|
+
* the sample's weight, not 1 row.
|
|
3095
|
+
*
|
|
3096
|
+
* Stacks are sorted by `samples` descending then `stack` ascending, so equal
|
|
3097
|
+
* weights never fall back to row order, and sliced to `top` — omit `top` to
|
|
3098
|
+
* get every distinct stack, which is what a count of stacks needs. A chain
|
|
3099
|
+
* with no frames contributes nothing. An empty `threadIds`, a missing
|
|
3100
|
+
* `perf_callchain`/`perf_files`, or no samples in range yields `[]`.
|
|
3101
|
+
*/
|
|
3102
|
+
foldedStacks(threadIds: readonly number[], range: TimeRange, top?: number): FoldedStack[];
|
|
3103
|
+
/**
|
|
3104
|
+
* Attributes each sample's weight to the deepest frame of its callchain.
|
|
3105
|
+
*
|
|
3106
|
+
* This is the "self cost" table a hotspot list needs, as opposed to
|
|
3107
|
+
* {@link foldedStacks}, which preserves the whole stack. Rows are sorted by
|
|
3108
|
+
* `samples` descending, then symbol, then filePath, so equal weights never
|
|
3109
|
+
* fall back to row order (D5). A chain with no frames or with an empty leaf
|
|
3110
|
+
* symbol contributes nothing; an empty `threadIds` or a missing
|
|
3111
|
+
* `perf_sample`/`perf_callchain`/`perf_files` returns `[]`.
|
|
3112
|
+
*/
|
|
3113
|
+
leafAttribution(threadIds: readonly number[], range: TimeRange): PerfLeafAttribution[];
|
|
3114
|
+
/**
|
|
3115
|
+
* Summed weight per `(symbol, filePath, unresolved)` over the window.
|
|
3116
|
+
*
|
|
3117
|
+
* This is the typed form of HapRay's `symbol_statistics` table, and the same
|
|
3118
|
+
* population {@link leafAttribution} reports — plus the frames no symbol
|
|
3119
|
+
* resolves at all, which `leafAttribution` drops. Keeping them here is what
|
|
3120
|
+
* makes the rows sum to {@link eventCount} exactly, so a caller can check
|
|
3121
|
+
* that no weight went missing.
|
|
3122
|
+
*
|
|
3123
|
+
* A chain with no frames still holds weight: a truncated conversion or a
|
|
3124
|
+
* dropped kernel chain leaves `perf_sample` rows whose `callchain_id` names
|
|
3125
|
+
* nothing. So does a sample the recorder could not unwind at all, whose
|
|
3126
|
+
* `callchain_id` is NULL — `eventCount` counts that weight too. Both land in
|
|
3127
|
+
* the unresolved `('', '')` row rather than vanishing from the identity.
|
|
3128
|
+
*/
|
|
3129
|
+
symbolStats(threadIds: readonly number[], range: TimeRange): SymbolStat[];
|
|
3130
|
+
/**
|
|
3131
|
+
* The unresolved subset of {@link symbolStats}: frames the recorder could
|
|
3132
|
+
* not name.
|
|
3133
|
+
*
|
|
3134
|
+
* A subset, not an addition — the weights are already inside
|
|
3135
|
+
* `symbolStats`, so a caller must not add the two populations together.
|
|
3136
|
+
*/
|
|
3137
|
+
unresolvedSymbols(threadIds: readonly number[], range: TimeRange): SymbolStat[];
|
|
3138
|
+
/**
|
|
3139
|
+
* Summed `event_count` per `callchain_id` for the threads and range.
|
|
3140
|
+
*
|
|
3141
|
+
* Shared by {@link foldedStacks} and {@link leafAttribution} so both weight
|
|
3142
|
+
* samples identically. `callchain_id IS NULL` rows are omitted; the map is
|
|
3143
|
+
* ordered by the caller.
|
|
3144
|
+
*/
|
|
3145
|
+
private chainWeights;
|
|
3146
|
+
/**
|
|
3147
|
+
* Weight of the samples in the window that recorded no call chain at all.
|
|
3148
|
+
*
|
|
3149
|
+
* `callchain_id` is NULL when the recorder could not unwind — the sample is
|
|
3150
|
+
* still real, and {@link eventCount} counts it. {@link chainWeights} cannot
|
|
3151
|
+
* carry it (there is no chain id to key on), so {@link symbolStats} adds it
|
|
3152
|
+
* to the unresolved `('', '')` row explicitly; without that the documented
|
|
3153
|
+
* identity would be false by exactly this weight.
|
|
3154
|
+
*/
|
|
3155
|
+
private nullChainWeight;
|
|
3156
|
+
/**
|
|
3157
|
+
* Resolves each chain id to its frames, ordered by `depth`.
|
|
3158
|
+
*
|
|
3159
|
+
* A symbol comes from the exact `(file_id, symbol_id → serial_id)` row of
|
|
3160
|
+
* `perf_files`; when that row is missing or names nothing, from the
|
|
3161
|
+
* `data_dict` text for `perf_callchain.name`; and when the column holds text
|
|
3162
|
+
* rather than an id (a hand-built database), from that text. A frame whose
|
|
3163
|
+
* `name` is a dangling id gets `''` — the recorder had no symbol, and
|
|
3164
|
+
* repeating the number would claim a name. A missing `perf_callchain` or
|
|
3165
|
+
* `perf_files` yields an empty map (nothing can be resolved).
|
|
3166
|
+
*/
|
|
3167
|
+
private chainFunctions;
|
|
3168
|
+
/**
|
|
3169
|
+
* The `data_dict` text for the `name` ids these frames carry.
|
|
3170
|
+
*
|
|
3171
|
+
* Optional table: a hand-built database may omit it, and then every frame
|
|
3172
|
+
* keeps its raw `name` column. Loaded once per call, ordered by id so the
|
|
3173
|
+
* query itself is deterministic.
|
|
3174
|
+
*/
|
|
3175
|
+
private loadDataDict;
|
|
3176
|
+
private hasTable;
|
|
3177
|
+
}
|
|
3178
|
+
|
|
3179
|
+
/**
|
|
3180
|
+
* One `native_hook` row with camelCase field names.
|
|
3181
|
+
*
|
|
3182
|
+
* `event_type` is alloc for `'AllocEvent'`/`'MmapEvent'`/`0`, free for
|
|
3183
|
+
* `'FreeEvent'`/`'MunmapEvent'`/`1`, and anything else is neither. `null` means
|
|
3184
|
+
* the column itself was NULL, which is not an allocation: the direction is
|
|
3185
|
+
* unknown, so it stays `null` and the pairing layer counts it as `other`.
|
|
3186
|
+
* `heapSize` is a magnitude: the stored sign carries no meaning, the pairing
|
|
3187
|
+
* layer applies the direction. `allHeapSize` and `currentSizeDur` are read for
|
|
3188
|
+
* callers but are never interpreted — their semantics are undocumented upstream.
|
|
3189
|
+
*/
|
|
3190
|
+
interface NativeHookEvent {
|
|
3191
|
+
id: number;
|
|
3192
|
+
callchainId: number;
|
|
3193
|
+
ipid: number;
|
|
3194
|
+
/** `process.pid` resolved through `ipid`; the number space an app is known by. */
|
|
3195
|
+
pid: number;
|
|
3196
|
+
itid: number;
|
|
3197
|
+
eventType: number | string | null;
|
|
3198
|
+
subTypeId: number;
|
|
3199
|
+
startTs: number;
|
|
3200
|
+
endTs: number;
|
|
3201
|
+
dur: number;
|
|
3202
|
+
/** Heap address; `0` means the column was NULL, so the block cannot be freed. */
|
|
3203
|
+
addr: number;
|
|
3204
|
+
heapSize: number;
|
|
3205
|
+
allHeapSize: number;
|
|
3206
|
+
currentSizeDur: number;
|
|
3207
|
+
lastLibId: number;
|
|
3208
|
+
lastSymbolId: number;
|
|
3209
|
+
}
|
|
3210
|
+
/** One frame of a native callchain, ordered by `depth`. */
|
|
3211
|
+
interface NativeHookFrame {
|
|
3212
|
+
id: number;
|
|
3213
|
+
callchainId: number;
|
|
3214
|
+
depth: number;
|
|
3215
|
+
ip: number;
|
|
3216
|
+
symbolId: number;
|
|
3217
|
+
fileId: number;
|
|
3218
|
+
offset: number;
|
|
3219
|
+
symbolOffset: number;
|
|
3220
|
+
vaddr: number;
|
|
3221
|
+
}
|
|
3222
|
+
/**
|
|
3223
|
+
* One `native_hook_statistic` row: a pre-aggregated alloc/free pair per
|
|
3224
|
+
* callchain, with no per-allocation timestamp, thread or address.
|
|
3225
|
+
*/
|
|
3226
|
+
interface NativeHookStatistic {
|
|
3227
|
+
id: number;
|
|
3228
|
+
callchainId: number;
|
|
3229
|
+
ipid: number;
|
|
3230
|
+
ts: number;
|
|
3231
|
+
type: number | string;
|
|
3232
|
+
subTypeId: number;
|
|
3233
|
+
applyCount: number;
|
|
3234
|
+
releaseCount: number;
|
|
3235
|
+
applySize: number;
|
|
3236
|
+
releaseSize: number;
|
|
3237
|
+
lastLibId: number;
|
|
3238
|
+
lastSymbolId: number;
|
|
3239
|
+
}
|
|
3240
|
+
/**
|
|
3241
|
+
* Typed, batched access to the `native_hook*` tables.
|
|
3242
|
+
*
|
|
3243
|
+
* The tables exist only when a capture ran `hiprofiler` with the `nativehook`
|
|
3244
|
+
* plugin, so every accessor checks `sqlite_master` first and returns
|
|
3245
|
+
* `[]`/`false`/an empty map instead of letting SQLite throw `no such table`.
|
|
3246
|
+
* That is what lets the analyzer report a degraded proxy with a reason rather
|
|
3247
|
+
* than crash on a plain hitrace capture.
|
|
3248
|
+
*
|
|
3249
|
+
* `events` joins `process` on `ipid` and filters on `process.pid`, which is the
|
|
3250
|
+
* same number space the rest of the package resolves an app to.
|
|
3251
|
+
*/
|
|
3252
|
+
declare class NativeHookQuery {
|
|
3253
|
+
private readonly db;
|
|
3254
|
+
constructor(db: QueryHandle);
|
|
3255
|
+
/** True when `native_hook` exists and holds at least one row. */
|
|
3256
|
+
hasData(): boolean;
|
|
3257
|
+
/** True when `native_hook_statistic` exists and holds at least one row. */
|
|
3258
|
+
hasStatistics(): boolean;
|
|
3259
|
+
/**
|
|
3260
|
+
* App events ordered by `(start_ts, id)`, optionally inside an inclusive
|
|
3261
|
+
* `range` on `start_ts`.
|
|
3262
|
+
*
|
|
3263
|
+
* The `(start_ts, id)` tie-break is ours; upstream orders by timestamp alone,
|
|
3264
|
+
* which makes a capture with equal timestamps depend on row order.
|
|
3265
|
+
*
|
|
3266
|
+
* `DISTINCT` on the event columns collapses the duplicate rows a repeated
|
|
3267
|
+
* `process.ipid` would produce: a merged trace can carry two `process` rows
|
|
3268
|
+
* with the same ipid, and a plain join then returns each event once per row,
|
|
3269
|
+
* doubling every byte. `p.pid` is selected from the same ipid group, so the
|
|
3270
|
+
* duplicate rows are identical.
|
|
3271
|
+
*/
|
|
3272
|
+
events(pids: readonly number[], range?: TimeRange): NativeHookEvent[];
|
|
3273
|
+
/** Frames of `callchainIds`, ordered by `(callchain_id, depth, id)`. */
|
|
3274
|
+
frames(callchainIds: readonly number[]): Map<number, NativeHookFrame[]>;
|
|
3275
|
+
/**
|
|
3276
|
+
* Statistics rows for the app, ordered by `(ts, id)`.
|
|
3277
|
+
*
|
|
3278
|
+
* `DISTINCT` and the `process` guard mirror {@link events} for the same two
|
|
3279
|
+
* reasons: a repeated ipid must not multiply rows, and a missing join table
|
|
3280
|
+
* must degrade rather than throw.
|
|
3281
|
+
*/
|
|
3282
|
+
statistics(pids: readonly number[]): NativeHookStatistic[];
|
|
3283
|
+
/** `data_dict` text for `ids`; ids absent from the table are simply missing. */
|
|
3284
|
+
dataDict(ids: readonly number[]): Map<number, string>;
|
|
3285
|
+
private hasTable;
|
|
3286
|
+
}
|
|
3287
|
+
|
|
3288
|
+
/**
|
|
3289
|
+
* One binder-related `callstack` row with its arguments resolved.
|
|
1790
3290
|
*
|
|
1791
3291
|
* `args` is keyed by the `data_dict` text for `args.key`. A value becomes a
|
|
1792
3292
|
* string when `args.datatype = 1` and the value is present in `data_dict`;
|
|
@@ -1861,7 +3361,7 @@ declare class StartupQuery {
|
|
|
1861
3361
|
private hasTable;
|
|
1862
3362
|
}
|
|
1863
3363
|
|
|
1864
|
-
type EvidenceKind = 'no_data' | 'jank' | 'empty_frame' | 'vsync_anomaly' | 'fps_baseline' | 'degraded_capability' | 'fault_pattern' | 'binder_hotspot' | 'thread_redundancy' | 'memory_growth' | 'startup';
|
|
3364
|
+
type EvidenceKind = 'no_data' | 'jank' | 'frame_load' | 'empty_frame' | 'vsync_anomaly' | 'fps_baseline' | 'degraded_capability' | 'fault_pattern' | 'binder_hotspot' | 'thread_redundancy' | 'memory_growth' | 'native_memory' | 'hilog_match' | 'gc_pressure' | 'rs_skip' | 'startup' | 'ui_tree' | 'tech_stack' | 'duplicate_asset' | 'oversized_asset' | 'symbol_stats' | 'unresolved_symbol';
|
|
1865
3365
|
/**
|
|
1866
3366
|
* A follow-up query an agent can issue to drill into an evidence item.
|
|
1867
3367
|
*
|
|
@@ -1885,9 +3385,23 @@ interface Evidence {
|
|
|
1885
3385
|
thread?: string;
|
|
1886
3386
|
frameNo?: number;
|
|
1887
3387
|
pid?: number;
|
|
3388
|
+
/**
|
|
3389
|
+
* The rule a `hilog_match` item reports. It is part of the subject rather
|
|
3390
|
+
* than a signal because two rules firing on one log are two findings, and
|
|
3391
|
+
* the subject is what the id and the human-readable line describe.
|
|
3392
|
+
*/
|
|
3393
|
+
rule?: string;
|
|
1888
3394
|
};
|
|
1889
3395
|
window: TimeRange;
|
|
1890
|
-
|
|
3396
|
+
/**
|
|
3397
|
+
* The measured facts behind the finding.
|
|
3398
|
+
*
|
|
3399
|
+
* Scalars are the common case; a `hilog_match` item carries its sample
|
|
3400
|
+
* messages as a list, which the renderers stringify the same way they do a
|
|
3401
|
+
* number. Lists are always ordered by the analyzer, so output stays
|
|
3402
|
+
* byte-stable.
|
|
3403
|
+
*/
|
|
3404
|
+
signals: Record<string, number | string | readonly string[]>;
|
|
1891
3405
|
explain: string;
|
|
1892
3406
|
drillDown: DrillDownHandle[];
|
|
1893
3407
|
}
|
|
@@ -1908,9 +3422,11 @@ declare function evidence(input: Omit<Evidence, 'id'> & {
|
|
|
1908
3422
|
|
|
1909
3423
|
/**
|
|
1910
3424
|
* Unit of a metric value. `none` is for dimensionless values such as rates,
|
|
1911
|
-
* ratios expressed as plain numbers, or identifiers.
|
|
3425
|
+
* ratios expressed as plain numbers, or identifiers. `hash` is a computed
|
|
3426
|
+
* fingerprint (a dHash), not a measurement: it is a string, and comparing two
|
|
3427
|
+
* of them is a separate operation from comparing numbers.
|
|
1912
3428
|
*/
|
|
1913
|
-
type MetricUnit = 'ms' | 'fps' | '%' | 'count' | 'bytes' | 'none';
|
|
3429
|
+
type MetricUnit = 'ms' | 'fps' | '%' | 'count' | 'bytes' | 'none' | 'hash';
|
|
1914
3430
|
/**
|
|
1915
3431
|
* Where a metric came from.
|
|
1916
3432
|
*
|
|
@@ -2001,6 +3517,36 @@ interface AnalyzeContext {
|
|
|
2001
3517
|
procfs?: ProcfsSample[];
|
|
2002
3518
|
/** RenderService counter snapshots; present only when a hidumper capture ran. */
|
|
2003
3519
|
hidumper?: HidumperCapture;
|
|
3520
|
+
/**
|
|
3521
|
+
* The scene's parsed hilog rows. Absent when the scene carries no
|
|
3522
|
+
* `hilog.log`; the analyzer degrades with a reason rather than reporting
|
|
3523
|
+
* zero matches for a capture that never logged.
|
|
3524
|
+
*/
|
|
3525
|
+
hilog?: HilogLine[];
|
|
3526
|
+
/**
|
|
3527
|
+
* The rule set to evaluate. Defaults to HapRay's ported rules, so a capture
|
|
3528
|
+
* with no user configuration still produces HapRay's numbers.
|
|
3529
|
+
*/
|
|
3530
|
+
hilogRules?: readonly HilogRule[];
|
|
3531
|
+
/**
|
|
3532
|
+
* The scene's flattened UI tree, when it carried a `ui.json`. The `ui`
|
|
3533
|
+
* analyzer decides from what it is given rather than declaring `ui.tree` as a
|
|
3534
|
+
* requirement: a scene can carry a dump captured on a different device, and a
|
|
3535
|
+
* missing artifact is a degradation with a reason, not a skipped analyzer.
|
|
3536
|
+
*/
|
|
3537
|
+
ui?: readonly UiNode[];
|
|
3538
|
+
/**
|
|
3539
|
+
* The scene's decoded screenshot, when it carried a `screenshot.png`. Decoded
|
|
3540
|
+
* by the caller so the analyzer performs no IO; a decode failure reaches it
|
|
3541
|
+
* as an absent field plus a reason.
|
|
3542
|
+
*/
|
|
3543
|
+
screenshot?: RgbaImage;
|
|
3544
|
+
/**
|
|
3545
|
+
* Why a `screenshot.png` that exists could not be decoded. Present only when
|
|
3546
|
+
* the file was there and the decoder refused it, so the image half degrades
|
|
3547
|
+
* with the decoder's own message instead of claiming no capture happened.
|
|
3548
|
+
*/
|
|
3549
|
+
screenshotError?: string;
|
|
2004
3550
|
metadata?: SceneMetadata;
|
|
2005
3551
|
app: AppIdentity;
|
|
2006
3552
|
window: TimeRange;
|
|
@@ -2221,12 +3767,27 @@ interface QueryContext {
|
|
|
2221
3767
|
readonly db: QueryHandle;
|
|
2222
3768
|
readonly app: AppIdentity;
|
|
2223
3769
|
readonly caps: CapabilityMatrix;
|
|
3770
|
+
/**
|
|
3771
|
+
* The scene's second handle, holding the perf tables when the capture
|
|
3772
|
+
* included `--hiperf`. A scene that carries `perf.data` converts it into
|
|
3773
|
+
* `perf.db`, so `perf_sample` / `perf_thread` / `perf_callchain` are **not**
|
|
3774
|
+
* in `db`; a query that reads them through `db` alone returns nothing on a
|
|
3775
|
+
* real capture. Absent means the scene has no perf capture, and every
|
|
3776
|
+
* `frame.load.*` query returns `[]`.
|
|
3777
|
+
*/
|
|
3778
|
+
readonly perfDb?: QueryHandle;
|
|
2224
3779
|
/**
|
|
2225
3780
|
* The scene's flattened UI tree, when the capture included a `uitest`
|
|
2226
3781
|
* dump. Absent means the scene has no `ui.json`; `ui.get` then returns no
|
|
2227
3782
|
* rows rather than failing.
|
|
2228
3783
|
*/
|
|
2229
3784
|
readonly uiTree?: readonly UiNode[];
|
|
3785
|
+
/**
|
|
3786
|
+
* The scene's parsed hilog rows, when the capture included `--hilog`. Absent
|
|
3787
|
+
* means the scene has no `hilog.log`; every `hilog.*` query then returns no
|
|
3788
|
+
* rows rather than failing, and the analyzer reports a degraded proxy.
|
|
3789
|
+
*/
|
|
3790
|
+
readonly hilog?: readonly HilogLine[];
|
|
2230
3791
|
}
|
|
2231
3792
|
/** One argument a query accepts, for `ohos-perf tools` and validation. */
|
|
2232
3793
|
interface QueryArgument {
|
|
@@ -2359,6 +3920,140 @@ declare class FrameAnalyzer implements Analyzer {
|
|
|
2359
3920
|
run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
|
|
2360
3921
|
}
|
|
2361
3922
|
|
|
3923
|
+
/** One app thread's share of a frame's sampled-event load. */
|
|
3924
|
+
interface FrameLoadThread {
|
|
3925
|
+
threadId: number;
|
|
3926
|
+
threadName: string;
|
|
3927
|
+
/** Summed `event_count` inside the frame window. */
|
|
3928
|
+
samples: number;
|
|
3929
|
+
}
|
|
3930
|
+
/** Sampled-event weight attributed to one file path. */
|
|
3931
|
+
interface PerfFileAttribution {
|
|
3932
|
+
filePath: string;
|
|
3933
|
+
samples: number;
|
|
3934
|
+
}
|
|
3935
|
+
/** The setup a caller hands {@link FrameLoadIndex.build}. */
|
|
3936
|
+
interface FrameLoadIndexInput {
|
|
3937
|
+
perf: PerfQuery;
|
|
3938
|
+
/** App process ids (`process.pid`), matching `perf_thread.process_id`. */
|
|
3939
|
+
pids: readonly number[];
|
|
3940
|
+
/** The range to read samples for; frame windows must fall inside it. */
|
|
3941
|
+
range: TimeRange;
|
|
3942
|
+
}
|
|
3943
|
+
/**
|
|
3944
|
+
* One batched read of `perf_sample` that answers per-frame load queries.
|
|
3945
|
+
*
|
|
3946
|
+
* Reading the samples once and bucketing in memory is what makes a
|
|
3947
|
+
* per-frame join affordable: issuing one `SUM` per frame does a table scan
|
|
3948
|
+
* per frame, and HapRay's batch path solves the same problem the same way.
|
|
3949
|
+
*
|
|
3950
|
+
* The window is the frame's own **inclusive** `[ts, ts + dur]`; `dur <= 0`
|
|
3951
|
+
* collapses it to the point `[ts, ts]`, so a sample exactly at `ts` counts.
|
|
3952
|
+
* Only threads whose `perf_thread.process_id` is one of the app pids are
|
|
3953
|
+
* included; samples from other processes never contribute.
|
|
3954
|
+
*
|
|
3955
|
+
* ## Overlap
|
|
3956
|
+
*
|
|
3957
|
+
* `load()` is a per-frame window aggregate. When two app frames overlap in
|
|
3958
|
+
* time, the same sample contributes to both frame loads — matching HapRay's
|
|
3959
|
+
* batch path — so summing frame loads can exceed {@link spanWeight}, the
|
|
3960
|
+
* unique sample weight read for the whole range. Callers that need a share of
|
|
3961
|
+
* the app's total work should use `spanWeight`; callers that need a frame's
|
|
3962
|
+
* own cost use `load`.
|
|
3963
|
+
*/
|
|
3964
|
+
declare class FrameLoadIndex {
|
|
3965
|
+
private readonly threads;
|
|
3966
|
+
/** `perf_sample` rows read (not the summed weight). */
|
|
3967
|
+
readonly sampleRows: number;
|
|
3968
|
+
/** Distinct app thread ids in `perf_thread`. */
|
|
3969
|
+
readonly threadCount: number;
|
|
3970
|
+
/** Summed `event_count` of every sample read, without frame overlap. */
|
|
3971
|
+
readonly spanWeight: number;
|
|
3972
|
+
private constructor();
|
|
3973
|
+
/**
|
|
3974
|
+
* Reads app-thread samples for `range`.
|
|
3975
|
+
*
|
|
3976
|
+
* Returns `undefined` when there is nothing to measure: no `perf_sample`
|
|
3977
|
+
* rows, no `perf_thread` rows for the app pids, or no samples inside the
|
|
3978
|
+
* range. Callers turn that into a degraded result with a reason rather than
|
|
3979
|
+
* reporting zeros.
|
|
3980
|
+
*/
|
|
3981
|
+
static build(input: FrameLoadIndexInput): FrameLoadIndex | undefined;
|
|
3982
|
+
/** Summed sampled-event weight of every app thread inside the frame window. */
|
|
3983
|
+
load(frame: Pick<Frame, 'ts' | 'dur'>): number;
|
|
3984
|
+
/**
|
|
3985
|
+
* Splits a frame window by app thread.
|
|
3986
|
+
*
|
|
3987
|
+
* Only positive-weight threads are returned, sorted by `samples` descending
|
|
3988
|
+
* then `threadId` ascending, so equal weights never depend on row order.
|
|
3989
|
+
*/
|
|
3990
|
+
threadLoads(frame: Pick<Frame, 'ts' | 'dur'>): FrameLoadThread[];
|
|
3991
|
+
}
|
|
3992
|
+
/**
|
|
3993
|
+
* Per-frame sampled-event load for the app's rendered actual frames.
|
|
3994
|
+
*
|
|
3995
|
+
* ## What a load is
|
|
3996
|
+
*
|
|
3997
|
+
* The summed `perf_sample.event_count` of every app-process thread whose
|
|
3998
|
+
* `timestamp_trace` falls inside the frame's own inclusive
|
|
3999
|
+
* `[ts, ts + dur]`. `event_count` is sample weight; it is not an instruction
|
|
4000
|
+
* count, CPU time or power.
|
|
4001
|
+
*
|
|
4002
|
+
* Frames from several app processes can overlap in time (ui and render in one
|
|
4003
|
+
* vsync period), so a sample contributes to each frame that contains it.
|
|
4004
|
+
* `frame.load.total` is therefore the sum of per-frame loads and can exceed
|
|
4005
|
+
* `frame.load.span.weight`, the unique weight read for the whole span.
|
|
4006
|
+
*
|
|
4007
|
+
* Only **rendered** app actual frames (`type = 0`, `flag !== 2`) feed the
|
|
4008
|
+
* summary and the top list: expect frames are predictions, and empty frames
|
|
4009
|
+
* are measured by the empty-frame analyzer.
|
|
4010
|
+
*
|
|
4011
|
+
* ## Degraded cases
|
|
4012
|
+
*
|
|
4013
|
+
* No app process, no perf samples, no app threads, or samples that exist but
|
|
4014
|
+
* never land inside a frame window all yield one `frame.load.degraded` proxy
|
|
4015
|
+
* with a reason. The last case matters most: it usually means the frame and
|
|
4016
|
+
* perf tables use different timestamp bases, and exact zeros would read as a
|
|
4017
|
+
* workload-free app.
|
|
4018
|
+
*/
|
|
4019
|
+
declare class FrameLoadAnalyzer implements Analyzer {
|
|
4020
|
+
readonly id = "frame-load";
|
|
4021
|
+
readonly requires: CapabilityId[];
|
|
4022
|
+
run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
|
|
4023
|
+
}
|
|
4024
|
+
|
|
4025
|
+
/** One tumbling FPS window. */
|
|
4026
|
+
interface FpsWindow {
|
|
4027
|
+
startNs: number;
|
|
4028
|
+
endNs: number;
|
|
4029
|
+
/** Rendered frames whose `ts` falls in `[startNs, endNs)`. */
|
|
4030
|
+
frames: number;
|
|
4031
|
+
fps: number;
|
|
4032
|
+
}
|
|
4033
|
+
/**
|
|
4034
|
+
* Tiles rendered frames into fixed-width FPS windows.
|
|
4035
|
+
*
|
|
4036
|
+
* HapRay's FPS path uses `FPS_WINDOW_SIZE_MS = 1000`; this reproduces the
|
|
4037
|
+
* definition without its vsync-group iteration order, which walks frames
|
|
4038
|
+
* group-by-group rather than chronologically. Frames are therefore sorted by
|
|
4039
|
+
* `(ts, id)` first, and a frame exactly on a boundary belongs to the next
|
|
4040
|
+
* window.
|
|
4041
|
+
*
|
|
4042
|
+
* Every window is exactly `windowMs` long, including the last one: a capture
|
|
4043
|
+
* that ends mid-second reports its final window over the full second, which
|
|
4044
|
+
* under-reports that window. This is the standard tumbling-window artifact
|
|
4045
|
+
* and matches upstream, so `frame.fps.window.*` stays comparable to HapRay.
|
|
4046
|
+
*
|
|
4047
|
+
* Idle gaps longer than one window produce explicit `frames: 0` windows; that
|
|
4048
|
+
* is the observable "the UI stopped drawing" signal, not noise to collapse.
|
|
4049
|
+
*
|
|
4050
|
+
* Only actual rendered frames count: `type = 1` rows are predictions and
|
|
4051
|
+
* `flag = 2` rows drew nothing. Duplicate frame ids are counted once.
|
|
4052
|
+
*
|
|
4053
|
+
* An empty input, or a non-positive `windowMs`, returns `[]`.
|
|
4054
|
+
*/
|
|
4055
|
+
declare function computeFpsWindows(frames: readonly Frame[], windowMs?: number): FpsWindow[];
|
|
4056
|
+
|
|
2362
4057
|
/**
|
|
2363
4058
|
* HapRay's fault-tree payload, with the exact nesting and key names of
|
|
2364
4059
|
* `fault_tree_analyzer.py:34-60`.
|
|
@@ -2574,6 +4269,190 @@ declare class MemoryMeasureAnalyzer implements Analyzer {
|
|
|
2574
4269
|
run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
|
|
2575
4270
|
}
|
|
2576
4271
|
|
|
4272
|
+
/** What an event does to the running total. */
|
|
4273
|
+
type NativeEventKind = 'alloc' | 'free' | 'other';
|
|
4274
|
+
/**
|
|
4275
|
+
* Classifies `native_hook.event_type`.
|
|
4276
|
+
*
|
|
4277
|
+
* The column is numeric on the recorded traces but upstream compares it to
|
|
4278
|
+
* strings, so both forms are accepted. `null` — the column was NULL — and
|
|
4279
|
+
* anything else unrecognised is `other`: it is counted, but it must not move
|
|
4280
|
+
* the total in either direction.
|
|
4281
|
+
*/
|
|
4282
|
+
declare function nativeEventKind(eventType: number | string | null): NativeEventKind;
|
|
4283
|
+
/** One allocation still live at a given instant. */
|
|
4284
|
+
interface ActiveAlloc {
|
|
4285
|
+
addr: number;
|
|
4286
|
+
/** Remaining bytes; a partial free leaves a smaller size. */
|
|
4287
|
+
size: number;
|
|
4288
|
+
pid: number;
|
|
4289
|
+
tid: number;
|
|
4290
|
+
/** `0` means the event carried no callchain, so the block is unattributable. */
|
|
4291
|
+
callchainId: number;
|
|
4292
|
+
relativeNs: number;
|
|
4293
|
+
}
|
|
4294
|
+
/** Everything one replay of the events establishes. */
|
|
4295
|
+
interface NativeMemoryResult {
|
|
4296
|
+
/** Events read, including types that are neither alloc nor free. */
|
|
4297
|
+
events: number;
|
|
4298
|
+
allocCount: number;
|
|
4299
|
+
allocBytes: number;
|
|
4300
|
+
freeCount: number;
|
|
4301
|
+
freeBytes: number;
|
|
4302
|
+
/** Highest running total and the timestamp of the event that produced it. */
|
|
4303
|
+
peak: number;
|
|
4304
|
+
peakTs: number;
|
|
4305
|
+
/**
|
|
4306
|
+
* Id of the event that produced the peak, `null` when the peak is the initial
|
|
4307
|
+
* zero before any event. `(peakTs, peakId)` is the position the peak's
|
|
4308
|
+
* unreleased set must be replayed to: several events can share a timestamp,
|
|
4309
|
+
* and replaying all of them would report the set after later events already
|
|
4310
|
+
* ran.
|
|
4311
|
+
*/
|
|
4312
|
+
peakId: number | null;
|
|
4313
|
+
/** Lowest running total; negative when the capture started mid-lifetime. */
|
|
4314
|
+
trough: number;
|
|
4315
|
+
/** Running total after the last event. */
|
|
4316
|
+
endTotal: number;
|
|
4317
|
+
/** Allocations whose address was NULL; they can never be freed. */
|
|
4318
|
+
unaddressedAllocs: number;
|
|
4319
|
+
/** Frees of an address with no tracked allocation. */
|
|
4320
|
+
unpairedFrees: number;
|
|
4321
|
+
/** Live bytes at the end whose event carried no callchain. */
|
|
4322
|
+
unattributedBytes: number;
|
|
4323
|
+
/**
|
|
4324
|
+
* Live allocations at the `(ts, id)` position, in event order. Omit `id` to
|
|
4325
|
+
* take the state after every event at `ts`.
|
|
4326
|
+
*/
|
|
4327
|
+
unreleasedAt(ts: number, id?: number): ActiveAlloc[];
|
|
4328
|
+
}
|
|
4329
|
+
/**
|
|
4330
|
+
* Pairs allocation and free events by address and derives the memory profile.
|
|
4331
|
+
*
|
|
4332
|
+
* The result is a pure function of the events: ordering, ties and the
|
|
4333
|
+
* unreleased sets never depend on map iteration or input order, so two runs
|
|
4334
|
+
* over the same capture are byte-identical.
|
|
4335
|
+
*
|
|
4336
|
+
* A capture that began after allocations happened starts its total at `0` and
|
|
4337
|
+
* may trough negative. That is reported, not clamped: clamping would make every
|
|
4338
|
+
* absolute figure after the trough look larger than it is.
|
|
4339
|
+
*/
|
|
4340
|
+
declare function pairNativeMemory(events: readonly NativeHookEvent[]): NativeMemoryResult;
|
|
4341
|
+
/** Name lookups the aggregation needs, all resolved by the caller once. */
|
|
4342
|
+
interface NativeNames {
|
|
4343
|
+
/** `process.pid` → process name. */
|
|
4344
|
+
processes: Map<number, string>;
|
|
4345
|
+
/** `thread.itid` → thread name. */
|
|
4346
|
+
threads: Map<number, string>;
|
|
4347
|
+
/** `data_dict` id → file path. */
|
|
4348
|
+
files: Map<number, string>;
|
|
4349
|
+
/** `data_dict` id → symbol. */
|
|
4350
|
+
symbols: Map<number, string>;
|
|
4351
|
+
/** `callchain_id` → its deepest frame, the one that owns the allocation. */
|
|
4352
|
+
frameLeaves: Map<number, {
|
|
4353
|
+
fileId: number;
|
|
4354
|
+
symbolId: number;
|
|
4355
|
+
}>;
|
|
4356
|
+
}
|
|
4357
|
+
/** One unreleased-memory row: a callchain and thread at one instant. */
|
|
4358
|
+
interface UnreleasedRow {
|
|
4359
|
+
callchainId: number;
|
|
4360
|
+
pid: number;
|
|
4361
|
+
process: string;
|
|
4362
|
+
tid: number;
|
|
4363
|
+
thread: string;
|
|
4364
|
+
file: string;
|
|
4365
|
+
symbol: string;
|
|
4366
|
+
/** Summed remaining bytes. */
|
|
4367
|
+
size: number;
|
|
4368
|
+
/** Active allocations merged into this row. */
|
|
4369
|
+
count: number;
|
|
4370
|
+
/** Earliest allocation instant, relative to the first app event. */
|
|
4371
|
+
firstRelativeNs: number;
|
|
4372
|
+
category: number;
|
|
4373
|
+
categoryName: string;
|
|
4374
|
+
subCategory: string;
|
|
4375
|
+
}
|
|
4376
|
+
/**
|
|
4377
|
+
* Merges live allocations into rows keyed by `(callchainId, pid, tid)`.
|
|
4378
|
+
*
|
|
4379
|
+
* The process, thread, file and symbol come from the trace's own name tables;
|
|
4380
|
+
* a name the trace does not carry is `''` for a process and `'unknown'` for a
|
|
4381
|
+
* thread, matching how the rest of the package renders a missing name. The
|
|
4382
|
+
* category is resolved from the leaf frame, because the leaf is the allocation
|
|
4383
|
+
* site, not the outermost caller.
|
|
4384
|
+
*/
|
|
4385
|
+
declare function aggregateUnreleased(allocs: readonly ActiveAlloc[], names: NativeNames): UnreleasedRow[];
|
|
4386
|
+
/** One timeline bucket; only buckets that saw an event are emitted. */
|
|
4387
|
+
interface NativeTimelineBucket {
|
|
4388
|
+
startNs: number;
|
|
4389
|
+
endNs: number;
|
|
4390
|
+
allocBytes: number;
|
|
4391
|
+
freeBytes: number;
|
|
4392
|
+
/** `allocBytes - freeBytes` for this bucket. */
|
|
4393
|
+
deltaBytes: number;
|
|
4394
|
+
/** Running total after the bucket's last event. */
|
|
4395
|
+
totalBytes: number;
|
|
4396
|
+
isPeak: boolean;
|
|
4397
|
+
}
|
|
4398
|
+
/**
|
|
4399
|
+
* Buckets the events into fixed windows anchored at the first event.
|
|
4400
|
+
*
|
|
4401
|
+
* An empty bucket is omitted rather than emitted as zeros: "the capture
|
|
4402
|
+
* recorded nothing here" and "nothing changed here" are different facts, and a
|
|
4403
|
+
* zero would conflate them. `isPeak` marks the bucket holding the peak event,
|
|
4404
|
+
* so a reader can find the worst instant without re-deriving it.
|
|
4405
|
+
*/
|
|
4406
|
+
declare function buildNativeTimeline(events: readonly NativeHookEvent[], bucketNs?: number): NativeTimelineBucket[];
|
|
4407
|
+
/**
|
|
4408
|
+
* Native heap growth from the `nativehook` hiprofiler plugin.
|
|
4409
|
+
*
|
|
4410
|
+
* The analyzer pairs alloc and free events per address and reports the running
|
|
4411
|
+
* total, its peak and trough, and what was still live at the peak and at the
|
|
4412
|
+
* end. "Unreleased" is a statement about the capture window, not a leak claim:
|
|
4413
|
+
* memory still held when the trace stopped may be freed a millisecond later,
|
|
4414
|
+
* and a trace that began mid-lifetime starts at zero and can trough negative.
|
|
4415
|
+
*
|
|
4416
|
+
* When only `native_hook_statistic` exists the analyzer reports the end-of-
|
|
4417
|
+
* capture unreleased bytes per callchain as a proxy and deliberately omits the
|
|
4418
|
+
* peak, the timeline and the thread split — those rows cannot support them.
|
|
4419
|
+
*/
|
|
4420
|
+
declare class NativeMemoryAnalyzer implements Analyzer {
|
|
4421
|
+
readonly id = "native-memory";
|
|
4422
|
+
readonly requires: CapabilityId[];
|
|
4423
|
+
run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
|
|
4424
|
+
/**
|
|
4425
|
+
* The top rows at one instant, each with the queries that explain it.
|
|
4426
|
+
*
|
|
4427
|
+
* The severity threshold is a concentration signal — a row holding a large
|
|
4428
|
+
* share of live memory is worth a look — not a judgment that it is wrong.
|
|
4429
|
+
*/
|
|
4430
|
+
private pointEvidence;
|
|
4431
|
+
/** The statistic-only path: end-of-capture totals, explicitly a proxy. */
|
|
4432
|
+
private statisticsOnly;
|
|
4433
|
+
}
|
|
4434
|
+
|
|
4435
|
+
/** Where a native file or thread belongs in the component hierarchy. */
|
|
4436
|
+
interface NativeCategory {
|
|
4437
|
+
/** `ComponentCategory` id; `-1` when nothing matched. */
|
|
4438
|
+
category: number;
|
|
4439
|
+
categoryName: string;
|
|
4440
|
+
/** Component name, package name, basename or thread name, depending on the rule. */
|
|
4441
|
+
subCategory: string;
|
|
4442
|
+
/** The classified path; the ArkTS package path for a refined `.abc` frame. */
|
|
4443
|
+
file: string;
|
|
4444
|
+
}
|
|
4445
|
+
/**
|
|
4446
|
+
* Classifies a native file, its leaf symbol and its thread.
|
|
4447
|
+
*
|
|
4448
|
+
* Precedence: exact path, then regex rules by priority, then the app bundle
|
|
4449
|
+
* rule, then an exact basename, then `SYS_SDK`. A symbol refines an app `.abc`
|
|
4450
|
+
* frame to its ArkTS package and a KMP frame to its Kotlin package. When there
|
|
4451
|
+
* is no usable file the thread rules decide, and a thread that matches nothing
|
|
4452
|
+
* is reported as `Thread` rather than `SYS_SDK`.
|
|
4453
|
+
*/
|
|
4454
|
+
declare function classifyNativePath(filePath: string | null, symbol: string | null, thread: string | null): NativeCategory;
|
|
4455
|
+
|
|
2577
4456
|
/**
|
|
2578
4457
|
* Startup analyzer over `app_startup`, with a marker-to-first-frame fallback.
|
|
2579
4458
|
*
|
|
@@ -2623,6 +4502,324 @@ declare class RenderAnalyzer implements Analyzer {
|
|
|
2623
4502
|
}>;
|
|
2624
4503
|
}
|
|
2625
4504
|
|
|
4505
|
+
/**
|
|
4506
|
+
* The capture's log, evaluated against the rule set.
|
|
4507
|
+
*
|
|
4508
|
+
* The analyzer reads no tables: the collector wrote a raw log, and the caller
|
|
4509
|
+
* parsed it (`ctx.hilog`). That keeps the capture artifact exactly what the
|
|
4510
|
+
* device printed and makes a parser or rule change a re-analysis rather than a
|
|
4511
|
+
* re-capture.
|
|
4512
|
+
*
|
|
4513
|
+
* Zero matches is a measurement, not an absence: a capture that printed
|
|
4514
|
+
* nothing the rules care about reports a zero per rule with `exact` fidelity.
|
|
4515
|
+
* Only a scene with no log at all degrades, and it says so.
|
|
4516
|
+
*/
|
|
4517
|
+
declare class HilogAnalyzer implements Analyzer {
|
|
4518
|
+
readonly id = "hilog";
|
|
4519
|
+
readonly requires: CapabilityId[];
|
|
4520
|
+
run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
|
|
4521
|
+
}
|
|
4522
|
+
|
|
4523
|
+
/**
|
|
4524
|
+
* What is on screen: the dump's shape and the screenshot's fingerprint.
|
|
4525
|
+
*
|
|
4526
|
+
* The analyzer requires no capability and decides from the artifacts it is
|
|
4527
|
+
* given. `requires: ['ui.tree']` would skip it on a device without `uitest`,
|
|
4528
|
+
* but a scene can carry a `ui.json` captured elsewhere — and a scene with a
|
|
4529
|
+
* screenshot and no dump still has a width, a height and a hash worth
|
|
4530
|
+
* reporting. Each half degrades on its own, so a capture that produced only one
|
|
4531
|
+
* artifact reports the other's absence instead of discarding what it has.
|
|
4532
|
+
*
|
|
4533
|
+
* Neither artifact present is one `ui.degraded` proxy and one `no_data` item
|
|
4534
|
+
* naming both files, which is how the report says "this scene was not captured
|
|
4535
|
+
* with UI data" rather than reporting four zero node counts as measurements.
|
|
4536
|
+
*/
|
|
4537
|
+
declare class UiAnalyzer implements Analyzer {
|
|
4538
|
+
readonly id = "ui";
|
|
4539
|
+
readonly requires: CapabilityId[];
|
|
4540
|
+
run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
|
|
4541
|
+
}
|
|
4542
|
+
|
|
4543
|
+
interface GcSignals {
|
|
4544
|
+
full: number;
|
|
4545
|
+
sharedFull: number;
|
|
4546
|
+
shared: number;
|
|
4547
|
+
partial: number;
|
|
4548
|
+
/** Every GC phase event the app emitted. */
|
|
4549
|
+
invocations: number;
|
|
4550
|
+
/** `max(ts) - min(ts)` over the whole `callstack` table. */
|
|
4551
|
+
spanNs: number;
|
|
4552
|
+
/** `invocations` per second over `spanNs`; 0 when the span is empty. */
|
|
4553
|
+
rate: number;
|
|
4554
|
+
/** True when the count clause alone fires: `> 10` invocations and `> 1/s`. */
|
|
4555
|
+
tooMany: boolean;
|
|
4556
|
+
}
|
|
4557
|
+
/**
|
|
4558
|
+
* Counts the app's GC phase events and measures its invocation rate.
|
|
4559
|
+
*
|
|
4560
|
+
* `ipids` must already be resolved (see `resolveAppIpids`); an empty list
|
|
4561
|
+
* matches nothing, so the result is all zeros rather than device-wide counts.
|
|
4562
|
+
* The raw SQL is here because no query class owns a `LIKE` count scoped by
|
|
4563
|
+
* `thread.ipid`; the `LIKE` predicates stay bound as parameters.
|
|
4564
|
+
*/
|
|
4565
|
+
declare function computeGc(db: QueryHandle, opts: {
|
|
4566
|
+
ipids: readonly number[];
|
|
4567
|
+
}): GcSignals;
|
|
4568
|
+
/**
|
|
4569
|
+
* Emits `gc.*` metrics from Ark-runtime GC phase events.
|
|
4570
|
+
*
|
|
4571
|
+
* Counts only events the app's own threads emitted (`callstack.callid` joins
|
|
4572
|
+
* `thread.id`), so another process's GCs never inflate the app's numbers.
|
|
4573
|
+
*/
|
|
4574
|
+
declare class GcAnalyzer implements Analyzer {
|
|
4575
|
+
readonly id = "gc";
|
|
4576
|
+
readonly requires: CapabilityId[];
|
|
4577
|
+
run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
|
|
4578
|
+
/**
|
|
4579
|
+
* `gc.perf.share` plus the number behind it, or a degraded proxy and
|
|
4580
|
+
* `undefined`.
|
|
4581
|
+
*
|
|
4582
|
+
* HapRay computes the share over the app's own perf threads, so the
|
|
4583
|
+
* denominator is the app's sample weight — not the device's. The caller
|
|
4584
|
+
* needs the number, not just the metric: HapRay's second pressure clause is
|
|
4585
|
+
* `perf_percentage > 0.15`.
|
|
4586
|
+
*/
|
|
4587
|
+
private perfShare;
|
|
4588
|
+
private pressureEvidence;
|
|
4589
|
+
}
|
|
4590
|
+
|
|
4591
|
+
type VsyncPeriodKind = 'high_frequency' | 'low_frequency';
|
|
4592
|
+
type VsyncSeverity = 'low' | 'medium' | 'high';
|
|
4593
|
+
interface VsyncPeriod {
|
|
4594
|
+
kind: VsyncPeriodKind;
|
|
4595
|
+
startVsync: number;
|
|
4596
|
+
endVsync: number;
|
|
4597
|
+
/** Absolute trace nanoseconds; the window an evidence item covers. */
|
|
4598
|
+
startNs: number;
|
|
4599
|
+
endNs: number;
|
|
4600
|
+
intervalCount: number;
|
|
4601
|
+
avgIntervalNs: number;
|
|
4602
|
+
avgFrequencyHz: number;
|
|
4603
|
+
severity: VsyncSeverity;
|
|
4604
|
+
}
|
|
4605
|
+
interface VsyncAnalysis {
|
|
4606
|
+
/** Distinct `vsync` values the app rendered under. */
|
|
4607
|
+
signals: number;
|
|
4608
|
+
mismatches: number;
|
|
4609
|
+
periods: VsyncPeriod[];
|
|
4610
|
+
anomalyRate: number;
|
|
4611
|
+
}
|
|
4612
|
+
/**
|
|
4613
|
+
* The pure VSync analysis over an already app-scoped frame list.
|
|
4614
|
+
*
|
|
4615
|
+
* Exported so a caller can test or reuse the algorithm without a database.
|
|
4616
|
+
*/
|
|
4617
|
+
declare function computeVsyncAnomalies(frames: readonly Frame[]): VsyncAnalysis;
|
|
4618
|
+
/**
|
|
4619
|
+
* Emits `vsync.*` metrics and one `vsync_anomaly` evidence item per period.
|
|
4620
|
+
*
|
|
4621
|
+
* Only the app's frames are analyzed; an app that rendered nothing in the
|
|
4622
|
+
* window produces no metrics and one `no_data` item rather than an exact 0%
|
|
4623
|
+
* anomaly rate, which would read as "the cadence was perfect".
|
|
4624
|
+
*/
|
|
4625
|
+
declare class VsyncAnalyzer implements Analyzer {
|
|
4626
|
+
readonly id = "vsync";
|
|
4627
|
+
readonly requires: CapabilityId[];
|
|
4628
|
+
run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
|
|
4629
|
+
}
|
|
4630
|
+
|
|
4631
|
+
/** The two filter verdicts, plus the frames that survived both. */
|
|
4632
|
+
interface EmptyFrameFilter {
|
|
4633
|
+
/** Frames no rule dropped. */
|
|
4634
|
+
confirmed: Frame[];
|
|
4635
|
+
/** Frames dropped by either rule, in input order. */
|
|
4636
|
+
filtered: Frame[];
|
|
4637
|
+
/** Frames dropped because their own thread submitted a buffer inside them. */
|
|
4638
|
+
rule1: Frame[];
|
|
4639
|
+
/** Frames dropped because the same `(vsync, itid)` already drew a frame. */
|
|
4640
|
+
rule2: Frame[];
|
|
4641
|
+
}
|
|
4642
|
+
/**
|
|
4643
|
+
* Splits `frames` into confirmed empties and the ones each rule dropped.
|
|
4644
|
+
*
|
|
4645
|
+
* Input order is preserved in every output list, and a frame dropped by both
|
|
4646
|
+
* rules appears in both — the lists answer "which rule would have caught this",
|
|
4647
|
+
* not "which rule did".
|
|
4648
|
+
*/
|
|
4649
|
+
declare function filterEmptyFrames(db: QueryHandle, frames: readonly Frame[]): EmptyFrameFilter;
|
|
4650
|
+
/**
|
|
4651
|
+
* Emits `empty_frame.*` metrics and one `empty_frame` evidence per confirmed
|
|
4652
|
+
* frame.
|
|
4653
|
+
*
|
|
4654
|
+
* `empty_frame.rate` is **this package's** definition — `confirmed / app actual
|
|
4655
|
+
* frames × 100` — not a HapRay field: upstream reports empty-frame counts and
|
|
4656
|
+
* load, not a rate. It is omitted when the app rendered no actual frames, so a
|
|
4657
|
+
* consumer never reads a fabricated 0% as "the app never wasted a frame".
|
|
4658
|
+
*/
|
|
4659
|
+
declare class EmptyFrameAnalyzer implements Analyzer {
|
|
4660
|
+
readonly id = "empty-frame";
|
|
4661
|
+
readonly requires: CapabilityId[];
|
|
4662
|
+
run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
|
|
4663
|
+
}
|
|
4664
|
+
|
|
4665
|
+
/** One RenderService frame that skipped, and what it traced back to. */
|
|
4666
|
+
interface RsSkipFrame {
|
|
4667
|
+
frame: Frame;
|
|
4668
|
+
/** `DisplayNode skip` rows inside the frame's inclusive window. */
|
|
4669
|
+
events: number;
|
|
4670
|
+
traced?: {
|
|
4671
|
+
frame: Frame;
|
|
4672
|
+
/** The buffer event's timestamp. */
|
|
4673
|
+
eventNs: number;
|
|
4674
|
+
/** `|appFrame.ts - eventNs|`. */
|
|
4675
|
+
timeDiffNs: number;
|
|
4676
|
+
};
|
|
4677
|
+
}
|
|
4678
|
+
interface RsSkipResult {
|
|
4679
|
+
/** RenderService frames with at least one skip event, ordered by `ts`. */
|
|
4680
|
+
frames: RsSkipFrame[];
|
|
4681
|
+
/** Every skip event assigned to a frame. */
|
|
4682
|
+
totalEvents: number;
|
|
4683
|
+
}
|
|
4684
|
+
/**
|
|
4685
|
+
* Traces every RenderService skip back to the app frame that fed it.
|
|
4686
|
+
*
|
|
4687
|
+
* Both `appIpids` and `rsIpids` must already be resolved; an empty list matches
|
|
4688
|
+
* nothing rather than widening the query. `window` bounds the RenderService
|
|
4689
|
+
* frames and the skip events considered — the buffer and app-frame windows are
|
|
4690
|
+
* relative to each frame, so they may reach slightly outside it.
|
|
4691
|
+
*/
|
|
4692
|
+
declare function computeRsSkip(db: QueryHandle, opts: {
|
|
4693
|
+
window: TimeRange;
|
|
4694
|
+
appIpids: readonly number[];
|
|
4695
|
+
rsIpids: readonly number[];
|
|
4696
|
+
}): RsSkipResult;
|
|
4697
|
+
/**
|
|
4698
|
+
* Emits `rs_skip.*` metrics and one `rs_skip` evidence per RenderService frame
|
|
4699
|
+
* that skipped.
|
|
4700
|
+
*
|
|
4701
|
+
* `rs_skip.trace.accuracy` is traced / skip frames × 100 — HapRay's
|
|
4702
|
+
* `trace_accuracy`, emitted only when at least one skip frame exists. A trace
|
|
4703
|
+
* with no `render_service` process or no skip event produces one `no_data` item
|
|
4704
|
+
* naming what is missing rather than four fabricated zeros.
|
|
4705
|
+
*/
|
|
4706
|
+
declare class RsSkipAnalyzer implements Analyzer {
|
|
4707
|
+
readonly id = "rs-skip";
|
|
4708
|
+
readonly requires: CapabilityId[];
|
|
4709
|
+
run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
|
|
4710
|
+
}
|
|
4711
|
+
|
|
4712
|
+
/**
|
|
4713
|
+
* Folded flamegraph stacks from a perf capture.
|
|
4714
|
+
*
|
|
4715
|
+
* HapRay renders flamegraph HTML by shelling out to `perf -i` and a
|
|
4716
|
+
* flamegraph.pl script; neither works from a trace database alone, so this
|
|
4717
|
+
* analyzer produces the data a renderer needs instead of the HTML: folded
|
|
4718
|
+
* stacks (`a;b;c N`), weighted by `perf_sample.event_count`.
|
|
4719
|
+
*
|
|
4720
|
+
* ## What the numbers mean
|
|
4721
|
+
*
|
|
4722
|
+
* - `flamegraph.samples.count` — the app threads' summed sample weight, not a
|
|
4723
|
+
* row count. `event_count` is how many events each sample stands for.
|
|
4724
|
+
* - `flamegraph.app.share` — that weight over every sample in the database
|
|
4725
|
+
* × 100. On a capture filtered to the app this is 100; on a device-wide one
|
|
4726
|
+
* it is the app's slice of the profile.
|
|
4727
|
+
* - `flamegraph.stacks.count` — the number of distinct folded stacks in the
|
|
4728
|
+
* window. The `top.*` payload is cut to the heaviest 20; this count is not.
|
|
4729
|
+
* - `flamegraph.top.symbol` / `flamegraph.top.samples` — the leaf of the
|
|
4730
|
+
* heaviest folded stack and that stack's weight.
|
|
4731
|
+
*
|
|
4732
|
+
* These are **not** HapRay metrics: upstream reports flamegraph files, not
|
|
4733
|
+
* numbers. The definitions live here and in the test, not in a parity claim.
|
|
4734
|
+
*
|
|
4735
|
+
* Without `perf.db` there is nothing to fold, so the analyzer emits one
|
|
4736
|
+
* `flamegraph.degraded` proxy naming the capture requirements rather than five
|
|
4737
|
+
* zeros that read as "the app did nothing".
|
|
4738
|
+
*/
|
|
4739
|
+
declare class FlamegraphAnalyzer implements Analyzer {
|
|
4740
|
+
readonly id = "flamegraph";
|
|
4741
|
+
readonly requires: CapabilityId[];
|
|
4742
|
+
run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
|
|
4743
|
+
}
|
|
4744
|
+
|
|
4745
|
+
declare class SymbolsAnalyzer implements Analyzer {
|
|
4746
|
+
readonly id = "symbols";
|
|
4747
|
+
readonly requires: CapabilityId[];
|
|
4748
|
+
run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
|
|
4749
|
+
}
|
|
4750
|
+
|
|
4751
|
+
/** HapRay's payload shape: the busiest component plus per-component counts. */
|
|
4752
|
+
interface ComponentReuse {
|
|
4753
|
+
max_component: string;
|
|
4754
|
+
/** The max component's build count, not the total across components. */
|
|
4755
|
+
total_builds: number;
|
|
4756
|
+
/** The max component's recycled builds. */
|
|
4757
|
+
recycled_builds: number;
|
|
4758
|
+
/** `round2HalfEven(recycled_builds / total_builds)`, or 0 when nothing built. */
|
|
4759
|
+
reusability_ratio: number;
|
|
4760
|
+
/** `[builds, recycled]` per component, in first-seen order. */
|
|
4761
|
+
details: Record<string, [number, number]>;
|
|
4762
|
+
}
|
|
4763
|
+
/**
|
|
4764
|
+
* Python's `round(value, 2)` for a non-negative double.
|
|
4765
|
+
*
|
|
4766
|
+
* Python rounds the **exact decimal value of the double** to two places,
|
|
4767
|
+
* breaking exact ties toward the even digit. `Math.round(value * 100) / 100`
|
|
4768
|
+
* is half-up and also rounds the already-rounded product, so it disagrees at
|
|
4769
|
+
* `0.125` (→ `0.13`) and agrees only by luck elsewhere.
|
|
4770
|
+
*
|
|
4771
|
+
* The decomposition below is exact: a finite double is `mantissa × 2^exponent`
|
|
4772
|
+
* with an integer mantissa, so the scaled value is a rational whose rounding
|
|
4773
|
+
* can be decided with integers alone.
|
|
4774
|
+
*/
|
|
4775
|
+
declare function round2HalfEven(value: number): number;
|
|
4776
|
+
/**
|
|
4777
|
+
* Counts builds and recycles per component and picks the busiest one.
|
|
4778
|
+
*
|
|
4779
|
+
* `ipids` must already be resolved. An empty list means "no app to scope to"
|
|
4780
|
+
* and matches every process, which is what makes the parity fixture
|
|
4781
|
+
* reproducible; a non-empty list restricts to `callstack` rows whose
|
|
4782
|
+
* `thread.id` belongs to one of those ipids. **The analyzer never passes an
|
|
4783
|
+
* empty list** — it degrades first, because a device-wide answer labelled as
|
|
4784
|
+
* the app's is worse than no answer. This function keeps the unscoped mode
|
|
4785
|
+
* because the parity golden needs it. Ties for the busiest component
|
|
4786
|
+
* resolve to the first one seen (rows are read `ORDER BY ts, id`), matching
|
|
4787
|
+
* HapRay's strict `>`.
|
|
4788
|
+
*/
|
|
4789
|
+
declare function computeComponentReuse(db: QueryHandle, opts: {
|
|
4790
|
+
ipids: readonly number[];
|
|
4791
|
+
}): ComponentReuse;
|
|
4792
|
+
/**
|
|
4793
|
+
* Emits the four `components.*` metrics and no evidence.
|
|
4794
|
+
*
|
|
4795
|
+
* There is no evidence kind for component reuse: a busy component is not a
|
|
4796
|
+
* fault, and HapRay reports it as a table rather than an issue. The reuse rate
|
|
4797
|
+
* and the top name are omitted when nothing was built, so a consumer never
|
|
4798
|
+
* reads a fabricated 0% as "the app reused nothing".
|
|
4799
|
+
*/
|
|
4800
|
+
declare class ComponentReuseAnalyzer implements Analyzer {
|
|
4801
|
+
readonly id = "components";
|
|
4802
|
+
readonly requires: CapabilityId[];
|
|
4803
|
+
run(ctx: AnalyzeContext): Promise<AnalyzeResult>;
|
|
4804
|
+
}
|
|
4805
|
+
|
|
4806
|
+
/**
|
|
4807
|
+
* One analyzer's share of a run.
|
|
4808
|
+
*
|
|
4809
|
+
* A skipped analyzer still gets a section, with `status: 'degraded'` and the
|
|
4810
|
+
* placeholder metric/evidence pair the engine synthesizes, so a report can
|
|
4811
|
+
* name the missing capability in place instead of dropping the section.
|
|
4812
|
+
*/
|
|
4813
|
+
interface AnalyzerSection {
|
|
4814
|
+
readonly analyzerId: string;
|
|
4815
|
+
readonly status: 'measured' | 'degraded';
|
|
4816
|
+
readonly result: AnalyzeResult;
|
|
4817
|
+
}
|
|
4818
|
+
/** A whole run: the merged result plus the per-analyzer sections it came from. */
|
|
4819
|
+
interface AnalyzerRun {
|
|
4820
|
+
readonly result: AnalyzeResult;
|
|
4821
|
+
readonly sections: AnalyzerSection[];
|
|
4822
|
+
}
|
|
2626
4823
|
/**
|
|
2627
4824
|
* Runs every analyzer whose capability requirements are satisfied.
|
|
2628
4825
|
*
|
|
@@ -2631,6 +4828,8 @@ declare class RenderAnalyzer implements Analyzer {
|
|
|
2631
4828
|
* order (D5). An analyzer with an unsatisfied requirement is not called: it
|
|
2632
4829
|
* contributes one `<id>.degraded` proxy metric and one `degraded_capability`
|
|
2633
4830
|
* evidence item naming the missing capabilities and the device's own reasons.
|
|
4831
|
+
* Every analyzer also contributes one {@link AnalyzerSection} to `sections`,
|
|
4832
|
+
* in the same id order, so a report can attribute each metric to its source.
|
|
2634
4833
|
*
|
|
2635
4834
|
* The returned arrays are new and sorted (`metrics` by `id`, `evidence` by
|
|
2636
4835
|
* `(kind, window.startNs, id)`). Two analyzers emitting the same metric id
|
|
@@ -2639,6 +4838,13 @@ declare class RenderAnalyzer implements Analyzer {
|
|
|
2639
4838
|
* integrity rule applies to evidence ids (`DUPLICATE_EVIDENCE_ID`). Neither
|
|
2640
4839
|
* the context nor any analyzer (including its result arrays) is mutated.
|
|
2641
4840
|
*/
|
|
4841
|
+
declare function runAnalyzerSections(analyzers: readonly Analyzer[], ctx: AnalyzeContext): Promise<AnalyzerRun>;
|
|
4842
|
+
/**
|
|
4843
|
+
* Runs every analyzer and returns only the merged result.
|
|
4844
|
+
*
|
|
4845
|
+
* A thin wrapper over {@link runAnalyzerSections}; existing callers keep the
|
|
4846
|
+
* old shape and behavior exactly.
|
|
4847
|
+
*/
|
|
2642
4848
|
declare function runAnalyzers(analyzers: readonly Analyzer[], ctx: AnalyzeContext): Promise<AnalyzeResult>;
|
|
2643
4849
|
/**
|
|
2644
4850
|
* The analyzers an offline `analyze` run executes by default.
|
|
@@ -2664,6 +4870,208 @@ declare function defaultAnalyzers(): Analyzer[];
|
|
|
2664
4870
|
* when the process was not found.
|
|
2665
4871
|
*/
|
|
2666
4872
|
declare function resolveAppIdentity(processes: ProcessQuery, packageName: string): AppIdentity;
|
|
4873
|
+
/**
|
|
4874
|
+
* The `ipid` of every app pid, in `pids` order, without duplicates.
|
|
4875
|
+
*
|
|
4876
|
+
* `AppIdentity.pids` are **pids** while `thread.ipid`, `frame_slice.ipid`,
|
|
4877
|
+
* `process_measure_filter.ipid` and `app_startup.ipid` are **ipids**: the two
|
|
4878
|
+
* number spaces overlap, so comparing them directly silently reads another
|
|
4879
|
+
* process's rows (measured on the Mate 60: sceneboard has `pid=6500` and
|
|
4880
|
+
* `ipid=117`). `ProcessQuery.byPid` is the only safe translation, and it
|
|
4881
|
+
* resolves duplicate pids to the lowest row id (D5).
|
|
4882
|
+
*
|
|
4883
|
+
* `ipid` 0 is a NULL column, not a process — the query layer maps NULL to 0 —
|
|
4884
|
+
* so it is skipped, as are non-integers. An empty result means "no process
|
|
4885
|
+
* identified", which every caller must treat as "no data", never as
|
|
4886
|
+
* "device-wide".
|
|
4887
|
+
*/
|
|
4888
|
+
declare function resolveAppIpids(processes: ProcessQuery, pids: readonly number[]): number[];
|
|
4889
|
+
|
|
4890
|
+
/** One non-directory entry, as the central directory records it. */
|
|
4891
|
+
interface ZipEntry {
|
|
4892
|
+
/** The name exactly as stored; forward slashes. */
|
|
4893
|
+
readonly name: string;
|
|
4894
|
+
readonly size: number;
|
|
4895
|
+
readonly compressedSize: number;
|
|
4896
|
+
readonly crc32: number;
|
|
4897
|
+
readonly method: number;
|
|
4898
|
+
/** Where the entry's payload starts in the archive. */
|
|
4899
|
+
readonly dataOffset: number;
|
|
4900
|
+
}
|
|
4901
|
+
interface ZipArchive {
|
|
4902
|
+
/** Non-directory entries, in central-directory order. */
|
|
4903
|
+
readonly entries: readonly ZipEntry[];
|
|
4904
|
+
/** Inflated bytes, CRC-checked. Throws on a mismatch or a bad stream. */
|
|
4905
|
+
read(entry: ZipEntry): Uint8Array;
|
|
4906
|
+
}
|
|
4907
|
+
/** True when the bytes start with a local file header. */
|
|
4908
|
+
declare function isZip(bytes: Uint8Array): boolean;
|
|
4909
|
+
/** Read the central directory and return an archive over `bytes`. */
|
|
4910
|
+
declare function openZip(bytes: Uint8Array): ZipArchive;
|
|
4911
|
+
|
|
4912
|
+
type FileCategory = 'images' | 'videos' | 'audio' | 'fonts' | 'scripts' | 'styles' | 'binaries' | 'bytecode' | 'data' | 'other';
|
|
4913
|
+
/** One archive entry, measured. Paths are archive names, forward slashes. */
|
|
4914
|
+
interface InventoryFile {
|
|
4915
|
+
readonly path: string;
|
|
4916
|
+
readonly size: number;
|
|
4917
|
+
readonly compressedSize: number;
|
|
4918
|
+
/** 8 lowercase hex chars. */
|
|
4919
|
+
readonly crc32: string;
|
|
4920
|
+
/** Lowercase, without the dot; `''` when the name has no extension. */
|
|
4921
|
+
readonly extension: string;
|
|
4922
|
+
readonly category: FileCategory;
|
|
4923
|
+
}
|
|
4924
|
+
/** HapRay's extension table, verbatim. */
|
|
4925
|
+
declare const CATEGORY_EXTENSIONS: Readonly<Record<FileCategory, readonly string[]>>;
|
|
4926
|
+
/**
|
|
4927
|
+
* HapRay's per-category "max optimal size", in bytes.
|
|
4928
|
+
*
|
|
4929
|
+
* The fractions are HapRay's decimal megabytes (0.5, 0.2), converted once here
|
|
4930
|
+
* so no caller has to guess whether a threshold is 500000 or 524288.
|
|
4931
|
+
*/
|
|
4932
|
+
declare const CATEGORY_MAX_BYTES: Readonly<Record<FileCategory, number>>;
|
|
4933
|
+
/** The category a lowercase extension belongs to; unknown is `other`. */
|
|
4934
|
+
declare function categorize(extension: string): FileCategory;
|
|
4935
|
+
/** Every non-directory entry, sorted by path. */
|
|
4936
|
+
declare function buildInventory(archive: ZipArchive): InventoryFile[];
|
|
4937
|
+
|
|
4938
|
+
type RuleMatchKind = 'filename' | 'path' | 'extension' | 'magic' | 'content' | 'combined';
|
|
4939
|
+
/** A content pattern, optionally carrying its own confidence (HapRay's YAML). */
|
|
4940
|
+
interface ContentPattern {
|
|
4941
|
+
readonly pattern: string;
|
|
4942
|
+
readonly confidence?: number;
|
|
4943
|
+
}
|
|
4944
|
+
interface FileRule {
|
|
4945
|
+
readonly kind: RuleMatchKind;
|
|
4946
|
+
/** Regex sources, tried in order. */
|
|
4947
|
+
readonly patterns?: readonly (string | ContentPattern)[];
|
|
4948
|
+
readonly extensions?: readonly string[];
|
|
4949
|
+
readonly bytes?: readonly number[];
|
|
4950
|
+
readonly offset?: number;
|
|
4951
|
+
readonly operator?: 'and' | 'or' | 'not';
|
|
4952
|
+
readonly rules?: readonly FileRule[];
|
|
4953
|
+
/** Multiplies the rule's confidence when this file rule decides the match. */
|
|
4954
|
+
readonly confidence?: number;
|
|
4955
|
+
}
|
|
4956
|
+
/** One field read out of a matched file, beside the match. */
|
|
4957
|
+
interface MetadataPattern {
|
|
4958
|
+
readonly field: string;
|
|
4959
|
+
readonly source: 'content' | 'path' | 'filename';
|
|
4960
|
+
readonly pattern: string;
|
|
4961
|
+
readonly captureGroup?: number;
|
|
4962
|
+
}
|
|
4963
|
+
interface TechRule {
|
|
4964
|
+
readonly id: string;
|
|
4965
|
+
readonly name: string;
|
|
4966
|
+
readonly type: string;
|
|
4967
|
+
readonly confidence: number;
|
|
4968
|
+
readonly fileRules: readonly FileRule[];
|
|
4969
|
+
/** When true, a file match without extracted metadata is not a match. */
|
|
4970
|
+
readonly requireMetadata?: boolean;
|
|
4971
|
+
readonly metadataPatterns?: readonly MetadataPattern[];
|
|
4972
|
+
}
|
|
4973
|
+
interface RuleMatch {
|
|
4974
|
+
readonly ruleId: string;
|
|
4975
|
+
readonly ruleName: string;
|
|
4976
|
+
readonly type: string;
|
|
4977
|
+
readonly confidence: number;
|
|
4978
|
+
readonly files: InventoryFile[];
|
|
4979
|
+
readonly bytes: number;
|
|
4980
|
+
readonly metadata: Readonly<Record<string, string>>;
|
|
4981
|
+
}
|
|
4982
|
+
/**
|
|
4983
|
+
* HapRay's `excludes`: entries under these paths are not offered to any rule.
|
|
4984
|
+
*
|
|
4985
|
+
* Its config excludes `resources/base/.*`, and keeping the exclusion means the
|
|
4986
|
+
* same package yields the same detections here as there.
|
|
4987
|
+
*/
|
|
4988
|
+
declare const EXCLUDE_PATTERNS: readonly string[];
|
|
4989
|
+
/**
|
|
4990
|
+
* Run every rule against the inventory and report the rules that matched.
|
|
4991
|
+
*
|
|
4992
|
+
* A rule matches when at least one file matches it; the match carries every
|
|
4993
|
+
* matching file, their summed bytes, and the highest confidence any of them
|
|
4994
|
+
* produced. Rules keep their configured order on the way in; the output is
|
|
4995
|
+
* sorted by `(type, ruleId)` so two runs of the same archive agree byte for
|
|
4996
|
+
* byte.
|
|
4997
|
+
*/
|
|
4998
|
+
declare function matchHapRules(rules: readonly TechRule[], archive: ZipArchive, inventory: readonly InventoryFile[]): RuleMatch[];
|
|
4999
|
+
/**
|
|
5000
|
+
* Refuse a rule set that cannot run: an unknown kind, an invalid regex, or a
|
|
5001
|
+
* malformed combined rule. HapRay logs a warning and skips the pattern, which
|
|
5002
|
+
* turns a typo into a detection that never fires; a load-time refusal names
|
|
5003
|
+
* the rule instead.
|
|
5004
|
+
*/
|
|
5005
|
+
declare function validateRules(rules: readonly TechRule[]): void;
|
|
5006
|
+
/**
|
|
5007
|
+
* HapRay's shipped detections, in its own order.
|
|
5008
|
+
*
|
|
5009
|
+
* Ids and types are the upstream ones so a comparison against its output is
|
|
5010
|
+
* meaningful. The ELF-backed metadata fields (`soDependencies`, `Key`,
|
|
5011
|
+
* `openSourcePackages`, …) are not ported; see the module comment.
|
|
5012
|
+
*/
|
|
5013
|
+
declare const TECH_RULES: readonly TechRule[];
|
|
5014
|
+
|
|
5015
|
+
interface DuplicateGroup {
|
|
5016
|
+
readonly sha256: string;
|
|
5017
|
+
readonly size: number;
|
|
5018
|
+
readonly copies: number;
|
|
5019
|
+
readonly wastedBytes: number;
|
|
5020
|
+
readonly paths: readonly string[];
|
|
5021
|
+
}
|
|
5022
|
+
interface OversizedFile {
|
|
5023
|
+
readonly path: string;
|
|
5024
|
+
readonly category: FileCategory;
|
|
5025
|
+
readonly size: number;
|
|
5026
|
+
readonly threshold: number;
|
|
5027
|
+
}
|
|
5028
|
+
interface HapPackage {
|
|
5029
|
+
readonly name: string;
|
|
5030
|
+
readonly bundleName: string;
|
|
5031
|
+
readonly versionName: string;
|
|
5032
|
+
readonly versionCode: number;
|
|
5033
|
+
readonly appName: string;
|
|
5034
|
+
}
|
|
5035
|
+
interface CategoryTotal {
|
|
5036
|
+
readonly name: FileCategory;
|
|
5037
|
+
readonly files: number;
|
|
5038
|
+
readonly size: number;
|
|
5039
|
+
readonly compressedSize: number;
|
|
5040
|
+
}
|
|
5041
|
+
interface HapAnalysis {
|
|
5042
|
+
readonly schemaVersion: 1;
|
|
5043
|
+
readonly package: HapPackage;
|
|
5044
|
+
readonly totals: {
|
|
5045
|
+
files: number;
|
|
5046
|
+
size: number;
|
|
5047
|
+
compressedSize: number;
|
|
5048
|
+
};
|
|
5049
|
+
readonly categories: CategoryTotal[];
|
|
5050
|
+
readonly technologies: RuleMatch[];
|
|
5051
|
+
readonly duplicates: DuplicateGroup[];
|
|
5052
|
+
readonly oversized: OversizedFile[];
|
|
5053
|
+
readonly largest: Array<{
|
|
5054
|
+
path: string;
|
|
5055
|
+
size: number;
|
|
5056
|
+
}>;
|
|
5057
|
+
/**
|
|
5058
|
+
* Every non-directory entry, measured: the population the totals, categories
|
|
5059
|
+
* and largest lists are taken from. This is what a caller opens when an
|
|
5060
|
+
* evidence item raises a question about one file.
|
|
5061
|
+
*/
|
|
5062
|
+
readonly files: readonly InventoryFile[];
|
|
5063
|
+
readonly metrics: Metric[];
|
|
5064
|
+
readonly evidence: Evidence[];
|
|
5065
|
+
}
|
|
5066
|
+
/**
|
|
5067
|
+
* Analyze one HAP's bytes into a deterministic document.
|
|
5068
|
+
*
|
|
5069
|
+
* `packageName` names the archive in the document (the caller's file name, not
|
|
5070
|
+
* an absolute path) so the same bytes under a different path stay identical.
|
|
5071
|
+
*/
|
|
5072
|
+
declare function analyzeHap(bytes: Uint8Array, packageName: string): HapAnalysis;
|
|
5073
|
+
/** Wrap an analysis as the `static-hap` section the report renderer takes. */
|
|
5074
|
+
declare function hapSection(analysis: HapAnalysis): AnalyzerSection;
|
|
2667
5075
|
|
|
2668
5076
|
/**
|
|
2669
5077
|
* Which way a metric improves.
|
|
@@ -2720,4 +5128,212 @@ interface BaselineComparison {
|
|
|
2720
5128
|
*/
|
|
2721
5129
|
declare function compareResults(baseline: AnalyzeResult, current: AnalyzeResult): BaselineComparison;
|
|
2722
5130
|
|
|
2723
|
-
|
|
5131
|
+
/** The report document schema. A change to any shape below bumps this. */
|
|
5132
|
+
declare const REPORT_SCHEMA_VERSION = 1;
|
|
5133
|
+
/** Who produced the report; the version is the CLI package version. */
|
|
5134
|
+
interface ReportGenerator {
|
|
5135
|
+
name: string;
|
|
5136
|
+
version: string;
|
|
5137
|
+
}
|
|
5138
|
+
/** The scene the report describes. Inputs are copied, never referenced. */
|
|
5139
|
+
interface ReportScenario {
|
|
5140
|
+
app: {
|
|
5141
|
+
packageName: string;
|
|
5142
|
+
processNames: string[];
|
|
5143
|
+
};
|
|
5144
|
+
device: string;
|
|
5145
|
+
window: TimeRange;
|
|
5146
|
+
/** Capture start from `scene.json`; absent when the scene did not record one. */
|
|
5147
|
+
startedAtNs?: number;
|
|
5148
|
+
/**
|
|
5149
|
+
* The screenshot the bundle carries at `assets/screenshot.png`. Present only
|
|
5150
|
+
* when the scene had one, so a renderer can tell "no image" from "an image
|
|
5151
|
+
* whose size it was not told".
|
|
5152
|
+
*/
|
|
5153
|
+
screenshot?: {
|
|
5154
|
+
width: number;
|
|
5155
|
+
height: number;
|
|
5156
|
+
};
|
|
5157
|
+
}
|
|
5158
|
+
/** One analyzer's contribution, ready for rendering. */
|
|
5159
|
+
interface ReportSection {
|
|
5160
|
+
/** The analyzer id, e.g. `frames`. Also the HTML section anchor. */
|
|
5161
|
+
id: string;
|
|
5162
|
+
title: string;
|
|
5163
|
+
status: 'measured' | 'degraded';
|
|
5164
|
+
/** The engine's explanation of why the analyzer was skipped. */
|
|
5165
|
+
degradedReason?: string;
|
|
5166
|
+
/** Sorted by `id`, as the engine emits them. */
|
|
5167
|
+
metrics: Metric[];
|
|
5168
|
+
/** Sorted by `(kind, window.startNs, id)`, as the engine emits them. */
|
|
5169
|
+
evidence: Evidence[];
|
|
5170
|
+
}
|
|
5171
|
+
interface ReportTotals {
|
|
5172
|
+
metrics: number;
|
|
5173
|
+
evidence: number;
|
|
5174
|
+
bySeverity: {
|
|
5175
|
+
info: number;
|
|
5176
|
+
warn: number;
|
|
5177
|
+
critical: number;
|
|
5178
|
+
};
|
|
5179
|
+
measured: number;
|
|
5180
|
+
degraded: number;
|
|
5181
|
+
}
|
|
5182
|
+
/** The complete, versioned report document. */
|
|
5183
|
+
interface ReportModel {
|
|
5184
|
+
schemaVersion: typeof REPORT_SCHEMA_VERSION;
|
|
5185
|
+
generator: ReportGenerator;
|
|
5186
|
+
scenario: ReportScenario;
|
|
5187
|
+
sections: ReportSection[];
|
|
5188
|
+
totals: ReportTotals;
|
|
5189
|
+
comparison?: BaselineComparison;
|
|
5190
|
+
}
|
|
5191
|
+
/** Everything `buildReport` needs; all values are already measured. */
|
|
5192
|
+
interface ReportInput {
|
|
5193
|
+
generator: ReportGenerator;
|
|
5194
|
+
app: AppIdentity;
|
|
5195
|
+
device: string;
|
|
5196
|
+
window: TimeRange;
|
|
5197
|
+
startedAtNs?: number;
|
|
5198
|
+
sections: readonly AnalyzerSection[];
|
|
5199
|
+
comparison?: BaselineComparison;
|
|
5200
|
+
/**
|
|
5201
|
+
* The scene's screenshot dimensions, when one was captured. The report copies
|
|
5202
|
+
* the file to `assets/screenshot.png` and renders it in the `ui` section; the
|
|
5203
|
+
* dimensions are here so the page can state them without decoding the PNG
|
|
5204
|
+
* again. Absent means no image was captured, and the page says so instead of
|
|
5205
|
+
* pointing at a file that does not exist.
|
|
5206
|
+
*/
|
|
5207
|
+
screenshot?: {
|
|
5208
|
+
width: number;
|
|
5209
|
+
height: number;
|
|
5210
|
+
};
|
|
5211
|
+
}
|
|
5212
|
+
/** The compact roll-up written to `summary.json`. */
|
|
5213
|
+
interface ReportSummary {
|
|
5214
|
+
schemaVersion: typeof REPORT_SCHEMA_VERSION;
|
|
5215
|
+
app: string;
|
|
5216
|
+
device: string;
|
|
5217
|
+
window: TimeRange;
|
|
5218
|
+
sections: Array<{
|
|
5219
|
+
id: string;
|
|
5220
|
+
title: string;
|
|
5221
|
+
status: 'measured' | 'degraded';
|
|
5222
|
+
degradedReason?: string;
|
|
5223
|
+
metrics: number;
|
|
5224
|
+
evidence: number;
|
|
5225
|
+
}>;
|
|
5226
|
+
totals: ReportTotals;
|
|
5227
|
+
comparison?: Record<DeltaStatus, number>;
|
|
5228
|
+
}
|
|
5229
|
+
/**
|
|
5230
|
+
* Human titles for the analyzers shipped today.
|
|
5231
|
+
*
|
|
5232
|
+
* An id absent here titles as itself: a new analyzer renders honestly before
|
|
5233
|
+
* anyone writes its title, instead of failing the report.
|
|
5234
|
+
*/
|
|
5235
|
+
declare const SECTION_TITLES: Readonly<Record<string, string>>;
|
|
5236
|
+
/**
|
|
5237
|
+
* Builds the report document from a section-aware engine run.
|
|
5238
|
+
*
|
|
5239
|
+
* The inputs are copied and sorted, never mutated. Sorting repeats the engine's
|
|
5240
|
+
* order so a model assembled by hand (as in tests) is just as deterministic as
|
|
5241
|
+
* one produced by `runAnalyzerSections` — the report must be byte-stable (D5)
|
|
5242
|
+
* no matter which layer produced its parts.
|
|
5243
|
+
*/
|
|
5244
|
+
declare function buildReport(input: ReportInput): ReportModel;
|
|
5245
|
+
/** Collapses the model to its per-section counts and totals. */
|
|
5246
|
+
declare function summarizeReport(model: ReportModel): ReportSummary;
|
|
5247
|
+
/**
|
|
5248
|
+
* The canonical JSON serialization for `report.json` and `summary.json`.
|
|
5249
|
+
*
|
|
5250
|
+
* Two-space indent plus a trailing newline matches `analyze --json`, so a
|
|
5251
|
+
* consumer reads every document in this package the same way.
|
|
5252
|
+
*/
|
|
5253
|
+
declare function renderReportJson(model: ReportModel): string;
|
|
5254
|
+
declare function renderSummaryJson(summary: ReportSummary): string;
|
|
5255
|
+
|
|
5256
|
+
/**
|
|
5257
|
+
* One CSV row per metric, in model order (sections by id, metrics by id).
|
|
5258
|
+
*
|
|
5259
|
+
* The header is a documented contract; adding a column is a schema change and
|
|
5260
|
+
* belongs to a new report schema version, not a silent append.
|
|
5261
|
+
*/
|
|
5262
|
+
declare function renderMetricsCsv(model: ReportModel): string;
|
|
5263
|
+
/**
|
|
5264
|
+
* One CSV row per evidence item, in model order.
|
|
5265
|
+
*
|
|
5266
|
+
* `drillDown` is intentionally absent: it is structured data that belongs in
|
|
5267
|
+
* the JSON and HTML, and flattening it would make the cell ambiguous.
|
|
5268
|
+
*/
|
|
5269
|
+
declare function renderEvidenceCsv(model: ReportModel): string;
|
|
5270
|
+
|
|
5271
|
+
/**
|
|
5272
|
+
* Render the whole report as one self-contained HTML document.
|
|
5273
|
+
*
|
|
5274
|
+
* No scripts, no stylesheets, no images and no URLs: the page is a pure
|
|
5275
|
+
* function of the model, so it opens offline and renders identically anywhere.
|
|
5276
|
+
* Every interpolation goes through {@link escapeHtml}.
|
|
5277
|
+
*/
|
|
5278
|
+
declare function renderReportHtml(model: ReportModel): string;
|
|
5279
|
+
|
|
5280
|
+
/**
|
|
5281
|
+
* Render the whole model as a minimal XLSX workbook.
|
|
5282
|
+
*
|
|
5283
|
+
* Sheets: `Summary`, `Metrics`, `Evidence` and, when a comparison is present,
|
|
5284
|
+
* `Compare`. All names are well under Excel's 31-character limit.
|
|
5285
|
+
*/
|
|
5286
|
+
declare function renderReportXlsx(model: ReportModel): Uint8Array;
|
|
5287
|
+
|
|
5288
|
+
/**
|
|
5289
|
+
* HTML-escape every interpolated value.
|
|
5290
|
+
*
|
|
5291
|
+
* `&` first, or the other replacements would double-escape. The result is safe
|
|
5292
|
+
* inside text nodes and double-quoted attributes; no renderer emits single
|
|
5293
|
+
* quotes into attribute values, but escaping them is cheaper than remembering
|
|
5294
|
+
* that at each call site.
|
|
5295
|
+
*
|
|
5296
|
+
* One copy serves every page the package writes — the report, the UI diff and
|
|
5297
|
+
* the flamegraph — so a page cannot escape less than its neighbours.
|
|
5298
|
+
*/
|
|
5299
|
+
declare function escapeHtml(value: string): string;
|
|
5300
|
+
|
|
5301
|
+
/** The artifacts a report bundle carries for this view, in write order. */
|
|
5302
|
+
declare const FLAMEGRAPH_FILES: readonly ['flamegraph.svg', 'flamegraph.html'];
|
|
5303
|
+
/**
|
|
5304
|
+
* Render folded stacks as a self-contained SVG document.
|
|
5305
|
+
*
|
|
5306
|
+
* An empty list still renders a valid document that says so, rather than a
|
|
5307
|
+
* zero-sized canvas a viewer would show as a blank rectangle.
|
|
5308
|
+
*/
|
|
5309
|
+
declare function renderFlamegraphSvg(stacks: readonly FoldedStack[]): string;
|
|
5310
|
+
|
|
5311
|
+
/** Everything the page states around the drawing. */
|
|
5312
|
+
interface FlamegraphPageInput {
|
|
5313
|
+
readonly stacks: readonly FoldedStack[];
|
|
5314
|
+
readonly app: string;
|
|
5315
|
+
readonly window: TimeRange;
|
|
5316
|
+
/**
|
|
5317
|
+
* Unresolved leaf weight as a percentage of the window, or `null` when the
|
|
5318
|
+
* capture had no samples to measure it from.
|
|
5319
|
+
*/
|
|
5320
|
+
readonly unresolvedShare: number | null;
|
|
5321
|
+
/**
|
|
5322
|
+
* Whether the capture *asked* for symbolization: `true`, `false`, or `null`
|
|
5323
|
+
* when the scene did not record it.
|
|
5324
|
+
*
|
|
5325
|
+
* Requested, not achieved: `scene.json` records that `--so-dir` was passed,
|
|
5326
|
+
* and nothing records how many frames the symbolizer actually named. A page
|
|
5327
|
+
* that claimed the frames were resolved would contradict the unresolved
|
|
5328
|
+
* share printed directly above it.
|
|
5329
|
+
*/
|
|
5330
|
+
readonly symbolizationRequested: boolean | null;
|
|
5331
|
+
}
|
|
5332
|
+
/**
|
|
5333
|
+
* The page: a header card stating what was measured and what the names mean,
|
|
5334
|
+
* then the drawing inline. Everything is in this one file, so the artifact
|
|
5335
|
+
* opens from a folder with no server and no network.
|
|
5336
|
+
*/
|
|
5337
|
+
declare function renderFlamegraphHtml(input: FlamegraphPageInput): string;
|
|
5338
|
+
|
|
5339
|
+
export { type ActionDevice, type ActionOutcome, type ActiveAlloc, type AnalyzeContext, type AnalyzeResult, type Analyzer, type AnalyzerRun, type AnalyzerSection, type AppIdentity, type BaselineComparison, type BelowThresholdPattern, type BinderAnalysis, BinderAnalyzer, type BinderEndpoint, type BinderEvent, type BinderInterfaceStat, type BinderProcessStat, BinderQuery, type BinderThreadStat, type BinderTransaction, CATEGORY_EXTENSIONS, CATEGORY_MAX_BYTES, COLLECTOR_NAMES, type CallchainSample, type CallstackEvent, type CallstackEventWithArgs, CallstackQuery, type CapabilityId, type CapabilityInputs, CapabilityMatrix, type CapabilityState, type CategoryTotal, type CollectOptions, type CollectSession, type Collector, type CollectorName, type CompiledRule, type ComponentReuse, ComponentReuseAnalyzer, type ConnectOptions, type ContentPattern, type CreateEmulatorRequest, DEFAULT_HILOG_RULES, DEFAULT_QUERY_LIMIT, DEVICE_PERF_PATH, DEVICE_SCREENSHOT_PATH, DEVICE_UI_PATH, type DeltaStatus, Device, type DeviceDeps, type DeviceIdentity, DeviceNotFoundError, type DrillDownHandle, type DuplicateGroup, EXCLUDE_PATTERNS, EmptyFrameAnalyzer, type EmptyFrameFilter, type EmulatorBackend, EmulatorClient, type EmulatorClientOptions, EmulatorCommandError, type EmulatorImage, EmulatorImageMissingError, type EmulatorInstance, EmulatorLifecycle, type EmulatorLifecycleOptions, EmulatorNotFoundError, type EmulatorStartResult, type EmulatorStopResult, type Env, type Evidence, type EvidenceKind, FLAMEGRAPH_FILES, FPS_COMMAND, FTRACE_CATEGORIES, FaultTreeAnalyzer, type FaultTreeSignals, type Fidelity, type FileCategory, type FileRule, FlamegraphAnalyzer, type FlamegraphPageInput, type FoldedStack, type FpsBucket, type FpsWindow, type Frame, FrameAnalyzer, type FrameFlag, FrameLoadAnalyzer, FrameLoadIndex, type FrameLoadIndexInput, type FrameLoadThread, FrameQuery, type FrameStats, type FrameType, type FtraceOptions, GEOMETRY_TOLERANCE_PX, GcAnalyzer, type GcSignals, type Gesture, GestureDriver, type GestureResult, HILOG_COMMAND, HIPROFILER_PLUGIN_NAMES, HITCH_COMMAND, HITRACE_DEFAULT_CATEGORIES, type HapAnalysis, type HapPackage, Hdc, HdcNotFoundError, type HdcOptions, type HdcResult, type HdcSlice, type HdcTarget, type HidumperCapture, HidumperCollector, type HidumperSnapshot, HilogAnalyzer, HilogCollector, type HilogLevel, type HilogLine, type HilogMatch, type HilogParseOptions, type HilogRule, type HiperfCapture, type HiperfCollectOptions, HiperfCollector, type HiprofilerCollectOptions, type HiprofilerCollectRequest, HiprofilerCollector, type HiprofilerConfigOptions, type HiprofilerPlugin, type HiprofilerPluginName, HitraceCollector, IGNORED_ATTRIBUTES, type ImageComparison, IngestError, InstantQuery, type InventoryFile, MAX_QUERY_LIMIT, METRIC_DIRECTIONS, MIN_BUFFER_PAGES, MemMeasureQuery, MemoryAnalyzer, MemoryMeasureAnalyzer, type MemoryPluginOptions, type MetadataPattern, type Metric, type MetricDelta, type MetricDirection, type MetricUnit, type NamedQueryDefinition, type NamedQueryInfo, type NamedQueryResult, type NativeCategory, type NativeEventKind, type NativeHookEvent, type NativeHookFrame, NativeHookQuery, type NativeHookStatistic, NativeMemoryAnalyzer, type NativeMemoryResult, type NativeNames, type NativeTimelineBucket, type NativehookOptions, OhosPerfError, type OptimizationPotential, type OversizedFile, PLANE_A_PLUGINS, type PerfCallchain, type PerfFileAttribution, type PerfFunction, type PerfLeafAttribution, PerfQuery, type PerfSampleRow, type PerfThread, type ProbeResult, type ProbeRunner, type ProbeSnapshot, type ProcessInfo, type ProcessMeasure, type ProcessMeasureFilter, ProcessQuery, ProcfsCollector, type ProcfsSample, type ProcfsStatus, type Provenance, type QueryArgument, type QueryContext, type QueryHandle, REPORT_SCHEMA_VERSION, type Rect, type RedundancyLevel, type RedundancyType, type RedundantThreadPattern, type RedundantThreadsSummary, RenderAnalyzer, type ReportGenerator, type ReportInput, type ReportModel, type ReportScenario, type ReportSection, type ReportSummary, type ReportTotals, type RgbaImage, RsSkipAnalyzer, type RsSkipFrame, type RsSkipResult, type RuleMatch, type RuleMatchKind, type RunOptions, type RunResult, type RunStepResult, type RunnerCollectOptions, type RunnerDevice, SECTION_TITLES, type Scenario, type ScenarioAction, ScenarioRunner, type ScenarioStep, Scene, type SceneLayout, type SceneMetadata, type SceneStepRef, SchedQuery, type SchedSlice, type ScreenshotCapture, ScreenshotCollector, type SmapsRollup, StartupAnalyzer, StartupQuery, type StartupRecord, type StepCapture, Streamer, StreamerNotFoundError, type StreamerOptions, type SymbolStat, SymbolsAnalyzer, TECH_RULES, type TechRule, type ThreadAnalysis, type ThreadAnalysisSummary, ThreadAnalyzer, type ThreadInfo, ThreadQuery, type ThreadState, ThreadStateQuery, type ThreadWakeupResult, type ThreadWakeupThread, type TimeRange, type TraceCollectOptions, UI_DIFF_FILES, UiAnalyzer, type UiCompareOptions, type UiDiff, type UiDiffSide, type UiNode, type UiTreeDiff, type UiTreeDifference, UitestCollector, type UnreleasedRow, type VsyncAnalysis, VsyncAnalyzer, type VsyncPeriod, type VsyncPeriodKind, type VsyncSeverity, type WakeupEvent, type WindowHitches, type ZipArchive, type ZipEntry, aggregateUnreleased, analyzeHap, analyzeThreadWakeup, buildHiprofilerConfig, buildInventory, buildMatrix, buildNativeTimeline, buildReport, categorize, classifyNativePath, compareImages, compareResults, compareSceneDirs, compileRules, computeBinderAnalysis, computeComponentReuse, computeFaultTree, computeFpsWindows, computeGc, computeRsSkip, computeThreadAnalysis, computeVsyncAnomalies, connect, createSceneLayout, decodePng, defaultAnalyzers, dhash, diffTrees, encodePng, escapeHtml, evidence, executeAction, filterEmptyFrames, flattenUiTree, ftracePlugin, gpuPlugin, hapSection, hiperfRecordCommand, ingestScene, isUnresolvedSymbol, isZip, lookupQuery, markRegions, matchHapRules, matchRules, memoryPlugin, metric, nativeEventKind, nativehookPlugin, nodeIdentity, openDb, openZip, pairNativeMemory, parseBounds, parseFpsCounts, parseHilogLine, parseHilogText, parseHiperfSummary, parseHitches, parseProcfsStatus, parseScenario, parseSmapsRollup, queryDefinitions, readHidumperCapture, readHilogText, readProcfsSamples, readSceneMetadata, readUiTree, renderEvidenceCsv, renderFlamegraphHtml, renderFlamegraphSvg, renderMetricsCsv, renderReportHtml, renderReportJson, renderReportXlsx, renderSummaryJson, renderUiDiffHtml, resolveAppIdentity, resolveAppIpids, resolveQueryLimit, round2HalfEven, runAnalyzerSections, runAnalyzers, runDrillDown, runNamedQuery, runProbe, summarizeReport, tableRowCounts, unknownQueryError, validateRules, writeProcfsSamples, writeRunFiles, writeSceneMetadata, xpowerPlugin };
|