https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=43138 Bug ID: 43138 Summary: Add health_check plugin hook for publishing alerts to the system health framework Initiative type: --- Sponsorship --- status: Product: Koha Version: Main Hardware: All OS: All Status: NEW Severity: enhancement Priority: P5 - low Component: Plugin architecture Assignee: koha-bugs@lists.koha-community.org Reporter: tomascohen@gmail.com QA Contact: testopia@bugs.koha-community.org CC: kyle@bywatersolutions.com, martin.renvoize@openfifth.co.uk, tomascohen@gmail.com Depends on: 43137 Target Milestone: --- Companion to Bug 43137 (system health monitoring). Plugins that manage external service connections need a way to publish their warnings and critical alerts through the same health framework, grouped by plugin. How it works: Core calls the hook, wraps the result with the plugin's metadata, and keys it by class in the 'plugins' hash of the /api/v1/health response. Plugin hook contract: sub health_check { my ($self) = @_; return { url => '/cgi-bin/koha/plugins/run.pl?...&page=status', # optional drill-down link checks => [ { id => 'pod_dev03', label => 'Pod dev03-na', warnings => ['3 tasks in retry state for over 1 hour'], critical => ['HTTP 500 -- task queue delayed until 15:19 (100 tasks affected)'], }, { id => 'pod_prod', label => 'Pod prod-eu', warnings => [], critical => [], }, ], }; } Core assembles the response: { "core": [ ... ], "plugins": { "Koha::Plugin::Com::ByWaterSolutions::RapidoILL": { "name": "Rapido ILL", "url": "/cgi-bin/koha/plugins/run.pl?...&page=status", "checks": [ { "id": "pod_dev03", "label": "Pod dev03-na", "warnings": ["3 tasks in retry state for over 1 hour"], "critical": ["HTTP 500 -- task queue delayed until 15:19 (100 tasks affected)"] }, { "id": "pod_prod", "label": "Pod prod-eu", "warnings": [], "critical": [] } ] } } } - 'name' is derived automatically from the plugin's metadata ($plugin->get_metadata->{name}) - 'url' is optional -- if provided, the detail view links the plugin heading to its own status page - The plugin class is used as the hash key -- stable, unique, no collisions Requirements for plugin authors: - The hook MUST be cheap (local DB queries only, no external HTTP calls) - Return one or more checks (e.g., one per configured endpoint/pod/service) - Empty 'warnings'/'critical' arrays = healthy (still shows OK in the detail view under the plugin group) - Return undef to not participate at all Fault isolation: - Each plugin's health_check call is wrapped in try/catch - A failing hook produces: { name => $plugin_name, checks => [{ id => 'error', label => $plugin_name, warnings => [], critical => ["Health check failed: $error"] }] } - Other sources are unaffected Header indicator logic includes plugin alerts: - Plugin criticals turn the dot red - Plugin warnings turn the dot yellow (if no criticals anywhere) - A broken plugin hook counts as a critical (the framework itself is unhealthy) Use cases: - Rapido ILL: critical when 5xx errors delay the task queue, warning when tasks are stuck in retry - NCIP relay: warning when response times exceed threshold - SIP2 connector: critical when connection pool is exhausted - Discovery sync: warning when last successful sync exceeds configured interval Referenced Bugs: https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=43137 [Bug 43137] Add system health monitoring with status indicators in the staff interface header -- You are receiving this mail because: You are watching all bug changes. You are the assignee for the bug.