SoliDB Docs
Back to API Reference

Health & Metrics

Health check and Prometheus metrics endpoints. No authentication required.

GET /_api/health

Check if the server is running.

Response

{ "status": "ok", "timestamp": "2025-01-01T00:00:00Z" }
GET /metrics

Prometheus metrics endpoint. Returns metrics in Prometheus text exposition format for monitoring and alerting.

Available Metrics

solidb_http_requests_total

Total HTTP requests processed (counter)

solidb_uptime_seconds

Server uptime in seconds (gauge)

solidb_cpu_usage_percent

Current CPU usage percentage (gauge)

solidb_memory_*_bytes

Memory stats: total, used, available (gauge)

solidb_databases_total

Number of databases (gauge)

solidb_collections_total

Total collections across all databases (gauge)

solidb_active_scripts

Active Lua scripts (gauge)

solidb_cluster_healthy_nodes

Healthy cluster nodes (gauge, if clustered)

Example Response

# HELP solidb_http_requests_total Total number of HTTP requests processed
# TYPE solidb_http_requests_total counter
solidb_http_requests_total 1542

# HELP solidb_uptime_seconds Time since server started in seconds
# TYPE solidb_uptime_seconds gauge
solidb_uptime_seconds 3600.123

# HELP solidb_cpu_usage_percent Current CPU usage percentage
# TYPE solidb_cpu_usage_percent gauge
solidb_cpu_usage_percent 15.50

Prometheus Configuration

scrape_configs:
  - job_name: 'solidb'
    static_configs:
      - targets: ['localhost:6745']

Slow Query Logging

Automatic logging of queries exceeding the performance threshold.

Overview

SoliDB automatically logs queries that exceed 100ms execution time to a special _slow_queries collection in each database. This helps identify performance bottlenecks and queries that need optimization.

Configuration

The slow query threshold is configured via a constant in the server:

// src/server/handlers.rs
const SLOW_QUERY_THRESHOLD_MS: f64 = 100.0;  // Default: 100ms

Slow Query Document Structure

Each slow query is logged with the following fields:

{
  "_key": "auto-generated-uuid",
  "query": "FOR doc IN users FILTER doc.age > 25 RETURN doc",
  "execution_time_ms": 245.67,
  "timestamp": "2025-01-13T10:30:00.000Z",
  "results_count": 1000,
  "documents_inserted": 0,
  "documents_updated": 0,
  "documents_removed": 0
}

Querying Slow Queries

You can query the slow queries collection like any other collection:

// Get recent slow queries
FOR sq IN _slow_queries
  SORT sq.timestamp DESC
  LIMIT 100
  RETURN sq

// Find queries slower than 500ms
FOR sq IN _slow_queries
  FILTER sq.execution_time_ms > 500
  SORT sq.execution_time_ms DESC
  RETURN sq

// Find slow queries with mutations
FOR sq IN _slow_queries
  FILTER sq.documents_inserted > 0 OR sq.documents_updated > 0
  RETURN sq

Dashboard Integration

The SoliDB Dashboard includes a dedicated Slow Queries page that displays logged slow queries with filtering, sorting, and the ability to copy queries to the query editor for optimization.

Note: The _slow_queries collection is created automatically when the first slow query is detected. You can truncate this collection to clear the log. Consider adding a TTL index to automatically expire old slow query records.

Datadog Integration

Integrate SoliDB metrics with Datadog using the Prometheus scraping feature.

Overview

Datadog can scrape the /metrics endpoint directly using its OpenMetrics integration. This requires no code changes to SoliDB - just configure the Datadog Agent.

Datadog Agent Configuration

Create a configuration file at conf.d/openmetrics.d/conf.yaml:

init_config:

instances:
  - openmetrics_endpoint: http://localhost:6745/metrics
    namespace: solidb
    metrics:
      - solidb_http_requests_total
      - solidb_uptime_seconds
      - solidb_cpu_usage_percent
      - solidb_memory_total_bytes
      - solidb_memory_used_bytes
      - solidb_memory_available_bytes
      - solidb_databases_total
      - solidb_collections_total
      - solidb_active_scripts
      - solidb_active_websockets
      - solidb_cluster_healthy_nodes

Docker Compose Setup

Run Datadog Agent alongside SoliDB:

services:
  solidb:
    image: solidb/solidb:latest
    ports:
      - "6745:6745"

  datadog-agent:
    image: datadog/agent:latest
    environment:
      - DD_API_KEY=${DD_API_KEY}
      - DD_SITE=datadoghq.com
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./datadog-conf.d:/etc/datadog-agent/conf.d

Kubernetes with Autodiscovery

Add annotations to your SoliDB pod:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    ad.datadoghq.com/solidb.checks: |
      {
        "openmetrics": {
          "instances": [{
            "openmetrics_endpoint": "http://%%host%%:6745/metrics",
            "namespace": "solidb",
            "metrics": ["solidb_*"]
          }]
        }
      }

Tip: Once configured, all SoliDB metrics will appear in Datadog with the solidb. prefix. You can create dashboards, monitors, and alerts using these metrics.

Jobs API Overview