tutorial

Monitoring Apache Clerezza with Vigilmon

Apache Clerezza's OSGi-based RDF graph management exposes SPARQL endpoints and graph access APIs — when the Felix container stalls, RDF graph serialization fails, or the SPARQL engine times out, semantic web applications silently receive empty graphs. Here's how to monitor Apache Clerezza availability, SPARQL endpoint health, and OSGi bundle status with Vigilmon.

Apache Clerezza is an OSGi-based Java platform for managing RDF data — it provides a type-safe Java API for RDF graph manipulation, a SPARQL query engine, pluggable storage backends, and a set of RESTful services that expose RDF graphs over HTTP. Clerezza runs inside an Apache Felix OSGi container, making it common in semantic web applications, knowledge graph management systems, and enterprise Linked Data platforms. When the Felix OSGi runtime encounters a bundle activation failure, the SPARQL engine runs out of heap due to an unbounded graph query, or the storage backend becomes unavailable, Clerezza continues accepting HTTP connections while returning malformed RDF or HTTP 500 errors — silently breaking every client that depends on graph data. Vigilmon provides external monitoring for Clerezza's HTTP endpoints, SPARQL availability, OSGi health, and storage backend connectivity so you detect service degradation before your semantic applications receive corrupted graph data.

What You'll Set Up

  • Clerezza HTTP endpoint availability monitoring
  • SPARQL query engine health and response time
  • OSGi Felix container bundle status monitoring
  • Storage backend connectivity checks
  • RDF serialization and graph access validation

Prerequisites

  • Apache Clerezza running inside Apache Felix (typically on port 8080)
  • Clerezza accessible at a known URL (e.g., http://clerezza.internal:8080)
  • A configured storage backend (TDB, in-memory, or custom)
  • A free Vigilmon account

Step 1: Monitor the Clerezza HTTP Endpoint

Clerezza exposes its RDF management services over HTTP through the Felix OSGi runtime. The root context and the SPARQL endpoint provide immediate availability signals. When Felix fails to start, a critical bundle throws an unhandled exception during activation, or the HTTP server component deregisters due to a classloader conflict, requests either time out or return OSGi error pages. Set up a basic availability monitor:

  1. In Vigilmon, click Add Monitor → HTTP/HTTPS.
  2. Set the URL to http://clerezza.internal:8080/sparql.
  3. Set Check interval to 1 minute.
  4. Under Expected response, add keyword sparql — a healthy Clerezza SPARQL endpoint always includes the SPARQL service description in its root response.
  5. Set Timeout to 15 seconds.

For a scripted availability check that validates the HTTP layer independently of the SPARQL engine:

# Verify Clerezza's HTTP service is responding
CLEREZZA_URL="http://clerezza.internal:8080"

HTTP_CODE=$(curl -sf \
  --max-time 15 \
  -o /dev/null \
  -w "%{http_code}" \
  "${CLEREZZA_URL}/sparql" 2>/dev/null)

if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "302" ]; then
  echo "Clerezza HTTP endpoint available: HTTP ${HTTP_CODE}"
  curl -s "https://vigilmon.online/heartbeat/REPLACE_WITH_YOUR_TOKEN"
else
  echo "Clerezza HTTP endpoint unavailable: HTTP ${HTTP_CODE:-timeout}"
  exit 1
fi

Step 2: Monitor the SPARQL Query Engine

Clerezza's SPARQL endpoint is the primary query interface for applications that read RDF graphs. A healthy SPARQL engine returns results within milliseconds for simple triple pattern matches against a warmed graph. When a graph update holds a write lock, the in-memory store approaches its heap limit, or a storage backend read fails mid-query, SPARQL queries either stall or return HTTP 500. Set up a synthetic SPARQL health check using a Vigilmon heartbeat:

  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set Expected ping interval to 5 minutes.
  3. Copy the heartbeat URL (e.g., https://vigilmon.online/heartbeat/abc123).

Create the SPARQL health script:

#!/bin/bash
# /usr/local/bin/clerezza-sparql-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/abc123"
CLEREZZA_URL="http://clerezza.internal:8080"
TIMEOUT=30

# Execute a minimal SELECT query — asks for a single triple from the default graph
# Using ASK is also valid but SELECT gives us a binding to validate
SPARQL_QUERY="SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 1"

SPARQL_RESPONSE=$(curl -sf \
  --max-time "$TIMEOUT" \
  -G \
  --data-urlencode "query=${SPARQL_QUERY}" \
  -H "Accept: application/sparql-results+json" \
  "${CLEREZZA_URL}/sparql" 2>/dev/null)

if echo "$SPARQL_RESPONSE" | python3 -c "
import sys, json
try:
    data = json.load(sys.stdin)
    # A valid SPARQL JSON response always contains 'results' and 'head'
    if 'results' in data and 'head' in data:
        sys.exit(0)
    sys.exit(1)
except:
    sys.exit(1)
" 2>/dev/null; then
  echo "Clerezza SPARQL engine healthy"
  curl -s "$HEARTBEAT_URL"
else
  echo "Clerezza SPARQL engine not returning valid JSON results"
  exit 1
fi

Install the cron job:

chmod +x /usr/local/bin/clerezza-sparql-check.sh
(crontab -l 2>/dev/null; echo "*/5 * * * * /usr/local/bin/clerezza-sparql-check.sh >> /var/log/clerezza-health.log 2>&1") | crontab -

A SPARQL query that returns valid JSON structure but no bindings is still a healthy response — it means the graph is empty, not that the engine is broken. Only a non-JSON response, a timeout, or an HTTP error status indicates a real failure.

Step 3: Monitor OSGi Bundle Status

Clerezza runs as a collection of OSGi bundles inside the Felix container. When a required bundle fails to activate — due to a missing dependency, a version conflict, or a service registration failure — Clerezza's API surface degrades silently: some endpoints return errors while others appear healthy. Felix exposes a web console that reports bundle states. Monitor it:

#!/bin/bash
# /usr/local/bin/clerezza-bundle-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/def456"
FELIX_CONSOLE="http://clerezza.internal:8080/system/console"
TIMEOUT=20

# Felix web console bundles endpoint returns bundle state information
# Default credentials for Felix console are admin/admin — change in production
BUNDLES_RESPONSE=$(curl -sf \
  --max-time "$TIMEOUT" \
  -u "admin:admin" \
  -H "Accept: application/json" \
  "${FELIX_CONSOLE}/bundles.json" 2>/dev/null)

if echo "$BUNDLES_RESPONSE" | python3 -c "
import sys, json
try:
    data = json.load(sys.stdin)
    bundles = data.get('data', [])
    # Check for bundles in INSTALLED or RESOLVED state that should be ACTIVE
    # State 32 = ACTIVE, State 4 = INSTALLED, State 8 = RESOLVED
    problem_bundles = [
        b for b in bundles
        if b.get('state') not in (32,)  # not ACTIVE
        and 'fragment' not in b.get('name', '').lower()
        and b.get('stateRaw', 32) not in (32, 8)  # not ACTIVE or RESOLVED fragment
    ]
    if len(problem_bundles) > 0:
        print(f'Problem bundles: {[b.get(\"name\") for b in problem_bundles[:5]]}', file=sys.stderr)
        sys.exit(1)
    sys.exit(0)
except Exception as e:
    print(f'Parse error: {e}', file=sys.stderr)
    sys.exit(1)
" 2>/dev/null; then
  echo "Clerezza OSGi bundles all active"
  curl -s "$HEARTBEAT_URL"
else
  echo "Clerezza OSGi bundle health check failed"
  exit 1
fi

If the Felix web console is not accessible, use the OSGi shell over SSH or Telnet (if enabled) to query bundle states:

# Via Felix Gogo shell (if telnet access is enabled)
# telnet clerezza.internal 6666
# Gogo command: lb | grep -v Active

Set the Vigilmon heartbeat to 10 minutes — bundle state changes are infrequent but critical.

Step 4: Monitor RDF Graph Access

Clerezza's core value is its typed RDF graph API. Applications that read and write triples use the GraphStore service, which may be backed by an in-memory store, a TDB (Turtle/N-Triples file), or a remote SPARQL endpoint. When the GraphStore service fails to retrieve a named graph, the underlying storage returns a read error, or a concurrent graph modification corrupts an iterator, applications receive incomplete or exception-wrapped responses. Monitor graph access directly:

#!/bin/bash
# /usr/local/bin/clerezza-graph-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/ghi789"
CLEREZZA_URL="http://clerezza.internal:8080"
TIMEOUT=20

# Use a SPARQL GRAPH query to confirm the graph store is accessible
# Replace GRAPH_URI with a known named graph in your deployment
GRAPH_URI="http://example.org/monitoring/health"

GRAPH_QUERY="ASK { GRAPH <${GRAPH_URI}> { ?s ?p ?o } }"

GRAPH_RESPONSE=$(curl -sf \
  --max-time "$TIMEOUT" \
  -G \
  --data-urlencode "query=${GRAPH_QUERY}" \
  -H "Accept: application/sparql-results+json" \
  "${CLEREZZA_URL}/sparql" 2>/dev/null)

# ASK returns {"boolean": true} or {"boolean": false} — both are healthy
# Only a non-JSON response or HTTP error indicates a storage problem
if echo "$GRAPH_RESPONSE" | python3 -c "
import sys, json
try:
    data = json.load(sys.stdin)
    if 'boolean' in data:
        sys.exit(0)
    sys.exit(1)
except:
    sys.exit(1)
" 2>/dev/null; then
  echo "Clerezza graph store accessible"
  curl -s "$HEARTBEAT_URL"
else
  echo "Clerezza graph store not accessible or returning invalid response"
  exit 1
fi

Set the heartbeat to 5 minutes.

Step 5: Alert Configuration

Configure Vigilmon alerts for Clerezza incidents:

  1. Open your Clerezza monitors in the Vigilmon dashboard.
  2. Click Alerts → Add alert channel.
  3. Add your preferred notification channel (email, Slack, PagerDuty, webhook).
  4. Set Alert after to 2 consecutive failures to avoid noise from transient network hiccups.
  5. Enable Recovery alerts so you know when Clerezza comes back online after an incident.

For production deployments, configure a separate alert channel for the OSGi bundle monitor with immediate (1 failure) alerting — a bundle activation failure almost always requires human intervention and should never wait for a second check cycle.

Step 6: Validate Your Monitoring Setup

Before relying on your monitors, verify each check detects real failures:

# Test SPARQL monitor: stop Clerezza and confirm the heartbeat stops
# systemctl stop clerezza  (or stop the Felix process)
# Wait 6 minutes — the heartbeat should stop arriving and trigger an alert

# Test graph access monitor: check that the script works against a live instance
chmod +x /usr/local/bin/clerezza-sparql-check.sh
/usr/local/bin/clerezza-sparql-check.sh
# Should print "Clerezza SPARQL engine healthy" and exit 0

# Test the bundle monitor explicitly
/usr/local/bin/clerezza-bundle-check.sh
# Should print "Clerezza OSGi bundles all active" and exit 0

Verify the Vigilmon dashboard shows all monitors green before declaring the setup complete.

What to Monitor in Production

| Monitor | Type | Interval | What it catches | |---------|------|----------|-----------------| | HTTP endpoint | HTTP/HTTPS | 1 min | Felix container crash, network partition | | SPARQL engine | Cron heartbeat | 5 min | Query engine failure, heap exhaustion | | OSGi bundle status | Cron heartbeat | 10 min | Bundle activation failures, dependency issues | | Graph store access | Cron heartbeat | 5 min | Storage backend errors, corrupted iterators |

Summary

Apache Clerezza's OSGi architecture makes individual component failures harder to detect than a simple process crash — the Felix container keeps running even when critical Clerezza bundles are in a failed state. External monitoring with Vigilmon covers the gaps: HTTP availability catches container-level failures, the SPARQL heartbeat catches query engine degradation, and the bundle status check catches the silent partial failures that OSGi makes possible. Start with the HTTP and SPARQL monitors, add the bundle check once you've confirmed Felix console access, and set up alerting before your first production incident.

Start monitoring Apache Clerezza for free with Vigilmon →

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