hiperf_txt_parser 1.0.5 → 1.0.7

package/README.md

@@ -33,6 +33,9 @@ import {
 - `formatPerfDataToText(data: PerfData): string`
 - `formatPerfDataToJson(data: PerfData): Array<{ issuce: "unknow"; call_chain: string }>`
 - `filterByTgid(data: PerfData, tgid: number): PerfData`（仅保留 `pid === tgid` 的 RecordSample）
+- `parseTraceFormat(text: string): ParsedTraceFormat`（解析 `sample/trace_format` 风格文本）
+- `parseCommonFieldsFromRaw(raw: Uint8Array, format: ParsedTraceFormat): Record<string, number | bigint>`（按 format 仅解析 `common_*` 字段，小端）
+- `rawHexLinesToBuffer(lines): Uint8Array`（将 perf 文本里 raw 段的 hex 行拼成字节缓冲，便于喂给 `parseCommonFieldsFromRaw`）
 
 ## 快速示例
 

package/dist/backtrace.js

@@ -32,6 +32,10 @@ export function toBackTraceStacks(data) {
             return sample;
         }
         const frameLines = backtrace ? backtrace.split("\n") : [];
+        if (frameLines.length === 0) {
+            const { callchainFrames, ...rest } = sample;
+            return rest;
+        }
         return {
             ...sample,
             callchainFrames: {

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { parsePerfData, filterByTgid } from "./parser.js";
 export { formatPerfDataToText, formatPerfDataToJson } from "./serializer.js";
 export { toBackTraceStack, toBackTraceStacks } from "./backtrace.js";
+export { parseTraceFormat, parseCommonFieldsFromRaw, parseAllFieldsFromRaw, rawHexLinesToBuffer, buildTraceParserRegistry, decodeRawByRegistry, decodePerfRawData, } from "./traceFormat.js";
+export type { ParsedTraceFormat, TraceFormatField, TraceParserRegistry, DecodedRawSample, } from "./traceFormat.js";
 export type { PerfData, RecordSample } from "./types.js";
 export type { RecordSampleJsonExportItem } from "./serializer.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { parsePerfData, filterByTgid } from "./parser.js";
 export { formatPerfDataToText, formatPerfDataToJson } from "./serializer.js";
 export { toBackTraceStack, toBackTraceStacks } from "./backtrace.js";
+export { parseTraceFormat, parseCommonFieldsFromRaw, parseAllFieldsFromRaw, rawHexLinesToBuffer, buildTraceParserRegistry, decodeRawByRegistry, decodePerfRawData, } from "./traceFormat.js";

package/dist/traceFormat.d.ts

@@ -0,0 +1,70 @@
+import type { PerfData } from "./types.js";
+/**
+ * perf trace 事件 format 段中的单字段描述（与 sample/trace_format 一致）
+ */
+export interface TraceFormatField {
+    /** 完整类型串，如 "unsigned short"、"int" */
+    typeName: string;
+    /** 字段名，如 common_type、args[6] */
+    name: string;
+    offset: number;
+    size: number;
+    signed: boolean;
+}
+export interface ParsedTraceFormat {
+    eventName?: string;
+    eventId?: number;
+    printFmt?: string;
+    printArgs?: string[];
+    fields: TraceFormatField[];
+}
+export interface TraceParserRegistry {
+    byEventId: Map<number, ParsedTraceFormat>;
+    commonFormat?: ParsedTraceFormat;
+}
+export interface DecodedRawSample {
+    sampleIndex: number;
+    commonType?: number;
+    commonFields: Record<string, number | bigint>;
+    eventName?: string;
+    renderedText?: string;
+    skipped: boolean;
+}
+/**
+ * 解析 sample/trace_format 风格的文本，得到字段列表
+ */
+export declare function parseTraceFormat(text: string): ParsedTraceFormat;
+/**
+ * 仅解析 format 中 common_* 字段（按 offset/size/signed，小端）
+ */
+export declare function parseCommonFieldsFromRaw(raw: Uint8Array, format: ParsedTraceFormat): Record<string, number | bigint>;
+/**
+ * 解析 format 中全部字段（含数组），数组字段名会去掉 []，如 args[6] => args: [...]
+ */
+export declare function parseAllFieldsFromRaw(raw: Uint8Array, format: ParsedTraceFormat): Record<string, number | bigint | Array<number | bigint>>;
+/**
+ * 将 perf 文本里 raw 段的 hex 行拼成连续字节（小端：每行一个数值，宽度由 hex 位数决定，4→2 字节，8→4 字节，16→8 字节）
+ */
+export declare function rawHexLinesToBuffer(lines: Array<{
+    hex: string;
+}>): Uint8Array;
+/**
+ * 从多个 trace_format 文本构建解析器集合（按 event ID 索引）
+ */
+export declare function buildTraceParserRegistry(formatTexts: string[]): TraceParserRegistry;
+/**
+ * 对一条 raw 数据先解 common_*，再按 common_type 选择解析器，最后按 print fmt 渲染。
+ * 找不到解析器时返回 skipped=true，并打印 common_type。
+ */
+export declare function decodeRawByRegistry(raw: Uint8Array, registry: TraceParserRegistry): Omit<DecodedRawSample, "sampleIndex">;
+/**
+ * 批量处理 perfData 的 raw 数据。仅处理有 raw 的 sample。
+ */
+/**
+ * 对 PerfData 中每个 record sample 的 raw 段进行 trace 解码，并将解码结果“替换回 raw 段内容”。
+ *
+ * 规则：
+ * - 若找到 common_type 对应解析器：将 print fmt 渲染结果写入 `sample.raw.lines`（一行）。
+ * - 若找不到解析器：放弃解析，并将 `common_type` 写入 `sample.raw.lines`（一行）。
+ */
+export declare function decodePerfRawData(perfData: PerfData, registry: TraceParserRegistry): PerfData;

package/dist/traceFormat.js

@@ -0,0 +1,328 @@
+const FIELD_LINE_RE = /^\s*field:([^;]+);\s*offset:(\d+);\s*size:(\d+);\s*signed:([01]);/;
+function splitTypeAndName(rest) {
+    const trimmed = rest.trim();
+    const m = trimmed.match(/^(.+?)\s+(\w+(?:\[[^\]]*])?)$/);
+    if (!m) {
+        return { typeName: trimmed, name: trimmed };
+    }
+    return { typeName: m[1].trim(), name: m[2] };
+}
+/**
+ * 解析 sample/trace_format 风格的文本，得到字段列表
+ */
+export function parseTraceFormat(text) {
+    const lines = text.split(/\r?\n/);
+    let eventName;
+    let eventId;
+    const fields = [];
+    let printFmt;
+    let printArgs;
+    let inFormat = false;
+    for (const line of lines) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        if (!inFormat) {
+            const nameM = t.match(/^name:\s*(.+)$/);
+            if (nameM) {
+                eventName = nameM[1].trim();
+                continue;
+            }
+            const idM = t.match(/^ID:\s*(\d+)\s*$/);
+            if (idM) {
+                eventId = parseInt(idM[1], 10);
+                continue;
+            }
+            if (t.startsWith("format:")) {
+                inFormat = true;
+                continue;
+            }
+            continue;
+        }
+        if (t.startsWith("print fmt:")) {
+            const pf = t.match(/^print fmt:\s*"([^"]*)"\s*(?:,\s*(.*))?$/);
+            if (pf) {
+                printFmt = pf[1];
+                const argsPart = pf[2];
+                if (argsPart) {
+                    const exprs = argsPart.match(/REC->[^,]+/g);
+                    printArgs = exprs ? exprs.map((s) => s.trim()) : [];
+                }
+                else {
+                    printArgs = [];
+                }
+            }
+            break;
+        }
+        const fm = line.match(FIELD_LINE_RE);
+        if (!fm)
+            continue;
+        const { typeName, name } = splitTypeAndName(fm[1]);
+        fields.push({
+            typeName,
+            name,
+            offset: parseInt(fm[2], 10),
+            size: parseInt(fm[3], 10),
+            signed: fm[4] === "1",
+        });
+    }
+    return { eventName, eventId, printFmt, printArgs, fields };
+}
+function normalizeType(t) {
+    return t.replace(/\s+/g, " ").trim().toLowerCase();
+}
+/**
+ * 从 little-endian 原始缓冲区按字段描述读一个标量
+ */
+function readFieldScalar(view, field) {
+    const { offset, size, signed, typeName } = field;
+    if (offset + size > view.byteLength)
+        return undefined;
+    const t = normalizeType(typeName);
+    if (size === 1) {
+        if (signed || t === "signed char") {
+            return view.getInt8(offset);
+        }
+        return view.getUint8(offset);
+    }
+    if (size === 2) {
+        if (signed || t === "short") {
+            return view.getInt16(offset, true);
+        }
+        return view.getUint16(offset, true);
+    }
+    if (size === 4) {
+        if (t.includes("float")) {
+            return view.getFloat32(offset, true);
+        }
+        if (signed || t === "int" || t === "long" /* 32-bit 内核上 */) {
+            return view.getInt32(offset, true);
+        }
+        return view.getUint32(offset, true);
+    }
+    if (size === 8) {
+        if (t.includes("double")) {
+            return view.getFloat64(offset, true);
+        }
+        if (signed || t === "long" || t === "long long" || t === "__s64") {
+            return view.getBigInt64(offset, true);
+        }
+        return view.getBigUint64(offset, true);
+    }
+    return undefined;
+}
+function parseArrayName(name) {
+    const m = name.match(/^(\w+)\[(\d+)\]$/);
+    if (!m)
+        return undefined;
+    return { baseName: m[1], len: parseInt(m[2], 10) };
+}
+function readFieldValue(view, field) {
+    const arr = parseArrayName(field.name);
+    if (!arr)
+        return readFieldScalar(view, field);
+    if (arr.len <= 0)
+        return [];
+    const elemSize = Math.floor(field.size / arr.len);
+    if (elemSize <= 0)
+        return undefined;
+    const values = [];
+    for (let i = 0; i < arr.len; i++) {
+        const elemField = {
+            ...field,
+            name: arr.baseName,
+            offset: field.offset + i * elemSize,
+            size: elemSize,
+        };
+        const v = readFieldScalar(view, elemField);
+        if (v === undefined)
+            return undefined;
+        values.push(v);
+    }
+    return values;
+}
+/**
+ * 仅解析 format 中 common_* 字段（按 offset/size/signed，小端）
+ */
+export function parseCommonFieldsFromRaw(raw, format) {
+    const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    const out = {};
+    for (const field of format.fields) {
+        if (!field.name.startsWith("common_"))
+            continue;
+        const v = readFieldScalar(view, field);
+        if (v !== undefined) {
+            out[field.name] = v;
+        }
+    }
+    return out;
+}
+/**
+ * 解析 format 中全部字段（含数组），数组字段名会去掉 []，如 args[6] => args: [...]
+ */
+export function parseAllFieldsFromRaw(raw, format) {
+    const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength);
+    const out = {};
+    for (const field of format.fields) {
+        const arr = parseArrayName(field.name);
+        const key = arr ? arr.baseName : field.name;
+        const v = readFieldValue(view, field);
+        if (v !== undefined) {
+            out[key] = v;
+        }
+    }
+    return out;
+}
+/**
+ * 将 perf 文本里 raw 段的 hex 行拼成连续字节（小端：每行一个数值，宽度由 hex 位数决定，4→2 字节，8→4 字节，16→8 字节）
+ */
+export function rawHexLinesToBuffer(lines) {
+    const chunks = [];
+    for (const { hex } of lines) {
+        const s = hex.replace(/^0x/i, "").trim();
+        if (!s)
+            continue;
+        const byteLen = Math.ceil(s.length / 2);
+        const width = byteLen <= 2 ? 2 : byteLen <= 4 ? 4 : 8;
+        let value = BigInt("0x" + s);
+        const mask = (1n << BigInt(width * 8)) - 1n;
+        value &= mask;
+        for (let i = 0; i < width; i++) {
+            chunks.push(Number((value >> BigInt(8 * i)) & 0xffn));
+        }
+    }
+    return Uint8Array.from(chunks);
+}
+/**
+ * 从多个 trace_format 文本构建解析器集合（按 event ID 索引）
+ */
+export function buildTraceParserRegistry(formatTexts) {
+    const byEventId = new Map();
+    let commonFormat;
+    for (const text of formatTexts) {
+        const fmt = parseTraceFormat(text);
+        if (fmt.eventId !== undefined) {
+            byEventId.set(fmt.eventId, fmt);
+            if (!commonFormat && fmt.fields.some((f) => f.name === "common_type")) {
+                commonFormat = fmt;
+            }
+        }
+    }
+    return { byEventId, commonFormat };
+}
+function formatArgBySpecifier(value, spec) {
+    const isBig = typeof value === "bigint";
+    const lower = spec.toLowerCase();
+    if (lower === "x") {
+        return isBig ? value.toString(16) : Math.trunc(value).toString(16);
+    }
+    if (lower === "u") {
+        if (isBig)
+            return (value < 0n ? 0n : value).toString(10);
+        return Math.max(0, Math.trunc(value)).toString(10);
+    }
+    return isBig ? value.toString(10) : Math.trunc(value).toString(10);
+}
+function renderPrintFmt(printFmt, printArgs, fieldMap) {
+    const values = [];
+    for (const expr of printArgs ?? []) {
+        const em = expr.match(/^REC->(\w+)(?:\[(\d+)])?$/);
+        if (!em) {
+            values.push(0);
+            continue;
+        }
+        const name = em[1];
+        const idxRaw = em[2];
+        const v = fieldMap[name];
+        if (idxRaw !== undefined) {
+            const idx = parseInt(idxRaw, 10);
+            if (Array.isArray(v) && idx >= 0 && idx < v.length) {
+                values.push(v[idx]);
+            }
+            else {
+                values.push(0);
+            }
+        }
+        else if (Array.isArray(v)) {
+            values.push(v[0] ?? 0);
+        }
+        else if (v !== undefined) {
+            values.push(v);
+        }
+        else {
+            values.push(0);
+        }
+    }
+    let valueIdx = 0;
+    return printFmt.replace(/%[0-9]*[lh]*([duxX])/g, (_all, spec) => {
+        const v = values[valueIdx++] ?? 0;
+        return formatArgBySpecifier(v, spec);
+    });
+}
+/**
+ * 对一条 raw 数据先解 common_*，再按 common_type 选择解析器，最后按 print fmt 渲染。
+ * 找不到解析器时返回 skipped=true，并打印 common_type。
+ */
+export function decodeRawByRegistry(raw, registry) {
+    const commonType = raw.length >= 2 ? Number(new DataView(raw.buffer, raw.byteOffset, raw.byteLength).getUint16(0, true)) : undefined;
+    const commonFields = registry.commonFormat !== undefined
+        ? parseCommonFieldsFromRaw(raw, registry.commonFormat)
+        : {};
+    const commonTypeFromFields = commonFields.common_type;
+    const eventId = typeof commonTypeFromFields === "bigint"
+        ? Number(commonTypeFromFields)
+        : typeof commonTypeFromFields === "number"
+            ? commonTypeFromFields
+            : commonType;
+    if (eventId === undefined || !registry.byEventId.has(eventId)) {
+        console.info(`[hiperf_txt_parser] trace parser not found for common_type=${eventId ?? "unknown"}`);
+        return {
+            commonType: eventId,
+            commonFields,
+            skipped: true,
+        };
+    }
+    const fmt = registry.byEventId.get(eventId);
+    const allFields = parseAllFieldsFromRaw(raw, fmt);
+    const renderedText = fmt.printFmt
+        ? renderPrintFmt(fmt.printFmt, fmt.printArgs, allFields)
+        : undefined;
+    return {
+        commonType: eventId,
+        commonFields,
+        eventName: fmt.eventName,
+        renderedText,
+        skipped: false,
+    };
+}
+/**
+ * 批量处理 perfData 的 raw 数据。仅处理有 raw 的 sample。
+ */
+/**
+ * 对 PerfData 中每个 record sample 的 raw 段进行 trace 解码，并将解码结果“替换回 raw 段内容”。
+ *
+ * 规则：
+ * - 若找到 common_type 对应解析器：将 print fmt 渲染结果写入 `sample.raw.lines`（一行）。
+ * - 若找不到解析器：放弃解析，并将 `common_type` 写入 `sample.raw.lines`（一行）。
+ */
+export function decodePerfRawData(perfData, registry) {
+    return {
+        recordSamples: perfData.recordSamples.map((sample) => {
+            if (!sample.raw || sample.raw.lines.length === 0)
+                return sample;
+            const raw = rawHexLinesToBuffer(sample.raw.lines);
+            const decoded = decodeRawByRegistry(raw, registry);
+            const replacement = decoded.renderedText ??
+                (decoded.commonType !== undefined ? String(decoded.commonType) : "");
+            if (!replacement)
+                return sample;
+            return {
+                ...sample,
+                raw: {
+                    ...sample.raw,
+                    lines: [{ hex: replacement }],
+                },
+            };
+        }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hiperf_txt_parser",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Parse perf data.txt and output structured TypeScript data",
   "type": "module",
   "main": "dist/index.js",