Prometheus

NodeLink exposes Prometheus metrics out of the box. No plugins, no extra setup, just detailed observability into your audio streaming performance.

What you get

Production metrics that matter:

Quick setup

npm install prom-client

export default {
  options: {
    metrics: {
      enabled: true,
      authorization: {
        type: 'Bearer',
        password: 'your_secret_here'
      }
    }
  }
}

curl -H "Authorization: Bearer your_secret_here" \
  http://localhost:2333/v4/metrics

# HELP nodelink_playing_players Number of active audio players
# TYPE nodelink_playing_players gauge
nodelink_playing_players 5

# HELP nodelink_frames_sent Audio frames sent to Discord
# TYPE nodelink_frames_sent counter
nodelink_frames_sent 150234

scrape_configs:
  - job_name: 'nodelink'
    scrape_interval: 15s
    static_configs:
      - targets: ['localhost:2333']
    metrics_path: '/metrics'
    authorization:
      type: Bearer
      credentials: 'your_secret_here'

curl -X POST http://localhost:9090/-/reload

Grafana dashboard

We built a complete dashboard template for quick deployment.

What's included

Real-time audio health with active players, frame rates, and CPU load. Memory anatomy showing RSS vs heap vs external buffers. V8 heap space breakdown for new, old, code, and large objects. Event loop lag percentiles and GC pause heatmap. Frame delivery comparison and quality loss tracking.

Import to Grafana

Import it in Grafana:

1. Go to Dashboards → Import
2. Paste the JSON or upload the file
3. Select your Prometheus datasource
4. Done

The dashboard uses two template variables:

• $datasource - Your Prometheus instance
• $job - Job name filter (supports multi-select)

Available Metrics

NodeLink exposes metrics through the /v4/metrics endpoint. All metrics follow the Prometheus format.

NodeLink-Specific Metrics

Players & Playback

Audio Frame Statistics

High frames_nulled or positive frames_deficit indicates audio quality problems.

API & Source Tracking

Example endpoints tracked: /v4/loadtracks, /v4/stats, /v4/info, /v4/loadlyrics

System Resources

Node.js Runtime Metrics

These are automatically collected by prom-client and provide deep insights into the Node.js process.

Event Loop

High lag values indicate the event loop is blocked, which can cause audio stuttering.

Memory & Heap

Heap spaces include: new, old, code, large_object, trusted, and more.

Garbage Collection

Frequent or long GC pauses can impact audio streaming performance.

Active Resources

Process Info

Example Queries

Audio Quality

Alerting Rules

Example rules for production monitoring.

Audio Degradation

groups:
  - name: nodelink_audio
    interval: 30s
    rules:
      - alert: HighFrameDeficit
        expr: nodelink_frames_deficit > 100
        for: 1m
        labels:
          severity: warning
        annotations:
          summary: "Audio quality degraded"

      - alert: FrequentNulledFrames
        expr: rate(nodelink_frames_nulled[5m]) > 5
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "High nulled frame rate"

Performance Issues

- alert: HighEventLoopLag
  expr: nodejs_eventloop_lag_p99_seconds > 0.1
  for: 2m
  labels:
    severity: warning

- alert: MemoryLeakSuspected
  expr: |
    (nodejs_heap_size_used_bytes - nodejs_heap_size_used_bytes offset 1h) 
    / nodejs_heap_size_used_bytes offset 1h > 0.5
  for: 30m
  labels:
    severity: warning

Pro Tips

Frame deficit should stay within ±50. Large spikes need immediate investigation.

External memory grows with active players. Each player holds decoded audio buffers, this is normal behavior.

Watch for GC pauses over 100ms. Frequent long pauses mean you should increase heap size or reduce player count.

Event loop lag spikes indicate blocking code. Use Node.js profiler to find synchronous bottlenecks.

Use recording rules to pre-aggregate expensive queries:

- record: nodelink:frame_delivery_rate
  expr: rate(nodelink_frames_sent[5m])