docs(profiler): document V8 native pprof addon requirement on Bun by danieljbruce · Pull Request #9727 · googleapis/google-cloud-node

danieljbruce · 2026-10-26T18:58:36Z

Description

Documents @google-cloud/profiler V8 native pprof addon requirement and Bun incompatibility.

Impact

Clarifies why @google-cloud/profiler requires V8 Node.js and cannot run on Bun.

Changes

Update handwritten/cloud-profiler/.readme-partials.yaml and handwritten/cloud-profiler/README.md to explicitly document that @google-cloud/profiler depends on the native C++ pprof addon compiled against V8's v8::CpuProfiler and v8::HeapProfiler C++ APIs (v8-profiler.h).
Document that JavaScriptCore-based runtimes such as Bun are unsupported for @google-cloud/profiler, and advise Bun users to use --ignore-scripts or omit @google-cloud/profiler in Bun deployments while using OpenTelemetry (@google-cloud/opentelemetry-cloud-trace-exporter / Cloud Monitoring) for observability.

Testing

Steps to Reproduce (in terminal):
- Run python3 .agents/skills/cistack/scripts/cistack.py --repo-root . --base-ref fix/b578003818-gax-stream-cancel-abort --branches docs/b578005545-profiler-bun-v8-addon --mode preflight-push2 and bun --bun bin/run-test.cjs --no-c8 core/packages/gax/build/test/unit/streamArrayParser.js.
Verified Markdown formatting and node ./bin/linter.mjs --strict in handwritten/cloud-profiler.
Verified handwritten/cloud-profiler unit tests pass under Node.js.

Alternatives

Throw a custom JavaScript runtime guard inside handwritten/cloud-profiler/src/index.ts before importing pprof; rejected as a standalone fix because top-level import {heap as heapProfiler} from 'pprof' and bun install native node-gyp rebuild hooks already fail before user code calls profiler.start().
Attempt to port pprof C++ bindings to JavaScriptCore; infeasible because JSC does not expose V8's v8-profiler.h C++ ABI (v8::CpuProfiler / v8::HeapProfiler).
Do not document the limitation, leaving Bun users encountering opaque node-gyp build or native addon load errors.

Fixes b/578005545
For b/564576254

gemini-code-assist

Code Review

This pull request updates the documentation in .readme-partials.yaml and README.md to clarify Node.js version support and explicitly note that @google-cloud/profiler is incompatible with the Bun runtime due to its dependency on V8 C++ APIs. Feedback on these changes suggests simplifying the Node.js version requirement phrasing to refer generally to supported V8-based LTS releases (Node.js 14 or higher). Additionally, the reviewer warns that manual edits to README.md may be overwritten during template regeneration and recommends applying these updates upstream.

gemini-code-assist · 2026-10-26T18:59:49Z

    ### Prerequisites

-    1. Your application will need to be using Node.js version between 14 and 20.
+    1. Your application will need to be using Node.js version between 14 and 20 (or a supported V8-based Node.js LTS release).


The phrasing "Node.js version between 14 and 20 (or a supported V8-based Node.js LTS release)" is redundant and slightly confusing. Since Node.js 22 is now an LTS release and is supported, we can simplify this to refer generally to supported V8-based Node.js LTS releases (Node.js 14 or higher).

1. Your application will need to be using a supported V8-based Node.js LTS release (Node.js 14 or higher).

gemini-code-assist · 2026-10-26T18:59:49Z

 For example, `npm install @google-cloud/profiler@legacy-8` installs client libraries
 for versions compatible with Node.js 8.

+> **Note on Bun and Non-V8 Runtimes:** `@google-cloud/profiler` depends on [`pprof`](https://www.npmjs.com/package/pprof), a native C++ addon compiled against V8's `v8::CpuProfiler` and `v8::HeapProfiler` C++ APIs (`v8-profiler.h`). Because Bun uses JavaScriptCore (JSC) instead of V8, `@google-cloud/profiler` is **not supported on the Bun runtime**. For Bun applications on Google Cloud, use OpenTelemetry (`@google-cloud/opentelemetry-cloud-trace-exporter` and `@google-cloud/opentelemetry-cloud-monitoring-exporter`) for observability.


Since README.md is typically generated from templates and .readme-partials.yaml, any manual edits made directly to README.md (such as this note) may be overwritten during the next regeneration. Please ensure this note is either added via a supported partial in .readme-partials.yaml or that the generation process is updated to preserve it.

References

Do not manually edit auto-generated files to fix typos or make other changes, as these edits will be overwritten during the next regeneration. Instead, apply the fixes upstream in the generator or templates.

danieljbruce · 2026-10-26T19:08:35Z

    ### Prerequisites

-    1. Your application will need to be using Node.js version between 14 and 20.
+    1. Your application will need to be using Node.js version between 14 and 20 (or a supported V8-based Node.js LTS release).


[Generated] Document the V8 C++ CPU & Heap Profiler (v8::CpuProfiler, v8::HeapProfiler) requirement of the pprof native addon in .readme-partials.yaml so automated README generation preserves the Bun (JavaScriptCore) runtime compatibility notice.

danieljbruce · 2026-10-26T19:08:35Z

+    [`pprof`](https://www.npmjs.com/package/pprof) module, a module with a native C++
+    component (`pprof.node`) compiled against V8's `v8::CpuProfiler` and `v8::HeapProfiler`
+    C++ APIs (`v8-profiler.h`).
+        * **Bun / JavaScriptCore Incompatibility:** Because Bun uses JavaScriptCore (JSC) instead of V8 and does not expose V8's C++ profiling ABI, `@google-cloud/profiler` is **not supported on the Bun runtime**. For Bun workloads on Google Cloud, use OpenTelemetry (`@google-cloud/opentelemetry-cloud-trace-exporter` and `@google-cloud/opentelemetry-cloud-monitoring-exporter`) instead.


[Generated] Document the V8 C++ CPU & Heap Profiler (v8::CpuProfiler, v8::HeapProfiler) requirement of the pprof native addon in .readme-partials.yaml so automated README generation preserves the Bun (JavaScriptCore) runtime compatibility notice.

danieljbruce · 2026-10-26T19:08:36Z

 for versions compatible with Node.js 8.

+> **Note on Bun and Non-V8 Runtimes:** `@google-cloud/profiler` depends on [`pprof`](https://www.npmjs.com/package/pprof), a native C++ addon compiled against V8's `v8::CpuProfiler` and `v8::HeapProfiler` C++ APIs (`v8-profiler.h`). Because Bun uses JavaScriptCore (JSC) instead of V8, `@google-cloud/profiler` is **not supported on the Bun runtime**. For Bun applications on Google Cloud, use OpenTelemetry (`@google-cloud/opentelemetry-cloud-trace-exporter` and `@google-cloud/opentelemetry-cloud-monitoring-exporter`) for observability.
+


[Generated] Add a Runtime Compatibility (Node.js vs. Bun) section to @google-cloud/profiler README.md explaining why pprof requires Node.js V8 C++ profiler APIs and providing a safe typeof Bun === "undefined" dynamic import guard for multi-runtime services.

danieljbruce · 2026-10-27T16:56:47Z

/gemini review

gemini-code-assist

Code Review

This pull request updates the documentation in README.md and .readme-partials.yaml to clarify Node.js version requirements and explicitly document that @google-cloud/profiler is incompatible with the Bun runtime due to its dependency on V8 C++ APIs. Feedback on the changes suggests simplifying the Node.js version phrasing in .readme-partials.yaml to avoid contradiction and clearly state support for any V8-based Node.js LTS release of version 14 or higher.

gemini-code-assist · 2026-10-27T17:02:11Z

    ### Prerequisites

-    1. Your application will need to be using Node.js version between 14 and 20.
+    1. Your application will need to be using Node.js version between 14 and 20 (or a supported V8-based Node.js LTS release).


The phrasing "Node.js version between 14 and 20 (or a supported V8-based Node.js LTS release)" is slightly contradictory and confusing, as it first restricts the version to 14-20 and then immediately expands it to other LTS releases (like Node 22). We should simplify this to clearly state that any supported V8-based Node.js LTS release (version 14 or higher) is required.

1. Your application will need to be using a supported V8-based Node.js LTS release (Node.js 14 or higher).

quirogas · 2026-10-28T22:08:14Z

    ### Prerequisites

-    1. Your application will need to be using Node.js version between 14 and 20.
+    1. Your application will need to be using Node.js version between 14 and 20 (or a supported V8-based Node.js LTS release).


Nit: should we update this sentence to include the Node ranges we support?

quirogas · 2026-10-28T22:10:28Z

 For example, `npm install @google-cloud/profiler@legacy-8` installs client libraries
 for versions compatible with Node.js 8.

+> **Note on Bun and Non-V8 Runtimes:** `@google-cloud/profiler` depends on [`pprof`](https://www.npmjs.com/package/pprof), a native C++ addon compiled against V8's `v8::CpuProfiler` and `v8::HeapProfiler` C++ APIs (`v8-profiler.h`). Because Bun uses JavaScriptCore (JSC) instead of V8, `@google-cloud/profiler` is **not supported on the Bun runtime**. For Bun applications on Google Cloud, use OpenTelemetry (`@google-cloud/opentelemetry-cloud-trace-exporter` and `@google-cloud/opentelemetry-cloud-monitoring-exporter`) for observability.


Nit: This note seems quite specific, and I feel like it implies that we want to support runtimes other than Node, which isn't the case for this profiler.

product-auto-label Bot added the api: cloudprofiler Issues related to the Cloud Profiler API. label Oct 26, 2026

gemini-code-assist Bot reviewed Oct 26, 2026

View reviewed changes

danieljbruce commented Oct 26, 2026

View reviewed changes

docs(profiler): document V8 native pprof addon requirement on Bun

3c00882

danieljbruce force-pushed the docs/b578005545-profiler-bun-v8-addon branch from 0782bd2 to 3c00882 Compare October 27, 2026 16:55

gemini-code-assist Bot reviewed Oct 27, 2026

View reviewed changes

danieljbruce mentioned this pull request Oct 28, 2026

refactor(profiler): replace native pprof dependency with inspector bindings #9762

Draft

danieljbruce added do not merge Indicates a pull request not ready for merge, due to either quality or timing. and removed do not merge Indicates a pull request not ready for merge, due to either quality or timing. labels Oct 28, 2026

danieljbruce marked this pull request as ready for review October 28, 2026 21:17

danieljbruce requested review from a team as code owners October 28, 2026 21:17

danieljbruce requested review from quirogas and removed request for a team October 28, 2026 21:18

quirogas reviewed Oct 28, 2026

View reviewed changes

Navigation Menu

Repository navigation

docs(profiler): document V8 native pprof addon requirement on Bun - #9727

docs(profiler): document V8 native pprof addon requirement on Bun#9727
danieljbruce wants to merge 1 commit into
fix/b578003818-gax-stream-cancel-abortfrom
docs/b578005545-profiler-bun-v8-addon

danieljbruce commented Oct 26, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Oct 26, 2026

Uh oh!

gemini-code-assist Bot Oct 26, 2026

Uh oh!

danieljbruce Oct 26, 2026

Uh oh!

danieljbruce Oct 26, 2026

Uh oh!

danieljbruce Oct 26, 2026

Uh oh!

danieljbruce commented Oct 27, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Oct 27, 2026

Uh oh!

quirogas Oct 28, 2026

Uh oh!

quirogas Oct 28, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		for versions compatible with Node.js 8.

		> Note on Bun and Non-V8 Runtimes: `@google-cloud/profiler` depends on [`pprof`](https://www.npmjs.com/package/pprof), a native C++ addon compiled against V8's `v8::CpuProfiler` and `v8::HeapProfiler` C++ APIs (`v8-profiler.h`). Because Bun uses JavaScriptCore (JSC) instead of V8, `@google-cloud/profiler` is not supported on the Bun runtime. For Bun applications on Google Cloud, use OpenTelemetry (`@google-cloud/opentelemetry-cloud-trace-exporter` and `@google-cloud/opentelemetry-cloud-monitoring-exporter`) for observability.

Conversation

danieljbruce commented Oct 26, 2026

Description

Impact

Changes

Testing

Alternatives

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

danieljbruce Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

danieljbruce Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

danieljbruce Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

danieljbruce commented Oct 27, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Oct 27, 2026

Choose a reason for hiding this comment

Uh oh!

quirogas Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

quirogas Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants