Metrics
note
PayString was previously known as PayID.
The reference implementation of PayString server automatically collects metrics using Prometheus. By default, metrics are pushed to the RippleX Prometheus pushgateway. This document describes how you can explicitly configure the PayString server to push to RippleX, or how to collect and analyze these metrics using your own metrics server.
#
Reporting metrics to RippleXRippleX runs a metrics collection server for general use by anyone running a PayString server. Sharing your metrics with RippleX allows the PayString community to aggregate and monitor PayString adoption and growth metrics in one place.
Metrics are reported to RippleX by default but you can push metrics to your own Prometheus pushgateway. Here's how to configure your PayString server to do that:
To opt out of pushing metrics entirely, set the following environment variable on your server:
#
Available metricsThe PayString server captures the following metrics.
Metric | Description |
---|---|
payid_count | The number of PayString address mappings in the system. This is calculated periodically by querying the PayString database and published as metrics periodically (every 60 seconds by default). In Prometheus terms, this metric is a gauge. |
payid_count.paymentNetwork | The payment network for the PayString address mapping. (XRPL, BTC, ETH, ACH, ...) |
payid_count.environment | The payment network’s environment for the PayString address mapping (MAINNET, TESTNET, RINKEBY, ...) |
payid_lookup_request | The number of PayString lookup requests. This metric is updated every time a PayString server is hit with a HTTP request to look up an address or addresses for a PayString. |
payid_lookup_request.paymentNetwork | The payment network for the PayString address mapping. (XRPL, BTC, ETH, ACH, ...) |
payid_lookup_request.environment | The payment network’s environment for the PayString address mapping (MAINNET, TESTNET, RINKEBY, ...) |
payid_lookup_request.result | The result of the lookup. Possible values include:
|
You can use this data to generate real-time charts. For example, this chart shows how many PayString address mappings exist in the system over time:
This chart shows the rate per minute of PayString lookup requests:
#
Import metrics from the PayString server to PrometheusYou can use a push or pull method to obtain metrics from Prometheus.
Tip: Note that both push and pull methods can be used together simultaneously. For example, to pull metrics into an internal Prometheus server and push metrics to a third-party Prometheus server like RippleX.
#
How to pull metrics to PrometheusPrometheus pulls metrics by scraping a known endpoint for metrics data. The PayString server exposes metrics in Prometheus format on the admin port (default 8081
). For simplicity, you can configure Prometheus to scrape metrics directly from the PayString server. Prometheus must be running inside the same network as PayString server because Prometheus needs access to the admin port. If multiple instances of the PayString server are being run behind a load balancer, then Prometheus must pull metrics directly from each instance, not through the load balancer. This direct method is recommended for collecting metrics using your own Prometheus server.
Here is a sample prometheus.yml
configuration file set up to pull metrics from a PayString server running locally.
#
How to push metrics from the PayString server to PrometheusAlternatively, you can push metrics from the PayString server to Prometheus using a pushgateway. This setup requires running a pushgateway in addition to a Prometheus server, and configuring the PayString server to push metrics to the pushgateway. Prometheus then pulls metrics from the pushgateway. In this setup, Prometheus and pushgateway do not need to run inside the same network as the PayString server(s), but the PayString server must be able to reach the pushgateway over http. This is the recommended method for pushing metrics to a third party such as RippleX.
By default, the reference PayString server pushes metrics to the RippleX pushgateway. To push metrics to your own pushgateway, follow these steps:
- Set the environment variables
PUSH_GATEWAY_URL
with the url to your pushgateway. - Restart your PayString server.
For example, if the fictitious company Vandelay Industries wants to push metrics to a pushgateway running at https://some-pushgateway.com
, then set these environment variables: PUSH_GATEWAY_URL= https://some-pushgateway.com
.
By default, a PayString server will push metrics every 15 seconds to the configured pushgateway. To change this frequency, set the PUSH_METRICS_INTERVAL
value. For example, to push every 5 minutes (300 seconds), set PUSH_METRICS_INTERVAL=300
. This value must be a positive number.
As mentioned above, you can also explicitly set PUSH_GATEWAY_URL=https://push00.mon.payid.tech
to push the metrics from your PayString server to RippleX.
#
Visualize metrics with Prometheus and GrafanaPrometheus has an admin web console with limited visualization capabilities on port 9090 (default), as shown in this example.
To build dashboards with multiple charts, you can use Grafana and configure Prometheus as a datasource.
#
Deploy a PayString server with Docker, and pull PayString metrics into PrometheusIn this tutorial, you will deploy a PayString server and run Prometheus locally using Docker, and you will create a configuration file for the PayString server so that PayString metrics are pulled into Prometheus.
#
PrerequisitesInstall the following software on your machine, if not already present.
#
Build a Docker container for setting up a PayString serverRun these commands to build a Docker container for a PayString server.
#
Create Docker network for PayStringYou will run several containers in Docker that must talk to each other. To set up these containers, create a docker network called paystring-network
.
#
Start a Postgres DatabaseTo have a PayString server, you require a Postgres database to store PayString accounts and address mappings. To do this, run the postgres database in docker with a default password of password
, and tell the database to use the paystring-network
that you previously created. Name this docker container paystring-postgres
, so that you can reference the container by name when you connect your PayString server. Note that both the default database and the user are named postgres
, as described at Postgres Docker Official Images.
#
Start and test the PayString serverTo start the PayString server, run the PayString server in docker using the image you created. You must also use the docker network paystring-network
so that it can connect to the paystring-postgres
container.
Test whether the PayString server is running by creating a PayString with this cURL command.
You should get a Created
response.
Query the PayString server to make sure it resolves, using this cURL command.
#
Start PrometheusIn this step, you will run prometheus in docker and configure it to scrape the PayString server’s metrics. To do this, you need to create a prometheus.yml
file on the host machine and mount it in the docker container.
Create a file named prometheus.yml
with these contents.
Start the docker container:
You can verify Prometheus is running by opening http://localhost:9090/graph
in a browser.
You can verify metrics collection metrics are being collected by entering the following expression into the form:
sum(payid_count)
Click Execute
. If successful, the results look like this:
Click the Graph tab to display the results in graph format.
Here are some other example expressions:
sum(payid_count) by (paymentNetwork)
- Sum ofPayString
count by payment network, such as XRPL, BTC, and so forth.sum(payid_lookup_request)
- Total number ofPayString
lookup requests.rate(payid_lookup_request[5m])
- Rate ofPayString
lookup requests per second.