@watchtowerobservability/node 0.7.3 → 0.7.4

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/CHANGELOG.md CHANGED
@@ -2,6 +2,10 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ## 0.7.4
6
+
7
+ - Heap profiling (opt-in): `startProfiling({ types: ['cpu', 'heap'] })` or `WT_PROFILING_TYPES=cpu,heap` adds V8's sampling heap profiler. Each period posts a live-heap pprof with sample types `inuse_objects/count` and `inuse_space/bytes` to `/v1/profiles` (`heapIntervalBytes`, default 512 KiB). The default stays cpu only. New exports `parseProfilingTypes`, `foldHeap`.
8
+
5
9
  ## 0.7.3
6
10
 
7
11
  - URL scrubbing is narrower: only secret-looking path segments are redacted (UUIDs, hex runs >= 16, JWTs, digit runs >= 16, random-looking tokens >= 16 chars mixing letters and digits). Hosts are never touched (also scheme-relative `//host`); readable words, kebab/snake slugs and short ids stay (`/atlas/.well-known/jwks.json`, `/gallery/legal-consultation-intake`, `/config/a1b2c3d4`). Behaviour change: 10 to 15 character ids that used to be redacted now show. Same rule as the browser SDK and the gateway. `looksSecret` is now `isSecretSegment`.
@@ -4,3 +4,5 @@
4
4
  * sample labels. Frame names keep their `(file:line)` suffix; one function per distinct frame.
5
5
  */
6
6
  export declare function foldedToPprof(counts: Map<string, number>, periodNs: number, startMs: number, durationMs: number): Uint8Array;
7
+ /** Live heap stacks (`a;b;c` root first) with `[objects, bytes]` to a pprof with inuse_objects/count and inuse_space/bytes. */
8
+ export declare function heapToPprof(stacks: Map<string, [number, number]>, periodBytes: number, startMs: number, durationMs: number): Uint8Array;
package/dist/cjs/pprof.js CHANGED
@@ -1,6 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.foldedToPprof = foldedToPprof;
4
+ exports.heapToPprof = heapToPprof;
4
5
  // Minimal pprof (profile.proto) encoder, no dependency: folded stacks in, gzipped protobuf out.
5
6
  const node_zlib_1 = require("node:zlib");
6
7
  /** Protobuf writer for the handful of field shapes profile.proto needs. */
@@ -44,6 +45,16 @@ class Pb {
44
45
  * sample labels. Frame names keep their `(file:line)` suffix; one function per distinct frame.
45
46
  */
46
47
  function foldedToPprof(counts, periodNs, startMs, durationMs) {
48
+ const rows = new Map();
49
+ for (const [k, n] of counts)
50
+ rows.set(k, [n, n * periodNs]);
51
+ return encodePprof([['samples', 'count'], ['cpu', 'nanoseconds']], rows, ['cpu', 'nanoseconds'], periodNs, startMs, durationMs);
52
+ }
53
+ /** Live heap stacks (`a;b;c` root first) with `[objects, bytes]` to a pprof with inuse_objects/count and inuse_space/bytes. */
54
+ function heapToPprof(stacks, periodBytes, startMs, durationMs) {
55
+ return encodePprof([['inuse_objects', 'count'], ['inuse_space', 'bytes']], stacks, ['space', 'bytes'], periodBytes, startMs, durationMs);
56
+ }
57
+ function encodePprof(types, counts, periodType, period, startMs, durationMs) {
47
58
  const strings = [''];
48
59
  const index = new Map([['', 0]]);
49
60
  const s = (x) => {
@@ -55,10 +66,12 @@ function foldedToPprof(counts, periodNs, startMs, durationMs) {
55
66
  }
56
67
  return i;
57
68
  };
58
- const vt = (type, unit) => new Pb().int(1, s(type)).int(2, s(unit));
69
+ const vt = ([type, unit]) => new Pb().int(1, s(type)).int(2, s(unit));
59
70
  const frames = new Map();
60
- const out = new Pb().msg(1, vt('samples', 'count')).msg(1, vt('cpu', 'nanoseconds'));
61
- for (const [key, n] of counts) {
71
+ const out = new Pb();
72
+ for (const t of types)
73
+ out.msg(1, vt(t));
74
+ for (const [key, values] of counts) {
62
75
  const tab = key.indexOf('\t');
63
76
  const labels = tab >= 0 ? key.slice(0, tab) : '';
64
77
  // pprof location ids are leaf first
@@ -68,7 +81,7 @@ function foldedToPprof(counts, periodNs, startMs, durationMs) {
68
81
  frames.set(f, (id = frames.size + 1));
69
82
  return id;
70
83
  });
71
- const sample = new Pb().packed(1, ids).packed(2, [n, n * periodNs]);
84
+ const sample = new Pb().packed(1, ids).packed(2, values);
72
85
  for (const kv of labels ? labels.split(',') : []) {
73
86
  const eq = kv.indexOf('=');
74
87
  if (eq > 0)
@@ -81,7 +94,7 @@ function foldedToPprof(counts, periodNs, startMs, durationMs) {
81
94
  out.msg(5, new Pb().int(1, id).int(2, s(f))); // Function{id, name}
82
95
  }
83
96
  out.int(9, BigInt(Math.round(startMs)) * 1000000n).int(10, BigInt(Math.round(durationMs)) * 1000000n);
84
- out.msg(11, vt('cpu', 'nanoseconds')).int(12, periodNs);
97
+ out.msg(11, vt(periodType)).int(12, period);
85
98
  for (const str of strings)
86
99
  out.bytes(6, Buffer.from(str));
87
100
  return new Uint8Array((0, node_zlib_1.gzipSync)(Uint8Array.from(out.b)));
@@ -38,7 +38,29 @@ export declare function withSpan<T>(fn: () => T, ids?: {
38
38
  }): T;
39
39
  /** Takes the intervals a profile up to `until` can need; open ones stay for the next profile. */
40
40
  export declare function takeIntervals(until: number): SpanInterval[];
41
+ /** V8's sampling heap profile: a tree of live (not yet collected) sampled allocations. */
42
+ export interface HeapProfileNode {
43
+ callFrame: CallFrame;
44
+ selfSize: number;
45
+ id: number;
46
+ children?: HeapProfileNode[];
47
+ }
48
+ export interface HeapProfile {
49
+ head: HeapProfileNode;
50
+ samples?: {
51
+ size: number;
52
+ nodeId: number;
53
+ ordinal: number;
54
+ }[];
55
+ }
56
+ export type ProfileType = 'cpu' | 'heap';
57
+ /** `cpu,heap` (WT_PROFILING_TYPES) to types; unknown names are ignored, nothing valid means cpu only. */
58
+ export declare function parseProfilingTypes(v?: string): ProfileType[];
41
59
  export interface ProfilerOptions {
60
+ /** Profile types (default: WT_PROFILING_TYPES, else `['cpu']`). `heap` adds V8's sampling heap profiler. */
61
+ types?: ProfileType[];
62
+ /** Heap sampling interval in bytes (default 524 288). */
63
+ heapIntervalBytes?: number;
42
64
  /** Ingest key; defaults to WT_INGEST_KEY. */
43
65
  apiKey?: string;
44
66
  /** Gateway base URL; defaults to WT_OTLP_ENDPOINT or http://localhost:4318. */
@@ -55,6 +77,11 @@ export interface ProfilerOptions {
55
77
  }
56
78
  /** Root-first folded stacks with their sample counts; V8's synthetic `(root)` is left out. */
57
79
  export declare function foldProfile(p: CpuProfile, spans?: SpanInterval[]): Map<string, number>;
80
+ /**
81
+ * Root-first stacks of live heap with `[objects, bytes]`: bytes are the node's self size, objects the
82
+ * number of sampled allocations that still live in it (at least 1 for a node with bytes).
83
+ */
84
+ export declare function foldHeap(p: HeapProfile): Map<string, [number, number]>;
58
85
  export declare function foldedBody(counts: Map<string, number>): string;
59
86
  /** `/v1/profiles?format=pprof&service=…&version=…` on the gateway. */
60
87
  export declare function profilesUrl(endpoint: string, service: string, version?: string): string;
@@ -69,6 +96,8 @@ export declare class Profiler {
69
96
  private readonly tags;
70
97
  private readonly intervalUs;
71
98
  private readonly periodMs;
99
+ private readonly types;
100
+ private readonly heapIntervalBytes;
72
101
  private session?;
73
102
  private timer?;
74
103
  private from;
@@ -77,7 +106,9 @@ export declare class Profiler {
77
106
  start(): Promise<this>;
78
107
  /** Stop the current profile, upload it and (when `restart`) start the next one. */
79
108
  flush(restart: boolean): Promise<void>;
109
+ uploadHeap(stacks: Map<string, [number, number]>, fromS: number, untilS: number): Promise<void>;
80
110
  upload(counts: Map<string, number>, fromS: number, untilS: number): Promise<void>;
111
+ private send;
81
112
  stop(): Promise<void>;
82
113
  }
83
114
  /** Start a [[Profiler]] with the SDK's environment defaults. */
@@ -4,12 +4,14 @@ exports.Profiler = void 0;
4
4
  exports.enableAsyncSpanLabels = enableAsyncSpanLabels;
5
5
  exports.withSpan = withSpan;
6
6
  exports.takeIntervals = takeIntervals;
7
+ exports.parseProfilingTypes = parseProfilingTypes;
7
8
  exports.foldProfile = foldProfile;
9
+ exports.foldHeap = foldHeap;
8
10
  exports.foldedBody = foldedBody;
9
11
  exports.profilesUrl = profilesUrl;
10
12
  exports.ingestUrl = ingestUrl;
11
13
  exports.startProfiling = startProfiling;
12
- // Continuous CPU profiler on V8's own sampler (`node:inspector`, no native addon): every
14
+ // Continuous CPU (and opt-in heap) profiler on V8's own samplers (`node:inspector`, no native addon): every
13
15
  // `periodMs` the CPU profile is folded into stacks, encoded as pprof and posted to the gateway's
14
16
  // `/v1/profiles?format=pprof` with `service` and `version`. Best effort: a failed upload is
15
17
  // counted and dropped. `withSpan` labels samples taken while its function runs, joined
@@ -108,6 +110,11 @@ function prefixAt(sorted, t) {
108
110
  return sorted[i].prefix;
109
111
  return '';
110
112
  }
113
+ /** `cpu,heap` (WT_PROFILING_TYPES) to types; unknown names are ignored, nothing valid means cpu only. */
114
+ function parseProfilingTypes(v) {
115
+ const t = [...new Set((v ?? '').split(',').map((x) => x.trim().toLowerCase()))].filter((x) => x === 'cpu' || x === 'heap');
116
+ return t.length ? t : ['cpu'];
117
+ }
111
118
  const MAX_DEPTH = 128;
112
119
  function frameName(f) {
113
120
  const file = f.url ? f.url.split('/').pop() : '';
@@ -146,6 +153,28 @@ function foldProfile(p, spans = []) {
146
153
  }
147
154
  return counts;
148
155
  }
156
+ /**
157
+ * Root-first stacks of live heap with `[objects, bytes]`: bytes are the node's self size, objects the
158
+ * number of sampled allocations that still live in it (at least 1 for a node with bytes).
159
+ */
160
+ function foldHeap(p) {
161
+ const objs = new Map();
162
+ for (const x of p.samples ?? [])
163
+ objs.set(x.nodeId, (objs.get(x.nodeId) ?? 0) + 1);
164
+ const out = new Map();
165
+ const walk = (n, path) => {
166
+ const names = n.callFrame.functionName === '(root)' ? path : [...path, frameName(n.callFrame)];
167
+ if (n.selfSize > 0 && names.length && names.length <= MAX_DEPTH) {
168
+ const key = names.join(';');
169
+ const cur = out.get(key) ?? [0, 0];
170
+ out.set(key, [cur[0] + Math.max(objs.get(n.id) ?? 0, 1), cur[1] + n.selfSize]);
171
+ }
172
+ for (const c of n.children ?? [])
173
+ walk(c, names);
174
+ };
175
+ walk(p.head, []);
176
+ return out;
177
+ }
149
178
  function foldedBody(counts) {
150
179
  let out = '';
151
180
  for (const [k, n] of counts)
@@ -178,6 +207,8 @@ class Profiler {
178
207
  tags;
179
208
  intervalUs;
180
209
  periodMs;
210
+ types;
211
+ heapIntervalBytes;
181
212
  session;
182
213
  timer;
183
214
  from = 0;
@@ -191,6 +222,8 @@ class Profiler {
191
222
  this.tags = { env: process.env.WT_ENVIRONMENT, version: process.env.WT_RELEASE, ...o.tags };
192
223
  this.intervalUs = Math.min(Math.max(o.intervalUs ?? 10_000, 1_000), 1_000_000);
193
224
  this.periodMs = Math.max(o.periodMs ?? 60_000, 1_000);
225
+ this.types = o.types?.length ? o.types : parseProfilingTypes(process.env.WT_PROFILING_TYPES);
226
+ this.heapIntervalBytes = Math.max(o.heapIntervalBytes ?? 524_288, 1024);
194
227
  if (o.asyncSpans)
195
228
  enableAsyncSpanLabels();
196
229
  }
@@ -208,9 +241,14 @@ class Profiler {
208
241
  return this;
209
242
  this.session = new node_inspector_1.Session();
210
243
  this.session.connect();
211
- await this.post('Profiler.enable');
212
- await this.post('Profiler.setSamplingInterval', { interval: this.intervalUs });
213
- await this.post('Profiler.start');
244
+ if (this.types.includes('cpu')) {
245
+ await this.post('Profiler.enable');
246
+ await this.post('Profiler.setSamplingInterval', { interval: this.intervalUs });
247
+ await this.post('Profiler.start');
248
+ }
249
+ if (this.types.includes('heap')) {
250
+ await this.post('HeapProfiler.startSampling', { samplingInterval: this.heapIntervalBytes });
251
+ }
214
252
  this.from = Date.now() / 1000;
215
253
  this.timer = setInterval(() => void this.flush(true), this.periodMs);
216
254
  this.timer.unref();
@@ -221,19 +259,35 @@ class Profiler {
221
259
  if (!this.session)
222
260
  return;
223
261
  const until = Date.now() / 1000;
224
- const { profile } = await this.post('Profiler.stop');
225
262
  const from = this.from;
226
- if (restart) {
227
- await this.post('Profiler.start');
228
- this.from = until;
263
+ let heap;
264
+ if (this.types.includes('heap')) {
265
+ // live-heap snapshot; sampling keeps running
266
+ const { profile } = await this.post('HeapProfiler.getSamplingProfile');
267
+ heap = foldHeap(profile);
229
268
  }
230
- const counts = foldProfile(profile, takeIntervals(nowUs()));
231
- if (counts.size)
269
+ let counts;
270
+ if (this.types.includes('cpu')) {
271
+ const { profile } = await this.post('Profiler.stop');
272
+ if (restart)
273
+ await this.post('Profiler.start');
274
+ counts = foldProfile(profile, takeIntervals(nowUs()));
275
+ }
276
+ if (restart)
277
+ this.from = until;
278
+ if (counts?.size)
232
279
  await this.upload(counts, from, until);
280
+ if (heap?.size)
281
+ await this.uploadHeap(heap, from, until);
282
+ }
283
+ async uploadHeap(stacks, fromS, untilS) {
284
+ await this.send((0, pprof_js_1.heapToPprof)(stacks, this.heapIntervalBytes, fromS * 1000, (untilS - fromS) * 1000));
233
285
  }
234
286
  async upload(counts, fromS, untilS) {
287
+ await this.send((0, pprof_js_1.foldedToPprof)(counts, this.intervalUs * 1000, fromS * 1000, (untilS - fromS) * 1000));
288
+ }
289
+ async send(body) {
235
290
  try {
236
- const body = (0, pprof_js_1.foldedToPprof)(counts, this.intervalUs * 1000, fromS * 1000, (untilS - fromS) * 1000);
237
291
  const r = await fetch(profilesUrl(this.endpoint, this.service, this.tags.version), {
238
292
  method: 'POST', body,
239
293
  headers: { authorization: `Bearer ${this.key}`, 'content-type': 'application/octet-stream' },
@@ -252,6 +306,8 @@ class Profiler {
252
306
  if (this.timer)
253
307
  clearInterval(this.timer);
254
308
  await this.flush(false).catch(() => undefined);
309
+ if (this.types.includes('heap'))
310
+ await this.post('HeapProfiler.stopSampling').catch(() => undefined);
255
311
  this.session?.disconnect();
256
312
  this.session = undefined;
257
313
  }
@@ -1,2 +1,2 @@
1
1
  /** This package's version (test/distro.test.ts checks it against package.json); sent as `telemetry.distro.version`. */
2
- export declare const VERSION = "0.7.3";
2
+ export declare const VERSION = "0.7.4";
@@ -2,4 +2,4 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.VERSION = void 0;
4
4
  /** This package's version (test/distro.test.ts checks it against package.json); sent as `telemetry.distro.version`. */
5
- exports.VERSION = '0.7.3';
5
+ exports.VERSION = '0.7.4';
@@ -4,3 +4,5 @@
4
4
  * sample labels. Frame names keep their `(file:line)` suffix; one function per distinct frame.
5
5
  */
6
6
  export declare function foldedToPprof(counts: Map<string, number>, periodNs: number, startMs: number, durationMs: number): Uint8Array;
7
+ /** Live heap stacks (`a;b;c` root first) with `[objects, bytes]` to a pprof with inuse_objects/count and inuse_space/bytes. */
8
+ export declare function heapToPprof(stacks: Map<string, [number, number]>, periodBytes: number, startMs: number, durationMs: number): Uint8Array;
package/dist/esm/pprof.js CHANGED
@@ -41,6 +41,16 @@ class Pb {
41
41
  * sample labels. Frame names keep their `(file:line)` suffix; one function per distinct frame.
42
42
  */
43
43
  export function foldedToPprof(counts, periodNs, startMs, durationMs) {
44
+ const rows = new Map();
45
+ for (const [k, n] of counts)
46
+ rows.set(k, [n, n * periodNs]);
47
+ return encodePprof([['samples', 'count'], ['cpu', 'nanoseconds']], rows, ['cpu', 'nanoseconds'], periodNs, startMs, durationMs);
48
+ }
49
+ /** Live heap stacks (`a;b;c` root first) with `[objects, bytes]` to a pprof with inuse_objects/count and inuse_space/bytes. */
50
+ export function heapToPprof(stacks, periodBytes, startMs, durationMs) {
51
+ return encodePprof([['inuse_objects', 'count'], ['inuse_space', 'bytes']], stacks, ['space', 'bytes'], periodBytes, startMs, durationMs);
52
+ }
53
+ function encodePprof(types, counts, periodType, period, startMs, durationMs) {
44
54
  const strings = [''];
45
55
  const index = new Map([['', 0]]);
46
56
  const s = (x) => {
@@ -52,10 +62,12 @@ export function foldedToPprof(counts, periodNs, startMs, durationMs) {
52
62
  }
53
63
  return i;
54
64
  };
55
- const vt = (type, unit) => new Pb().int(1, s(type)).int(2, s(unit));
65
+ const vt = ([type, unit]) => new Pb().int(1, s(type)).int(2, s(unit));
56
66
  const frames = new Map();
57
- const out = new Pb().msg(1, vt('samples', 'count')).msg(1, vt('cpu', 'nanoseconds'));
58
- for (const [key, n] of counts) {
67
+ const out = new Pb();
68
+ for (const t of types)
69
+ out.msg(1, vt(t));
70
+ for (const [key, values] of counts) {
59
71
  const tab = key.indexOf('\t');
60
72
  const labels = tab >= 0 ? key.slice(0, tab) : '';
61
73
  // pprof location ids are leaf first
@@ -65,7 +77,7 @@ export function foldedToPprof(counts, periodNs, startMs, durationMs) {
65
77
  frames.set(f, (id = frames.size + 1));
66
78
  return id;
67
79
  });
68
- const sample = new Pb().packed(1, ids).packed(2, [n, n * periodNs]);
80
+ const sample = new Pb().packed(1, ids).packed(2, values);
69
81
  for (const kv of labels ? labels.split(',') : []) {
70
82
  const eq = kv.indexOf('=');
71
83
  if (eq > 0)
@@ -78,7 +90,7 @@ export function foldedToPprof(counts, periodNs, startMs, durationMs) {
78
90
  out.msg(5, new Pb().int(1, id).int(2, s(f))); // Function{id, name}
79
91
  }
80
92
  out.int(9, BigInt(Math.round(startMs)) * 1000000n).int(10, BigInt(Math.round(durationMs)) * 1000000n);
81
- out.msg(11, vt('cpu', 'nanoseconds')).int(12, periodNs);
93
+ out.msg(11, vt(periodType)).int(12, period);
82
94
  for (const str of strings)
83
95
  out.bytes(6, Buffer.from(str));
84
96
  return new Uint8Array(gzipSync(Uint8Array.from(out.b)));
@@ -38,7 +38,29 @@ export declare function withSpan<T>(fn: () => T, ids?: {
38
38
  }): T;
39
39
  /** Takes the intervals a profile up to `until` can need; open ones stay for the next profile. */
40
40
  export declare function takeIntervals(until: number): SpanInterval[];
41
+ /** V8's sampling heap profile: a tree of live (not yet collected) sampled allocations. */
42
+ export interface HeapProfileNode {
43
+ callFrame: CallFrame;
44
+ selfSize: number;
45
+ id: number;
46
+ children?: HeapProfileNode[];
47
+ }
48
+ export interface HeapProfile {
49
+ head: HeapProfileNode;
50
+ samples?: {
51
+ size: number;
52
+ nodeId: number;
53
+ ordinal: number;
54
+ }[];
55
+ }
56
+ export type ProfileType = 'cpu' | 'heap';
57
+ /** `cpu,heap` (WT_PROFILING_TYPES) to types; unknown names are ignored, nothing valid means cpu only. */
58
+ export declare function parseProfilingTypes(v?: string): ProfileType[];
41
59
  export interface ProfilerOptions {
60
+ /** Profile types (default: WT_PROFILING_TYPES, else `['cpu']`). `heap` adds V8's sampling heap profiler. */
61
+ types?: ProfileType[];
62
+ /** Heap sampling interval in bytes (default 524 288). */
63
+ heapIntervalBytes?: number;
42
64
  /** Ingest key; defaults to WT_INGEST_KEY. */
43
65
  apiKey?: string;
44
66
  /** Gateway base URL; defaults to WT_OTLP_ENDPOINT or http://localhost:4318. */
@@ -55,6 +77,11 @@ export interface ProfilerOptions {
55
77
  }
56
78
  /** Root-first folded stacks with their sample counts; V8's synthetic `(root)` is left out. */
57
79
  export declare function foldProfile(p: CpuProfile, spans?: SpanInterval[]): Map<string, number>;
80
+ /**
81
+ * Root-first stacks of live heap with `[objects, bytes]`: bytes are the node's self size, objects the
82
+ * number of sampled allocations that still live in it (at least 1 for a node with bytes).
83
+ */
84
+ export declare function foldHeap(p: HeapProfile): Map<string, [number, number]>;
58
85
  export declare function foldedBody(counts: Map<string, number>): string;
59
86
  /** `/v1/profiles?format=pprof&service=…&version=…` on the gateway. */
60
87
  export declare function profilesUrl(endpoint: string, service: string, version?: string): string;
@@ -69,6 +96,8 @@ export declare class Profiler {
69
96
  private readonly tags;
70
97
  private readonly intervalUs;
71
98
  private readonly periodMs;
99
+ private readonly types;
100
+ private readonly heapIntervalBytes;
72
101
  private session?;
73
102
  private timer?;
74
103
  private from;
@@ -77,7 +106,9 @@ export declare class Profiler {
77
106
  start(): Promise<this>;
78
107
  /** Stop the current profile, upload it and (when `restart`) start the next one. */
79
108
  flush(restart: boolean): Promise<void>;
109
+ uploadHeap(stacks: Map<string, [number, number]>, fromS: number, untilS: number): Promise<void>;
80
110
  upload(counts: Map<string, number>, fromS: number, untilS: number): Promise<void>;
111
+ private send;
81
112
  stop(): Promise<void>;
82
113
  }
83
114
  /** Start a [[Profiler]] with the SDK's environment defaults. */
@@ -1,4 +1,4 @@
1
- // Continuous CPU profiler on V8's own sampler (`node:inspector`, no native addon): every
1
+ // Continuous CPU (and opt-in heap) profiler on V8's own samplers (`node:inspector`, no native addon): every
2
2
  // `periodMs` the CPU profile is folded into stacks, encoded as pprof and posted to the gateway's
3
3
  // `/v1/profiles?format=pprof` with `service` and `version`. Best effort: a failed upload is
4
4
  // counted and dropped. `withSpan` labels samples taken while its function runs, joined
@@ -7,7 +7,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
7
7
  import { Session } from 'node:inspector';
8
8
  import { promiseHooks } from 'node:v8';
9
9
  import { trace } from '@opentelemetry/api';
10
- import { foldedToPprof } from './pprof.js';
10
+ import { foldedToPprof, heapToPprof } from './pprof.js';
11
11
  const intervals = [];
12
12
  const MAX_INTERVALS = 100_000;
13
13
  function nowUs() {
@@ -97,6 +97,11 @@ function prefixAt(sorted, t) {
97
97
  return sorted[i].prefix;
98
98
  return '';
99
99
  }
100
+ /** `cpu,heap` (WT_PROFILING_TYPES) to types; unknown names are ignored, nothing valid means cpu only. */
101
+ export function parseProfilingTypes(v) {
102
+ const t = [...new Set((v ?? '').split(',').map((x) => x.trim().toLowerCase()))].filter((x) => x === 'cpu' || x === 'heap');
103
+ return t.length ? t : ['cpu'];
104
+ }
100
105
  const MAX_DEPTH = 128;
101
106
  function frameName(f) {
102
107
  const file = f.url ? f.url.split('/').pop() : '';
@@ -135,6 +140,28 @@ export function foldProfile(p, spans = []) {
135
140
  }
136
141
  return counts;
137
142
  }
143
+ /**
144
+ * Root-first stacks of live heap with `[objects, bytes]`: bytes are the node's self size, objects the
145
+ * number of sampled allocations that still live in it (at least 1 for a node with bytes).
146
+ */
147
+ export function foldHeap(p) {
148
+ const objs = new Map();
149
+ for (const x of p.samples ?? [])
150
+ objs.set(x.nodeId, (objs.get(x.nodeId) ?? 0) + 1);
151
+ const out = new Map();
152
+ const walk = (n, path) => {
153
+ const names = n.callFrame.functionName === '(root)' ? path : [...path, frameName(n.callFrame)];
154
+ if (n.selfSize > 0 && names.length && names.length <= MAX_DEPTH) {
155
+ const key = names.join(';');
156
+ const cur = out.get(key) ?? [0, 0];
157
+ out.set(key, [cur[0] + Math.max(objs.get(n.id) ?? 0, 1), cur[1] + n.selfSize]);
158
+ }
159
+ for (const c of n.children ?? [])
160
+ walk(c, names);
161
+ };
162
+ walk(p.head, []);
163
+ return out;
164
+ }
138
165
  export function foldedBody(counts) {
139
166
  let out = '';
140
167
  for (const [k, n] of counts)
@@ -167,6 +194,8 @@ export class Profiler {
167
194
  tags;
168
195
  intervalUs;
169
196
  periodMs;
197
+ types;
198
+ heapIntervalBytes;
170
199
  session;
171
200
  timer;
172
201
  from = 0;
@@ -180,6 +209,8 @@ export class Profiler {
180
209
  this.tags = { env: process.env.WT_ENVIRONMENT, version: process.env.WT_RELEASE, ...o.tags };
181
210
  this.intervalUs = Math.min(Math.max(o.intervalUs ?? 10_000, 1_000), 1_000_000);
182
211
  this.periodMs = Math.max(o.periodMs ?? 60_000, 1_000);
212
+ this.types = o.types?.length ? o.types : parseProfilingTypes(process.env.WT_PROFILING_TYPES);
213
+ this.heapIntervalBytes = Math.max(o.heapIntervalBytes ?? 524_288, 1024);
183
214
  if (o.asyncSpans)
184
215
  enableAsyncSpanLabels();
185
216
  }
@@ -197,9 +228,14 @@ export class Profiler {
197
228
  return this;
198
229
  this.session = new Session();
199
230
  this.session.connect();
200
- await this.post('Profiler.enable');
201
- await this.post('Profiler.setSamplingInterval', { interval: this.intervalUs });
202
- await this.post('Profiler.start');
231
+ if (this.types.includes('cpu')) {
232
+ await this.post('Profiler.enable');
233
+ await this.post('Profiler.setSamplingInterval', { interval: this.intervalUs });
234
+ await this.post('Profiler.start');
235
+ }
236
+ if (this.types.includes('heap')) {
237
+ await this.post('HeapProfiler.startSampling', { samplingInterval: this.heapIntervalBytes });
238
+ }
203
239
  this.from = Date.now() / 1000;
204
240
  this.timer = setInterval(() => void this.flush(true), this.periodMs);
205
241
  this.timer.unref();
@@ -210,19 +246,35 @@ export class Profiler {
210
246
  if (!this.session)
211
247
  return;
212
248
  const until = Date.now() / 1000;
213
- const { profile } = await this.post('Profiler.stop');
214
249
  const from = this.from;
215
- if (restart) {
216
- await this.post('Profiler.start');
217
- this.from = until;
250
+ let heap;
251
+ if (this.types.includes('heap')) {
252
+ // live-heap snapshot; sampling keeps running
253
+ const { profile } = await this.post('HeapProfiler.getSamplingProfile');
254
+ heap = foldHeap(profile);
218
255
  }
219
- const counts = foldProfile(profile, takeIntervals(nowUs()));
220
- if (counts.size)
256
+ let counts;
257
+ if (this.types.includes('cpu')) {
258
+ const { profile } = await this.post('Profiler.stop');
259
+ if (restart)
260
+ await this.post('Profiler.start');
261
+ counts = foldProfile(profile, takeIntervals(nowUs()));
262
+ }
263
+ if (restart)
264
+ this.from = until;
265
+ if (counts?.size)
221
266
  await this.upload(counts, from, until);
267
+ if (heap?.size)
268
+ await this.uploadHeap(heap, from, until);
269
+ }
270
+ async uploadHeap(stacks, fromS, untilS) {
271
+ await this.send(heapToPprof(stacks, this.heapIntervalBytes, fromS * 1000, (untilS - fromS) * 1000));
222
272
  }
223
273
  async upload(counts, fromS, untilS) {
274
+ await this.send(foldedToPprof(counts, this.intervalUs * 1000, fromS * 1000, (untilS - fromS) * 1000));
275
+ }
276
+ async send(body) {
224
277
  try {
225
- const body = foldedToPprof(counts, this.intervalUs * 1000, fromS * 1000, (untilS - fromS) * 1000);
226
278
  const r = await fetch(profilesUrl(this.endpoint, this.service, this.tags.version), {
227
279
  method: 'POST', body,
228
280
  headers: { authorization: `Bearer ${this.key}`, 'content-type': 'application/octet-stream' },
@@ -241,6 +293,8 @@ export class Profiler {
241
293
  if (this.timer)
242
294
  clearInterval(this.timer);
243
295
  await this.flush(false).catch(() => undefined);
296
+ if (this.types.includes('heap'))
297
+ await this.post('HeapProfiler.stopSampling').catch(() => undefined);
244
298
  this.session?.disconnect();
245
299
  this.session = undefined;
246
300
  }
@@ -1,2 +1,2 @@
1
1
  /** This package's version (test/distro.test.ts checks it against package.json); sent as `telemetry.distro.version`. */
2
- export declare const VERSION = "0.7.3";
2
+ export declare const VERSION = "0.7.4";
@@ -1,2 +1,2 @@
1
1
  /** This package's version (test/distro.test.ts checks it against package.json); sent as `telemetry.distro.version`. */
2
- export const VERSION = '0.7.3';
2
+ export const VERSION = '0.7.4';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@watchtowerobservability/node",
3
- "version": "0.7.3",
3
+ "version": "0.7.4",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/watchtowerobservability/watchtower-node.git"