tutorial

Monitoring Apache Stanbol with Vigilmon

Apache Stanbol's semantic content management components — content enhancement, entity linking, and ontology management — run as OSGi bundles whose failure is invisible unless you actively probe each service endpoint. Here's how to monitor Apache Stanbol availability, enhancer pipeline health, and entity linking latency with Vigilmon.

Apache Stanbol is a set of reusable OSGi components for semantic content management. Its core services — the Enhancer pipeline (which annotates content with detected entities, categories, and language information), the EntityHub (which manages and resolves entity references), and the Reasoner (which applies OWL/RDF reasoning over linked data) — are deployed as a bundle within a Felix OSGi container. Stanbol is used in content management systems, knowledge graph ingestion pipelines, and semantic annotation workflows where structured metadata needs to be automatically extracted from unstructured text. When an OSGi bundle fails to resolve, a backend triple store becomes unavailable, or the enhancement engine chain returns empty results due to a misconfigured component, Stanbol continues accepting requests while silently failing to annotate content. Vigilmon provides external monitoring for Stanbol's HTTP API, enhancement pipeline health, and entity linking availability so you detect component failures before they corrupt your semantic metadata pipeline.

What You'll Set Up

  • Stanbol HTTP API availability monitoring
  • Enhancement engine chain health check
  • EntityHub availability and entity resolution
  • OSGi bundle state monitoring
  • Enhancement latency tracking

Prerequisites

  • Apache Stanbol 1.0.x or later running with the default launcher
  • Stanbol accessible at a known URL (e.g., http://stanbol.internal:8080)
  • At least one enhancement engine chain configured (e.g., default)
  • A free Vigilmon account

Step 1: Monitor the Stanbol HTTP API

Stanbol's root endpoint and the system status endpoint provide immediate liveness signals. When the Felix OSGi container fails to start, a critical bundle throws an uncaught exception during activation, or the embedded Solr instance that backs content enhancement becomes unavailable, the HTTP endpoints stop responding. Set up an availability monitor:

  1. In Vigilmon, click Add Monitor → HTTP/HTTPS.
  2. Set the URL to http://stanbol.internal:8080/enhancer.
  3. Set Check interval to 1 minute.
  4. Under Expected response, add keyword Enhancement — the enhancer root page always includes this in a healthy Stanbol deployment.
  5. Set Timeout to 15 seconds.

For a more targeted check that validates the enhancement engine chain is registered:

# Verify Stanbol's enhancement chain is active
STANBOL_URL="http://stanbol.internal:8080"
CHAIN="default"

CHAIN_INFO=$(curl -sf --max-time 15 \
  -H "Accept: application/json" \
  "${STANBOL_URL}/enhancer/chain/${CHAIN}" 2>/dev/null)

if echo "$CHAIN_INFO" | python3 -c "
import sys, json
try:
    data = json.load(sys.stdin)
    # Stanbol chain status returns active engines
    sys.exit(0 if data else 1)
except:
    sys.exit(1)
" 2>/dev/null; then
  echo "Stanbol enhancement chain '${CHAIN}' is registered and active"
  curl -s "https://vigilmon.online/heartbeat/REPLACE_WITH_YOUR_TOKEN"
else
  echo "Stanbol enhancement chain '${CHAIN}' not available"
  exit 1
fi

Step 2: Monitor the Enhancement Pipeline

Stanbol's Enhancer is the most commonly used component — it takes text input and returns RDF-formatted annotations with detected named entities, categories, language tags, and topics. The enhancement pipeline chains multiple engines (language detection, entity extraction, entity linking) sequentially. If any engine in the chain fails to initialize or encounters a runtime error, the pipeline returns partial or empty results without raising an HTTP error. Set up a synthetic enhancement check:

  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 enhancement health check:

#!/bin/bash
# /usr/local/bin/stanbol-enhance-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/abc123"
STANBOL_URL="http://stanbol.internal:8080"
CHAIN="default"
TEST_TEXT="Paris is the capital of France. The Eiffel Tower is located there."
TIMEOUT=30
MIN_ENHANCEMENTS=1  # Expect at least 1 entity annotation from the test text

RESPONSE=$(curl -sf \
  --max-time "$TIMEOUT" \
  -X POST \
  -H "Accept: application/rdf+json" \
  -H "Content-Type: text/plain; charset=UTF-8" \
  --data-binary "$TEST_TEXT" \
  "${STANBOL_URL}/enhancer/chain/${CHAIN}" 2>/dev/null)

if [ -z "$RESPONSE" ]; then
  echo "Stanbol enhancement request failed: no response"
  exit 1
fi

# Count entity annotations in the RDF response
ENHANCEMENT_COUNT=$(echo "$RESPONSE" | python3 -c "
import sys, json
try:
    data = json.load(sys.stdin)
    # Count subjects that have fise:extracted-from or fise:entity-reference
    count = sum(1 for k, v in data.items()
                if any('entity' in str(k2).lower() or 'TextAnnotation' in str(k2)
                       for k2 in v.keys()))
    print(count)
except Exception as e:
    print(0)
" 2>/dev/null || echo 0)

if [ "${ENHANCEMENT_COUNT:-0}" -ge "$MIN_ENHANCEMENTS" ]; then
  echo "Stanbol enhancement OK: ${ENHANCEMENT_COUNT} annotations for test text"
  curl -s "$HEARTBEAT_URL"
else
  echo "Stanbol enhancement degraded: only ${ENHANCEMENT_COUNT} annotations (min: ${MIN_ENHANCEMENTS})"
  exit 1
fi

Install the cron job:

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

The test text (Paris is the capital of France) should always produce at least one entity annotation when Stanbol's entity linking engine is functioning. Zero annotations from this text is a reliable failure signal.

Step 3: Monitor the EntityHub

Stanbol's EntityHub is its entity management component — it stores, indexes, and resolves references to entities (persons, organizations, places, concepts) across configured data sources. EntityHub is backed by Solr for indexing and can be connected to remote linked data sources like DBpedia. When the Solr backend becomes unavailable or the EntityHub's site configurations fail to load, entity linking in the enhancement pipeline silently stops resolving entities, resulting in unannotated content. Monitor EntityHub availability:

#!/bin/bash
# /usr/local/bin/stanbol-entityhub-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/def456"
STANBOL_URL="http://stanbol.internal:8080"
TIMEOUT=20

# Query EntityHub for a well-known entity (Paris/DBpedia)
# If EntityHub is healthy, it should return entity metadata
ENTITY_RESPONSE=$(curl -sf \
  --max-time "$TIMEOUT" \
  -H "Accept: application/json" \
  "${STANBOL_URL}/entityhub/sites/entity?id=http://dbpedia.org/resource/Paris" 2>/dev/null)

ENTITY_HTTP=$(curl -o /dev/null -sf \
  --max-time "$TIMEOUT" \
  -w "%{http_code}" \
  -H "Accept: application/json" \
  "${STANBOL_URL}/entityhub/sites/entity?id=http://dbpedia.org/resource/Paris" 2>/dev/null)

# HTTP 200 with data = entity found, HTTP 404 = entity not in local index (may be normal)
# HTTP 500 or timeout = EntityHub is down
if [ "$ENTITY_HTTP" = "200" ] || [ "$ENTITY_HTTP" = "404" ]; then
  echo "Stanbol EntityHub responding: HTTP ${ENTITY_HTTP}"
  curl -s "$HEARTBEAT_URL"
else
  echo "Stanbol EntityHub unavailable: HTTP ${ENTITY_HTTP:-timeout}"
  exit 1
fi

For sites using a locally-loaded dataset (e.g., a Jena TDB store), also verify the site is registered:

SITES=$(curl -sf --max-time 15 \
  -H "Accept: application/json" \
  "${STANBOL_URL}/entityhub/sites" 2>/dev/null)

SITE_COUNT=$(echo "$SITES" | python3 -c "
import sys, json
try:
    data = json.load(sys.stdin)
    print(len(data) if isinstance(data, list) else 0)
except:
    print(0)
" 2>/dev/null || echo 0)

echo "EntityHub sites registered: ${SITE_COUNT}"

Set the Vigilmon heartbeat to 10 minutes.

Step 4: Monitor OSGi Bundle State

Stanbol runs as a collection of OSGi bundles within the Apache Felix container. Bundle failures — caused by missing dependencies, ClassNotFoundException during activation, or configuration errors — prevent individual Stanbol components from starting. Since the Felix web console is the primary window into bundle state, monitor it as a proxy for overall Stanbol component health:

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

HEARTBEAT_URL="https://vigilmon.online/heartbeat/ghi789"
STANBOL_URL="http://stanbol.internal:8080"
FELIX_CONSOLE="${STANBOL_URL}/system/console/bundles"
TIMEOUT=20
MAX_INACTIVE_BUNDLES=5  # Alert if more than 5 bundles are not active/resolved

# Felix console requires credentials (default: admin/admin — change in production)
BUNDLE_STATUS=$(curl -sf \
  --max-time "$TIMEOUT" \
  -u "admin:admin" \
  -H "Accept: application/json" \
  "${FELIX_CONSOLE}.json" 2>/dev/null)

if [ -z "$BUNDLE_STATUS" ]; then
  echo "Felix console unreachable — Stanbol OSGi container may be down"
  exit 1
fi

INACTIVE_COUNT=$(echo "$BUNDLE_STATUS" | python3 -c "
import sys, json
try:
    data = json.load(sys.stdin)
    bundles = data.get('data', [])
    inactive = [b for b in bundles
                if b.get('state_raw') not in [32, 4, 8]  # 32=ACTIVE, 4=RESOLVED, 8=STARTING
                and 'stanbol' in b.get('symbolicName', '').lower()]
    print(len(inactive))
except Exception as e:
    print(0)
" 2>/dev/null || echo 0)

if [ "${INACTIVE_COUNT:-0}" -le "$MAX_INACTIVE_BUNDLES" ]; then
  echo "Stanbol OSGi bundles OK: ${INACTIVE_COUNT} inactive Stanbol bundles"
  curl -s "$HEARTBEAT_URL"
else
  echo "Stanbol OSGi bundle failure: ${INACTIVE_COUNT} inactive bundles (threshold: ${MAX_INACTIVE_BUNDLES})"
  exit 1
fi

Set the Vigilmon heartbeat to 5 minutes. Bundle failures in Stanbol cascade — when an entity linking bundle fails, the enhancer chain silently produces incomplete annotations without any HTTP-level error.

Step 5: Monitor Enhancement Latency

Stanbol's enhancement pipeline performance depends on the engines in the active chain. A chain that includes remote entity lookup (against a SPARQL endpoint or remote DBpedia instance) will be slower and more failure-prone than one using only local engines. Monitor end-to-end enhancement latency:

#!/bin/bash
# /usr/local/bin/stanbol-latency-check.sh

HEARTBEAT_URL="https://vigilmon.online/heartbeat/jkl012"
STANBOL_URL="http://stanbol.internal:8080"
CHAIN="default"
TEST_TEXT="London is the capital of England and is home to Buckingham Palace."
MAX_LATENCY_SECONDS=15
TIMEOUT=60

START_TIME=$(date +%s%3N)

RESPONSE=$(curl -sf \
  --max-time "$TIMEOUT" \
  -X POST \
  -H "Accept: application/rdf+json" \
  -H "Content-Type: text/plain; charset=UTF-8" \
  --data-binary "$TEST_TEXT" \
  "${STANBOL_URL}/enhancer/chain/${CHAIN}" 2>/dev/null)

END_TIME=$(date +%s%3N)
LATENCY_MS=$(( END_TIME - START_TIME ))
LATENCY_S=$(( LATENCY_MS / 1000 ))

if [ -z "$RESPONSE" ]; then
  echo "Stanbol enhancement timed out after ${LATENCY_MS}ms"
  exit 1
fi

if [ "$LATENCY_S" -le "$MAX_LATENCY_SECONDS" ]; then
  echo "Stanbol enhancement latency OK: ${LATENCY_MS}ms"
  curl -s "$HEARTBEAT_URL"
else
  echo "Stanbol enhancement slow: ${LATENCY_MS}ms (threshold: ${MAX_LATENCY_SECONDS}s)"
  exit 1
fi

Run this every 5 minutes. Enhancement latency above 15 seconds for a short sentence typically indicates a remote SPARQL endpoint is timing out or the EntityHub's Solr backend is under GC pressure.

Step 6: Set Up Alert Channels

Configure Vigilmon to route Stanbol alerts to the right teams:

  1. Go to Alert Channels in Vigilmon.
  2. Add a Slack webhook to #semantic-pipeline — Stanbol failures affect all content annotation and entity linking workflows.
  3. Add PagerDuty for the HTTP availability and OSGi bundle monitors — these indicate a complete Stanbol outage.
  4. Add email for the enhancement quality and latency monitors — these allow investigation before a full outage occurs.
  5. Set Consecutive failures before alert to 2 for the enhancement quality monitor — transient engine failures during OSGi bundle reloads can cause a single false alert.

Add a maintenance window during Stanbol configuration updates:

curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "monitor_id": "STANBOL_HTTP_MONITOR_ID",
    "duration_minutes": 10,
    "reason": "Stanbol OSGi bundle reload for engine chain reconfiguration"
  }'

sudo systemctl restart stanbol

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP monitor (API) | /enhancer keyword check | Felix container crash, HTTP server down, port unavailable | | Cron heartbeat (enhancement) | Enhancement output annotation count | Engine chain failure, empty results, entity linking broken | | Cron heartbeat (EntityHub) | /entityhub/sites HTTP response | Solr backend down, site configuration lost | | Cron heartbeat (OSGi bundles) | Felix console inactive bundle count | Bundle activation failure, missing dependency, config error | | Cron heartbeat (latency) | Enhancement round-trip time | Remote SPARQL timeout, GC pressure, engine slowdown |

Stanbol's OSGi architecture makes it particularly susceptible to silent partial failures — when one bundle fails, the components that depend on it degrade gracefully rather than failing loudly, which means your content annotation pipeline continues running while silently producing lower-quality or incomplete semantic metadata. Vigilmon gives you external visibility into every layer of the Stanbol stack so you catch component failures before they corrupt the semantic annotations in your content pipeline.

Start monitoring for free at vigilmon.online.

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