Package hudson.model

Class AdministrativeMonitor

java.lang.Object
hudson.model.AbstractModelObject
hudson.model.AdministrativeMonitor
All Implemented Interfaces:
ExtensionPoint, ModelObject, SearchableModelObject, SearchItem, org.kohsuke.stapler.StaplerProxy
Direct Known Subclasses:
AdministrativeError, ApiTokenPropertyDisabledDefaultAdministrativeMonitor, ApiTokenPropertyEnabledNewLegacyAdministrativeMonitor, AsynchronousAdministrativeMonitor, BuiltInNodeMigration, CompletedInitializationMonitor, ControllerExecutorsAgents, ControllerExecutorsNoAgents, CSRFAdministrativeMonitor, DoubleLaunchChecker, HsErrPidList, HudsonHomeDiskUsageMonitor, JavaVersionRecommendationAdminMonitor, Jenkins.EnforceSlaveAgentPortAdministrativeMonitor, LegacyApiTokenAdministrativeMonitor, MonitorMarkedNodeOffline, NullIdDescriptorMonitor, OldDataMonitor, OperatingSystemEndOfLifeAdminMonitor, PluginManager.PluginCycleDependenciesMonitor, PluginManager.PluginDeprecationMonitor, PluginManager.PluginUpdateMonitor, PluginWrapper.PluginWrapperAdministrativeMonitor, ResourceDomainRecommendation, ReverseProxySetupMonitor, RootUrlNotSetMonitor, SCMTrigger.AdministrativeMonitorImpl, SecurityIsOffMonitor, SlowTriggerAdminMonitor, TooManyJobsButNoView, UpdateCenter.CoreUpdateMonitor, UpdateSiteWarningsMonitor, URICheckEncodingMonitor
public abstract class AdministrativeMonitor extends AbstractModelObject implements ExtensionPoint, org.kohsuke.stapler.StaplerProxy
Checks the health of a subsystem of Jenkins and if there's something that requires administrator's attention, notify the administrator.

How to implement?

Plugins who wish to contribute such notifications can implement this class and put Extension on it to register it to Jenkins.

Once installed, it's the implementer's responsibility to perform monitoring and activate/deactivate the monitor accordingly. Sometimes this can be done by updating a flag from code (see SCMTrigger for one such example), while other times it's more convenient to do so by running some code periodically (for this, use Trigger.timer)

AdministrativeMonitors are bound to URL by Jenkins.getAdministrativeMonitor(String). See getUrl().

Views

message.jelly
If isActivated() returns true, Jenkins will use the message.jelly view of this object to render the warning text. This happens in the http://SERVER/jenkins/manage page. This view should typically render a DIV box with class='alert alert-danger' or class='alert alert-warning' with a human-readable text inside it. It often also contains a link to a page that provides more details about the problem.
Additionally 2 numbers are shown in the Jenkins header of administrators, one with the number or active non-security relevant monitors and one with the number of active security relevant monitors.

Use with System Read permission

By default administrative monitors are visible only to users with Administer permission. Users with Jenkins.SYSTEM_READ permission can access administrative monitors that override getRequiredPermission(). Care needs to be taken to ensure users with that permission don't have access to actions modifying system state. For more details, see getRequiredPermission().

Since:
1.273
Author:
Kohsuke Kawaguchi
See Also:

  • Field Details

    • id

      public final String id
      Human-readable ID of this monitor, which needs to be unique within the system.

      This ID is used to remember persisted setting for this monitor, so the ID should remain consistent beyond the Hudson JVM lifespan.

  • Constructor Details

    • AdministrativeMonitor

      protected AdministrativeMonitor(String id)

    • AdministrativeMonitor

      protected AdministrativeMonitor()

  • Method Details

    • getUrl

      public String getUrl()
      Returns the URL of this monitor, relative to the context path, like "administrativeMonitor/foobar".

    • getDisplayName

      public String getDisplayName()
      Specified by:
      getDisplayName in interface ModelObject

    • getSearchUrl

      public final String getSearchUrl()
      Description copied from interface: SearchItem
      Returns the URL of this item relative to the parent SearchItem.
      Specified by:
      getSearchUrl in interface SearchItem
      Returns:
      URL like "foo" or "foo/bar". The path can end with '/'. The path that starts with '/' will be interpreted as the absolute path (within the context path of Jenkins.)

    • disable

      public void disable(boolean value) throws IOException
      Mark this monitor as disabled, to prevent this from showing up in the UI.
      Throws:
      IOException

    • isEnabled

      public boolean isEnabled()
      Returns true if this monitor isn't disabled earlier.

      This flag implements the ability for the admin to say "no thank you" to the monitor that he wants to ignore.

    • isActivated

      public abstract boolean isActivated()
      Returns true if this monitor is activated and wants to produce a warning message.

      This method is called from the HTML rendering thread, so it should run efficiently.

    • isSecurity

      public boolean isSecurity()
      Returns true if this monitor is security related. This will be used to determine which icon will be used in the navigation bar.
      Since:
      2.267

    • doDisable

      public void doDisable(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) throws IOException
      URL binding to disable this monitor.
      Throws:
      IOException

    • getRequiredPermission

      public Permission getRequiredPermission()
      Required permission to view this admin monitor. By default Jenkins.ADMINISTER, but Jenkins.SYSTEM_READ or Jenkins.MANAGE are also supported.

      Changing this permission check to return Jenkins.SYSTEM_READ will make the active administrative monitor appear on manage.jelly and on the globally visible AdministrativeMonitorsDecorator to users without Administer permission. doDisable(StaplerRequest, StaplerResponse) will still always require Administer permission.

      This method only allows for a single permission to be returned. If more complex permission checks are required, override checkRequiredPermission() and hasRequiredPermission() instead.

      Implementers need to ensure that doAct and other web methods perform necessary permission checks: Users with System Read permissions are expected to be limited to read-only access. Form UI elements that change system state, e.g. toggling a feature on or off, need to be hidden from users lacking Administer permission.

    • checkRequiredPermission

      public void checkRequiredPermission()
      Checks if the current user has the minimum required permission to view this administrative monitor.

      Subclasses may override this method and hasRequiredPermission() instead of getRequiredPermission() to perform more complex permission checks, for example, checking either Jenkins.MANAGE or Jenkins.SYSTEM_READ.

      See Also:

    • hasRequiredPermission

      public boolean hasRequiredPermission()
      Checks if the current user has the minimum required permission to view this administrative monitor.

      Subclasses may override this method and checkRequiredPermission() instead of getRequiredPermission() to perform more complex permission checks, for example, checking either Jenkins.MANAGE or Jenkins.SYSTEM_READ.

      See Also:

    • hasPermissionToDisplay

      public static boolean hasPermissionToDisplay()
      Checks if the current user has the minimum required permission to view any administrative monitor.
      Returns:
      true if the current user has the minimum required permission to view any administrative monitor.
      Since:
      2.468

    • getTarget

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public Object getTarget()
      Ensure that URLs in this administrative monitor are only accessible to users with getRequiredPermission().
      Specified by:
      getTarget in interface org.kohsuke.stapler.StaplerProxy

    • all

      public static ExtensionList<AdministrativeMonitor> all()
      All registered AdministrativeMonitor instances.