pprof-format

library2.2.1jsnpmunverified

pprof-format is a pure JavaScript library for encoding and decoding PProf (Profiling Protobuf) profiles. It distinguishes itself by providing a zero-dependency implementation that avoids the full Protobuf runtime, instead focusing on the subset of the PProf specification required for profiling data. This design choice contributes to a smaller bundle size and faster execution, making it highly suitable for both Node.js and browser environments. The library explicitly uses Uint8Arrays over Node.js Buffers to ensure universal compatibility. Currently at version 2.2.1, its release cadence is typically driven by new features or specification updates rather than a fixed schedule. Key differentiators include its browser-friendliness, lack of external dependencies, and performance optimizations. It ships with TypeScript types for enhanced developer experience.

serialization observability

npm install pprof-format

github ↗package ↗

INSTALL

IMPORT

SIG · PPROF-FORMAT

pprof-format

serializationjavascriptv2.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Profile

✓ import { Profile } from 'pprof-format'

✗ const Profile = require('pprof-format').Profile

The library is ESM-first; `require` will lead to errors in most modern Node.js environments and is not supported in browsers.

StringTable

✓ import { StringTable } from 'pprof-format'

✗ import StringTable from 'pprof-format'

All core components are named exports. `StringTable` is essential for deduplicating strings within a PProf profile.

Location

✓ import { Location } from 'pprof-format'

✗ import * as pprof from 'pprof-format'; new pprof.Location()

While star imports work, direct named imports are generally preferred for clarity and tree-shaking benefits.

This quickstart demonstrates how to construct a basic PProf profile programmatically, including defining functions, locations, and samples, utilizing the mandatory StringTable for string deduplication, and handling BigInt for time and address values. It then shows how to encode the profile into a Uint8Array and subsequently decode it, verifying the integrity of the data.

import { Function, Label, Line, Location, Mapping, Profile, Sample, ValueType, StringTable } from 'pprof-format' const stringTable = new StringTable() const periodType = new ValueType({ type: stringTable.dedup('cpu'), unit: stringTable.dedup('nanoseconds') }) const fun = new Function({ id: 1, name: stringTable.dedup('main'), systemName: stringTable.dedup('main'), filename: stringTable.dedup('app.js'), startLine: 1 }) const mapping = new Mapping({ id: 1, memoryStart: 0n, memoryLimit: 1000n, fileOffset: 0n, filename: stringTable.dedup('app.js') }) const location = new Location({ id: 1, mappingId: mapping.id, address: 123n, // Addresses are BigInt line: [ new Line({ functionId: fun.id, line: 1 }) ] }) const profile = new Profile({ sampleType: [ new ValueType({ type: stringTable.dedup('samples'), unit: stringTable.dedup('count') }) ], sample: [ new Sample({ locationId: [location.id], value: [1000n] // Values are BigInt }) ], mapping: [mapping], location: [location], 'function': [fun], stringTable, timeNanos: BigInt(Date.now()) * 1_000_000n, durationNanos: 500_000_000n, // 500ms periodType, period: 1_000_000n, // 1ms period for CPU samples comment: [ stringTable.dedup('Example PProf profile') ] }) // Encode to Uint8Array const encodedProfile = profile.encode() console.log('Encoded profile length:', encodedProfile.length) // Decode from Uint8Array const copied = Profile.decode(encodedProfile) console.log('Decoded profile sample count:', copied.sample.length) // Verify string table content console.log('Decoded string table entry 1:', copied.stringTable.at(1))

Debug

Known issues

gotchaThis library is designed for modern JavaScript environments and uses ESM for its module system. Attempting to use `require()` for imports will result in module resolution errors or runtime failures.

fix

Always use `import` statements (e.g., `import { Profile } from 'pprof-format'`). Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

affects: >=1.0.0

gotchaAll string values within the PProf structure (like function names, filenames, label keys/values, etc.) must be handled through an instance of `StringTable` for deduplication. Directly assigning string literals to fields expecting string table indices will lead to malformed profiles or runtime errors.

fix

Initialize `const stringTable = new StringTable()` and use `stringTable.dedup('your_string')` for all string assignments within profile objects.

affects: >=1.0.0

gotchaPProf values such as `timeNanos`, `durationNanos`, `address`, and `sample.value` require `BigInt` types for precision, not standard JavaScript `number` primitives. Using `number` will lead to loss of precision, incorrect profile data, or `TypeError`.

fix

Ensure all relevant numeric values are explicitly cast to `BigInt` (e.g., `BigInt(Date.now()) * 1_000_000n` or `12345n`).

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use CommonJS `require()` syntax in an ESM-only context or a browser environment that doesn't support it.

fix

Update your import statements to use ESM syntax: `import { Profile } from 'pprof-format'`. Ensure your Node.js project is configured for ESM (e.g., by adding `"type": "module"` to your `package.json`).

TypeError: Cannot read properties of undefined (reading 'dedup')

A string field within a PProf component (e.g., `Function.name`, `ValueType.type`) was assigned a raw string instead of a string table index, or `stringTable` was not initialized or passed to the `Profile` constructor.

fix

Ensure `stringTable = new StringTable()` is initialized and used for all string values via `stringTable.dedup('my string')`. Also, confirm the `stringTable` instance is passed to the `Profile` constructor.

TypeError: Type 'number' is not assignable to type 'bigint'.

A PProf field expecting a `BigInt` (like `timeNanos`, `durationNanos`, `address`, or sample values) received a standard JavaScript `number`.

fix

Explicitly convert numeric values to `BigInt` using the `BigInt()` constructor or by appending `n` to integer literals (e.g., `123n`, `BigInt(Date.now())`).

Upgrade

Version history

2.2.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/DataDog/pprof-format ↗

packagehttps://www.npmjs.com/package/pprof-format ↗