diff --git a/docs/_rpc/ns-debug.md b/docs/_rpc/ns-debug.md index 4cfd547d01..5adc4d7589 100644 --- a/docs/_rpc/ns-debug.md +++ b/docs/_rpc/ns-debug.md @@ -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_---`. 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_---`. 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