profiler-md 0.9.0 → 0.9.1

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/dist/index.d.mts CHANGED
@@ -164,6 +164,12 @@ type CallGraph = {
164
164
  * call stack profile, a call graph has no count to fall back on.
165
165
  */
166
166
  metrics: Metric[];
167
+ /**
168
+ * What one unit of an arc's {@link CallGraphArc.callCount} measures, or
169
+ * `null` when the call counts measure nothing (counts the profiler estimated
170
+ * rather than recorded).
171
+ */
172
+ callCountMetric: Metric | null;
167
173
  /**
168
174
  * Each function's frame record (name and definition location),
169
175
  * index-aligned with {@link CallGraph.functions}. The aggregator merges
@@ -184,7 +190,7 @@ type CallGraphFunction = {
184
190
  type CallGraphArc = {
185
191
  /** The called function's index in {@link CallGraph.functions}. */
186
192
  callee: number;
187
- /** The recorded number of calls, or `0` when the format records none. */
193
+ /** The number of calls the arc records. */
188
194
  callCount: number;
189
195
  /**
190
196
  * The calls' total cost per metric: cost recorded in the callee and its
@@ -479,7 +485,6 @@ type TraceSpan = TraceEventFields & {
479
485
  start?: number;
480
486
  /** Absent for a span the input never ends. */
481
487
  duration?: number;
482
- /** The span's CPU time, when recorded. */
483
488
  cpuDuration?: number;
484
489
  /**
485
490
  * Whether the span is an operation that stays pending while threads do
@@ -854,6 +859,7 @@ declare const originSpecs: ({
854
859
  readonly categorizeHeapSnapshotConstructor: (name: string) => HeapSnapshotNodeCategory | undefined;
855
860
  readonly matchHeapSnapshotEdgeName: (name: string) => string | undefined;
856
861
  readonly categorizeTraceEvent: (event: {
862
+ readonly type: "span" | "instant";
857
863
  readonly name: string;
858
864
  readonly declaredCategories?: readonly string[] | undefined;
859
865
  }) => "script" | "parsing" | "compilation" | "garbage-collection-pause" | "garbage-collection" | "style" | "layout" | "paint" | "io" | "other" | undefined;
@@ -902,7 +908,8 @@ declare const originSpecs: ({
902
908
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
903
909
  readonly categorizeHeapSnapshotConstructor: (name: string) => HeapSnapshotNodeCategory | undefined;
904
910
  readonly matchHeapSnapshotEdgeName: (name: string) => string | undefined;
905
- readonly categorizeTraceEvent: ({ name, declaredCategories }: DeepReadonly<Pick<TraceEvent, `name` | `declaredCategories`>>) => TraceEventCategory | undefined;
911
+ readonly normalizeSourceReference: (reference: SourceReference) => SourceReference;
912
+ readonly categorizeTraceEvent: ({ type, name, declaredCategories }: DeepReadonly<Pick<TraceEvent, `type` | `name` | `declaredCategories`>>) => TraceEventCategory | undefined;
906
913
  readonly normalizeTraceEvent: (event: TraceEvent) => NormalizedTraceEvent;
907
914
  } | {
908
915
  readonly id: "node-pprof";
@@ -1032,9 +1039,17 @@ declare const originSpecs: ({
1032
1039
  readonly column?: number | undefined;
1033
1040
  } | undefined;
1034
1041
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1042
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame | null;
1035
1043
  } | {
1036
1044
  readonly id: "pprof-jl";
1037
1045
  readonly formats: ["pprof"];
1046
+ readonly countMetric: () => {
1047
+ type: `count`;
1048
+ proseUnit: string;
1049
+ } & {
1050
+ phrases: MetricPhrases;
1051
+ improvement: MetricImprovement;
1052
+ };
1038
1053
  readonly isMarkerEntry: (entry: {
1039
1054
  readonly name?: string | undefined;
1040
1055
  readonly location?: {
@@ -1176,6 +1191,7 @@ declare const originSpecs: ({
1176
1191
  }) => boolean;
1177
1192
  readonly isOriginHint: (hint: string) => boolean;
1178
1193
  readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1194
+ readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
1179
1195
  readonly normalizeStackFrame: (input: StackFrame, format: "callgrind" | "collapsed" | "ghc-eventlog" | "ghc-json-profile" | "hprof" | "jfr" | "jsc-heap-snapshot" | "memray" | "perf" | "pprof" | "speedscope" | "systing" | "trace-event" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => StackFrame;
1180
1196
  } | {
1181
1197
  readonly id: "tachyon";
@@ -1338,7 +1354,7 @@ declare const originSpecs: ({
1338
1354
  readonly column?: number | undefined;
1339
1355
  } | undefined;
1340
1356
  }) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
1341
- readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
1357
+ readonly normalizeStackFrame: (input: StackFrame) => StackFrame | null;
1342
1358
  } | {
1343
1359
  readonly id: "nix";
1344
1360
  readonly title: "Nix";
@@ -1406,6 +1422,7 @@ declare const originSpecs: ({
1406
1422
  readonly column?: number | undefined;
1407
1423
  } | undefined;
1408
1424
  }) => boolean;
1425
+ readonly countMetric: (format: "callgrind" | "collapsed" | "ghc-eventlog" | "ghc-json-profile" | "hprof" | "jfr" | "jsc-heap-snapshot" | "memray" | "perf" | "pprof" | "speedscope" | "systing" | "trace-event" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => null | undefined;
1409
1426
  readonly isOriginHint: (hint: string, format: "callgrind" | "collapsed" | "ghc-eventlog" | "ghc-json-profile" | "hprof" | "jfr" | "jsc-heap-snapshot" | "memray" | "perf" | "pprof" | "speedscope" | "systing" | "trace-event" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => boolean;
1410
1427
  readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
1411
1428
  readonly categorizeEntry: (entry: {
@@ -1501,6 +1518,7 @@ declare const originSpecs: ({
1501
1518
  readonly id: "excimer";
1502
1519
  readonly title: "Excimer";
1503
1520
  readonly formats: ["collapsed", "speedscope"];
1521
+ readonly countMetric: (format: "callgrind" | "collapsed" | "ghc-eventlog" | "ghc-json-profile" | "hprof" | "jfr" | "jsc-heap-snapshot" | "memray" | "perf" | "pprof" | "speedscope" | "systing" | "trace-event" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => null | undefined;
1504
1522
  readonly isMarkerEntry: ({ name }: {
1505
1523
  readonly name?: string | undefined;
1506
1524
  readonly location?: {
@@ -1575,6 +1593,7 @@ declare const originSpecs: ({
1575
1593
  readonly isOriginHint: (hint: string) => boolean;
1576
1594
  readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1577
1595
  readonly categorizeTraceEvent: ({ name }: {
1596
+ readonly type: "span" | "instant";
1578
1597
  readonly name: string;
1579
1598
  readonly declaredCategories?: readonly string[] | undefined;
1580
1599
  }) => "parsing" | "compilation";
@@ -1586,6 +1605,7 @@ declare const originSpecs: ({
1586
1605
  readonly isMarkerEntry: () => false;
1587
1606
  readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
1588
1607
  readonly categorizeTraceEvent: ({ declaredCategories }: {
1608
+ readonly type: "span" | "instant";
1589
1609
  readonly name: string;
1590
1610
  readonly declaredCategories?: readonly string[] | undefined;
1591
1611
  }) => "parsing" | "compilation";
@@ -3335,6 +3355,8 @@ type AggregatedCallGraph = {
3335
3355
  /** @see {@link AggregatedCallStackProfile.context} */
3336
3356
  context: ProfileToMdContext;
3337
3357
  metrics: Metric[];
3358
+ /** @see {@link CallGraph.callCountMetric} */
3359
+ callCountMetric: Metric | null;
3338
3360
  /**
3339
3361
  * For each metric in {@link AggregatedCallGraph.metrics}, the whole
3340
3362
  * input's recorded cost: the sum of every function's self values.
@@ -3381,7 +3403,7 @@ type AggregatedCallGraphFunction = {
3381
3403
  /** One function's recorded costs during calls from a given direct caller. */
3382
3404
  type AggregatedCallGraphCallerMetrics = {
3383
3405
  caller: AggregatedCallGraphFunction;
3384
- /** The recorded number of calls, or `0` when the format records none. */
3406
+ /** The number of calls the arc records. */
3385
3407
  callCount: number;
3386
3408
  /**
3387
3409
  * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
@@ -3392,7 +3414,7 @@ type AggregatedCallGraphCallerMetrics = {
3392
3414
  /** One function's recorded costs during its calls to a given direct callee. */
3393
3415
  type AggregatedCallGraphCalleeMetrics = {
3394
3416
  callee: AggregatedCallGraphFunction;
3395
- /** The recorded number of calls, or `0` when the format records none. */
3417
+ /** The number of calls the arc records. */
3396
3418
  callCount: number;
3397
3419
  /**
3398
3420
  * For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
@@ -3550,8 +3572,8 @@ type RetainerPathEdge = RetainerEdge | {
3550
3572
  * Aggregates one {@link HeapSnapshot}.
3551
3573
  *
3552
3574
  * The constructor computes everything that needs no origin, including the
3553
- * entries origin detection reads. {@link aggregate} categorizes under the
3554
- * resolved origin.
3575
+ * entries origin detection reads. {@link aggregate} normalizes locations and
3576
+ * categorizes under the resolved origin.
3555
3577
  */
3556
3578
  declare class HeapSnapshotAggregator implements InputAggregator<AggregatedHeapSnapshot> {
3557
3579
  #private;
@@ -3860,7 +3882,7 @@ export declare const diffProfilesAsync: (base: ProfileInput<AsyncProfileData>, c
3860
3882
  * a failure is a bug in this package. The exception is a parser failing on an
3861
3883
  * error it did not classify, which is either an input violating the format in
3862
3884
  * a way the parser does not check or a parser bug. That failure throws a
3863
- * `ProfilerMdError` too, and `mayBeParserBug` identifies it.
3885
+ * `ProfilerMdError` too, and `unclassifiedParseFailures` identifies it.
3864
3886
  */
3865
3887
  export declare class ProfilerMdError extends Error {
3866
3888
  constructor(message: string, options?: ErrorOptions);