From dcadfda6a1af0fc6f76855d78967de0e311d1622 Mon Sep 17 00:00:00 2001 From: Ruben Bridgewater Date: Wed, 18 Nov 2026 16:57:59 +0100 Subject: [PATCH] perf: write profile samples directly Object serialization builds Sample and Label objects for callers that only need bytes. Writing samples directly avoids retaining that object graph without changing the existing object-returning methods. --- README.md | 8 ++ benchmark/direct-profile-writer.cjs | 133 ++++++++++++++++++++++++++++ ts/src/heap-profiler.ts | 62 +++++++++++-- ts/src/index.ts | 2 + ts/src/profile-serializer.ts | 113 +++++++++++++++++------ ts/src/time-profiler.ts | 23 +++++ ts/test/test-heap-profiler.ts | 29 ++++++ ts/test/test-profile-serializer.ts | 55 ++++++++++++ ts/test/test-time-profiler.ts | 28 ++++++ 9 files changed, 419 insertions(+), 34 deletions(-) create mode 100644 benchmark/direct-profile-writer.cjs diff --git a/README.md b/README.md index a3799c34..eda087e6 100644 --- a/README.md +++ b/README.md @@ -102,6 +102,14 @@ Install [`pprof`][npm-url] with `npm` or add to your `package.json`. const profile = await pprof.heap.v8Profile(); ``` +### Collect without building a `Profile` object + +Use `time.stopEncoded()` or `heap.profileEncoded()` when you only need profile +bytes. They accept the same arguments as `time.stop()` and `heap.profile()`. +The result includes `hasMissingSourceMaps` and an `encodeAsync()` method that +returns uncompressed pprof protobuf bytes. Compress the bytes separately if +your output requires gzip. + [build-image]: https://github.com/Datadog/pprof-nodejs/actions/workflows/build.yml/badge.svg?branch=main [build-url]: https://github.com/Datadog/pprof-nodejs/actions/workflows/build.yml [npm-image]: https://badge.fury.io/js/@datadog%2Fpprof.svg diff --git a/benchmark/direct-profile-writer.cjs b/benchmark/direct-profile-writer.cjs new file mode 100644 index 00000000..ad7533ac --- /dev/null +++ b/benchmark/direct-profile-writer.cjs @@ -0,0 +1,133 @@ +'use strict'; + +const assert = require('node:assert/strict'); +const {performance} = require('node:perf_hooks'); +const {visitTimeProfile} = require('../out/src/profile-normalizer'); +const { + serializeEncodedProfile, + serializeTimeProfile, +} = require('../out/src/profile-serializer'); + +const count = Number(process.env.SAMPLES ?? 6500); +const depth = Number(process.env.DEPTH ?? 16); +const stackCount = Number(process.env.STACKS ?? 64); +const iterations = Number(process.env.ITERATIONS ?? 80); +const contexts = Array.from({length: count}, (_, index) => ({ + timestamp: 1700000000000000n + BigInt(index) * 10000n, + cpuTime: 1000, +})); +let leaf = { + name: 'dispatcher', + scriptName: '/service.js', + hitCount: 0, + children: Array.from({length: stackCount}, (_, index) => { + const from = Math.floor((index * count) / stackCount); + const to = Math.floor(((index + 1) * count) / stackCount); + return { + name: `handler${index}`, + scriptName: '/service.js', + hitCount: to - from, + children: [], + contexts: contexts.slice(from, to), + }; + }), +}; +for (let index = 0; index < depth; index++) { + leaf = { + name: `frame${index}`, + scriptName: '/service.js', + hitCount: 0, + children: [leaf], + }; +} +const profile = { + startTime: 0, + endTime: count * 10000, + epochOffset: 1700000000000000, + hasCpuTime: true, + topDownRoot: {name: '(root)', scriptName: '', hitCount: 0, children: [leaf]}, +}; +const intervalMicros = 10000; +const generateLabels = ({context}) => ({ + 'thread name': 'Main', + 'thread id': 1, + 'span id': (context.timestamp << 12n) | 13n, + end_timestamp_ns: context.timestamp * 1000n, +}); +const lowCardinality = ['thread name', 'thread id']; +const paths = { + objects: () => + serializeTimeProfile( + profile, + intervalMicros, + undefined, + true, + generateLabels, + lowCardinality, + ), + writer: () => + serializeEncodedProfile( + visitor => + visitTimeProfile(profile, visitor, { + intervalMicros, + generateLabels, + recomputeSamplingInterval: true, + }), + lowCardinality, + 'drop', + ), +}; + +function summarize(values) { + values.sort((left, right) => left - right); + return [0.5, 0.95].map(percentile => + Number(values[Math.floor(values.length * percentile)].toFixed(2)), + ); +} + +async function main() { + const now = Date.now; + Date.now = () => 1700000000000; + const writer = paths.writer(); + const objects = paths.objects(); + Date.now = now; + assert.deepEqual(await writer.encodeAsync(), await objects.encodeAsync()); + const results = {objects: [], writer: []}; + for (let index = -20; index < iterations; index++) { + const order = + index % 2 === 0 ? ['objects', 'writer'] : ['writer', 'objects']; + for (const name of order) { + const start = performance.now(); + const collected = paths[name](); + const pause = performance.now() - start; + await collected.encodeAsync(); + if (index >= 0) + results[name].push({pause, total: performance.now() - start}); + } + } + for (const [name, samples] of Object.entries(results)) { + let collected; + global.gc(); + const before = process.memoryUsage(); + collected = paths[name](); + global.gc(); + const retained = process.memoryUsage(); + console.log(name, { + collectionMs: summarize(samples.map(sample => sample.pause)), + totalMs: summarize(samples.map(sample => sample.total)), + retainedKiB: Math.round( + (retained.heapUsed + + retained.arrayBuffers - + before.heapUsed - + before.arrayBuffers) / + 1024, + ), + }); + await collected.encodeAsync(); + } +} + +main().catch(error => { + console.error(error); + process.exitCode = 1; +}); diff --git a/ts/src/heap-profiler.ts b/ts/src/heap-profiler.ts index a9af3924..4c4ddc18 100644 --- a/ts/src/heap-profiler.ts +++ b/ts/src/heap-profiler.ts @@ -28,8 +28,14 @@ import { ColumnNumbers, DEFAULT_COLUMN_NUMBERS, serializeHeapProfile, + serializeEncodedProfile, + EncodedProfile, } from './profile-serializer'; -import {NormalizedProfile, normalizeHeapProfile} from './profile-normalizer'; +import { + NormalizedProfile, + normalizeHeapProfile, + visitHeapProfile, +} from './profile-normalizer'; import {SourceMapper} from './sourcemapper/sourcemapper'; import { AllocationProfileNode, @@ -160,17 +166,59 @@ export function convertProfile( generateLabels?: GenerateAllocationLabelsFunction, columnNumbers: ColumnNumbers = DEFAULT_COLUMN_NUMBERS, ): Profile { + return convertProfileWith(rootNode, (root, startTimeNanos, allocations) => + serializeHeapProfile( + root, + startTimeNanos, + heapIntervalBytes, + ignoreSamplePath, + sourceMapper, + generateLabels, + allocations, + columnNumbers, + ), + ); +} + +export function profileEncoded( + ignoreSamplePath?: string, + sourceMapper?: SourceMapper, + generateLabels?: GenerateAllocationLabelsFunction, + columnNumbers: ColumnNumbers = DEFAULT_COLUMN_NUMBERS, +): EncodedProfile { + return collectProfile(rootNode => + convertProfileWith(rootNode, (root, startTimeNanos, allocations) => + serializeEncodedProfile( + visitor => + visitHeapProfile(root, visitor, { + startTimeNanos, + intervalBytes: heapIntervalBytes, + ignoreSamplesPath: ignoreSamplePath, + sourceMapper, + generateLabels, + allocations, + }), + [], + columnNumbers, + ), + ), + ); +} + +function convertProfileWith( + rootNode: AllocationProfileNode | AllocationProfileNodeWithStats, + convert: ( + root: AllocationProfileNode | AllocationProfileNodeWithStats, + startTimeNanos: bigint, + allocations: boolean, + ) => Output, +): Output { const allocations = startedWithAllocations; const startTimeNanos = BigInt(Date.now()) * 1_000_000n; - return serializeHeapProfile( + return convert( addExternalMemoryNode(rootNode, allocations), startTimeNanos, - heapIntervalBytes, - ignoreSamplePath, - sourceMapper, - generateLabels, allocations, - columnNumbers, ); } diff --git a/ts/src/index.ts b/ts/src/index.ts index 95415114..bb478817 100644 --- a/ts/src/index.ts +++ b/ts/src/index.ts @@ -56,6 +56,7 @@ export const time = { profile: timeProfiler.profile, start: timeProfiler.start, stop: timeProfiler.stop, + stopEncoded: timeProfiler.stopEncoded, stopNormalized: timeProfiler.stopNormalized, profileV2: timeProfiler.profileV2, getContext: timeProfiler.getContext, @@ -73,6 +74,7 @@ export const heap = { start: heapProfiler.start, stop: heapProfiler.stop, profile: heapProfiler.profile, + profileEncoded: heapProfiler.profileEncoded, profileV2: heapProfiler.profileV2, normalizedProfile: heapProfiler.normalizedProfile, convertProfile: heapProfiler.convertProfile, diff --git a/ts/src/profile-serializer.ts b/ts/src/profile-serializer.ts index aecac7a2..ff274851 100644 --- a/ts/src/profile-serializer.ts +++ b/ts/src/profile-serializer.ts @@ -22,6 +22,7 @@ import { Location, Profile, ProfileInput, + ProfileWriter, Sample, ValueType, StringTable, @@ -30,6 +31,7 @@ import { Frame, frameFunctionName, HeapProfileNormalizerOptions, + NormalizedSample, ProfileVisitor, SampleLabel, SampleType, @@ -77,6 +79,17 @@ export type ColumnNumbers = 'drop' | 'pack' | 'emit'; export const DEFAULT_COLUMN_NUMBERS: ColumnNumbers = 'drop'; +export interface EncodedProfile { + hasMissingSourceMaps: boolean; + encodeAsync(): Promise; +} + +interface SampleSink { + stack(locationIds: number[]): number; + sample(sample: NormalizedSample): void; + finish(data: ProfileInput, hasMissingMapFiles: boolean): Output; +} + /** * Packs a frame's line and column into the single value carried by the pprof * Line.line field: the column in the high 32 bits, the line in the low 32 bits @@ -105,27 +118,19 @@ function packLineAndColumn( /** * Encodes a normalized profile as a profile proto. * - * @param visit - function that delivers the normalized profile to a visitor. - * @param lowCardinalityLabels - keys of labels with few distinct values, whose - * Label objects are shared between samples to save memory. */ -function serialize( +function serialize( visit: (visitor: ProfileVisitor) => VisitResult, - lowCardinalityLabels: string[] = [], - columnNumbers: ColumnNumbers = DEFAULT_COLUMN_NUMBERS, -): Profile { + columnNumbers: ColumnNumbers, + createSink: (stringTable: StringTable) => SampleSink, +): Output { const stringTable = new StringTable(); - const samples: Sample[] = []; + const sink = createSink(stringTable); const locations: Location[] = []; - const stacks: number[][] = []; const functions: Function[] = []; const functionIdMap = new Map(); const packColumns = columnNumbers === 'pack'; const emitColumns = columnNumbers === 'emit'; - const labelCaches: Map[] = []; - for (const l of lowCardinalityLabels) { - labelCaches[stringTable.dedup(l)] = new Map(); - } let profile: ProfileInput = {}; const {hasMissingMapFiles} = visit({ @@ -151,19 +156,10 @@ function serialize( locations.push(new Location({id, line: [getLine(frame)]})); return id; }, - stack: frameIds => stacks.push(frameIds) - 1, - sample: sample => { - samples.push( - new Sample({ - locationId: stacks[sample.stackId], - value: sample.values, - label: dedupLabels(buildLabels(sample.labels)), - }), - ); - }, + stack: sink.stack, + sample: sink.sample, }); - profile.sample = samples; profile.location = locations; profile.function = functions; profile.stringTable = stringTable; @@ -172,7 +168,7 @@ function serialize( profile.comment = [stringTable.dedup('dd:has-missing-map-files')]; } - return new Profile(profile); + return sink.finish(profile, hasMissingMapFiles); function getLine(frame: Frame): Line { // Both 'pack' and 'emit' carry the column only for frames whose source map @@ -221,6 +217,35 @@ function serialize( functions.push(f); return f; } +} + +function createObjectSampleSink( + stringTable: StringTable, + lowCardinalityLabels: string[], +): SampleSink { + const samples: Sample[] = []; + const stacks: number[][] = []; + const labelCaches: Map[] = []; + for (const key of lowCardinalityLabels) { + labelCaches[stringTable.dedup(key)] = new Map(); + } + + return { + stack: locationIds => stacks.push(locationIds) - 1, + sample({stackId, values, labels}) { + samples.push( + new Sample({ + locationId: stacks[stackId], + value: values, + label: dedupLabels(buildLabels(labels)), + }), + ); + }, + finish(data) { + data.sample = samples; + return new Profile(data); + }, + }; function buildLabels(sampleLabels: SampleLabel[]): Label[] { const labels: Label[] = new Array(sampleLabels.length); @@ -259,6 +284,40 @@ function serialize( } } +export function serializeEncodedProfile( + visit: (visitor: ProfileVisitor) => VisitResult, + lowCardinalityLabels: string[], + columnNumbers: ColumnNumbers, +): EncodedProfile { + return serialize(visit, columnNumbers, stringTable => { + const writer = new ProfileWriter(); + const stacks: Uint8Array[] = []; + for (const key of lowCardinalityLabels) { + stringTable.dedup(key); + } + return { + stack: locationIds => stacks.push(writer.packStack(locationIds)) - 1, + sample({stackId, values, labels}) { + writer.writeSample(stacks[stackId], values); + for (const [key, value] of labels) { + const keyId = stringTable.dedup(key); + if (typeof value === 'string') { + writer.writeLabel(keyId, stringTable.dedup(value)); + } else { + writer.writeLabel(keyId, 0, value); + } + } + }, + finish(data, hasMissingSourceMaps) { + return { + hasMissingSourceMaps, + encodeAsync: writer.encodeAsync.bind(writer, data), + }; + }, + }; + }); +} + /** * Converts v8 time profile into into a profile proto. * (https://github.com/google/pprof/blob/master/proto/profile.proto) @@ -283,8 +342,8 @@ export function serializeTimeProfile( }; return serialize( visitor => visitTimeProfile(prof, visitor, options), - lowCardinalityLabels, columnNumbers, + stringTable => createObjectSampleSink(stringTable, lowCardinalityLabels), ); } @@ -316,7 +375,7 @@ export function serializeHeapProfile( }; return serialize( visitor => visitHeapProfile(prof, visitor, options), - [], columnNumbers, + stringTable => createObjectSampleSink(stringTable, []), ); } diff --git a/ts/src/time-profiler.ts b/ts/src/time-profiler.ts index 40cf3ff2..1f842b72 100644 --- a/ts/src/time-profiler.ts +++ b/ts/src/time-profiler.ts @@ -21,6 +21,8 @@ import { ColumnNumbers, DEFAULT_COLUMN_NUMBERS, serializeTimeProfile, + serializeEncodedProfile, + EncodedProfile, GARBAGE_COLLECTION_FUNCTION_NAME, NON_JS_THREADS_FUNCTION_NAME, } from './profile-serializer'; @@ -28,6 +30,7 @@ import { NormalizedProfile, normalizeTimeProfile, TimeProfileNormalizerOptions, + visitTimeProfile, } from './profile-normalizer'; import {SourceMapper} from './sourcemapper/sourcemapper'; import { @@ -196,6 +199,26 @@ export function stop( ); } +export function stopEncoded( + restart = false, + generateLabels?: GenerateTimeLabelsFunction, + lowCardinalityLabels: string[] = [], +): EncodedProfile { + return stopAndProcess(restart, profile => + serializeEncodedProfile( + visitor => + visitTimeProfile(profile, visitor, { + intervalMicros: gIntervalMicros, + sourceMapper: gSourceMapper, + recomputeSamplingInterval: true, + generateLabels, + }), + lowCardinalityLabels, + gColumnNumbers, + ), + ); +} + /** * Same as stop(), but returns the profile normalized into a format-neutral * representation instead of serialized as pprof. diff --git a/ts/test/test-heap-profiler.ts b/ts/test/test-heap-profiler.ts index 743302f9..3b95cd09 100644 --- a/ts/test/test-heap-profiler.ts +++ b/ts/test/test-heap-profiler.ts @@ -16,6 +16,7 @@ import * as sinon from 'sinon'; +import {heap} from '../src'; import * as heapProfiler from '../src/heap-profiler'; import * as v8HeapProfiler from '../src/heap-profiler-bindings'; import { @@ -281,6 +282,34 @@ describe('HeapProfiler', () => { assert.ok(profile.sample.some(sample => sample.value[2] === 1024)); }); + it('should reset the allocation window before encoding its snapshot', async () => { + profileStub = sinon + .stub(v8HeapProfiler, 'getAllocationProfile') + .callsFake(() => copy(v8AllocationProfile)); + memoryUsageStub = sinon.stub(process, 'memoryUsage').returns({ + external: 1024, + rss: 2048, + heapTotal: 4096, + heapUsed: 2048, + arrayBuffers: 512, + }); + const intervalBytes = 1024 * 512; + const stackDepth = 32; + heapProfiler.start(intervalBytes, stackDepth, true); + const expected = heapProfiler.profile().encode(); + restartStub.resetHistory(); + + const snapshot = heap.profileEncoded(); + + sinon.assert.calledOnceWithExactly( + restartStub, + intervalBytes, + stackDepth, + true, + ); + assert.deepStrictEqual(await snapshot.encodeAsync(), expected); + }); + it('should throw when profileV2 is requested from allocation mode', async () => { const intervalBytes = 1024 * 512; const stackDepth = 32; diff --git a/ts/test/test-profile-serializer.ts b/ts/test/test-profile-serializer.ts index 7beed1f7..26d9707e 100644 --- a/ts/test/test-profile-serializer.ts +++ b/ts/test/test-profile-serializer.ts @@ -18,9 +18,11 @@ import * as tmp from 'tmp'; import { NON_JS_THREADS_FUNCTION_NAME, + serializeEncodedProfile, serializeHeapProfile, serializeTimeProfile, } from '../src/profile-serializer'; +import {visitHeapProfile, visitTimeProfile} from '../src/profile-normalizer'; import {SourceMapper} from '../src/sourcemapper/sourcemapper'; import {Label, Profile} from 'pprof-format'; import { @@ -546,6 +548,34 @@ describe('profile-serializer', () => { assertHasMissingMapToken(profile); }); + it('writes labelled time samples and missing-map columns before encoding metadata', async () => { + const input = makeSingleNodeTimeProfile(missingJsPath); + const generateLabels = () => ({tier: 'prod', span: 2 ** 40, cpu: -1}); + const lowCardinality = ['tier', 'cpu']; + const expected = serializeTimeProfile( + input, + 1000, + sourceMapper, + true, + generateLabels, + lowCardinality, + 'emit', + ); + const direct = serializeEncodedProfile( + visitor => + visitTimeProfile(input, visitor, { + intervalMicros: 1000, + sourceMapper, + recomputeSamplingInterval: true, + generateLabels, + }), + lowCardinality, + 'emit', + ); + assert.strictEqual(direct.hasMissingSourceMaps, true); + assert.deepStrictEqual(await direct.encodeAsync(), expected.encode()); + }); + it('packs the column for a missing-map frame when columnNumbers is "pack"', () => { // The frame's map is declared but missing, so it is bound for server-side // unminification (same condition as the missing-map token). Its generated @@ -649,6 +679,31 @@ describe('profile-serializer', () => { assertHasMissingMapToken(profile); }); + it('writes heap samples and labels without changing the profile bytes', async () => { + const generateLabels = () => ({tier: 'prod', span: 2 ** 40}); + const intervalBytes = 512 * 1024; + const expected = serializeHeapProfile( + v8HeapProfile, + 0, + intervalBytes, + undefined, + undefined, + generateLabels, + ); + const direct = serializeEncodedProfile( + visitor => + visitHeapProfile(v8HeapProfile, visitor, { + startTimeNanos: 0n, + intervalBytes, + generateLabels, + }), + [], + 'drop', + ); + assert.strictEqual(direct.hasMissingSourceMaps, false); + assert.deepStrictEqual(await direct.encodeAsync(), expected.encode()); + }); + it('does not emit missing-map token when no source mapper is used', () => { const profile = serializeTimeProfile( makeSingleNodeTimeProfile(missingJsPath), diff --git a/ts/test/test-time-profiler.ts b/ts/test/test-time-profiler.ts index 80d7f012..1ecad3e9 100644 --- a/ts/test/test-time-profiler.ts +++ b/ts/test/test-time-profiler.ts @@ -579,6 +579,34 @@ describe('Time Profiler', () => { ); }); + it('should encode packed columns on restart and final stop', async () => { + const sourceMapper = new SourceMapper(); + sinon.stub(sourceMapper, 'mappingInfo').callsFake(location => ({ + ...location, + missingMapFile: true, + })); + const options = { + intervalMicros: PROFILE_OPTIONS.intervalMicros, + columnNumbers: 'pack' as const, + sourceMapper, + }; + time.start(options); + const expected = time.stop().encode(); + + time.start(options); + const restarted = time.stopEncoded(true); + assert.ok(time.isStarted()); + const stopped = time.stopEncoded(); + assert.ok(!time.isStarted()); + + const [restartBytes, stopBytes] = await Promise.all([ + restarted.encodeAsync(), + stopped.encodeAsync(), + ]); + assert.deepStrictEqual(restartBytes, expected); + assert.deepStrictEqual(stopBytes, expected); + }); + it('should serialize with the source mapper still set when stopping', () => { // Regression test: stop() used to tear down the profiler state (via // handleStopNoRestart, which clears gSourceMapper) *before* serializing,