feat(tracing): adding block production tracing

[chatton]

Overview

[claude]

Claude finished @chatton's task in 1m 57s —— View job

---

Comprehensive Code Review

I've completed a thorough review of the block production tracing implementation. Overall, this is a well-structured addition that follows good design patterns. Here are my findings across multiple dimensions:

---

✅ Strengths

1. Architecture & Design

• Excellent use of the decorator pattern to add tracing without modifying core logic
• Clean separation of concerns with the BlockProducer interface
• Optional tracing via config flag (IsTracingEnabled()) is a good practice
• The interface extraction enables easy testing and extensibility

2. Test Coverage

• Comprehensive test suite with 342 lines covering all methods and error paths
• Proper use of OpenTelemetry test infrastructure (tracetest.SpanRecorder)
• Good test isolation with mock implementations
• Tests verify both success and error cases systematically

3. Code Quality

• Follows Go idioms and conventions throughout
• Clear, descriptive naming (tracedBlockProducer, WithTracingBlockProducer)
• Consistent error handling patterns
• Proper context propagation

---

🔍 Issues & Recommendations

1. Critical: Context Handling Bug in ValidateBlock (block/internal/executing/tracing.go:108)

func (t *tracedBlockProducer) ValidateBlock(lastState types.State, header *types.SignedHeader, data *types.Data) error {
    _, span := t.tracer.Start(context.Background(), "BlockExecutor.ValidateBlock",

Problem: Using context.Background() instead of accepting a context.Context parameter breaks the trace hierarchy and loses parent span relationships.

Impact:

• Validation spans won't be properly nested under parent operations
• Distributed tracing will be broken for this operation
• Timeout/cancellation from parent context is lost

Recommendation:

1. Update the BlockProducer interface to accept context.Context for ValidateBlock:

   ValidateBlock(ctx context.Context, lastState types.State, header *types.SignedHeader, data *types.Data) error

2. Update both the interface implementation and all call sites

Fix this →

---

2. Consistency: Attribute Naming (block/internal/executing/tracing.go:56, 71, 89)

The code uses inconsistent attribute naming:

• batch.tx_count (line 56)
• tx.count (line 71)

Recommendation: Standardize to follow OpenTelemetry semantic conventions. Prefer:

attribute.Int("batch.transaction_count", len(batchData.Transactions))
attribute.Int("block.transaction_count", txCount)

This aligns with OTel conventions where related metrics use consistent prefixes.

---

3. Documentation: Missing Package-Level Comment (block/internal/executing/tracing.go:1)

The new tracing.go file lacks a package comment explaining its purpose.

Recommendation: Add a package comment:

// Package executing provides block production and execution logic for the ev-node.
// This file implements OpenTelemetry tracing decorators for block production operations.

---

4. Performance: Unnecessary Nil Checks (block/internal/executing/tracing.go:54, 64)

if batchData != nil && batchData.Batch != nil {
    span.SetAttributes(
        attribute.Int("batch.tx_count", len(batchData.Transactions)),
    )
}

The check for batchData.Batch != nil is redundant since batchData.Transactions is directly accessible. Consider simplifying to:

if batchData != nil && len(batchData.Transactions) > 0 {

Though this is minor, it's more idiomatic and avoids the extra pointer dereference check.

---

5. Test Quality: Magic Numbers (block/internal/executing/tracing_test.go:183-184, etc.)

Tests use hardcoded values without explanation:

requireAttribute(t, attrs, "block.height", int64(100))
requireAttribute(t, attrs, "tx.count", 3)

Recommendation: Use named constants or variables to make test intent clearer:

const testBlockHeight = 100
const testTxCount = 3

---

6. Observability: Missing Span Events

The tracing implementation captures basic metrics but could be more informative with span events for significant milestones:

func (t *tracedBlockProducer) ApplyBlock(ctx context.Context, header types.Header, data *types.Data) (types.State, error) {
    // ... existing code ...
    
    state, err := t.inner.ApplyBlock(ctx, header, data)
    if err != nil {
        span.RecordError(err)
        span.SetStatus(codes.Error, err.Error())
        return types.State{}, err
    }
    
    // Add event for transaction execution completion
    span.AddEvent("transactions_executed", trace.WithAttributes(
        attribute.Int("tx.successful", len(data.Txs)),
    ))
    
    span.SetAttributes(
        attribute.String("state_root", hex.EncodeToString(state.AppHash)),
    )
    return state, nil
}

This would provide better observability for debugging production issues.

---

🔐 Security

✅ No security concerns identified:

• No credential handling or sensitive data exposure
• State root is intentionally logged (public information)
• No injection vulnerabilities
• Proper error wrapping maintains information hiding

---

⚡ Performance

✅ Performance impact is minimal:

• Tracing is opt-in via configuration
• The decorator pattern adds negligible overhead
• No blocking operations or unnecessary allocations
• Proper use of defer span.End() ensures cleanup

⚠️ Minor concern: The hex.EncodeToString(state.AppHash) on line 102 allocates a new string on every block. Consider whether this attribute is necessary in production traces, or sample it.

---

🧪 Testing

Coverage Assessment: ✅ Excellent

• All 5 interface methods have dedicated success/error tests (10 tests total)
• Proper assertion of span attributes, status codes, and error descriptions
• Good use of table-driven test helper (requireAttribute)
• Mock implementation is clean and maintainable

Minor improvement: Consider adding a test for span hierarchy/nesting to ensure parent-child relationships are correct.

---

📝 Documentation

Missing:

• No inline comments explaining why blockProducer field was added to Executor
• No documentation on when tracing is enabled (though config is self-explanatory)
• The BlockProducer interface could use more detailed method documentation

Recommendation: Add a comment in executor.go at line 66-68:

// blockProducer is the interface used for block production operations.
// Defaults to self, but can be wrapped with tracing or other decorators.
// This enables instrumentation without modifying core execution logic.

---

🔄 Integration with Existing Code

✅ Well integrated:

• The changes to executor.go are minimal and non-invasive (lines 127-135)
• Proper integration point in components.go:223-225
• Test updates correctly reflect the API change (private → public)
• No breaking changes to external APIs

---

📊 Summary

Category	Rating	Notes
Architecture	⭐⭐⭐⭐⭐	Excellent decorator pattern usage
Code Quality	⭐⭐⭐⭐	Good, but has the context.Background() issue
Testing	⭐⭐⭐⭐⭐	Comprehensive coverage
Security	⭐⭐⭐⭐⭐	No concerns
Performance	⭐⭐⭐⭐⭐	Minimal overhead
Documentation	⭐⭐⭐	Adequate but could be improved

---

🎯 Action Items

Must Fix:

1. ❗ Fix ValidateBlock to accept context.Context (critical for trace hierarchy)

Should Fix:
2. Standardize attribute naming conventions
3. Add package-level documentation
4. Improve inline comments for the blockProducer field

Nice to Have:
5. Add span events for better observability
6. Add test for span hierarchy
7. Consider sampling state root logging in production

---

✨ Conclusion

This is a solid implementation that demonstrates good software engineering practices. The decorator pattern is the right choice here, and the test coverage is exemplary. The main issue is the context.Background() bug in ValidateBlock, which should be fixed before merging. The other suggestions are improvements that would enhance maintainability and observability but aren't blocking.

Great work on maintaining clean separation of concerns and comprehensive testing! 🚀

---

[github-actions]

The latest Buf updates on your PR. Results from workflow CI / buf-check (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	⏩ skipped	✅ passed	✅ passed	Jan 14, 2026, 3:02 PM

[gemini-code-assist]

Summary of Changes

Hello @chatton, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the observability of the block production process by integrating OpenTelemetry tracing. It achieves this through a clean architectural change, introducing a BlockProducer interface and a tracedBlockProducer decorator. This design allows for the instrumentation of critical block creation, retrieval, application, and validation steps, providing invaluable insights into the system's behavior and performance characteristics, all configurable at runtime.

Highlights

• Tracing Integration: Introduced OpenTelemetry tracing for block production operations, allowing for detailed performance monitoring and debugging.
• Decorator Pattern for BlockProducer: Refactored the Executor to implement a new BlockProducer interface, enabling the use of a decorator pattern to inject tracing logic without altering core business logic.
• Conditional Tracing: Tracing can now be enabled or disabled via configuration, providing flexibility for different deployment environments.
• Detailed Span Attributes: Tracing spans capture relevant attributes such as block height, transaction count, and state root, offering rich context for each traced operation.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[codecov]

Codecov Report

❌ Patch coverage is 91.75258% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 58.48%. Comparing base (d63f852) to head (0bc03f0).

Files with missing lines	Patch %	Lines
block/internal/executing/executor.go	75.00%	5 Missing and 1 partial ⚠️
block/components.go	0.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@                Coverage Diff                 @@
##           tracing-part-6    #2980      +/-   ##
==================================================
+ Coverage           58.19%   58.48%   +0.28%     
==================================================
  Files                  99      100       +1     
  Lines                9543     9619      +76     
==================================================
+ Hits                 5554     5626      +72     
- Misses               3379     3382       +3     
- Partials              610      611       +1     

Flag	Coverage Δ
combined	58.48% <91.75%> (+0.28%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[gemini-code-assist]

Code Review

This pull request introduces OpenTelemetry tracing for the block production process, which is a great addition for observability. The implementation uses a clean decorator pattern by defining a BlockProducer interface and wrapping the Executor with a tracedBlockProducer. This approach is well-executed and enhances modularity. Additionally, the changes include several important fixes for context propagation, improving the overall robustness of the code. The new tracing logic is also well-tested. I have one suggestion to improve trace context propagation for the ValidateBlock step to ensure the trace hierarchy is correctly maintained.

[gemini-code-assist]

Using context.Background() here creates a new root span for ValidateBlock, which means it won't appear as a child of the ProduceBlock span in traces. This breaks the trace context propagation.

To fix this, the ValidateBlock method should accept a context.Context argument. This will require updating the BlockProducer interface and all its implementations (Executor, tracedBlockProducer, and mockBlockProducer in tests).

I've provided a suggestion for this file. You'll also need to update:

• block/internal/executing/block_producer.go: Add ctx context.Context to ValidateBlock in the interface.
• block/internal/executing/executor.go: Add ctx to the ValidateBlock implementation and pass it from ProduceBlock.
• block/internal/executing/tracing_test.go: Update the mockBlockProducer to match the new interface.

This change will ensure ValidateBlock spans are correctly parented under ProduceBlock spans.

Suggested change

	func (t *tracedBlockProducer) ValidateBlock(lastState types.State, header *types.SignedHeader, data *types.Data) error {
	_, span := t.tracer.Start(context.Background(), "BlockExecutor.ValidateBlock",
	trace.WithAttributes(
	attribute.Int64("block.height", int64(header.Height())),
	),
	)
	defer span.End()
	err := t.inner.ValidateBlock(lastState, header, data)
	if err != nil {
	span.RecordError(err)
	span.SetStatus(codes.Error, err.Error())
	}
	return err
	}
	func (t *tracedBlockProducer) ValidateBlock(ctx context.Context, lastState types.State, header *types.SignedHeader, data *types.Data) error {
	ctx, span := t.tracer.Start(ctx, "BlockExecutor.ValidateBlock",
	trace.WithAttributes(
	attribute.Int64("block.height", int64(header.Height())),
	),
	)
	defer span.End()
	err := t.inner.ValidateBlock(ctx, lastState, header, data)
	if err != nil {
	span.RecordError(err)
	span.SetStatus(codes.Error, err.Error())
	}
	return err
	}