Skip to content

Metrics Quick Start

Novelty 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 {model-name}.ingest.{ingest-name}.count, are available through JMX or a metrics reporter. Novelty reports no ingest timers either, so the response has no per-ingest metrics. Read an ingest's count and bytes meters through JMX.

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

{
  "atTime": "2026-11-04T02:31:29.577096Z",
  "counters": [
    {
      "name": "vastdata.shard.shard-0.sleep-counters.woken",
      "count": 1099
    },
    {
      "name": "vastdata.shard.shard-1.sleep-counters.woken",
      "count": 1074
    }
  ],
  "timers": [
    {
      "name": "persistor.persist-event",
      "min": 0.015209,
      "max": 7.631041,
      "median": 0.150583,
      "mean": 0.4141653719135679,
      "q1": 0.046333,
      "q3": 0.50075,
      "oneMinuteRate": 406.35812362493994,
      "90": 1.128792,
      "99": 3.285583,
      "80": 0.649416,
      "20": 0.036625,
      "10": 0.026291
    }
  ],
  "gauges": [
    {
      "name": "memory.heap.used",
      "value": 316535712
    },
    {
      "name": "shared.valve.ingest",
      "value": 0
    }
  ]
}

Key Metrics to Monitor

Metric Type In the REST response What It Tells You
{model-name}.ingest.{ingest-name}.count Meter No Records ingested and ingest rate
{model-name}.ingest.{ingest-name}.bytes Meter No Data volume ingested
shared.valve.ingest Gauge Yes One per host. Nothing in Novelty closes this valve, so it reads 0
persistor.persist-event Timer Yes Persistence latency

View Metrics via JMX

Novelty exports its metrics via JMX only when the jmx metrics reporter is enabled, and no reporters are enabled by default. Add { type = jmx } to thatdot.novelty.metrics-reporters first, as shown in Metrics Output Formats. You can then browse the metrics using JConsole, VisualVM, or any JMX client.

Connect with JConsole

  1. Start JConsole (included with the JDK):

    jconsole
    
  2. Select the Novelty 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 Novelty with these JVM options from its unpacked distribution directory, where novelty.conf is the configuration file that holds your license key (see Novelty Setup):

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 \
  -Dconfig.file=novelty.conf \
  -jar novelty.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

Novelty supports multiple metrics reporters. No reporters are enabled by default. Configure the ones you want in your configuration file:

thatdot {
  novelty {
    metrics-reporters = [
      { type = jmx },
      { type = csv, period = "15s", log-directory = "metrics-csv" },
      { type = influxdb, database = "novelty", 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