System Status and Health Monitoring

Relevant source files

• admin/server/admin_server.py
• admin/server/auth.py
• admin/server/config.py
• admin/server/routes.py
• admin/server/services.py
• agent/component/list_operations.py
• api/db/joint_services/user_account_service.py
• api/db/services/doc_metadata_service.py
• api/db/services/system_settings_service.py
• api/ragflow_server.py
• api/utils/configs.py
• api/utils/health_utils.py
• conf/system_settings.json
• docker/launch_admin_service.sh
• docs/develop/launch_ragflow_from_source.md
• docs/develop/mcp/launch_mcp_server.md
• docs/guides/dataset/add_data_source/add_rss.md
• docs/guides/dataset/enable_excel2html.md
• internal/admin/service_variables_test.go
• internal/dao/mcp.go
• internal/dao/mcp_test.go
• internal/handler/mcp.go
• internal/handler/mcp_test.go
• internal/service/mcp.go
• internal/service/mcp_test.go
• internal/utility/mcp_client.go
• internal/utility/mcp_client_test.go
• internal/utility/oauth/client_test.go
• internal/utility/ssrf.go
• internal/utility/ssrf_test.go
• run_go_tests.sh
• test/testcases/test_web_api/test_canvas_app/test_list_operations_unit.py
• web/src/pages/agent/canvas/node/list-operations-node.tsx
• web/src/pages/agent/form/list-operations-form/index.tsx

Purpose and Scope

This document describes RAGFlow's system health monitoring and status reporting infrastructure. It covers the health check endpoints exposed for operational monitoring, component status reporting, task executor heartbeat monitoring, and the Model Context Protocol (MCP) server integration. This system ensures high availability by providing real-time visibility into the backend services, document engines, and task processing layers.

---

Health Check Endpoints

RAGFlow exposes multiple health check endpoints to support different monitoring use cases, from simple liveness probes to detailed component status reporting. The system uses a multi-layered approach involving the core Python backend (Quart/Flask), the Go-based administrative layer, and specialized storage engine probes.

Endpoint Overview

Endpoint	Authentication	Implementation	Purpose
GET /api/v1/admin/ping	None	admin/server/routes.py	Admin connectivity check admin/server/routes.py38-40
GET /api/v1/admin/auth	Required	admin/server/routes.py	Verify admin session validity admin/server/routes.py67-73
GET /oceanbase/status	Required	api/utils/health_utils.py	OceanBase specific metrics api/utils/health_utils.py104-133
GET /api/v1/mcp/list	Required	internal/handler/mcp.go	List and monitor registered MCP servers internal/handler/mcp.go98-140

Health Monitoring Architecture

The following diagram maps the health monitoring flow from external requests to internal code entities and storage systems.

System Health Data Flow

Sources: api/utils/health_utils.py34-69 admin/server/routes.py38-40

---

Component Health Probes

Healthz Implementation

The comprehensive health check logic resides in api/utils/health_utils.py. It uses a series of probes to verify the entire stack:

1. Relational Database: check_db() executes a lightweight SELECT 1 query via the DB model api/utils/health_utils.py34-41
2. Redis Connectivity: check_redis() uses the REDIS_CONN.health() method to verify connectivity api/utils/health_utils.py44-51
3. Document Engine: check_doc_engine() calls the health() method of the configured docStoreConn (Elasticsearch, Infinity, or OceanBase) api/utils/health_utils.py53-61
4. Object Storage: check_storage() verifies the health of the STORAGE_IMPL (MinIO or S3) api/utils/health_utils.py63-69

Metadata Index Integrity

The system monitors the state of document metadata storage. During user creation or deletion, the system ensures that tenant-specific metadata indices (e.g., ragflow_doc_meta_<tenant_id>) are properly managed api/db/services/doc_metadata_service.py70-80 Failure to initialize or clean up these indices results in logged exceptions during the user account lifecycle api/db/joint_services/user_account_service.py109-113

Sources: api/utils/health_utils.py34-69 api/db/services/doc_metadata_service.py70-80 api/db/joint_services/user_account_service.py106-113

---

Task Executor Heartbeat and Progress

RAGFlow monitors the background task processing layer through a distributed lock and progress update mechanism within the main server.

Progress Update Thread

The ragflow_server.py initializes a dedicated thread update_progress that runs periodically api/ragflow_server.py53-69

• It uses RedisDistributedLock named update_progress to ensure only one server instance updates progress at a time api/ragflow_server.py55-59
• It calls DocumentService.update_progress() to synchronize document parsing states and handle heartbeats api/ragflow_server.py60
• The thread starts with a 1-second delay after server initialization to ensure the DB and Redis are ready api/ragflow_server.py139-143

Sources: api/ragflow_server.py53-69 api/ragflow_server.py139-143

---

MCP Server Integration and Monitoring

The Model Context Protocol (MCP) server integration allows RAGFlow to connect to external tool providers. This integration is managed across the Python backend and the Go server layer.

MCP Lifecycle and Session Management

The RAGFlow server manages the lifecycle of MCP sessions. Upon receiving interrupt signals (SIGINT, SIGTERM), the server triggers shutdown_all_mcp_sessions() to cleanly close connections to MCP servers api/ragflow_server.py71-76

Go-based MCP Management

The Go server provides robust handling for MCP server registration and health testing:

• Registration: CreateMCPServer in internal/service/mcp.go validates server types (e.g., sse, streamable-http) and URLs before persisting to the database via MCPServerDAO internal/service/mcp.go102-157
• Transport Modes: Supports legacy SSE transport and modern streamable-HTTP transport docs/develop/mcp/launch_mcp_server.md63-66
• Error Mapping: mcpErrorResponse in internal/handler/mcp.go maps internal Go errors (like ErrMCPInvalidURL or ErrMCPTestFailed) to standardized API responses for the frontend internal/handler/mcp.go193-207

MCP Integration Mapping

Sources: api/ragflow_server.py44 api/ragflow_server.py71-76 internal/service/mcp.go102-157 internal/handler/mcp.go193-207 docs/develop/mcp/launch_mcp_server.md63-66

---

Operational Database Monitoring: OceanBase

For high-scale deployments using OceanBase as the document engine, RAGFlow provides deep visibility into performance metrics through specialized health functions.

OceanBase Status Reporting

The get_oceanbase_status() and check_oceanbase_health() functions collect comprehensive telemetry api/utils/health_utils.py104-200:

• Connection Health: Tracks if the OBConnection is "healthy" or "timeout" api/utils/health_utils.py120
• Performance Metrics: Aggregates query latency (ms), QPS (Queries Per Second), and slow query counts api/utils/health_utils.py175-179
• Resource Usage: Monitors storage used vs. total capacity api/utils/health_utils.py176-177
• Connection Pool: Reports active vs. maximum allowed connections api/utils/health_utils.py180-181

Sources: api/utils/health_utils.py104-200

---

Admin Service Monitoring

The Admin Service (running on port 9381 by default) provides a dedicated management layer admin/server/admin_server.py73

Service Classification

The admin layer provides endpoints for managing users and monitoring system-wide configurations. It is initialized via admin_server.py, which sets up a Flask application and registers the admin_bp blueprint admin/server/admin_server.py52-53

Admin Authentication Monitoring

The Admin service uses flask_login and a custom setup_auth to monitor and validate administrative access admin/server/auth.py39-85 It verifies JWT tokens against the UserService and checks the is_superuser status via the check_admin_auth decorator to ensure only authorized operators can access system status routes admin/server/auth.py144-157

Sources: admin/server/admin_server.py41-84 admin/server/auth.py39-85 admin/server/auth.py144-157 admin/server/routes.py35