[szegedi]

What does this PR do?:

Adds an OpenTelemetry profiles serializer, built as a ProfileVisitor on the normalizer from #430, and encoding with pprof-format/otel (pprof-format 2.4.0).

Multiple profiles (both time and heap) can be collected into a single ExportProfilesServiceRequest sharing the request's dictionary.
Each profile is added through builder.visitor(), so whatever drives the visit needs no knowledge of OTel. serializeTimeProfileOtel() and serializeHeapProfileOtel() are shorthands for a single-profile request.
builder.visitor() takes attributes and an original payload for the profiles of that visit, for per-collection metadata (e.g. event.json in dd-trace-js).

time.stopAndVisit() and heap.visitProfile() pass the normalized profile to a caller-supplied visitor instead of serializing it as pprof. They're the format-neutral counterparts of time.stop() and heap.profile()

Motivation:

Step 2 of emitting the OpenTelemetry profiles signal from the Node.js profiler: a second encoder that reuses the profile semantics from #430 instead of duplicating them.

Additional notes:

• One OTel profile is emitted per sample type (sample count, wall and CPU time; in-use and allocated objects and space).
• With samplePerContext, the sample count is folded into the wall-time profile, which gets an observation per sampling event. Idle samples, which deliberately have zero wall time (see Preserve idle samples with zero wall time and no CPU time rollup #199), stay as timestamped evidence that sampling happened, and we don't have to have a separate count profile that has to repeat every sample just to carry 1s.
• Labels become interned attributes: strings, integers, or doubles for fractional numbers. An optional extractLink callback can turn labels into a span link; all-zero trace or span IDs are treated as no link.
• Samples with the same stack, attributes and link are merged: timestamped ones accumulate a value and timestamp per observation, others are summed.
• Samples without frames (e.g. timeline events) get the dictionary's zero-value stack.
• All profiles in a request get the same time range (the union of their own), so a collection cycle's profiles cover the same period, including heap snapshots.
• Frames whose source map is declared but missing locally get a datadog.frame.missing_source_map location attribute, and their profiles a datadog.profile.has_missing_source_maps attribute. (pprof carries this as a profile comment, for lack of better solution.) The backend will need to be adjusted to recognize these.

AI generated PR description

Adds an **OpenTelemetry profiles serializer**, built as a `ProfileVisitor` on the format-neutral normalizer from #430, and encoding with `pprof-format/otel` (pprof-format 2.4.0).

• OtelProfilesBuilder (ts/src/otel-serializer.ts) collects any number of normalized profiles, e.g. the time and heap profiles of one collection cycle, into one ExportProfilesServiceRequest. All of them share the request's dictionary, as the OTel format intends. Each profile is added through builder.visitor(), so whatever drives the visit needs no knowledge of OTel. serializeTimeProfileOtel() and serializeHeapProfileOtel() are shorthands for a single-profile request.
• time.stopAndVisit() and heap.visitProfile() pass the normalized profile to a caller-supplied visitor instead of serializing it as pprof. They're the format-neutral counterparts of time.stop() and heap.profile(), and use the same eager stop paths. The lazy, callback-based paths stay opt-in because of the V8 CpuProfile deletion race (Revert lazy profile-tree changes to mitigate CpuProfile::Delete crash #329).
• builder.visitor({attributes, originalPayload}) sets attributes and an original payload on every OTel profile the visit adds. Attribute values can be structured (kvlistValue, arrayValue) and are interned by a canonical form of their value, so per-collection metadata such as the snapshot kind or endpoint counts costs an index per profile. The original payload carries a document the backend reads while an attribute representation is agreed (for now, event.json); its format and bytes are set together, as the proto requires.

Mapping highlights:

• One OTel profile per sample type (sample count, wall and CPU time; in-use and allocated objects and space).
• With samplePerContext, the sample count is folded into the wall-time profile, which gets an observation per sampling event. Idle samples, which deliberately have zero wall time (see Preserve idle samples with zero wall time and no CPU time rollup #199), thereby stay as timestamped evidence that sampling happened, and no count profile has to repeat every sample just to carry 1s.
• Sample timestamps fall within [time_unix_nano, time_unix_nano + duration_nano), since the time range starts at the start of collection.
• Functions, locations (with columns), stacks, attributes and links are deduplicated across all profiles. Every dictionary table starts with its zero value.
• Labels become interned attributes: strings, integers, or doubles for fractional numbers. An optional extractLink callback can turn labels into a span link; all-zero trace or span IDs are treated as no link.
• Samples with the same stack, attributes and link are merged: timestamped ones accumulate a value and timestamp per observation, others are summed.
• A sample whose stack has no frames, such as a timeline event, refers to the dictionary's zero-value stack.

Motivation:

Step 2 of emitting the OpenTelemetry profiles signal from the Node.js profiler: a second encoder that reuses the profile semantics from #430 instead of duplicating them.

Additional Notes:

• Based on main, now that refactor: extract a format-neutral profile normalizer from the pprof serializer #430 is merged.
• OtelProfilesBuilder, its options, the shorthands and the missing-source-map attribute keys are exported from the package, for dd-trace-js.
• Frames whose source map is declared but missing locally get a datadog.frame.missing_source_map location attribute, and their profiles a datadog.profile.has_missing_source_maps attribute. pprof carries this as a profile comment, but OTel's pprof.profile.comment is reserved for human-readable text. No semantic convention exists, so these keys are provisional until the Datadog backend confirms them.
• Visitors run synchronously. A visit that throws leaves partial data, so the builder should then be discarded.

How to test the change?:

Unit tests in ts/test/test-otel-serializer.ts cover the mapping, deduplication across profiles, sample merging, links, visit attributes and original payloads, samples without frames, the missing-source-map attributes and the package exports, and decode the encoded request to check it round-trips. ts/test/test-time-profiler.ts and ts/test/test-heap-profiler.ts cover stopAndVisit() and visitProfile(), including state after a throwing visitor. npm test.

[github-actions]

Overall package size

Self size: 2.98 MB
Deduped: 4.09 MB
No deduping: 4.09 MB

Dependency sizes

| name | version | self size | total size | |------|---------|-----------|------------| | pprof-format | 2.4.0 | 912.36 kB | 912.36 kB | | source-map | 0.8.0 | 185.66 kB | 185.66 kB | | node-gyp-build | 4.8.4 | 13.86 kB | 13.86 kB |

_{🤖 This report was automatically generated by heaviest-objects-in-the-universe}

[datadog-datadog-prod-us1]

❌ Errors

Your PR has failed checks. Please review the issues below and take necessary action before merging.

🚦 4 Pipeline jobs failed

Build | build / centos-test-26 — 🔄 Retry may pass, looks flaky

View more details · View in GitHub Actions

Build | build-successful

View more details · View in GitHub Actions

DDCI - DataDog/pprof-nodejs | benchmarks-pr-comment

View more details · View in DDCI

View all 4 failed jobs.

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: a136cc8 | Docs | View more details | Give us feedback!}