forks/go-ethereum
1
0
Fork 1
mirror of https://github.com/ethereum/go-ethereum.git synced 2026-03-11 13:49:02 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Website: add live tracing docs (#29371)

Browse source 
* tracing: add live tracing

* add to list of pages

* review fixes
This commit is contained in:
Sina M 2024-04-06 12:21:57 +02:00 committed by GitHub
parent 0fb2147c06
commit 8787b06b4b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 347 additions and 63 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

104
docs/developers/evm-tracing/custom-tracer.md
View file

@ -15,87 +15,65 @@ In this section a simple native tracer that counts the number of opcodes will be
package native
import (
"encoding/json"
"math/big"
"sync/atomic"
"time"
"encoding/json"
"sync/atomic"
"github.com/ethereum/go-ethereum/common"
"github.com/ethereum/go-ethereum/core/vm"
"github.com/ethereum/go-ethereum/eth/tracers"
"github.com/ethereum/go-ethereum/core/tracing"
"github.com/ethereum/go-ethereum/core/vm"
"github.com/ethereum/go-ethereum/eth/tracers"
)
func init() {
// This is how Geth will become aware of the tracer and register it under a given name
register("opcounter", newOpcounter)
tracers.DefaultDirectory.Register("opcounter", newOpcounter, false)
}
type opcounter struct {
env *vm.EVM
counts map[string]int // Store opcode counts
interrupt uint32 // Atomic flag to signal execution interruption
reason error // Textual reason for the interruption
counts map[string]int
interrupt uint32
reason error
}
func newOpcounter(ctx *tracers.Context, cfg json.RawMessage) tracers.Tracer {
return &opcounter{counts: make(map[string]int)}
// newOpcounter returns a new opcode counting tracer.
func newOpcounter(ctx *tracers.Context, _ json.RawMessage) (*tracers.Tracer, error) {
t := &opcounter{counts: make(map[string]int)}
return &tracers.Tracer{
Hooks: &tracing.Hooks{
OnOpcode: t.onOpcode,
},
GetResult: t.getResult,
Stop: t.stop,
}, nil
}
// CaptureStart implements the EVMLogger interface to initialize the tracing operation.
func (t *opcounter) CaptureStart(env *vm.EVM, from common.Address, to common.Address, create bool, input []byte, gas uint64, value *big.Int) {
t.env = env
func (t *opcounter) onOpcode(pc uint64, op byte, gas, cost uint64, scope tracing.OpContext, rData []byte, depth int, err error) {
// Skip if tracing was interrupted
if atomic.LoadUint32(&t.interrupt) > 0 {
return
}
name := vm.OpCode(op).String()
if _, ok := t.counts[name]; !ok {
t.counts[name] = 0
}
t.counts[name]++
}
// CaptureState implements the EVMLogger interface to trace a single step of VM execution.
func (t *opcounter) CaptureState(pc uint64, op vm.OpCode, gas, cost uint64, scope *vm.ScopeContext, rData []byte, depth int, err error) {
// Skip if tracing was interrupted
if atomic.LoadUint32(&t.interrupt) > 0 {
t.env.Cancel()
return
}
name := op.String()
if _, ok := t.counts[name]; !ok {
t.counts[name] = 0
}
t.counts[name]++
func (t *opcounter) getResult() (json.RawMessage, error) {
res, err := json.Marshal(t.counts)
if err != nil {
return nil, err
}
return res, t.reason
}
// CaptureEnter is called when EVM enters a new scope (via call, create or selfdestruct).
func (t *opcounter) CaptureEnter(op vm.OpCode, from common.Address, to common.Address, input []byte, gas uint64, value *big.Int) {}
// CaptureExit is called when EVM exits a scope, even if the scope didn't
// execute any code.
func (t *opcounter) CaptureExit(output []byte, gasUsed uint64, err error) {}
// CaptureFault implements the EVMLogger interface to trace an execution fault.
func (t *opcounter) CaptureFault(pc uint64, op vm.OpCode, gas, cost uint64, scope *vm.ScopeContext, depth int, err error) {}
// CaptureEnd is called after the call finishes to finalize the tracing.
func (t *opcounter) CaptureEnd(output []byte, gasUsed uint64, _ time.Duration, err error) {}
func (*opcounter) CaptureTxStart(gasLimit uint64) {}
func (*opcounter) CaptureTxEnd(restGas uint64) {}
// GetResult returns the json-encoded nested list of call traces, and any
// error arising from the encoding or forceful termination (via `Stop`).
func (t *opcounter) GetResult() (json.RawMessage, error) {
res, err := json.Marshal(t.counts)
if err != nil {
return nil, err
}
return res, t.reason
}
// Stop terminates execution of the tracer at the first opportune moment.
func (t *opcounter) Stop(err error) {
t.reason = err
atomic.StoreUint32(&t.interrupt, 1)
func (t *opcounter) stop(err error) {
t.reason = err
atomic.StoreUint32(&t.interrupt, 1)
}
```
Every method of the [EVMLogger interface](https://pkg.go.dev/github.com/ethereum/go-ethereum/core/vm#EVMLogger) needs to be implemented (even if empty). Key parts to notice are the `init()` function which registers the tracer in Geth, the `CaptureState` hook where the opcode counts are incremented and `GetResult` where the result is serialized and delivered. Note that the constructor takes in a `cfg json.RawMessage`. This will be filled with a JSON object that user provides to the tracer to pass in optional config fields.
Now let's walk through the different parts. First and foremost, the tracer will have to be registered with Geth as part of module initialization (`init()` function). This will give the tracer a name which can be used to invoke it later on through the API. What the API also needs is a way to fetch the final result from the tracer. This is done through the `GetResult` hook. The result should be JSON encoded. The `Stop` hook is used to signal the tracer to stop tracing. This will be done e.g. on a timeout. And finally, `OnOpcode` will be called for every opcode executed. This hook is used to do the tracing logic by tallying the count of each instruction.
The full set of hooks available to tracers are documented [here](https://pkg.go.dev/github.com/ethereum/go-ethereum/core/tracing#Hooks). Additionally, note that the tracer constructor takes in a `cfg json.RawMessage`. This will be filled with a JSON object that user provides to the tracer to pass in optional config fields.
To test out this tracer the source is first compiled with `make geth`. Then in the console it can be invoked through the usual API methods by passing in the name it was registered under:

304
docs/developers/evm-tracing/live-tracing.md Normal file
View file

@ -0,0 +1,304 @@
---
title: Live tracing
description: Continuous tracing of the blockchain
---
Geth v1.14.0 introduces a new optional feature, allowing users to stream (a subset of) all observable blockchain data in real-time. By writing some Go code you can develop a data indexing solution which will receive events from Geth as it is syncing and processing blocks. You may find the full list of events in the source code [here](https://github.com/ethereum/go-ethereum/blob/master/core/tracing/hooks.go), but below is a summary:
- Initialization: receives chain configuration including hard forks and chain ID. Also receives the genesis block.
- Block processing: receives the block which geth will process next and any error encountered during processing.
- Transaction processing: receives the transaction which geth will process next and the receipt post-execution.
- EVM:
- Call frame level events
- Opcode level events
- Logs
- Gas changes
- For more transparency into gas changes we have assigned a reason to each gas change.
- State modifications: receives any changes to the accounts.
- Balance changes come with a reason for more transparency into the change.
As this is a real-time stream, the data indexing solution must be able to handle chain reorgs. Upon receiving `OnBlock` events, it should check the chain of hashes it has already processed and unroll internal state that will be invalidated by the reorg.
<Note>A live tracer can impact the performance of your node as it is run synchronously within the sync process. It is better to keep the tracer code minimal and only with the purpose of getting raw data out and doing heavy post-processing of data in a later stage.</Note>
## Implementing a live tracer
The process is very similar to implementing a [custom native tracer](/docs/developers/evm-tracing/custom-tracer). These are the main differences:
- Custom native tracers are invoked through the API and will be instantiated for each request. Live tracers are instantiated once on startup and used throughout the lifetime of Geth.
- Live tracers will receive chain-related events as opposed to custom native tracers.
- The constructor for each of these types has a different signature. Live tracer constructors must return a `*tracing.Hooks` object, while custom native tracers must return a `*tracers.Tracer` object.
Below is a tracer that tracks changes of Ether supply across blocks.
### Set-up
First follow the instructions to [clone and build](/docs/getting-started/installing-geth) Geth from source code.
### Tracer code
Save the following snippet to a file under `eth/tracers/live/`.
```go
package live
import (
"encoding/json"
"errors"
"fmt"
"log"
"math/big"
"path/filepath"
"github.com/ethereum/go-ethereum/common"
"github.com/ethereum/go-ethereum/consensus/misc/eip4844"
"github.com/ethereum/go-ethereum/core/tracing"
"github.com/ethereum/go-ethereum/core/types"
"github.com/ethereum/go-ethereum/core/vm"
"github.com/ethereum/go-ethereum/eth/tracers"
"gopkg.in/natefinch/lumberjack.v2"
)
func init() {
tracers.LiveDirectory.Register("supply", newSupply)
}
type SupplyInfo struct {
Delta *big.Int `json:"delta"`
Reward *big.Int `json:"reward"`
Withdrawals *big.Int `json:"withdrawals"`
Burn *big.Int `json:"burn"`
// Block info
Number uint64 `json:"blockNumber"`
Hash common.Hash `json:"hash"`
ParentHash common.Hash `json:"parentHash"`
}
func newSupplyInfo() SupplyInfo {
return SupplyInfo{
Delta: big.NewInt(0),
Reward: big.NewInt(0),
Withdrawals: big.NewInt(0),
Burn: big.NewInt(0),
Number: 0,
Hash: common.Hash{},
ParentHash: common.Hash{},
}
}
func (s *SupplyInfo) burn(amount *big.Int) {
s.Burn.Add(s.Burn, amount)
s.Delta.Sub(s.Delta, amount)
}
type supplyTxCallstack struct {
calls []supplyTxCallstack
burn *big.Int
}
type Supply struct {
delta SupplyInfo
txCallstack []supplyTxCallstack // Callstack for current transaction
logger *log.Logger
}
type supplyTracerConfig struct {
Path string `json:"path"` // Path to the directory where the tracer logs will be stored
MaxSize int `json:"maxSize"` // MaxSize is the maximum size in megabytes of the tracer log file before it gets rotated. It defaults to 100 megabytes.
}
func newSupply(cfg json.RawMessage) (*tracing.Hooks, error) {
var config supplyTracerConfig
if cfg != nil {
if err := json.Unmarshal(cfg, &config); err != nil {
return nil, fmt.Errorf("failed to parse config: %v", err)
}
}
if config.Path == "" {
return nil, errors.New("supply tracer output path is required")
}
// Store traces in a rotating file
loggerOutput := &lumberjack.Logger{
Filename: filepath.Join(config.Path, "supply.jsonl"),
}
if config.MaxSize > 0 {
loggerOutput.MaxSize = config.MaxSize
}
logger := log.New(loggerOutput, "", 0)
supplyInfo := newSupplyInfo()
t := &Supply{
delta: supplyInfo,
logger: logger,
}
return &tracing.Hooks{
OnBlockStart: t.OnBlockStart,
OnBlockEnd: t.OnBlockEnd,
OnGenesisBlock: t.OnGenesisBlock,
OnTxStart: t.OnTxStart,
OnBalanceChange: t.OnBalanceChange,
OnEnter: t.OnEnter,
OnExit: t.OnExit,
}, nil
}
func (s *Supply) resetDelta() {
s.delta = newSupplyInfo()
}
func (s *Supply) OnBlockStart(ev tracing.BlockEvent) {
s.resetDelta()
s.delta.Number = ev.Block.NumberU64()
s.delta.Hash = ev.Block.Hash()
s.delta.ParentHash = ev.Block.ParentHash()
// Calculate Burn for this block
if ev.Block.BaseFee() != nil {
burn := new(big.Int).Mul(new(big.Int).SetUint64(ev.Block.GasUsed()), ev.Block.BaseFee())
s.delta.burn(burn)
}
// Blob burnt gas
if blobGas := ev.Block.BlobGasUsed(); blobGas != nil && *blobGas > 0 && ev.Block.ExcessBlobGas() != nil {
var (
excess = *ev.Block.ExcessBlobGas()
baseFee = eip4844.CalcBlobFee(excess)
burn = new(big.Int).Mul(new(big.Int).SetUint64(*blobGas), baseFee)
)
s.delta.burn(burn)
}
}
func (s *Supply) OnBlockEnd(err error) {
out, _ := json.Marshal(s.delta)
s.logger.Println(string(out))
}
func (s *Supply) OnGenesisBlock(b *types.Block, alloc types.GenesisAlloc) {
s.resetDelta()
s.delta.Number = b.NumberU64()
s.delta.Hash = b.Hash()
s.delta.ParentHash = b.ParentHash()
// Initialize supply with total allocation in genesis block
for _, account := range alloc {
s.delta.Delta.Add(s.delta.Delta, account.Balance)
}
out, _ := json.Marshal(s.delta)
s.logger.Println(string(out))
}
func (s *Supply) OnBalanceChange(a common.Address, prevBalance, newBalance *big.Int, reason tracing.BalanceChangeReason) {
diff := new(big.Int).Sub(newBalance, prevBalance)
// NOTE: don't handle "BalanceIncreaseGenesisBalance" because it is handled in OnGenesisBlock
switch reason {
case tracing.BalanceIncreaseRewardMineUncle:
case tracing.BalanceIncreaseRewardMineBlock:
s.delta.Reward.Add(s.delta.Reward, diff)
case tracing.BalanceIncreaseWithdrawal:
s.delta.Withdrawals.Add(s.delta.Withdrawals, diff)
case tracing.BalanceDecreaseSelfdestructBurn:
// BalanceDecreaseSelfdestructBurn is non-reversible as it happens
// at the end of the transaction.
s.delta.Burn.Sub(s.delta.Burn, diff)
default:
return
}
s.delta.Delta.Add(s.delta.Delta, diff)
}
func (s *Supply) OnTxStart(vm *tracing.VMContext, tx *types.Transaction, from common.Address) {
s.txCallstack = make([]supplyTxCallstack, 0, 1)
}
// internalTxsHandler handles internal transactions burned amount
func (s *Supply) internalTxsHandler(call *supplyTxCallstack) {
// Handle Burned amount
if call.burn != nil {
s.delta.burn(call.burn)
}
if len(call.calls) > 0 {
// Recursivelly handle internal calls
for _, call := range call.calls {
callCopy := call
s.interalTxsHandler(&callCopy)
}
}
}
func (s *Supply) OnEnter(depth int, typ byte, from common.Address, to common.Address, input []byte, gas uint64, value *big.Int) {
call := supplyTxCallstack{
calls: make([]supplyTxCallstack, 0),
}
// This is a special case of burned amount which has to be handled here
// which happens when type == selfdestruct and from == to.
if vm.OpCode(typ) == vm.SELFDESTRUCT && from == to && value.Cmp(common.Big0) == 1 {
call.burn = value
}
// Append call to the callstack, so we can fill the details in OnExit
s.txCallstack = append(s.txCallstack, call)
}
func (s *Supply) OnExit(depth int, output []byte, gasUsed uint64, err error, reverted bool) {
if depth == 0 {
// No need to handle Burned amount if transaction is reverted
if !reverted {
s.interalTxsHandler(&s.txCallstack[0])
}
return
}
size := len(s.txCallstack)
if size <= 1 {
return
}
// Pop call
call := s.txCallstack[size-1]
s.txCallstack = s.txCallstack[:size-1]
size -= 1
// In case of a revert, we can drop the call and all its subcalls.
// Caution, that this has to happen after popping the call from the stack.
if reverted {
return
}
s.txCallstack[size-1].calls = append(s.txCallstack[size-1].calls, call)
}
```
Note-worthy explanations:
- Tracer is registered in the Live Tracer directory as part of the `init()` function.
- It is possible to configure the tracer, e.g. pass in the path where the logs will be stored.
- Tracers don't have access to Geth's database. They will have to implement their own persistence layer or a way to extract data. In this example, the tracer logs the data to a file.
- Note that we are resetting the delta on every new block, because the same tracer instance will be used all the time.
### Running the tracer
First compile the source by running `make geth`. Then run the following command:
```bash
./build/bin/geth --vmtrace --vmtrace.config '{"config": "supply-logs"}' [OTHER_GETH_FLAGS]
```
Soon you will see `supply-logs/supply.jsonl` file being populated with lines such as:
```json lines
{"delta":97373601373111356,"reward":0,"withdrawals":466087699000000000,"burn":368714097626888644,"blockNumber":19503066,"hash":"0x6ad7b65b1ba0de044c490df739ea1e6605cbcae3685dcb69cca9afeb4edeb86b","parentHash":"0x8e68cc87ea7cef3643955f376aacf02ebfe3ff6ac6a28f30683fbd1da0fa0482"}
{"delta":-78769000248388266,"reward":0,"withdrawals":336059502000000000,"burn":414828502248388266,"blockNumber":19503067,"hash":"0xa17379379ecac8c37358ba26d6ef7de6e059aba18c752177b0b4aeb4d3377888","parentHash":"0x6ad7b65b1ba0de044c490df739ea1e6605cbcae3685dcb69cca9afeb4edeb86b"}
{"delta":201614678898811488,"reward":0,"withdrawals":335502106000000000,"burn":133887427101188512,"blockNumber":19503068,"hash":"0xbfb71586616e4d73ae0e12d9123b39168af71f2b52ab6cf94298cc8619a79b09","parentHash":"0xa17379379ecac8c37358ba26d6ef7de6e059aba18c752177b0b4aeb4d3377888"}
```

2
src/data/documentation-links.yaml
View file

@ -102,6 +102,8 @@
to: /docs/developers/evm-tracing/built-in-tracers
- id: Custom EVM tracer
to: /docs/developers/evm-tracing/custom-tracer
- id: Live tracing
to: /docs/developers/evm-tracing/live-tracing
- id: Tutorial for Javascript tracing
to: /docs/developers/evm-tracing/javascript-tutorial
- id: Geth developer