{"id":18357192,"url":"https://github.com/nethermindeth/jrpc-interceptor","last_synced_at":"2025-04-06T12:32:36.452Z","repository":{"id":252924499,"uuid":"841518782","full_name":"NethermindEth/jrpc-interceptor","owner":"NethermindEth","description":"A tool to intercept json rpc requests and publish metrics like response time to Prometheus","archived":false,"fork":false,"pushed_at":"2025-03-11T15:24:41.000Z","size":43,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-22T00:33:59.370Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NethermindEth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-12T15:08:57.000Z","updated_at":"2025-03-11T15:24:45.000Z","dependencies_parsed_at":"2024-08-13T13:33:52.115Z","dependency_job_id":null,"html_url":"https://github.com/NethermindEth/jrpc-interceptor","commit_stats":null,"previous_names":["dmitriy-b/jrpc-interceptor"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NethermindEth%2Fjrpc-interceptor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NethermindEth%2Fjrpc-interceptor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NethermindEth%2Fjrpc-interceptor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NethermindEth%2Fjrpc-interceptor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NethermindEth","download_url":"https://codeload.github.com/NethermindEth/jrpc-interceptor/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247484598,"owners_count":20946388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T22:13:11.182Z","updated_at":"2025-04-06T12:32:31.435Z","avatar_url":"https://github.com/NethermindEth.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Json RPC interceptor\n\nThe tool allows to intercept HTTP (Json RPC) requests and publish the results as Prometheus metrics.\n\n## How it works\n1. The interceptor is Nginx proxy server that listens on a specific port and forwards the requests to the JRPC app.\n2. Nginx contains Lua script that parses the requests to find out JRPC methods.\n3. Nginx sends the logs and other metrics (e.g. response time and parsed JRPC method) to syslog server in specific format.\n4. Syslog server is Go application that parses that logs and publishes the metrics to Prometheus.\n\nYour JRPC app and the interceptor should be running on the same machine (network).\n\n\n## How to run\n1. Build the interceptor docker image:\n```bash\ndocker build -t jrpc-interceptor .\n```\n2. Run your JRPC app, e.g.:\n```bash\ndocker run -p 8545:8545 -it horax/erigon:latest bash\n```\n3. Run the interceptor:\nOn MacOS:\n```bash\ndocker run -p 514:514/udp -p 9100:9100 -e LISTEN_PORT=80 -e SERVICE_TO_PROXY=192.168.1.2:8545 -e LOG_SERVER_URL=0.0.0.0:514 -p 8081:80 jrpc-interceptor\n```\nWhere `192.168.1.2` is the IP of the JRPC app.\n\nOn Linux:\n```bash\ndocker run --net=\"host\" -e LISTEN_PORT=0.0.0.0:8081 -e SERVICE_TO_PROXY=0.0.0.0:8545 -e LOG_SERVER_URL=0.0.0.0:514 jrpc-interceptor\n```\n\nWhere:\n- `LISTEN_PORT` - the port / IP where the interceptor listens for incoming requests.\n- `SERVICE_TO_PROXY` - the IP / port of the JRPC app.\n- `LOG_SERVER_URL` - the IP / port of the syslog server.\n- `PROMETHEUS_URL` - the IP / port of the Prometheus server. Optional, \"0.0.0.0:9100\" by default.\n- `USE_PROMETHEUS` - whether to publish metrics to Prometheus. Optional, \"true\" by default.\n- `LOG_SERVER_DEBUG` - whether to print the logs to stdout. Optional, \"true\" by default.\n\n4. Send requests to the interceptor:\n```bash\ncurl -X POST -H \"Content-Type: application/json\" -d '{\"jsonrpc\":\"2.0\",\"method\":\"eth_blockNumber\",\"params\":[],\"id\":1}' http://localhost:8081\n```\n5. Check the logs. You should see something like this:\n```bash\n2024/08/13 09:01:37 ef01982f3841: 192.168.65.1|http|localhost|POST|HTTP/1.1|/|200|0.002|193|326|0.003|eth_blockNumber\n```\n6. Open URL `http://localhost:9100/metrics` in your browser to see the metrics.\n\n## Local development\n1. Add download dependencies:\n```bash\ngo mod download\n```\n2. Build the package\n```bash\ngo build .\n```\n3. Run the interceptor:\n```bash\n./jrpc-interceptor -debug=${LOG_SERVER_DEBUG:-true} -listenSyslog=${LOG_SERVER_URL:-\"0.0.0.0:514\"} -listenHTTP=${PROMETHEUS_URL:-\"0.0.0.0:9100\"} -usePrometheus=${USE_PROMETHEUS:-true}\n```\n\n### Download docker image from github container registry\n\n1. Create a [personal access token ](https://github.com/settings/tokens)(PAT) on github with repo access\n2. Set the PAT as an environment variable\n\n```\nexport CR_PAT=\u003cyour_pat\u003e\n```\n3. Login to github container registry\n\n```\necho $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin\n```\n\n4. Download the image\n\n```\ndocker pull ghcr.io/NethermindEth/jrpc-interceptor:main\n```\n\n## Nginx configuration\nAll the configuration can be found inside the `nginx` folder.\n\nBasic info:\n\n- `worker_processes` sets to 4;\n- `worker_connections` sets 2048;\n- `client_body_buffer_size` sets to `10M`;;\n- `client_max_body_size` sets to `1000M` due to the large size of some jrpc requests;\n\nUsed `openresty/openresty:alpine` to be able to use Lua scripts.\n\n### Syslog format\nThe interceptor sends the logs to the syslog server in the following format:\n```\n$remote_addr|$scheme|$host|$request_method|$server_protocol|$request_uri|$status|$request_time|$request_length|$bytes_sent|$upstream_response_time|$jrpc_method\n```\nThat returns something like\n```\n2024/08/13 09:01:37 ef01982f3841: 192.168.65.1|http|localhost|POST|HTTP/1.1|/|200|0.002|193|326|0.003|eth_blockNumber\n```\n\n### Limitations and workarounds\n- All the original headers passes as is, except `Host` header. It's replaced with the `SERVICE_TO_PROXY` value.\n\n## Errors and Troubleshooting\nInstead of a valid `jrpc_method` you can show following errors:\n- `no_method_field` this means that original request contains `jsonrpc` but doesn't contain json rpc `method` field;\n- `invalid_jsonrpc_request` the request contains `jsonrpc` field but it's not a valid json rpc request (cannot decode json body);\n- `no_jsonrpc_field` the request does not contain `jsonrpc` field;\n\nTo see the errors you can use `LOG_SERVER_DEBUG=true` environment variable. To check full json logs, log in to container and check `/var/log/nginx/access_with_body.json` file.\n\n## Metrics\nThe interceptor publishes the following metrics:\n```\n- `ngx_request_count` - the number of requests;\n- `ngx_request_size_bytes` - the size of the request;\n- `ngx_response_size_bytes` - the size of the response;\n- `ngx_request_duration_seconds` - the time of the request;\n```\nFor the `ngx_request_duration_seconds` metric, we use `$request_time` value.\nIt's the time between the first bytes were read from the client and the log write after the last bytes were sent to the client.\n\n\n## License\nJson RPC interceptor is a Nethermind free and open-source software licensed under the [Apache 2.0 License](https://github.com/NethermindEth/jrpc-interceptor/blob/main/LICENSE) except 3 files that are licensed under the `Mozilla Public License Version 2.0`. See [Notice](https://github.com/NethermindEth/jrpc-interceptor/blob/main/Notice) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnethermindeth%2Fjrpc-interceptor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnethermindeth%2Fjrpc-interceptor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnethermindeth%2Fjrpc-interceptor/lists"}