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:

Jenkins.administrativeMonitors

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field	Description
String	id	Human-readable ID of this monitor, which needs to be unique within the system.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AdministrativeMonitor()
protected	AdministrativeMonitor(String id)

Method Summary

Modifier and Type	Method	Description
static ExtensionList<AdministrativeMonitor>	all()	All registered AdministrativeMonitor instances.
void	disable(boolean value)	Mark this monitor as disabled, to prevent this from showing up in the UI.
void	doDisable(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp)	URL binding to disable this monitor.
String	getDisplayName()
Permission	getRequiredPermission()	Required permission to view this admin monitor.
String	getSearchUrl()	Returns the URL of this item relative to the parent SearchItem.
Object	getTarget()	Ensure that URLs in this administrative monitor are only accessible to users with getRequiredPermission().
String	getUrl()	Returns the URL of this monitor, relative to the context path, like "administrativeMonitor/foobar".
abstract boolean	isActivated()	Returns true if this monitor is activated and wants to produce a warning message.
boolean	isEnabled()	Returns true if this monitor isn't disabled earlier.
boolean	isSecurity()	Returns true if this monitor is security related.

Methods inherited from class hudson.model.AbstractModelObject

getSearch, getSearchIndex, getSearchName, makeSearchIndex, requirePOST, sendError, sendError, sendError, sendError, sendError

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

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 Detail

AdministrativeMonitor

protected AdministrativeMonitor(String id)

AdministrativeMonitor

protected AdministrativeMonitor()

Method Detail

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 is 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.

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.

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.