Skip to main content

Monitoring

If you run Stellar RPC with the --admin-endpoint configured and expose the port, you'll have access to the Prometheus metrics via the /metrics endpoint. For example, if the admin endpoint is 0.0.0.0:8001 and you're running the Stellar RPC Docker image:

curl localhost:8001/metrics

You will see many of the default Go and Process metrics (prefixed by go_ and process_ respectively) such as memory usage, CPU usage, number of threads, etc.

We also expose metrics related to Stellar RPC (prefixed by soroban_rpc). There are many, but some notable ones are:

  • soroban_rpc_transactions_count - count of transactions ingested with a sliding window of 10m
  • soroban_rpc_events_count - count of events ingested with a sliding window of 10m
  • soroban_rpc_ingest_local_latest_ledger - latest ledger ingested
  • soroban_rpc_db_round_trip_time_seconds - time required to run SELECT 1 query in the DATABASE

Stellar RPC also provides logging to console for:

  • Startup activity
  • Ingesting, applying, and closing ledgers
  • Handling JSON RPC requests
  • Any errors

The logs have the format:

time=<timestamp in YYYY-MM-DDTHH:MM:SS.000Z format> level=<debug|info|error> msg=<Actual message> pid=<process ID> subservice=<optional if coming from subservice>

Grafana dashboard​

We provide a Grafana dashboard with different metrics to monitor your RPC instance.

Verify the RPC Instance​

After installation, it will be worthwhile to verify the installation of Stellar RPC is healthy. There are two methods:

  1. Access the health status endpoint of the JSON RPC service using an HTTP client
  2. Use our pre-built System Test Docker image as a tool to run a set of live tests against Stellar RPC

Health Status Endpoint​

If you send a JSON RPC HTTP request to your running instance of Stellar RPC:

curl --location 'http://localhost:8000' \
--header 'Content-Type: application/json' \
--data '{
"jsonrpc":"2.0",
"id":2,
"method":"getHealth"
}'

You should get back an HTTP 200 status response if the instance is healthy:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "status": "healthy"
  }
}

System Test Docker Image​

This test will compile, deploy, and invoke example contracts to the network to which your RPC instance is connected to. Here is an example for verifying your instance if it is connected to Testnet:

# checkout https://github.com/stellar/system-test repo first, and build the image locally with release component versions
system-test$ make  \
  CORE_IMAGE=stellar/stellar-core:22 \
  CORE_IMAGE_BIN_PATH=/usr/bin/stellar-core \
  SOROBAN_RPC_GIT_REF=https://github.com/stellar/soroban-rpc.git#v22.1.2 \
  SOROBAN_CLI_GIT_REF=https://github.com/stellar/soroban-cli.git#v22.2.0 \
  RS_XDR_GIT_REF=v22.1.0 \
  JS_STELLAR_SDK_NPM_VERSION=13.1.0 \
  build
# run the local system test image
$ docker run --rm -t --name e2e_test \
stellar/system-test:dev \
--VerboseOutput true \
--TargetNetworkRPCURL <your rpc url here> \
--TargetNetworkPassphrase "Test SDF Network ; September 2015" \
--TargetNetworkTestAccountSecret <your test account StrKey encoded key here > \
--TargetNetworkTestAccountPublic <your test account StrKey encoded pubkey here> \

Make sure you configure the system test correctly:

  • Set --TargetNetworkRPCURL to your RPC HTTP URL
  • Set --TargetNetworkPassphrase to the same network your RPC instance is connected to:
  • "Test SDF Network ; September 2015" for Testnet
  • "Test SDF Future Network ; October 2022" for Futurenet
  • Set --SorobanExamplesGitHash to the corresponding release tag on the Soroban Examples repo
  • Create and fund an account to be used for test purposes on the same network your RPC instance is connected to
  • This account needs a small XLM balance to submit Soroban transactions
  • Tests can be run repeatedly with the same account
  • Set --TargetNetworkTestAccountPublic to the StrKey encoded public key of the account
  • Set --TargetNetworkTestAccountSecret to the StrKey encoded secret for the account