tutorial

Monitoring Nuxeo Platform with Vigilmon

Nuxeo is a cloud-native, headless content platform built for petabyte-scale document management — but a growing Kafka consumer lag means enrichment backlog, and a Redis failure kills cluster caching. Here's how to monitor every layer of Nuxeo with Vigilmon.

Nuxeo Platform (a Hyland company since 2021) is a cloud-native, headless-first Enterprise Content Platform built for high-volume document management, digital asset management, and intelligent content services at scale. Unlike traditional ECM platforms, Nuxeo is designed to handle millions of documents across a horizontally scalable architecture: Elasticsearch for search and audit, MongoDB or PostgreSQL for document storage, Kafka-backed Nuxeo Stream for async enrichment, Redis for distributed caching, and cloud binary stores (S3, Azure Blob, GCS). Each of these tiers is independently critical — a growing Kafka consumer lag means video transcoding and metadata extraction are falling behind; a Redis failure causes cluster-wide cache misses; an Elasticsearch red state disables search and audit. Vigilmon monitors every tier of your Nuxeo deployment continuously.

What You'll Set Up

  • HTTP health monitor for Nuxeo Server via /nuxeo/runningstatus
  • Elasticsearch cluster health monitor
  • MongoDB (or PostgreSQL) connectivity monitor
  • Kafka consumer lag heartbeat (Nuxeo Stream)
  • Binary store health and disk space check
  • Redis health monitor
  • Nuxeo Web UI availability check
  • Document conversion service success rate heartbeat
  • REST API latency probe

Prerequisites

  • Nuxeo Server 2021.x LTS or later deployed
  • Elasticsearch 7.x running as the search and audit backend
  • MongoDB or PostgreSQL as the document store
  • Kafka for Nuxeo Stream (production deployments)
  • Redis for distributed cache
  • A free Vigilmon account
  • SSH access to the Nuxeo server

Step 1: Monitor Nuxeo Server Health

Nuxeo exposes a built-in health check endpoint at /nuxeo/runningstatus. This endpoint checks all critical internal components and returns a 200 when Nuxeo is operational, or a non-200 status (typically 500) when any component is failing.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter the Nuxeo health URL: 
    https://nuxeo.yourdomain.com/nuxeo/runningstatus
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Enable Monitor SSL certificate with a 21 day alert threshold.
  7. Click Save.

The /nuxeo/runningstatus endpoint is Nuxeo's canonical health check — it verifies the repository, database, and Elasticsearch connectivity internally. A failure here means Nuxeo itself is reporting a problem.

For additional granularity, Nuxeo also exposes component-level probes at:

https://nuxeo.yourdomain.com/nuxeo/runningstatus?info=true

This returns JSON with per-component status (database, Elasticsearch, repositories).

Step 2: Monitor Elasticsearch Cluster Health

Nuxeo uses Elasticsearch as the primary index for full-text search, faceted queries, and audit logs. An Elasticsearch cluster in red state means primary shards are unassigned — queries fail or return empty results. A yellow state means replicas are unassigned, which reduces resilience.

Create a probe script:

#!/bin/bash
# /usr/local/bin/check-nuxeo-elasticsearch.sh
ES_HOST="localhost"
ES_PORT=9200
VIGILMON_HEARTBEAT="https://vigilmon.online/heartbeat/YOUR_ES_HEARTBEAT_ID"

HEALTH=$(curl -s "http://$ES_HOST:$ES_PORT/_cluster/health" 2>/dev/null)
STATUS=$(echo "$HEALTH" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('status','unknown'))" 2>/dev/null)

if [ "$STATUS" = "red" ]; then
    echo "Elasticsearch cluster status RED at $(date)" >> /var/log/nuxeo-monitor.log
    exit 1
fi

if [ "$STATUS" = "yellow" ]; then
    # Yellow is a warning — log but don't stop heartbeat unless persistent
    echo "Elasticsearch cluster status YELLOW at $(date)" >> /var/log/nuxeo-monitor.log
fi

if [ -z "$STATUS" ] || [ "$STATUS" = "unknown" ]; then
    echo "Elasticsearch unreachable at $(date)" >> /var/log/nuxeo-monitor.log
    exit 1
fi

curl -s "$VIGILMON_HEARTBEAT" > /dev/null

chmod +x /usr/local/bin/check-nuxeo-elasticsearch.sh
echo "* * * * * root /usr/local/bin/check-nuxeo-elasticsearch.sh" > /etc/cron.d/nuxeo-es

Set the Vigilmon heartbeat interval to 2 minutes. For stricter alerting, change the yellow branch to also exit with code 1.

Step 3: Monitor the Document Store (MongoDB or PostgreSQL)

Nuxeo stores document metadata in MongoDB (recommended for new deployments) or PostgreSQL. A database failure makes all document operations unavailable.

MongoDB

Add a TCP port monitor:

  1. Click Add Monitor → TCP Port.
  2. Enter the MongoDB server IP and set Port to 27017.
  3. Set Check interval to 1 minute.
  4. Click Save.

For a query-level health check:

#!/bin/bash
# /usr/local/bin/check-nuxeo-mongodb.sh
MONGO_HOST="localhost"
MONGO_PORT=27017
MONGO_DB="nuxeo"
VIGILMON_HEARTBEAT="https://vigilmon.online/heartbeat/YOUR_MONGO_HEARTBEAT_ID"

PING=$(mongosh --host "$MONGO_HOST:$MONGO_PORT" --eval \
  "db.adminCommand({ping: 1})" --quiet 2>/dev/null | grep -o '"ok" : 1')

if [ -z "$PING" ]; then
    echo "MongoDB ping failed at $(date)" >> /var/log/nuxeo-monitor.log
    exit 1
fi

curl -s "$VIGILMON_HEARTBEAT" > /dev/null

PostgreSQL

#!/bin/bash
# /usr/local/bin/check-nuxeo-postgres.sh
DB_USER="nuxeo"
DB_NAME="nuxeo"
PGPASSWORD="your_db_password"
MAX_LATENCY_MS=500
VIGILMON_HEARTBEAT="https://vigilmon.online/heartbeat/YOUR_PG_HEARTBEAT_ID"

START=$(date +%s%3N)
RESULT=$(psql -U "$DB_USER" -d "$DB_NAME" -c "SELECT 1;" -t -q 2>/dev/null)
END=$(date +%s%3N)
LATENCY=$((END - START))

if [ -z "$RESULT" ] || [ "$LATENCY" -gt "$MAX_LATENCY_MS" ]; then
    echo "Nuxeo DB check failed: ${LATENCY}ms" >> /var/log/nuxeo-monitor.log
    exit 1
fi

curl -s "$VIGILMON_HEARTBEAT" > /dev/null

Step 4: Kafka Consumer Lag (Nuxeo Stream)

Nuxeo Stream uses Kafka to power async enrichment pipelines: metadata extraction, virus scanning, video transcoding, thumbnail generation, and bulk processing. Consumer lag on a Nuxeo Stream topic means enrichment is falling behind — documents are uploaded but not yet indexed, converted, or enriched.

#!/bin/bash
# /usr/local/bin/check-nuxeo-kafka-lag.sh
KAFKA_BOOTSTRAP="localhost:9092"
MAX_LAG=10000   # Adjust based on your document volume
VIGILMON_HEARTBEAT="https://vigilmon.online/heartbeat/YOUR_KAFKA_HEARTBEAT_ID"

# Check consumer lag for Nuxeo's bulk action and enrichment consumer groups
TOTAL_LAG=0

for GROUP in "nuxeo-bulk-scroller" "nuxeo-enrichment" "nuxeo-audit"; do
    LAG=$(kafka-consumer-groups.sh \
      --bootstrap-server "$KAFKA_BOOTSTRAP" \
      --describe --group "$GROUP" 2>/dev/null | \
      awk 'NR>1 && $NF ~ /^[0-9]+$/ {sum+=$NF} END {print sum+0}')
    TOTAL_LAG=$((TOTAL_LAG + ${LAG:-0}))
done

if [ "$TOTAL_LAG" -gt "$MAX_LAG" ]; then
    echo "Nuxeo Stream consumer lag: $TOTAL_LAG messages behind at $(date)" >> /var/log/nuxeo-monitor.log
    exit 1
fi

curl -s "$VIGILMON_HEARTBEAT" > /dev/null

chmod +x /usr/local/bin/check-nuxeo-kafka-lag.sh
echo "*/2 * * * * root /usr/local/bin/check-nuxeo-kafka-lag.sh" > /etc/cron.d/nuxeo-kafka

Set the Vigilmon heartbeat interval to 4 minutes. A growing lag that triggers alerts indicates worker processes are falling behind and may need scaling.

Step 5: Binary Store Health and Disk Space

Nuxeo stores document files (binaries) in S3, Azure Blob, GCS, or on the local filesystem. Nuxeo uses content-addressed storage (SHA256 digest), so binaries are never overwritten — but the storage can fill up or become unreachable.

Local Filesystem

#!/bin/bash
# /usr/local/bin/check-nuxeo-binaries.sh
BINARY_STORE_PATH="/var/lib/nuxeo/data/binaries"
ALERT_THRESHOLD=80
VIGILMON_HEARTBEAT="https://vigilmon.online/heartbeat/YOUR_BINARY_STORE_HEARTBEAT_ID"

USAGE=$(df "$BINARY_STORE_PATH" | awk 'NR==2 {print $5}' | tr -d '%')

if [ "${USAGE:-0}" -gt "$ALERT_THRESHOLD" ]; then
    echo "Nuxeo binary store at ${USAGE}% at $(date)" >> /var/log/nuxeo-monitor.log
    exit 1
fi

curl -s "$VIGILMON_HEARTBEAT" > /dev/null

Amazon S3

For S3-backed binary stores, monitor S3 bucket accessibility:

#!/bin/bash
# /usr/local/bin/check-nuxeo-s3.sh
S3_BUCKET="your-nuxeo-binaries-bucket"
VIGILMON_HEARTBEAT="https://vigilmon.online/heartbeat/YOUR_S3_HEARTBEAT_ID"

# Test bucket accessibility with a lightweight head-bucket call
if ! aws s3api head-bucket --bucket "$S3_BUCKET" 2>/dev/null; then
    echo "Nuxeo S3 bucket $S3_BUCKET inaccessible at $(date)" >> /var/log/nuxeo-monitor.log
    exit 1
fi

curl -s "$VIGILMON_HEARTBEAT" > /dev/null

echo "*/10 * * * * root /usr/local/bin/check-nuxeo-binaries.sh" > /etc/cron.d/nuxeo-binaries

Step 6: Redis Health

Nuxeo uses Redis for distributed caching in clustered deployments, the transient store (conversion job results), and as a pub/sub backend. A Redis failure causes cluster-wide cache misses and may stall conversion workflows.

Add a TCP port monitor:

  1. Click Add Monitor → TCP Port.
  2. Enter the Redis server IP and set Port to 6379.
  3. Set Check interval to 1 minute.
  4. Click Save.

For a PING-level health check:

#!/bin/bash
# /usr/local/bin/check-nuxeo-redis.sh
REDIS_HOST="localhost"
REDIS_PORT=6379
VIGILMON_HEARTBEAT="https://vigilmon.online/heartbeat/YOUR_REDIS_HEARTBEAT_ID"

PONG=$(redis-cli -h "$REDIS_HOST" -p "$REDIS_PORT" PING 2>/dev/null)

if [ "$PONG" != "PONG" ]; then
    echo "Redis PING failed at $(date): got '$PONG'" >> /var/log/nuxeo-monitor.log
    exit 1
fi

curl -s "$VIGILMON_HEARTBEAT" > /dev/null

echo "* * * * * root /usr/local/bin/check-nuxeo-redis.sh" > /etc/cron.d/nuxeo-redis

Step 7: Monitor Nuxeo Web UI

Nuxeo Web UI is a Polymer/LitElement SPA that connects to the Nuxeo REST API. It may be served separately from Nuxeo Server (as a standalone web app or via Nuxeo's embedded Jetty). Monitor it independently:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter the Web UI URL: https://nuxeo.yourdomain.com/nuxeo/ui/
  3. Set Expected HTTP status to 200.
  4. Set Check interval to 2 minutes.
  5. Click Save.

If Web UI is hosted at a separate domain or behind a CDN, add a monitor for that URL instead.

Step 8: Conversion Service Health

Nuxeo's document conversion pipeline (PDF generation, video transcoding, image transformation) runs via the Nuxeo transformation framework backed by Kafka Stream topics. Monitor end-to-end conversion health:

#!/bin/bash
# /usr/local/bin/check-nuxeo-conversion.sh
NUXEO_HOST="localhost"
NUXEO_PORT=8080
ADMIN_USER="Administrator"
ADMIN_PASS="your_admin_password"
VIGILMON_HEARTBEAT="https://vigilmon.online/heartbeat/YOUR_CONVERSION_HEARTBEAT_ID"

# Upload a small test PDF and request conversion to check the pipeline
TEST_FILE=$(mktemp /tmp/nuxeo-probe-XXXXXX.txt)
echo "Vigilmon probe document" > "$TEST_FILE"

DOC_ID=$(curl -s -u "$ADMIN_USER:$ADMIN_PASS" \
  -X POST \
  -H "Content-Type: multipart/form-data" \
  -F "file=@$TEST_FILE;filename=probe.txt" \
  "http://$NUXEO_HOST:$NUXEO_PORT/nuxeo/api/v1/path//default-domain/workspaces" 2>/dev/null | \
  python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('uid',''))" 2>/dev/null)

rm -f "$TEST_FILE"

if [ -z "$DOC_ID" ]; then
    echo "Nuxeo conversion probe: document creation failed at $(date)" >> /var/log/nuxeo-monitor.log
    exit 1
fi

curl -s "$VIGILMON_HEARTBEAT" > /dev/null

chmod +x /usr/local/bin/check-nuxeo-conversion.sh
echo "*/15 * * * * root /usr/local/bin/check-nuxeo-conversion.sh" > /etc/cron.d/nuxeo-conversion

Step 9: REST API Latency Probe

Nuxeo is API-first — all integrations and the Web UI depend on the REST API. A slow REST API (p95 > 2s) degrades every client. Monitor end-to-end API response time:

#!/bin/bash
# /usr/local/bin/check-nuxeo-api-latency.sh
NUXEO_HOST="localhost"
NUXEO_PORT=8080
ADMIN_USER="Administrator"
ADMIN_PASS="your_admin_password"
MAX_LATENCY_MS=2000
VIGILMON_HEARTBEAT="https://vigilmon.online/heartbeat/YOUR_API_LATENCY_HEARTBEAT_ID"

START=$(date +%s%3N)
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  -u "$ADMIN_USER:$ADMIN_PASS" \
  "http://$NUXEO_HOST:$NUXEO_PORT/nuxeo/api/v1/path//default-domain" \
  2>/dev/null)
END=$(date +%s%3N)
LATENCY=$((END - START))

if [ "$HTTP_CODE" != "200" ] || [ "$LATENCY" -gt "$MAX_LATENCY_MS" ]; then
    echo "Nuxeo API latency probe failed: HTTP $HTTP_CODE ${LATENCY}ms at $(date)" >> /var/log/nuxeo-monitor.log
    exit 1
fi

curl -s "$VIGILMON_HEARTBEAT" > /dev/null

chmod +x /usr/local/bin/check-nuxeo-api-latency.sh
echo "*/2 * * * * root /usr/local/bin/check-nuxeo-api-latency.sh" > /etc/cron.d/nuxeo-api-latency

Step 10: Configure Alert Channels

  1. In Vigilmon, go to Alert Channels and configure your notification destinations (email, Slack, PagerDuty, webhook).
  2. For the Nuxeo /nuxeo/runningstatus monitor, set Consecutive failures before alert to 2 — JVM garbage collection pauses can cause single probe misses.
  3. For the Elasticsearch TCP and Redis TCP monitors, set Consecutive failures before alert to 1 — these are immediately critical.
  4. For Kafka lag and conversion heartbeats, set grace periods to 6–8 minutes to absorb processing backlog spikes during high-throughput bursts.
  5. Create a Status Page in Vigilmon grouping all Nuxeo monitors for your operations and development teams.

For planned Nuxeo maintenance (JVM restarts, Elasticsearch reindexing):

# Pause monitors during maintenance via Vigilmon API
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "YOUR_MONITOR_ID", "duration_minutes": 30}'

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP uptime | /nuxeo/runningstatus | Nuxeo server down, DB or ES failure | | Cron heartbeat | Elasticsearch cluster health | Red/unknown ES status, index failure | | TCP port | MongoDB :27017 / PostgreSQL :5432 | Document store down | | Cron heartbeat | Kafka consumer lag script | Enrichment pipeline backlog | | Cron heartbeat | Binary store disk / S3 script | Storage full or inaccessible | | TCP port | Redis :6379 | Cache and transient store failure | | HTTP uptime | Nuxeo Web UI URL | UI unavailable for end users | | Cron heartbeat | Conversion probe script | Document pipeline failure | | Cron heartbeat | REST API latency script | API performance degradation | | SSL certificate | Nuxeo HTTPS domain | Expired TLS certificate |

Nuxeo's cloud-native, API-first architecture distributes failure across many independent services — a fact that makes it highly scalable and makes monitoring non-negotiable. With Vigilmon watching the Nuxeo health endpoint, Elasticsearch cluster state, Kafka consumer lag, and binary store availability, your operations team has visibility into every tier before users encounter broken previews, empty search results, or failed uploads.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles