# How Jenkins Implements Administrative Monitors and Alerts: A Deep Dive into the Extension Framework > Discover how Jenkins administrative monitors and alerts work with its extension framework. Learn to surface warnings, health checks, and security notices effectively. - Repository: [Jenkins/jenkins](https://github.com/jenkinsci/jenkins) - Tags: deep-dive - Published: 2026-06-19 --- **Jenkins uses the `AdministrativeMonitor` abstract class as an extension point to surface warnings, health checks, and security notices to administrators through a pluggable, permission-aware framework.** The jenkinsci/jenkins repository provides a lightweight infrastructure for administrative monitors that allows plugins and core components to register alerts that appear on the **Manage Jenkins** page. This system leverages Jenkins' extension annotation framework to automatically discover monitors, handle URL routing, and enforce permission controls without requiring boilerplate code from implementers. ## Core Architecture of Jenkins Administrative Monitors ### The AdministrativeMonitor Extension Point At the heart of the system lies `hudson.model.AdministrativeMonitor`, an abstract class that implements `ExtensionPoint`. According to the Jenkins source code, any plugin can create a subclass and annotate it with `@Extension` to automatically register with the Jenkins extension registry. This design follows the standard Jenkins pattern for extensible components, ensuring that monitors are discovered at runtime without explicit configuration. The base class is defined in [`core/src/main/java/hudson/model/AdministrativeMonitor.java`](https://github.com/jenkinsci/jenkins/blob/main/core/src/main/java/hudson/model/AdministrativeMonitor.java) and provides the contract that all monitors must fulfill: a unique identifier, an activation check, and optionally a custom permission requirement. ### Unique Identification and State Management Every administrative monitor must have a permanent `id` field, either supplied via the constructor or derived from the class name. This ID serves as the persistent key for URL binding and for tracking whether an administrator has disabled the monitor. In [`AdministrativeMonitor.java`](https://github.com/jenkinsci/jenkins/blob/main/AdministrativeMonitor.java), the constructor handles ID assignment, while the `isEnabled()` helper method checks against `Jenkins.get().getDisabledAdministrativeMonitors()` to determine if the monitor has been dismissed. ## Activation Logic and Permission Model ### The isActivated() Method Subclasses must implement the `boolean isActivated()` method to determine when the alert should appear. According to the source code in [`AdministrativeMonitor.java`](https://github.com/jenkinsci/jenkins/blob/main/AdministrativeMonitor.java), this method runs on the rendering thread, so implementations must be fast and read-only. When `isActivated()` returns `true` and the monitor is enabled, Jenkins includes the monitor in the active list and renders its message view. ### Permission-Based Visibility By default, monitors are visible only to users with `Jenkins.ADMINISTER` permission. However, implementations can override `getRequiredPermission()` or `checkRequiredPermission()` to allow broader visibility, such as `SYSTEM_READ` or `MANAGE` permissions. This granular control is defined in [`AdministrativeMonitor.java`](https://github.com/jenkinsci/jenkins/blob/main/AdministrativeMonitor.java) and evaluated by `Jenkins.getActiveAdministrativeMonitors()`, which filters the full extension list based on the current user's permissions. ## UI Integration and Rendering ### Jelly View Components When a monitor is active, Jenkins renders its `message.jelly` view, located at `core/src/main/resources/**//message.jelly`. For example, the CSRF monitor uses `jenkins/security/csrf/CSRFAdministrativeMonitor/message.jelly` as its display template. The view must wrap content in the `` tag to inherit standard styling and behavior. ### Header Icons and Manage Jenkins Page The `ManageJenkinsAction` class in [`hudson/model/ManageJenkinsAction.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/ManageJenkinsAction.java) coordinates UI integration. It calls `Jenkins.getActiveAdministrativeMonitors()` to determine whether to display warning icons in the top-right admin bar and populates the administrative monitors section on the **Manage Jenkins** page. The URL binding at `/administrativeMonitor/` is handled by `Jenkins.getAdministrativeMonitor(String)`, which scans the extension registry. ## Managing Monitor State ### Enable and Disable Mechanism Administrators can dismiss monitors via the UI using the *Disable* button, which invokes `doDisable()`. Internally, this adds the monitor's ID to the disabled set persisted in Jenkins configuration. The `AdministrativeMonitorsConfiguration` class in [`jenkins/management/AdministrativeMonitorsConfiguration.java`](https://github.com/jenkinsci/jenkins/blob/main/jenkins/management/AdministrativeMonitorsConfiguration.java) provides the global configuration UI that renders checkboxes for all monitors, calling each monitor's `disable(boolean)` method to persist user choices. ### Programmatic Control Plugins can programmatically control monitor states using the Jenkins API: ```java AdministrativeMonitor monitor = Jenkins.get().getAdministrativeMonitor("master-executor-limit"); if (monitor != null && monitor.isEnabled()) { monitor.disable(true); // persist disabled state } ``` This allows automated maintenance scripts or setup wizards to suppress specific warnings without manual UI interaction. ## Implementation Example: Creating a Custom Monitor To implement a custom administrative monitor, extend `AdministrativeMonitor` and provide a Jelly view. Here is a complete example that warns when the master node has too many executors: ```java package org.example.jenkins.monitor; import hudson.Extension; import hudson.model.AdministrativeMonitor; import jenkins.model.Jenkins; /** Warns when the number of executors on the master exceeds a threshold. */ @Extension public class MasterExecutorLimitMonitor extends AdministrativeMonitor { private static final int MAX_EXECUTORS = 4; public MasterExecutorLimitMonitor() { super("master-executor-limit"); } @Override public boolean isActivated() { // Fast read‑only check – no side effects. return Jenkins.get().getNumExecutors() > MAX_EXECUTORS; } @Override public String getDisplayName() { return "Master Executor Limit Exceeded"; } } ``` The corresponding view at `src/main/resources/org/example/jenkins/monitor/MasterExecutorLimitMonitor/message.jelly`: ```xml

Too many executors on the master

The master is configured with more than 4 executors. This can lead to resource contention. Consider moving builds to agents.

 ``` To access active monitors from a Jelly view, iterate over the filtered list: ```xml ``` ## Summary - **Jenkins administrative monitors** use the `AdministrativeMonitor` abstract class in [`hudson/model/AdministrativeMonitor.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/AdministrativeMonitor.java) as an extension point for surfacing alerts. - Monitors are automatically discovered via the `@Extension` annotation and registered in the Jenkins extension registry. - The `isActivated()` method determines visibility and must be fast and read-only since it runs on the rendering thread. - Permission controls default to `Jenkins.ADMINISTER` but can be customized via `getRequiredPermission()`. - The `Jenkins` class in [`jenkins/model/Jenkins.java`](https://github.com/jenkinsci/jenkins/blob/main/jenkins/model/Jenkins.java) provides URL binding via `getAdministrativeMonitor(String)` and filtered access via `getActiveAdministrativeMonitors()`. - UI rendering uses Jelly views named `message.jelly`, integrated into the **Manage Jenkins** page by `ManageJenkinsAction`. - State persistence is handled through `AdministrativeMonitorsConfiguration`, which manages the disabled monitors set. ## Frequently Asked Questions ### What is an Administrative Monitor in Jenkins? An administrative monitor is a plugin component that extends `hudson.model.AdministrativeMonitor` to display warnings, health checks, or security notices to Jenkins administrators. These monitors appear on the **Manage Jenkins** page and can trigger warning icons in the administrative header when their `isActivated()` method returns true. ### How do I disable a Jenkins administrative monitor? Administrators can disable a monitor by clicking the *Disable* button on the alert message, which calls `doDisable()` and adds the monitor's ID to the disabled set. Alternatively, navigate to **Manage Jenkins > System** and uncheck the monitor in the administrative monitors configuration section, or use the API: `monitor.disable(true)`. ### What permissions are required to view administrative monitors? By default, only users with `Jenkins.ADMINISTER` permission can view administrative monitors. However, monitor implementations can override `getRequiredPermission()` to allow `SYSTEM_READ` or `MANAGE` permissions, enabling delegated operators to see specific alerts without full administrative access. ### How do I create a custom administrative monitor plugin? Create a class that extends `AdministrativeMonitor`, annotate it with `@Extension`, implement `isActivated()` to define when the alert shows, and override `getDisplayName()` for the UI label. Package a `message.jelly` file in the resources directory under your class's package path to define the HTML content. Jenkins automatically registers the monitor and handles URL routing at `/administrativeMonitor/`.