Add opcode tracing plugin #10038
Open
Add opcode tracing plugin #10038
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
dmitriy-b
requested review from
LukaszRozmej,
MarekM25,
flcl42 and
rubo
as code owners
Member
LukaszRozmej
left a comment
LukaszRozmej
left a comment
There was a problem hiding this comment.
Didn't check everything, but things that potentially stand out:
- Not sure if converting to
stringis done too soon. IMO whole trace could be by domain types (byte, Hash256), and stringify only when outputing JSON - could be faster - Paths manipulation - should be standarised with other in node
- File writing - avoid serializing to string first, directly to file.
Comment on lines
1035
to
1041
| "Nethermind.Api": "[1.36.0-unstable, )", | ||
| "Nethermind.Blockchain": "[1.36.0-unstable, )", | ||
| "Nethermind.Config": "[1.36.0-unstable, )", | ||
| "Nethermind.Core": "[1.36.0-unstable, )", | ||
| "Nethermind.Evm": "[1.36.0-unstable, )", | ||
| "Nethermind.Logging": "[1.36.0-unstable, )", | ||
| "Nethermind.Synchronization": "[1.36.0-unstable, )" |
Member
There was a problem hiding this comment.
Should probably be 1.37.0-unstable
| /// <summary> | ||
| /// Gets or sets a value indicating whether the OpcodeTracing plugin is enabled. | ||
| /// </summary> | ||
| [ConfigItem(Description = "Enable the OpcodeTracing plugin.", DefaultValue = "false")] |
Member
There was a problem hiding this comment.
Suggested change
| [ConfigItem(Description = "Enable the OpcodeTracing plugin.", DefaultValue = "false")] | |
| [ConfigItem(Description = "Whether to enable opcode tracing.", DefaultValue = "false")] |
| /// <summary> | ||
| /// Gets or sets the directory where opcode trace JSON files are written. | ||
| /// </summary> | ||
| [ConfigItem(Description = "Directory where opcode trace JSON files are written.", DefaultValue = "traces/opcodes")] |
Member
There was a problem hiding this comment.
Suggested change
| [ConfigItem(Description = "Directory where opcode trace JSON files are written.", DefaultValue = "traces/opcodes")] | |
| [ConfigItem(Description = "Directory of opcode trace JSON files to be written.", DefaultValue = "traces/opcodes")] |
| /// Gets or sets the opcode counts dictionary mapping opcode names to occurrence counts. | ||
| /// </summary> | ||
| [JsonPropertyName("opcodeCounts")] | ||
| public required Dictionary<string, long> OpcodeCounts { get; init; } |
Member
There was a problem hiding this comment.
It would probably be faster to accumulate if it was
Suggested change
| public required Dictionary<string, long> OpcodeCounts { get; init; } | |
| public required Dictionary<byte, long> OpcodeCounts { get; init; } |
And we can add JsonConverter to serialize it later as string (or just convert to <string, long> dictionary
| /// <returns>The full path to the created file, or null if writing failed.</returns> | ||
| public async Task<string?> WriteAsync(string outputDirectory, TraceOutput traceOutput) | ||
| { | ||
| if (string.IsNullOrWhiteSpace(outputDirectory)) |
Member
There was a problem hiding this comment.
You might want to use PathUtils.GetApplicationResourcePath to use relative/absolute paths better and potentially avoid issues with environments with restricted access
| /// Gets or sets the opcode counts dictionary mapping opcode names to occurrence counts for this block. | ||
| /// </summary> | ||
| [JsonPropertyName("opcodeCounts")] | ||
| public required Dictionary<string, long> OpcodeCounts { get; init; } |
Member
There was a problem hiding this comment.
Suggested change
| public required Dictionary<string, long> OpcodeCounts { get; init; } | |
| public required Dictionary<byte, long> OpcodeCounts { get; init; } |
Comment on lines
28
to
30
| labels[i] = Enum.IsDefined(typeof(Instruction), opcode) | ||
| ? ((Instruction)opcode).ToString() | ||
| : $"0x{opcode:x2}"; |
Member
There was a problem hiding this comment.
use F
Suggested change
| labels[i] = Enum.IsDefined(typeof(Instruction), opcode) | |
| ? ((Instruction)opcode).ToString() | |
| : $"0x{opcode:x2}"; | |
| labels[i] = FastEnum.IsDefined(typeof(Instruction), opcode) | |
| ? FastEnum.ToString((Instruction)opcode) | |
| : $"0x{opcode:x2}"; |
Comment on lines
54
to
73
| if (traceOutput is null) | ||
| { | ||
| if (_logger.IsError) | ||
| { | ||
| _logger.Error("Cumulative trace output is null"); | ||
| } | ||
| return null; | ||
| } | ||
|
|
||
| try | ||
| { | ||
| // Ensure directory exists | ||
| if (!Directory.Exists(_outputDirectory)) | ||
| { | ||
| Directory.CreateDirectory(_outputDirectory); | ||
| } | ||
|
|
||
| // Serialize and write (overwrite existing file) | ||
| string json = JsonSerializer.Serialize(traceOutput, _serializerOptions); | ||
| await File.WriteAllTextAsync(_filePath!, json).ConfigureAwait(false); |
| /// Gets or sets the aggregated opcode counts dictionary mapping opcode names to total occurrence counts. | ||
| /// </summary> | ||
| [JsonPropertyName("opcodeCounts")] | ||
| public required Dictionary<string, long> OpcodeCounts { get; init; } |
Member
There was a problem hiding this comment.
Suggested change
| public required Dictionary<string, long> OpcodeCounts { get; init; } | |
| public required Dictionary<byte, long> OpcodeCounts { get; init; } |
Comment on lines
119
to
120
| BlockHash = blockHash.ToString(), | ||
| ParentHash = parentHash.ToString(), |
Contributor
Author
|
@LukaszRozmej thank you for the review. I think I fixed everything, please take a look |
kamilchodola
approved these changes
Jan 7, 2026
kamilchodola
requested review from
Marchhill,
deffrian,
dipkakwani,
emlautarom1,
marcindsobczak and
smartprogrammer93
as code owners
dmitriy-b
force-pushed
the
feat/opcode-tracing-plugin
branch
from
3b99ef7 to
dfab3a4
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Changes
--OpcodeTracing.Enabled,--OpcodeTracing.Mode,--OpcodeTracing.Blocks,--OpcodeTracing.StartBlock,--OpcodeTracing.EndBlock,--OpcodeTracing.OutputDirectory,--OpcodeTracing. MaxDegreeOfParallelism(for retrospective mode only).Types of changes
What types of changes does your code introduce?
Testing
Requires testing
If yes, did you write tests?
Notes on testing
Tested manually via Docker with Hoodi testnet:
See attached logs json files.
opcode-trace-block-1845471.json
opcode-trace-block-1845470.json
opcode-trace-all-20251224143649.json
opcode-trace-1844925-1844934.json
05-validation-error.log
04-realtime-mode.log
03-retrospective-mode.log
02-plugin-not-specified.log
01-plugin-disabled.log
Documentation
Requires documentation update
Usage examples needed in docs for CLI flags and output format.
I also added detailed documentation how it works at
src/Nethermind/Nethermind.OpcodeTracing.Plugin/README.md.Requires explanation in Release Notes
We can add something like: New optional plugin for tracing EVM opcode usage. Enable with
--OpcodeTracing.Enabled=true. Useful for analyzing opcode frequency across block ranges.