Skip to content

Metrics Quick Start

Quine collects metrics about ingest rates, graph operations, persistence, and system health. This guide shows you how to view these metrics immediately without setting up external monitoring tools.

For production monitoring with dashboards and alerting, see:

View Metrics via REST API

The simplest way to view metrics is through the built-in REST API endpoint Metrics: GET /api/v2/system/metrics:

curl http://localhost:8080/api/v2/system/metrics

The response is a JSON object holding atTime, the moment the metrics were collected, and three arrays: counters, timers, and gauges. Each entry gives the metric's name. A counter adds its count and a gauge its value. A timer adds min, max, mean, median, the quartiles q1 and q3, and the percentiles 10, 20, 80, 90, and 99, all in milliseconds, plus oneMinuteRate, the number of timed events per second over the last minute.

The response has no meters or histograms. Metrics of those types, such as quine.ingest.{ingest-name}.count, are available through JMX or a metrics reporter.

The response looks like this, filtered to a few entries of each kind. Values, and the ingest names in the metric names, vary between runs:

{
  "atTime": "2026-11-04T02:12:42.466236Z",
  "counters": [
    {
      "name": "quine.shard.shard-0.sleep-counters.woken",
      "count": 108
    },
    {
      "name": "quine.shard.shard-1.sleep-counters.woken",
      "count": 102
    }
  ],
  "timers": [
    {
      "name": "persistor.persist-event",
      "min": 0.042833,
      "max": 15.64075,
      "median": 0.169709,
      "mean": 0.23102840162508237,
      "q1": 0.148041,
      "q3": 0.202458,
      "oneMinuteRate": 8.385905099098002,
      "90": 0.274584,
      "99": 0.830875,
      "80": 0.214875,
      "20": 0.144125,
      "10": 0.13225
    },
    {
      "name": "quine.ingest.file-ingest.deserialization",
      "min": 0.004375,
      "max": 0.420583,
      "median": 0.009542,
      "mean": 0.017068899114036345,
      "q1": 0.006958,
      "q3": 0.0175,
      "oneMinuteRate": 20.311520313228563,
      "90": 0.028084,
      "99": 0.153292,
      "80": 0.018916,
      "20": 0.006542,
      "10": 0.006041
    }
  ],
  "gauges": [
    {
      "name": "memory.heap.used",
      "value": 375849216
    },
    {
      "name": "shared.valve.ingest",
      "value": 0
    }
  ]
}

Key Metrics to Monitor

Metric Type In the REST response What It Tells You
quine.ingest.{ingest-name}.count Meter No Records ingested and ingest rate
quine.ingest.{ingest-name}.bytes Meter No Data volume ingested
quine.ingest.{ingest-name}.query Timer Yes Ingest query time per record
quine.ingest.{ingest-name}.deserialization Timer Yes Time to decode each record, for ingests that decode their records (not NumberIterator)
shared.valve.ingest Gauge Yes Standing queries holding back ingest on this host (0 = none)
persistor.persist-event Timer Yes Persistence latency
quine.standing-queries.results.{standing-query-name} Meter No Standing query output rate
quine.standing-queries.dropped.{standing-query-name} Counter Yes Dropped results due to backpressure (should be 0)

Polling Metrics

To monitor metrics over time, poll the endpoint periodically. This loop prints the one-minute rate of each ingest timer every 5 seconds:

# Poll every 5 seconds, extract ingest timer rates
while true; do
  curl -s http://localhost:8080/api/v2/system/metrics | \
    jq '.timers[] | select(.name | contains(".ingest.")) | {name, oneMinuteRate}'
  sleep 5
done

Each record an ingest query runs on is one query timing, and an ingest that decodes its records, such as a file ingest, also times each decode as deserialization. A NumberIterator ingest decodes nothing, so it has only the query timer. Either way, oneMinuteRate follows the records per second that the ingest processes.

View Metrics via JMX

Quine exports all metrics via JMX by default. You can browse them using JConsole, VisualVM, or any JMX client.

Connect with JConsole

  1. Start JConsole (included with the JDK):

    jconsole

  2. Select the Quine process from the list of local Java applications, or connect to a remote host

  3. Navigate to the MBeans tab

  4. Expand metrics to browse all available metrics organized by category

Remote JMX Access

To enable remote JMX connections, start Quine with these JVM options:

java \
  -Dcom.sun.management.jmxremote=true \
  -Dcom.sun.management.jmxremote.port=9010 \
  -Dcom.sun.management.jmxremote.rmi.port=9010 \
  -Dcom.sun.management.jmxremote.local.only=false \
  -Dcom.sun.management.jmxremote.authenticate=false \
  -Dcom.sun.management.jmxremote.ssl=false \
  -Djava.rmi.server.hostname=YOUR_HOST_IP \
  -jar quine-2.2.1.jar

Then connect from a remote machine:

jconsole YOUR_HOST_IP:9010

For production environments, enable authentication and SSL. See Oracle's JMX documentation for secure configuration options.

Metrics Output Formats

Quine supports multiple metrics reporters. By default, only JMX is enabled. Configure additional reporters in your configuration file:

quine {
  metrics-reporters = [
    { type = jmx },
    { type = csv, period = "15s", log-directory = "metrics-csv" },
    { type = influxdb, database = "quine", period = "15s" }
  ]
}

The csv reporter writes one CSV file per metric into log-directory. Write each period with a unit, such as "15s", because a bare number is read as milliseconds.

See the Configuration Reference for all reporter options.

Next Steps