diff --git a/content/docs/interacting_with_geth/RPC/graphql.md b/content/docs/interacting_with_geth/RPC/graphql.md index 8cb82f4ebb..1abf0a9853 100644 --- a/content/docs/interacting_with_geth/RPC/graphql.md +++ b/content/docs/interacting_with_geth/RPC/graphql.md @@ -5,13 +5,13 @@ sort_key: C In addition to the [JSON-RPC APIs](../rpc/server), Geth supports the GraphQL API as specified by [EIP-1767](eip-1767). GraphQL lets you specify which fields of an objects you need as part of the query, eliminating the extra load on the client for filling in fields which are not needed. It also allows for combining several traditional JSON-RPC requests into one query which translates into less overhead and more performance. -The GraphQL endpoint piggybacks on the HTTP transport used by JSON-RPC. Hence you'll have to enable and configure the relevant `--http` flags, and the `--graphql` flag itself: +The GraphQL endpoint piggybacks on the HTTP transport used by JSON-RPC. Hence the relevant `--http` flags and the `--graphql` flag should be passed to Geth: ```bash geth --http --graphql ``` -Now you can start querying against `http://localhost:8545/graphql`. To change the port, you'll need to provide `--http.port`, e.g.: +Now queries can be raised against `http://localhost:8545/graphql`. To change the port, provide a custom port number to `--http.port`, e.g.: ```bash geth --http --http.port 9545 --graphql @@ -19,7 +19,7 @@ geth --http --http.port 9545 --graphql ### GraphiQL -An easy way to get started right away and try out queries is the GraphiQL interface shipped with Geth. To open it visit `http://localhost:8545/graphql/ui`. To see how this works let's read the sender, recipient and value of all transactions in block number 6000000. Try this out in GraphiQL: +An easy way to try out queries is the GraphiQL interface shipped with Geth. To open it visit `http://localhost:8545/graphql/ui`. To see how this works let's read the sender, recipient and value of all transactions in block number 6000000. In GraphiQL: ```graphql query txInfo { @@ -31,9 +31,9 @@ GraphiQL also provides a way to explore the schema Geth provides to help you for ### Query -Reading out data from Geth is the biggest use-case for GraphQL. However after trying out queries in the UI you may want to do it programmatically. You can consult the official [docs](graphql-code) to find bindings for your language. Or use your favorite tool for sending HTTP requests. For sake of completeness we briefly touch on two approaches here. First via cURL, and second via a JS script. +Reading out data from Geth is the biggest use-case for GraphQL. In addition to using the UI queries can also be sent programmatically. The official GraphQL[docs](graphql-code) explain how to find bindings for many languages, or send http requests from the terminal using tools such as Curl. -Here's how you'd get the latest block's number via cURL. Note the use of a JSON object for the data section: +For example, the code snippet below shows how to obtain the latest block number using Curl. Note the use of a JSON object for the data section: ```bash ❯ curl -X POST http://localhost:8545/graphql -H "Content-Type: application/json" --data '{ "query": "query { block { number } }" }' @@ -46,7 +46,7 @@ Alternatively store the JSON-ified query in a file (let's call it `block-num.que ❯ curl -X POST http://localhost:8545/graphql -H "Content-Type: application/json" --data '@block-num.query' ``` -Executing a simple query in JS looks like the following. Here we're using the lightweight library `graphql-request` to perform the request. Note the use of variables instead of hardcoding the block number in the query: +Executing a simple query in JS looks as follows. Here the lightweight library `graphql-request` is used to perform the request. Note the use of variables instead of hardcoding the block number in the query: ```javascript const { request, gql } = require('graphql-request') diff --git a/content/docs/interacting_with_geth/RPC/ns-admin.md b/content/docs/interacting_with_geth/RPC/ns-admin.md index fc15227b55..a545a226d9 100644 --- a/content/docs/interacting_with_geth/RPC/ns-admin.md +++ b/content/docs/interacting_with_geth/RPC/ns-admin.md @@ -3,12 +3,8 @@ title: admin Namespace sort_key: C --- -The `admin` API gives you access to several non-standard RPC methods, which will allow you to have -a fine grained control over your Geth instance, including but not limited to network peer and RPC -endpoint management. +The `admin` API gives access to several non-standard RPC methods, which allows fine grained control over a Geth instance, including but not limited to network peer and RPC endpoint management. -* TOC -{:toc} ### admin_addPeer @@ -16,7 +12,7 @@ The `addPeer` administrative method requests adding a new remote node to the lis nodes. The node will try to maintain connectivity to these nodes at all times, reconnecting every once in a while if the remote connection goes down. -The method accepts a single argument, the [`enode`](https://github.com/ethereum/wiki/wiki/enode-url-format) +The method accepts a single argument, the [`enode`](https://ethereum.org/en/developers/docs/networking-layer/network-addresses/#enode) URL of the remote peer to start tracking and returns a `BOOL` indicating whether the peer was accepted for tracking or some error occurred. @@ -91,7 +87,7 @@ It returns a boolean indicating whether the operation succeeded. The `nodeInfo` administrative property can be queried for all the information known about the running Geth node at the networking granularity. These include general information about the node itself as a -participant of the [ÐΞVp2p](https://github.com/ethereum/wiki/wiki/%C3%90%CE%9EVp2p-Wire-Protocol) P2P +participant of the [ÐΞVp2p](https://github.com/ethereum/devp2p/blob/master/caps/eth.md) P2P overlay protocol, as well as specialized information added by each of the running application protocols (e.g. `eth`, `les`, `shh`, `bzz`). @@ -141,7 +137,7 @@ The type of events emitted by the server are as follows: The `peers` administrative property can be queried for all the information known about the connected remote nodes at the networking granularity. These include general information about the nodes themselves -as participants of the [ÐΞVp2p](https://github.com/ethereum/wiki/wiki/%C3%90%CE%9EVp2p-Wire-Protocol) +as participants of the [ÐΞVp2p](https://github.com/ethereum/devp2p/blob/master/caps/eth.md) P2P overlay protocol, as well as specialized information added by each of the running application protocols (e.g. `eth`, `les`, `shh`, `bzz`). diff --git a/content/docs/interacting_with_geth/RPC/ns-debug.md b/content/docs/interacting_with_geth/RPC/ns-debug.md index 2fed88c96b..f9cbfe0d7b 100644 --- a/content/docs/interacting_with_geth/RPC/ns-debug.md +++ b/content/docs/interacting_with_geth/RPC/ns-debug.md @@ -3,11 +3,8 @@ title: debug Namespace sort_key: C --- -The `debug` API gives you access to several non-standard RPC methods, which will allow you -to inspect, debug and set certain debugging flags during runtime. +The `debug` API gives access to several non-standard RPC methods, which allow inspection, debugging and setting certain debugging flags during runtime. -* TOC -{:toc} ### debug_accountRange @@ -228,7 +225,7 @@ Retrieves and returns the RLP encoded block by number. | Console | `debug.getBlockRlp(number, [options])` | | RPC | `{"method": "debug_getBlockRlp", "params": [number]}` | -References: [RLP](https://github.com/ethereum/wiki/wiki/RLP) +References: [RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/#top) ### debug_getHeaderRlp @@ -365,7 +362,7 @@ collection. ### debug_setHead Sets the current head of the local chain by block number. **Note**, this is a -destructive action and may severely damage your chain. Use with *extreme* caution. +destructive action and may severely damage the chain. Use with *extreme* caution. | Client | Method invocation | |:--------|---------------------------------------------------| @@ -374,7 +371,7 @@ destructive action and may severely damage your chain. Use with *extreme* cautio | RPC | `{"method": "debug_setHead", "params": [number]}` | References: -[Ethash](https://eth.wiki/en/concepts/ethash/ethash) +[Ethash](https://ethereum.org/en/developers/docs/consensus-mechanisms/pow/mining-algorithms/ethash) ### debug_setMutexProfileFraction @@ -516,7 +513,7 @@ fail. | RPC | `{"method": "debug_traceBlock", "params": [blockRlp, {}]}` | References: -[RLP](https://github.com/ethereum/wiki/wiki/RLP) +[RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp) #### Example @@ -566,7 +563,7 @@ block that is already present in the database. | RPC | `{"method": "debug_traceBlockByNumber", "params": [number, {}]}` | References: -[RLP](https://github.com/ethereum/wiki/wiki/RLP) +[RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp) ### debug_traceBlockByHash @@ -580,7 +577,7 @@ block that is already present in the database. | RPC | `{"method": "debug_traceBlockByHash", "params": [hash {}]}` | References: -[RLP](https://github.com/ethereum/wiki/wiki/RLP) +[RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp) ### debug_traceBlockFromFile @@ -594,11 +591,11 @@ Similar to [debug_traceBlock](#debug_traceblock), `traceBlockFromFile` accepts a | RPC | `{"method": "debug_traceBlockFromFile", "params": [fileName, {}]}` | References: -[RLP](https://github.com/ethereum/wiki/wiki/RLP) +[RLP](https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp) ### debug_traceCall -The `debug_traceCall` method lets you run an `eth_call` within the context of the given block execution using the final state of parent block as the base. The first argument (just as in `eth_call`) is a [transaction object](/docs/rpc/objects#transaction-call-object). The block can be specified either by hash or by number as the second argument. A tracer can be specified as a third argument, similar to `debug_traceTransaction`. It returns the same output as `debug_traceTransaction`. +The `debug_traceCall` method enables running an `eth_call` within the context of the given block execution using the final state of parent block as the base. The first argument (just as in `eth_call`) is a [transaction object](/docs/rpc/objects#transaction-call-object). The block can be specified either by hash or by number as the second argument. A tracer can be specified as a third argument, similar to `debug_traceTransaction`. It returns the same output as `debug_traceTransaction`. | Client | Method invocation | |:-------:|-----------------------------------| @@ -689,7 +686,7 @@ as it was executed on the network. It will replay any transaction that may have to this one before it will finally attempt to execute the transaction that corresponds to the given hash. -In addition to the hash of the transaction you may give it a secondary *optional* argument, which +In addition to the hash of the transaction it can take a secondary *optional* argument, which specifies the options for this specific call. The possible options are: * `disableStorage`: `BOOL`. Setting this to true will disable storage capture (default = false). @@ -744,7 +741,7 @@ specifies the options for this specific call. The possible options are: #### JavaScript-based tracing -Specifying the `tracer` option in the second argument enables JavaScript-based tracing. In this mode, `tracer` is interpreted as a JavaScript expression that is expected to evaluate to an object which must expose the `result` and `fault` methods. There exist 3 additional methods, namely: `step`, `enter` and `exit`. You must provide either `step`, or `enter` AND `exit` (i.e. these two must be exposed together). You may expose all three if you choose to do so. +Specifying the `tracer` option in the second argument enables JavaScript-based tracing. In this mode, `tracer` is interpreted as a JavaScript expression that is expected to evaluate to an object which must expose the `result` and `fault` methods. There exist 3 additional methods, namely: `step`, `enter` and `exit`. One of either `step`, or `enter` AND `exit` must be provided(i.e. `enter` and `exit` must be exposed together). All three can be provided together. ##### Step @@ -768,7 +765,7 @@ and the following methods: If error is non-empty, all other fields should be ignored. -For efficiency, the same `log` object is reused on each execution step, updated with current values; make sure to copy values you want to preserve beyond the current call. For instance, this step function will not work: +For efficiency, the same `log` object is reused on each execution step, updated with current values; make sure to copy values that are needed beyond the current call. For instance, this step function will not work: function(log) { this.logs.append(log); @@ -887,30 +884,27 @@ Sets the logging verbosity pattern. #### Examples -If you want to see messages from a particular Go package (directory) +To see messages from a particular Go package (directory) and all subdirectories, use: ``` javascript > debug.vmodule("eth/*=6") ``` -If you want to restrict messages to a particular package (e.g. p2p) +To restrict messages to a particular package (e.g. p2p) but exclude subdirectories, use: ``` javascript > debug.vmodule("p2p=6") ``` -If you want to see log messages from a particular source file, use +To see log messages from a particular source file, use ``` javascript > debug.vmodule("server.go=6") ``` -You can compose these basic patterns. If you want to see all -output from peer.go in a package below eth (eth/peer.go, -eth/downloader/peer.go) as well as output from package p2p -at level <= 5, use: +To see all output from peer.go in a package below eth (eth/peer.go, eth/downloader/peer.go) as well as output from package p2p at level <= 5, use: ``` javascript debug.vmodule("eth/*/peer.go=6,p2p=5") diff --git a/content/docs/monitoring/ethstats.md b/content/docs/monitoring/ethstats.md index bc27d5a171..65b47e6913 100644 --- a/content/docs/monitoring/ethstats.md +++ b/content/docs/monitoring/ethstats.md @@ -38,9 +38,36 @@ Note that the Ethstats dashboard is not a reliable source of information about t network because submitting data to the Ethstats server is voluntary and has to be configured by individual nodes. Therefore, many nodes are omitted from the summary statistics. +## How to use +To report statistics about the local node to Ethstats, an Ethstats server and Ethstats client both have +to be installed alongside Geth. There are several options for installing Ethstats clients and servers, +each with detailed installation instructions. They all share the common trait that an Ethstats service is +started with a specific URL that can be passed to Geth. + +[EthNetStats "Classic"](https://github.com/ethereum/eth-netstats) +[EthNet Intelligence API](https://github.com/ethereum/eth-net-intelligence-api) +[Goerli Ethstats client](https://github.com/goerli/ethstats-client) +[Goerli Ethstats server](https://github.com/goerli/ethstats-server) + +If enabled, Geth spins up a minimal Ethstats reporting daemon that pushes statistics about the +local node to the Ethstats server. + +To enable this, start Geth with the `ethstats` flag, passing the Ethstats service (nodename:secret@host:port) URL. + +```sh +geth --ethstats node1:secret:127.0.0.1:9000 +``` + +The local node will then report to Ethstats, and the statistics will be displayed in a dashboard that can be +accessed via the web browser. + +## Note on WS_secret + +The `WS_secret` parameter is required for connecting to an Ethstats server. For a local network this can be user-defined +on startup by providing it as an environment variable. However, for Ethereum mainnet and the public testnets predefined +values must be known. Historically these have been made available on Gitter and Skype channels or of a forum, but these are +no longer in use. The user will have to track down existing Ethstats users to request the `WS_secret`. -.. UNFINISHED -Reporting URL of a ethstats service (nodename:secret@host:port)