Enable/disable trace fields for RPCs that dump traces to files #9183

lu-pinto · 2025-09-17T11:04:23Z

This PR allows for enabling and disabling stack, storage, returnData, etc.. for these 2 specific RPC endpoints: debug_traceStandardBlockToFile and debug_traceStandardBadBlockToFile. It does not change any previous defaults for memory which is shown by default. This is to allow debugging of big transactions by dumping them to disk instead of waiting for a JSON reply with debug_traceBlock* kind of methods.
This PR also refactors OpCodeTracerConfig to be created using a builder pattern and passed around to the 2 tracers involved in the mentioned RPC endpoints: DebugOperationTracer and StandardJsonTracer aka StreamingOperationTracer, avoiding code duplication.

Example of usage:

curl --location --globoff 'http://localhost:8545' --data '{
    "jsonrpc": "2.0",
    "method": "debug_standardTraceBlockToFile",
    "params": [
        "0x2476b23a03dd87f272724a12213dc4a1ca8f13a1aa9d128a690e1b7d7d312e5e",
        {
            "txHash": "0xdfd5028da0f2f306ae71dc558c26bb1935b13ec3a0e909223eaa77bf761189a8",
            "disableStack": true,
            "disableMemory": true,
            "disableStorage": false
        }
    ],
    "id": 1
}'

curl --location --globoff 'http://localhost:8545/' --data '{
    "jsonrpc": "2.0",
    "method": "debug_standardTraceBadBlockToFile",
    "params": [
        "0x2476b23a03dd87f272724a12213dc4a1ca8f13a1aa9d128a690e1b7d7d312e5e",
        {
            "txHash": "0xdfd5028da0f2f306ae71dc558c26bb1935b13ec3a0e909223eaa77bf761189a8",
            "disableStack": true,
            "disableMemory": true,
            "disableStorage": false
        }
    ],
    "id": 1
}'

Fixed Issue(s)

fixes #9182 9182

Thanks for sending a pull request! Have you done the following?

Checked out our contribution guidelines?
Considered documentation and added the doc-change-required label to this PR if updates are required.
Considered the changelog and included an update if required.
For database changes (e.g. KeyValueSegmentIdentifier) considered compatibility and performed forwards and backwards compatibility tests

Locally, you can run these tests to catch failures early:

spotless: ./gradlew spotlessApply
unit tests: ./gradlew build
acceptance tests: ./gradlew acceptanceTest
integration tests: ./gradlew integrationTest
reference tests: ./gradlew ethereum:referenceTests:referenceTests
hive tests: Engine or other RPCs modified?

macfarla · 2025-09-26T00:04:51Z

...erledger/besu/ethereum/api/jsonrpc/methods/DebugStandardTraceBlockToFileIntegrationTest.java

@@ -0,0 +1,225 @@
+/*
+ * Copyright ConsenSys AG.


Suggested change

* Copyright ConsenSys AG.

* Copyright contributors to Besu.

how did you spot this? was it some automated tool. I guess this should be done as part of spotless? do we need to make any changes?

build.gradle (spotless) should add the newer version if it's not there already

CHANGELOG.md

...erledger/besu/ethereum/api/jsonrpc/methods/DebugStandardTraceBlockToFileIntegrationTest.java

…nd debug_traceStandardBadBlockToFile Signed-off-by: Luis Pinto <luis.pinto@consensys.net>

Signed-off-by: Luis Pinto <luis.pinto@consensys.net>

macfarla

LGTM - maybe worth a quick doc on how to use it for devs

lu-pinto · 2025-10-06T11:12:09Z

LGTM - maybe worth a quick doc on how to use it for devs

@macfarla do you mean a doc entry in the readmes of this project or an entry in the wiki?

macfarla · 2025-10-07T05:10:13Z

LGTM - maybe worth a quick doc on how to use it for devs

@macfarla do you mean a doc entry in the readmes of this project or an entry in the wiki?

I think because it's for devs it could be a markdown file in docs folder https://github.com/hyperledger/besu/tree/main/docs

lu-pinto · 2025-10-07T12:51:16Z

LGTM - maybe worth a quick doc on how to use it for devs

@macfarla do you mean a doc entry in the readmes of this project or an entry in the wiki?

I think because it's for devs it could be a markdown file in docs folder main/docs

well this PR only allows for options to be overridden by the user like other RPC endpoints already do. It is nothing new I'm adding. It just happens that these 2 endpoints do not allow modification of these options by the user like the others. Looking at the main/docs folder I don't see RPCs being extensively documented there. I can add a paragraph to the RPC notes there, I just feel this information would be a bit out of context hidden in those folders without a full documentation on RPCs and how they work. I can add some thoughts to the RPC notes then, would that make sense?

macfarla · 2025-10-07T20:06:21Z

LGTM - maybe worth a quick doc on how to use it for devs

@macfarla do you mean a doc entry in the readmes of this project or an entry in the wiki?

I think because it's for devs it could be a markdown file in docs folder main/docs

well this PR only allows for options to be overridden by the user like other RPC endpoints already do. It is nothing new I'm adding. It just happens that these 2 endpoints do not allow modification of these options by the user like the others. Looking at the main/docs folder I don't see RPCs being extensively documented there. I can add a paragraph to the RPC notes there, I just feel this information would be a bit out of context hidden in those folders without a full documentation on RPCs and how they work. I can add some thoughts to the RPC notes then, would that make sense?

here might make sense too https://besu.hyperledger.org/public-networks/reference/api#debug-methods - also doesn't have to block this PR

macfarla · 2025-10-15T23:38:53Z

this PR only allows for options to be overridden by the user like other RPC endpoints already do.
in this case extra doc not needed.

…-more-options

lu-pinto · 2025-10-16T10:06:32Z

here might make sense too besu.hyperledger.org/public-networks/reference/api#debug-methods - also doesn't have to block this PR

As discussed offline I think it is good to document these changes in here. I added a doc-change-required tag for that.

Signed-off-by: Luis Pinto <luis.pinto@consensys.net>

…-more-options

macfarla

LGTM

…ledger#9183) Co-authored-by: Sally MacFarlane <macfarla.github@gmail.com> Allows for enabling and disabling stack, storage, returnData, etc.. for these 2 specific RPC endpoints: debug_traceStandardBlockToFile and debug_traceStandardBadBlockToFile. It does not change any previous defaults for memory which is shown by default. Example of usage: curl --location --globoff 'http://localhost:8545' --data '{ "jsonrpc": "2.0", "method": "debug_standardTraceBlockToFile", "params": [ "0x2476b23a03dd87f272724a12213dc4a1ca8f13a1aa9d128a690e1b7d7d312e5e", { "txHash": "0xdfd5028da0f2f306ae71dc558c26bb1935b13ec3a0e909223eaa77bf761189a8", "disableStack": true, "disableMemory": false, "disableStorage": false } ], "id": 1 }' curl --location --globoff 'http://localhost:8545/' --data '{ "jsonrpc": "2.0", "method": "debug_standardTraceBadBlockToFile", "params": [ "0x2476b23a03dd87f272724a12213dc4a1ca8f13a1aa9d128a690e1b7d7d312e5e", { "txHash": "0xdfd5028da0f2f306ae71dc558c26bb1935b13ec3a0e909223eaa77bf761189a8", "disableStack": true, "disableMemory": false, "disableStorage": false } ], "id": 1 }' # Conflicts: # ethereum/api/src/main/java/org/hyperledger/besu/ethereum/api/jsonrpc/internal/processor/TransactionTracer.java

…ledger#9183) Co-authored-by: Sally MacFarlane <macfarla.github@gmail.com> Allows for enabling and disabling stack, storage, returnData, etc.. for these 2 specific RPC endpoints: debug_traceStandardBlockToFile and debug_traceStandardBadBlockToFile. It does not change any previous defaults for memory which is shown by default. Example of usage: curl --location --globoff 'http://localhost:8545' --data '{ "jsonrpc": "2.0", "method": "debug_standardTraceBlockToFile", "params": [ "0x2476b23a03dd87f272724a12213dc4a1ca8f13a1aa9d128a690e1b7d7d312e5e", { "txHash": "0xdfd5028da0f2f306ae71dc558c26bb1935b13ec3a0e909223eaa77bf761189a8", "disableStack": true, "disableMemory": false, "disableStorage": false } ], "id": 1 }' curl --location --globoff 'http://localhost:8545/' --data '{ "jsonrpc": "2.0", "method": "debug_standardTraceBadBlockToFile", "params": [ "0x2476b23a03dd87f272724a12213dc4a1ca8f13a1aa9d128a690e1b7d7d312e5e", { "txHash": "0xdfd5028da0f2f306ae71dc558c26bb1935b13ec3a0e909223eaa77bf761189a8", "disableStack": true, "disableMemory": false, "disableStorage": false } ], "id": 1 }' Signed-off-by: stefan.pingel@consensys.net <stefan.pingel@consensys.net>

lu-pinto added the dev experience The build system, things that enable easier development etc. label Sep 17, 2025

lu-pinto self-assigned this Sep 17, 2025

lu-pinto force-pushed the trace-block-to-file-more-options branch from be9ca84 to fc4cf7d Compare September 18, 2025 13:58

lu-pinto added the doc-change-required Indicates an issue or PR that requires doc to be updated label Sep 18, 2025

macfarla reviewed Sep 26, 2025

View reviewed changes

lu-pinto force-pushed the trace-block-to-file-more-options branch from fc4cf7d to 3dfe7ce Compare October 1, 2025 14:22

lu-pinto added 5 commits October 2, 2025 09:45

enable stack and storage settings in debug_traceStandardBlockToFile a…

e735393

…nd debug_traceStandardBadBlockToFile Signed-off-by: Luis Pinto <luis.pinto@consensys.net>

Add integration test for debug_traceStandardBlockToFile RPC

0417490

Signed-off-by: Luis Pinto <luis.pinto@consensys.net>

spotless & javadoc

40339ea

Signed-off-by: Luis Pinto <luis.pinto@consensys.net>

changelog

1608602

Signed-off-by: Luis Pinto <luis.pinto@consensys.net>

split stack assert into another test

a409cd3

Signed-off-by: Luis Pinto <luis.pinto@consensys.net>

lu-pinto force-pushed the trace-block-to-file-more-options branch from 3dfe7ce to a409cd3 Compare October 2, 2025 13:06

macfarla approved these changes Oct 6, 2025

View reviewed changes

Merge branch 'upstream/main' into trace-block-to-file-more-options

4e2c0bf

Merge remote-tracking branch 'upstream/main' into trace-block-to-file…

283fb21

…-more-options

fix not honoring defaults when txHash provided

0eb307e

Signed-off-by: Luis Pinto <luis.pinto@consensys.net>

lu-pinto force-pushed the trace-block-to-file-more-options branch from a28978b to 0eb307e Compare October 16, 2025 19:58

Merge remote-tracking branch 'upstream/main' into trace-block-to-file…

5788b39

…-more-options

macfarla approved these changes Oct 16, 2025

View reviewed changes

Merge branch 'main' into trace-block-to-file-more-options

d160474

lu-pinto merged commit 3422940 into hyperledger:main Oct 17, 2025
46 checks passed

lu-pinto removed the dev experience The build system, things that enable easier development etc. label Oct 17, 2025

alexandratran mentioned this pull request Nov 12, 2025

Enable/disable trace fields for debug_traceStandardBlockToFile and debug_traceStandardBadBlockToFile hyperledger/besu-docs#1855

Open

alexandratran removed the doc-change-required Indicates an issue or PR that requires doc to be updated label Nov 12, 2025

Enable/disable trace fields for RPCs that dump traces to files #9183

Enable/disable trace fields for RPCs that dump traces to files #9183

Uh oh!

Conversation

lu-pinto commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Fixed Issue(s)

Thanks for sending a pull request! Have you done the following?

Locally, you can run these tests to catch failures early:

Uh oh!

macfarla Sep 26, 2025

Choose a reason for hiding this comment

Uh oh!

lu-pinto Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

macfarla Oct 7, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

macfarla left a comment

Choose a reason for hiding this comment

Uh oh!

lu-pinto commented Oct 6, 2025

Uh oh!

macfarla commented Oct 7, 2025

Uh oh!

lu-pinto commented Oct 7, 2025

Uh oh!

macfarla commented Oct 7, 2025

Uh oh!

macfarla commented Oct 15, 2025

Uh oh!

lu-pinto commented Oct 16, 2025

Uh oh!

macfarla left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lu-pinto commented Sep 17, 2025 •

edited

Loading