gh-146256: Add `--jsonl` collector to the `profiling.sampling` by maurycy · Pull Request #146257 · python/cpython

maurycy · 2026-03-21T15:59:53Z

This PR adds --jsonl discussed in #146256.

The aim is to introduce a subset of JSONL format that will be also used in streaming. I made some decisions but highlighted possible questions in the above PR.

The class is below 2**8 lines of code and does not touch existing profiling.sampling code, so I took a leap.

Usage

macOS:

sudo -E \
  uv run \
    --python /Users/maurycy/src/github.com/maurycy/cpython/python.exe \
      python \
        -m profiling.sampling \
           run \
             --jsonl \
             -o /tmp/profile.jsonl /tmp/hello_world.py

Where /tmp/hello_world.py could be:

import time
print("Hello, World!")
time.sleep(0.1)

Visual Studio Code Extension

For the purpose of demonstrating the --jsonl usefulness, I have vibe-coded (with Claude Code) a simple VSCode Extension (only that) that displays a JSONL profile in the editor:

I think that, once we have --stream it will be much more exciting.

Apart from headless profilers: updating the real-time hot spots from the production in VSCode, or, well, making agents' life easier.

You can fetch the vibe-coded VSCode Extension here (no guarantees):

Or:

mkdir -p ~/.vscode/extensions/profiling-heatmap                                                                                                                                                                                   
curl -sL 'https://gist.githubusercontent.com/maurycy/50a80586636a90216efc86065bbfd6de/raw/719e46f4f086c819edbbee7b20c45c41eae15e8b/extension.js' -o ~/.vscode/extensions/profiling-heatmap/extension.js                           
curl -sL 'https://gist.githubusercontent.com/maurycy/fa4c3acd9e8e681a609bddc9ad04c4ae/raw/1edd3c2716a4a9e55aba8ed94850fd70f61fa606/package.json' -o ~/.vscode/extensions/profiling-heatmap/package.json                           
echo "Restart VSCode, then: Cmd+Shift+P -> 'Profiling: Load JSONL Profile'"

Please do not forget about removing ~/.vscode/extensions/profiling-heatmap/ after tests.

Issue: Add --jsonl flag to the profiling.sampling #146256

…ktor * upstream/main: (119 commits) pythongh-144270: Make SubElement parent and tag positional-only (pythonGH-144845) pythongh-146558: JIT optimize dict access for objects with known hash (python#146559) pythongh-139922: always run MSVC 64-bit tail-calling CI (pythonGH-146570) pythongh-126835: Fix _PY_IS_SMALL_INT() macro (python#146631) pythongh-146587: fix type slot assignment incase of multiple slots for same name (python#146593) pythongh-138122: Add differential flame graph (python#145785) pythongh-146416: Emscripten: Improve standard stream handling in node_entry.mjs (python#146417) pythongh-146444: Don't package as part of iOS 'build hosts' target (python#146628) pythongh-138850: Add --disable-epoll to configure (pythonGH-145768) pythongh-146444: Make Platforms/Apple/ compatible with Python 3.9 (python#146624) pythongh-138577: Fix keyboard shortcuts in getpass with echo_char (python#141597) pythongh-146556: Fix infinite loop in annotationlib.get_annotations() on circular __wrapped__ (python#146557) pythongh-146579: _zstd: Fix decompression options dict error message (python#146577) pythongh-146083: Upgrade bundled Expat to 2.7.5 (python#146085) pythongh-146080: fix a crash in SNI callbacks when the SSL object is gone (python#146573) pythongh-146090: fix memory management of internal `sqlite3` callback contexts (python#146569) pythongh-145876: Do not mask KeyErrors raised during dictionary unpacking in call (pythonGH-146472) pythongh-146004: fix test_args_from_interpreter_flags on windows (python#146580) pythongh-139003: Use frozenset for module level attributes in _pyrepl.utils (python#139004) pythonGH-146527: Add more data to GC statistics and add it to PyDebugOffsets (python#146532) ...

pablogsal · 2026-03-31T08:55:30Z

@ivonastojanovic can you take a look?

maurycy · 2026-03-31T09:00:24Z

@ivonastojanovic @pablogsal Thank you.

Please note that I've started adding test coverage, so it might be worth waiting a day with a proper review (it's already interesting: confused myself with skip_idle), if you find the direction promising.

I will mark it as Ready for review immediately.

Perhaps #146256 and #145464 are the best places to discuss the format and the ideas.

* main: pythongh-145458: use `self.skip_idle` consistently in the tachyon profiler (python#145459) pythongh-146615: Fix format specifiers in Objects/ directory (pythonGH-146620) pythongh-146615: Fix format specifiers in Python/ directory (pythonGH-146619) pythongh-146615: Fix format specifiers in test cextensions (pythonGH-146618) pythongh-146615: Fix format specifiers in extension modules (pythonGH-146617) pythongh-146615: Fix crash in __get__() for METH_METHOD descriptors with invalid type argument (pythonGH-146634) pythongh-146376: Reduce timeout in Emscripten GHA workflow (python#146378) pythongh-146442: Fix various bugs in compiler pipeline (python#146443) pythongh-146238: Support half-floats in the array module (python#146242) pythongh-145056: Add support for merging collections.UserDict and frozendict (pythonGH-146465) pythongh-145056: Fix merging of collections.OrderedDict and frozendict (pythonGH-146466) pythongh-139633: Run netrc file permission check only once per parse (pythonGH-139634)

maurycy · 2026-03-31T14:51:00Z

Lib/profiling/sampling/jsonl_collector.py

+from .stack_collector import StackTraceCollector
+
+
+_CHUNK_SIZE = 256


More interesting than it looks!

The collector is not streaming yet. The values I found are on par with 256-512:

https://github.com/DataDog/dd-trace-py/blob/32a7d167b7628589ae1605aa5165ab4290836da2/ddtrace/internal/settings/_config.py#L454

https://github.com/open-telemetry/opentelemetry-specification/blob/3a4cba26572558609bdcb51dfcbb2d8259085387/specification/trace/sdk.md#L1111-L1114

https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecords.html

https://github.com/elastic/elasticsearch-py/blob/dc2f5f0662bc47e9c3072eddcbeb8564d7a766da/elasticsearch/helpers/actions.py#L421-L424

maurycy · 2026-03-31T14:51:44Z

Lib/profiling/sampling/jsonl_collector.py

+        if (frame_id := self._frame_to_id.get(frame_key)) is not None:
+            return frame_id
+
+        frame_id = len(self._frames) + 1


1 or 0 indexed?

maurycy · 2026-03-31T14:52:07Z

Lib/profiling/sampling/jsonl_collector.py

+        if (string_id := self._string_to_id.get(value)) is not None:
+            return string_id
+
+        string_id = len(self._strings) + 1


1 or 0 indexed?

maurycy · 2026-03-31T14:56:58Z

Lib/profiling/sampling/collector.py

    if location is None:
        return DEFAULT_LOCATION
+    if isinstance(location, int):
+        return (location, location, -1, -1)


This is now handled per collector:

https://github.com/python/cpython/blob/main/Lib/profiling/sampling/live_collector/collector.py#L319

https://github.com/python/cpython/blob/main/Lib/profiling/sampling/pstats_collector.py#L31

https://github.com/python/cpython/blob/main/Lib/profiling/sampling/gecko_collector.py#L470-L478

https://github.com/python/cpython/blob/main/Lib/profiling/sampling/gecko_collector.py#L274-L279

I don't know if it's necessary but I simply didn't want to make https://github.com/python/cpython/pull/146257/changes#diff-58ccdb8421c89943862c73d1cbeae3e961873b55ed2adb7efc875dafd549c01bR177 too defensive.

maurycy · 2026-03-31T15:05:50Z

Lib/profiling/sampling/jsonl_collector.py

+            location
+        )
+
+        fields = {"line": lineno}


Should it be -1 or 0 for synthetic?

To quote the Markdown:

lineno = -1: Synthetic frame (no source location)

On the other hand, DEFAULT_LINE settled on 0:

https://github.com/python/cpython/blob/main/Lib/profiling/sampling/constants.py#L24

This is the reason for adding the synthetic here:

https://github.com/python/cpython/pull/146257/changes#diff-58ccdb8421c89943862c73d1cbeae3e961873b55ed2adb7efc875dafd549c01bR162

maurycy · 2026-03-31T15:11:02Z

Lib/profiling/sampling/cli.py

 def _create_collector(format_type, sample_interval_usec, skip_idle, opcodes=False,
-                      output_file=None, compression='auto', diff_baseline=None):
+                      mode=None, output_file=None, compression='auto', diff_baseline=None):


This is already very complex. The collector constructor signature supports all collectors at once.

I've added mode for the purpose of meta but I don't think this scales for other meta.

(Truth to be told, I think that that complex signatures are also the underlying reason for the issue fixed by #145459)

maurycy · 2026-03-31T15:23:44Z

Lib/profiling/sampling/jsonl_collector.py

+}
+
+
+class JsonlCollector(StackTraceCollector):


Maybe the collectors should be separate from renderers?

maurycy · 2026-03-31T15:28:42Z

Lib/profiling/sampling/jsonl_collector.py

+                    "v": 1,
+                    "run_id": self.run_id,
+                    "kind": "frame",
+                    "scope": "final",


The very big thing here is ensuring that the format is future-proof. That's the reason for v.

For example, in the future: "window" for streaming, including timestamps.

maurycy · 2026-03-31T15:34:03Z

@ivonastojanovic @pablogsal Done; ready for review. Thank you.

first stab

2749a44

maurycy requested a review from pablogsal as a code owner March 21, 2026 15:59

bedevere-app bot mentioned this pull request Mar 21, 2026

Add --jsonl flag to the profiling.sampling #146256

Open

bedevere-app bot added the awaiting review label Mar 21, 2026

maurycy marked this pull request as draft March 21, 2026 16:00

bedevere-app bot removed the awaiting review label Mar 21, 2026

maurycy changed the title ~~gh-146256: Add --ndjson flag to the profiling.sampling~~ gh-146256: Add --jsonl flag to the profiling.sampling Mar 21, 2026

maurycy added 2 commits March 21, 2026 21:08

s/ndjson/jsonl/

f13d34c

printing to stdout isn't a great idea

c15d318

maurycy changed the title ~~gh-146256: Add --jsonl flag to the profiling.sampling~~ gh-146256: Add --jsonl collector to the profiling.sampling Mar 23, 2026

maurycy added 8 commits March 30, 2026 19:22

even a basic test

cb27fc0

separate func for end record

59cbb4a

proper name

25c6922

test_jsonl_collector_with_location_info

67cd39a

test synthetic frames

7c85d47

too many new lines

3eddae8

BUG? confusing... two ways to set skip_idle?

f71252e

pablogsal assigned ivonastojanovic Mar 31, 2026

maurycy added 9 commits March 31, 2026 12:25

ok, thx b4fac15

c183109

check if it works fine with (file, loc, func, op)

f20eb52

missing new line

546ce90

filter out sync coordinator

350ad99

s/collapsed_out/jsonl_out/, less copying :D

942d821

nicer reading

bd9aefe

typo

311a4e3

too much copying, left-over

749a868

maurycy added 18 commits March 31, 2026 13:49

just Counter

85ce978

ruff

820d3b9

future-proof name

aad4b18

future-proof iter for streaming

da3e754

truth to be told, this should be layer above

cb6ed34

helper

5a59e0b

reorder

192e54b

eh, just copy from heatmap

3189a8f

smaller chunk; matter of taste

935779f

test actual chunking

e3d8aff

test edge cases

d37f07a

ruff

aaaa972

match pep8

a9b6ccd

style

4fb3ade

too defensive

a0decb5

too many style changes

5f1704b

less style

f2a21fb

ha! even less style...

15b07ba

maurycy commented Mar 31, 2026

View reviewed changes

maurycy marked this pull request as ready for review March 31, 2026 15:29

bedevere-app bot added the awaiting review label Mar 31, 2026

maurycy added 2 commits March 31, 2026 17:33

news

148f4e2

news: proper formatting

69c5768

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

gh-146256: Add `--jsonl` collector to the `profiling.sampling`#146257

gh-146256: Add `--jsonl` collector to the `profiling.sampling`#146257
maurycy wants to merge 40 commits intopython:mainfrom
maurycy:tachyon-ndjson-kolektor

maurycy commented Mar 21, 2026 •

edited

Loading

Uh oh!

pablogsal commented Mar 31, 2026

Uh oh!

maurycy commented Mar 31, 2026 •

edited

Loading

Uh oh!

maurycy Mar 31, 2026

Uh oh!

maurycy Mar 31, 2026

Uh oh!

maurycy Mar 31, 2026

Uh oh!

maurycy Mar 31, 2026

Uh oh!

maurycy Mar 31, 2026

Uh oh!

maurycy Mar 31, 2026 •

edited

Loading

Uh oh!

maurycy Mar 31, 2026 •

edited

Loading

Uh oh!

maurycy Mar 31, 2026 •

edited

Loading

Uh oh!

maurycy commented Mar 31, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		from .stack_collector import StackTraceCollector


		_CHUNK_SIZE = 256

Uh oh!

Conversation

maurycy commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Usage

Visual Studio Code Extension

Uh oh!

pablogsal commented Mar 31, 2026

Uh oh!

maurycy commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maurycy Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

maurycy Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

maurycy Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

maurycy Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

maurycy Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

maurycy Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maurycy Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maurycy Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maurycy commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

maurycy commented Mar 21, 2026 •

edited

Loading

maurycy commented Mar 31, 2026 •

edited

Loading

maurycy Mar 31, 2026 •

edited

Loading

maurycy Mar 31, 2026 •

edited

Loading

maurycy Mar 31, 2026 •

edited

Loading

maurycy commented Mar 31, 2026 •

edited

Loading