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:

curl http://localhost:8081/api/v2/admin/metrics

This returns a JSON object containing all current metrics:

{
  "counters": {
    "shard.default.shard-0.sleep-counters.slept-success": { "count": 1523 },
    "shard.default.shard-0.sleep-counters.woken": { "count": 1847 }
  },
  "gauges": {
    "shared.valve.ingest.my-ingest.metric": { "value": 0 }
  },
  "meters": {
    "ingest.default.my-ingest.count": {
      "count": 50000,
      "mean_rate": 2534.21,
      "m1_rate": 2100.50,
      "m5_rate": 1890.33,
      "m15_rate": 1756.12
    }
  },
  "timers": {
    "persistor.default.persist-event": {
      "count": 12500,
      "mean_rate": 625.0,
      "duration_units": "milliseconds",
      "mean": 1.23,
      "p50": 0.95,
      "p99": 4.21
    }
  }
}

Key Metrics to Monitor

Metric Type What It Tells You
ingest.*.count Meter Records ingested and ingest rate
ingest.*.bytes Meter Data volume ingested
shared.valve.ingest.*.metric Gauge Backpressure level (0 = healthy)
persistor.*.persist-event Timer Persistence latency

Polling Metrics

To monitor metrics over time, poll the endpoint periodically:

# Poll every 5 seconds, extract ingest rate
while true; do
  curl -s http://localhost:8081/api/v2/admin/metrics | \
    jq '.meters | to_entries[] | select(.key | contains("ingest")) | {name: .key, rate: .value.m1_rate}'
  sleep 5
done

View Metrics via JMX

Novelty 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 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:

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 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. By default, only JMX is enabled. Configure additional reporters in your configuration file:

thatdot {
  novelty {
    metrics-reporters = [
      { type = jmx },
      { type = csv, period = "15s", output-file = "/var/log/novelty/metrics.csv" },
      { type = influxdb, database = "novelty", period = "15s" }
    ]
  }
}

See the Configuration Reference for all reporter options.

Next Steps