interesting
/
go-ethereum
mirror of https://github.com/ethereum/go-ethereum.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Debug namespace (#24828) 

* add api info to ns-debug.md

* fix typo

* Apply suggestions from code review

Co-authored-by: Sina Mahmoodi <1591639+s1na@users.noreply.github.com>

Co-authored-by: Sina Mahmoodi <1591639+s1na@users.noreply.github.com>
This commit is contained in:
Joseph Cook 2022-05-10 15:14:48 +01:00 committed by GitHub
parent bf43cb3038
commit 24465aabda
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 174 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

221
docs/_rpc/ns-debug.md
View File

@ -41,6 +41,19 @@ the rate and write the profile manually using
| Console | `debug.blockProfile(file, seconds)` |
| RPC | `{"method": "debug_blockProfile", "params": [string, number]}` |
### debug_chaindbProperty
Returns leveldb properties of the key-value database.
| Client | Method invocation |
|:--------|----------------------------------------------------------------|
| Console | `debug.chaindbProperty(property string)` |
| RPC | `{"method": "debug_chaindbProperty", "params": [property]}` |
### debug_cpuProfile
Turns on CPU profiling for the given duration and writes
@ -51,6 +64,18 @@ profile data to disk.
| Console | `debug.cpuProfile(file, seconds)` |
| RPC | `{"method": "debug_cpuProfile", "params": [string, number]}` |
### debug_dbGet
Returns the raw value of a key stored in the database.
| Client | Method invocation |
|:--------|----------------------------------------------------------------|
| Console | `debug.dbGet(key string)` |
| RPC | `{"method": "debug_dbGet", "params": [key]}` |
### debug_dumpBlock
Retrieves the state that corresponds to the block number and returns a list of accounts (including
@ -88,9 +113,33 @@ storage and code).
}
```
### debug_freeOSMemory
Forces garbage collection
| Client | Method invocation |
|:--------|---------------------------------------------------|
| Go | `debug.FreeOSMemory()` |
| Console | `debug.freeOSMemory()` |
| RPC | `{"method": "debug_freeOSMemory", "params": []}` |
### debug_freezeClient
Forces a temporary client freeze, normally when the server is overloaded.
Available as part of LES light server.
| Client | Method invocation |
|:--------|------------------------------------------------------|
| Console | `debug.freezeClient(node string)` |
| RPC | `{"method": "debug_freezeClient", "params": [node]}` |
### debug_gcStats
Returns GC statistics.
Returns garbage collection statistics.
See https://golang.org/pkg/runtime/debug/#GCStats for information about
the fields of the returned object.
@ -100,6 +149,31 @@ the fields of the returned object.
| Console | `debug.gcStats()` |
| RPC | `{"method": "debug_gcStats", "params": []}` |
### debug_getBadBlocks
Returns a list of the last 'bad blocks' that the client has seen on
the network and returns them as a JSON list of block-hashes.
| Client | Method invocation |
|:--------|---------------------------------------------------|
| Console | `debug.getBadBlocks()` |
| RPC | `{"method": "debug_getBadBlocks", "params": []}` |
### debug_getAccessibleState
Returns the first number where the node has accessible state on disk.
This is the post-state of that block and the pre-state of the next
block. The (from, to) parameters are the sequence of blocks
to search, which can go either forwards or backwards.
| Client | Method invocation |
|:--------|-----------------------------------------------------------------------|
| Console | `debug.getAccessibleState(from, to rpc.BlockNumber)` |
| RPC | `{"method": "debug_getAccessibleState", "params": [from, to]}` |
### debug_getBlockRlp
Retrieves and returns the RLP encoded block by number.
@ -112,6 +186,19 @@ Retrieves and returns the RLP encoded block by number.
References: [RLP](https://github.com/ethereum/wiki/wiki/RLP)
### debug_getModifiedAccountsByNumber
Returns all accounts that have changed between the two blocks specified.
A change is defined as a difference in nonce, balance, code hash or
storage hash.
| Client | Method invocation |
|:--------|---------------------------------------------------------------------------------|
| Console | `debug.getModifiedAccountsByNumber(startNum uint64, endNum uint64)` |
| RPC | `{"method": "debug_getModifiedAccountsByNumber", "params": [startNum, endNum]}` |
### debug_goTrace
Turns on Go runtime tracing for the given duration and writes
@ -134,6 +221,17 @@ the fields of the returned object.
| Console | `debug.memStats()` |
| RPC | `{"method": "debug_memStats", "params": []}` |
### debug_printBlock
Retrieves a block and returns its pretty printed form.
| Client | Method invocation |
|:--------|---------------------------------------------------|
| Console | `debug.printBlock(number uint64)` |
| RPC | `{"method": "debug_printBlock", "params": [number]}` |
### debug_seedHash
Fetches and retrieves the seed hash of the block by number
@ -144,6 +242,19 @@ Fetches and retrieves the seed hash of the block by number
| Console | `debug.seedHash(number, [options])` |
| RPC | `{"method": "debug_seedHash", "params": [number]}` |
### debug_setGCPercent
Sets the garbage collection target percentage. A negative value disables garbage
collection.
| Client | Method invocation |
|:--------|---------------------------------------------------|
| Go | `debug.SetGCPercent(v int)` |
| Console | `debug.setGCPercent(v)` |
| RPC | `{"method": "debug_setGCPercent", "params": [v]}` |
### debug_setHead
Sets the current head of the local chain by block number. **Note**, this is a
@ -181,6 +292,60 @@ and does not return the string.
| Console | `debug.stacks()` |
| RPC | `{"method": "debug_stacks", "params": []}` |
### debug_standardTraceBlockToFile
When JS-based tracing (see below) was first implemented, the intended usecase was to enable long-running tracers that could stream results back via a subscription channel.
This method works a bit differently. (For full details, see [PR](https://github.com/ethereum/go-ethereum/pull/17914))
- It streams output to disk during the execution, to not blow up the memory usage on the node
- It uses `jsonl` as output format (to allow streaming)
- Uses a cross-client standardized output, so called 'standard json'
* Uses `op` for string-representation of opcode, instead of `op`/`opName` for numeric/string, and other simlar small differences.
* has `refund`
* Represents memory as a contiguous chunk of data, as opposed to a list of `32`-byte segments like `debug_traceTransaction`
This means that this method is only 'useful' for callers who control the node -- at least sufficiently to be able to read the artefacts from the filesystem after the fact.
The method can be used to dump a certain transaction out of a given block:
```
> debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {txHash:"0x4049f61ffbb0747bb88dc1c85dd6686ebf225a3c10c282c45a8e0c644739f7e9", disableMemory:true})
["/tmp/block_0x0bbe9f14-14-0x4049f61f-099048234"]
```
Or all txs from a block:
```
> debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {disableMemory:true})
["/tmp/block_0x0bbe9f14-0-0xb4502ea7-409046657", "/tmp/block_0x0bbe9f14-1-0xe839be8f-954614764", "/tmp/block_0x0bbe9f14-2-0xc6e2052f-542255195", "/tmp/block_0x0bbe9f14-3-0x01b7f3fe-209673214", "/tmp/block_0x0bbe9f14-4-0x0f290422-320999749", "/tmp/block_0x0bbe9f14-5-0x2dc0fb80-844117472", "/tmp/block_0x0bbe9f14-6-0x35542da1-256306111", "/tmp/block_0x0bbe9f14-7-0x3e199a08-086370834", "/tmp/block_0x0bbe9f14-8-0x87778b88-194603593", "/tmp/block_0x0bbe9f14-9-0xbcb081ba-629580052", "/tmp/block_0x0bbe9f14-10-0xc254381a-578605923", "/tmp/block_0x0bbe9f14-11-0xcc434d58-405931366", "/tmp/block_0x0bbe9f14-12-0xce61967d-874423181", "/tmp/block_0x0bbe9f14-13-0x05a20b35-267153288", "/tmp/block_0x0bbe9f14-14-0x4049f61f-606653767", "/tmp/block_0x0bbe9f14-15-0x46d473d2-614457338", "/tmp/block_0x0bbe9f14-16-0x35cf5500-411906321", "/tmp/block_0x0bbe9f14-17-0x79222961-278569788", "/tmp/block_0x0bbe9f14-18-0xad84e7b1-095032683", "/tmp/block_0x0bbe9f14-19-0x4bd48260-019097038", "/tmp/block_0x0bbe9f14-20-0x1517411d-292624085", "/tmp/block_0x0bbe9f14-21-0x6857e350-971385904", "/tmp/block_0x0bbe9f14-22-0xbe3ae2ca-236639695"]
```
Files are created in a temp-location, with the naming standard `block_<blockhash:4>-<txindex>-<txhash:4>-<random suffix>`. Each opcode immediately streams to file, with no in-geth buffering aside from whatever buffering the os normally does.
On the server side, it also adds some more info when regenerating historical state, namely, the reexec-number if `required historical state is not avaiable` is encountered, so a user can experiment with increasing that setting. It also prints out the remaining block until it reaches target:
```
INFO [10-15|13:48:25.263] Regenerating historical state block=2385959 target=2386012 remaining=53 elapsed=3m30.990537767s
INFO [10-15|13:48:33.342] Regenerating historical state block=2386012 target=2386012 remaining=0 elapsed=3m39.070073163s
INFO [10-15|13:48:33.343] Historical state regenerated block=2386012 elapsed=3m39.070454362s nodes=10.03mB preimages=652.08kB
INFO [10-15|13:48:33.352] Wrote trace file=/tmp/block_0x14490c57-0-0xfbbd6d91-715824834
INFO [10-15|13:48:33.352] Wrote trace file=/tmp/block_0x14490c57-1-0x71076194-187462969
INFO [10-15|13:48:34.421] Wrote trace file=/tmp/block_0x14490c57-2-0x3f4263fe-056924484
```
The `options` is as follows:
```
type StdTraceConfig struct {
*vm.LogConfig
Reexec *uint64
TxHash *common.Hash
}
```
### debug_standardTraceBadBlockToFile
This method is similar to `debug_standardTraceBlockToFile`, but can be used to obtain info about a block which has been _rejected_ as invalid (for some reason).
### debug_startCPUProfile
Turns on CPU profiling indefinitely, writing to the given file.
@ -217,6 +382,8 @@ Stops writing the Go runtime trace.
| Console | `debug.startGoTrace(file)` |
| RPC | `{"method": "debug_stopGoTrace", "params": []}` |
### debug_traceBlock
The `traceBlock` method will return a full stack trace of all invoked opcodes of all transaction
@ -296,6 +463,7 @@ block that is already present in the database.
References:
[RLP](https://github.com/ethereum/wiki/wiki/RLP)
### debug_traceBlockFromFile
Similar to [debug_traceBlock](#debug_traceblock), `traceBlockFromFile` accepts a file containing the RLP of the block.
@ -309,57 +477,16 @@ Similar to [debug_traceBlock](#debug_traceblock), `traceBlockFromFile` accepts a
References:
[RLP](https://github.com/ethereum/wiki/wiki/RLP)
### debug_standardTraceBlockToFile
### debug_traceChain
When JS-based tracing (see below) was first implemented, the intended usecase was to enable long-running tracers that could stream results back via a subscription channel.
This method works a bit differently. (For full details, see [PR](https://github.com/ethereum/go-ethereum/pull/17914))
Returns the structured logs created during the execution of EVM between two blocks (excluding start) as a JSON object.
This endpoint must be invoked via `debug_subscribe` as follows:
- It streams output to disk during the execution, to not blow up the memory usage on the node
- It uses `jsonl` as output format (to allow streaming)
- Uses a cross-client standardized output, so called 'standard json'
* Uses `op` for string-representation of opcode, instead of `op`/`opName` for numeric/string, and other simlar small differences.
* has `refund`
* Represents memory as a contiguous chunk of data, as opposed to a list of `32`-byte segments like `debug_traceTransaction`
`const res = provider.send('debug_subscribe', ['traceChain', '0x3f3a2a', '0x3f3a2b'])`
This means that this method is only 'useful' for callers who control the node -- at least sufficiently to be able to read the artefacts from the filesystem after the fact.
please refer to the [subscription page](https://geth.ethereum.org/docs/rpc/pubsub) for more details.
The method can be used to dump a certain transaction out of a given block:
```
> debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {txHash:"0x4049f61ffbb0747bb88dc1c85dd6686ebf225a3c10c282c45a8e0c644739f7e9", disableMemory:true})
["/tmp/block_0x0bbe9f14-14-0x4049f61f-099048234"]
```
Or all txs from a block:
```
> debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {disableMemory:true})
["/tmp/block_0x0bbe9f14-0-0xb4502ea7-409046657", "/tmp/block_0x0bbe9f14-1-0xe839be8f-954614764", "/tmp/block_0x0bbe9f14-2-0xc6e2052f-542255195", "/tmp/block_0x0bbe9f14-3-0x01b7f3fe-209673214", "/tmp/block_0x0bbe9f14-4-0x0f290422-320999749", "/tmp/block_0x0bbe9f14-5-0x2dc0fb80-844117472", "/tmp/block_0x0bbe9f14-6-0x35542da1-256306111", "/tmp/block_0x0bbe9f14-7-0x3e199a08-086370834", "/tmp/block_0x0bbe9f14-8-0x87778b88-194603593", "/tmp/block_0x0bbe9f14-9-0xbcb081ba-629580052", "/tmp/block_0x0bbe9f14-10-0xc254381a-578605923", "/tmp/block_0x0bbe9f14-11-0xcc434d58-405931366", "/tmp/block_0x0bbe9f14-12-0xce61967d-874423181", "/tmp/block_0x0bbe9f14-13-0x05a20b35-267153288", "/tmp/block_0x0bbe9f14-14-0x4049f61f-606653767", "/tmp/block_0x0bbe9f14-15-0x46d473d2-614457338", "/tmp/block_0x0bbe9f14-16-0x35cf5500-411906321", "/tmp/block_0x0bbe9f14-17-0x79222961-278569788", "/tmp/block_0x0bbe9f14-18-0xad84e7b1-095032683", "/tmp/block_0x0bbe9f14-19-0x4bd48260-019097038", "/tmp/block_0x0bbe9f14-20-0x1517411d-292624085", "/tmp/block_0x0bbe9f14-21-0x6857e350-971385904", "/tmp/block_0x0bbe9f14-22-0xbe3ae2ca-236639695"]
```
Files are created in a temp-location, with the naming standard `block_<blockhash:4>-<txindex>-<txhash:4>-<random suffix>`. Each opcode immediately streams to file, with no in-geth buffering aside from whatever buffering the os normally does.
On the server side, it also adds some more info when regenerating historical state, namely, the reexec-number if `required historical state is not avaiable` is encountered, so a user can experiment with increasing that setting. It also prints out the remaining block until it reaches target:
```
INFO [10-15|13:48:25.263] Regenerating historical state block=2385959 target=2386012 remaining=53 elapsed=3m30.990537767s
INFO [10-15|13:48:33.342] Regenerating historical state block=2386012 target=2386012 remaining=0 elapsed=3m39.070073163s
INFO [10-15|13:48:33.343] Historical state regenerated block=2386012 elapsed=3m39.070454362s nodes=10.03mB preimages=652.08kB
INFO [10-15|13:48:33.352] Wrote trace file=/tmp/block_0x14490c57-0-0xfbbd6d91-715824834
INFO [10-15|13:48:33.352] Wrote trace file=/tmp/block_0x14490c57-1-0x71076194-187462969
INFO [10-15|13:48:34.421] Wrote trace file=/tmp/block_0x14490c57-2-0x3f4263fe-056924484
```
The `options` is as follows:
```
type StdTraceConfig struct {
*vm.LogConfig
Reexec *uint64
TxHash *common.Hash
}
```
### debug_standardTraceBadBlockToFile
This method is similar to `debug_standardTraceBlockToFile`, but can be used to obtain info about a block which has been _rejected_ as invalid (for some reason).
### debug_traceTransaction