[[service-monitors]]
= Service Monitors
:description: Learn about service monitors in {page-component-title} including configuration parameters and how to use placeholders in them.

This section describes all available built-in monitors for xref:operation:deep-dive/service-assurance/introduction.adoc[service assurance].
You can configure them to allow complex monitoring to meet the needs of your environment.

For information on how to extend the functionality of these monitors, see the xref:development:development.adoc#development[Development section] to contribute to the project.

[[ref-service-assurance-monitors-name-definition]]
== Name definitions

Service names are subject to certain definitions:

* Maximum length of 256 characters
* Alphanumeric characters +[Aa-Zz, 0-9]+
* Special characters +[_-:. ]+
* Spaces not allowed

[[ref-service-assurance-monitors-common-parameters]]
== Common configuration parameters

Application- or device-specific monitors are based on a generic API that provides common configuration parameters.
These minimum configuration parameters are available in all monitors and describe the behavior for timeouts, retries, and so on.

.Optional common configuration parameters
[options="header"]
[cols="1,3,2"]
|===
| Parameter
| Description
| Default

| retry
| Number of attempts to test a service's status (up or down).
| 3

| timeout
| Timeout for the isReachable method, in milliseconds.
| 3000

| invert-status
| Invert the up/down behavior of the monitor.
| false

| ds-name *
| Name of the RRD data source (DS) name in which to store this service monitor's response-time samples.
| response-time

| rrd-base-name *
| The file name of the RRD file (minus the `.rrd` file extension) within the specified rrd-repository path in which to persist this service monitor's response-time samples.
| value of `ds-name`

| rrd-repository *
| Base directory of an RRD repository in which to store this service monitor's response-time samples.
| null

| rrd-status
| Enable xref:operation:deep-dive/service-assurance/polling-packages.adoc#service-status-persistence[service status persistence]
| true

| thresholding-enabled
| Whether collected response time should be tested against thresholds.
| false
|===

NOTE: * If RRD properties are provided, the pollerd service will persist response times for the monitored service.

TIP: If the monitor uses SNMP, the default configuration for timeout and retry are taken from the SNMP configuration (`snmp-config.xml`).

[[ref-service-assurance-monitors-minion-parameters]]
=== Minion configuration parameters

When nodes are configured with a non-default location, the associated service monitors run on a Minion configured with that same location.
If a given location has multiple Minions, the service monitor may run on any of the Minions that are currently available.
To run a service monitor on a specific Minion, specify the System ID of the Minion.
Use this mechanism to monitor the Minions individually.

Use the following parameters to override this behavior and control where the service monitors run.

.Optional Minion configuration parameters
[options="header"]
[cols="1,3,2"]

|===
| Parameter
| Description
| Default

| location
| Specify the location to run the service monitor.
| The location of the associated node.

| system-id
| Specify the system ID on which to run the service monitor.
| n/a

| use-foreign-id-as-system-id
| Use the foreign id of the associated node as the system ID.
| false
|===

NOTE: When you specify a system ID, also set the location to the corresponding location for that system.

[[ref-service-assurance-monitors-placeholder-substitution-parameters]]
== Use placeholders in parameters
Some monitor parameters support placeholder substitution.
You can reference some node, interface, and asset record properties by enclosing them in `{` and `}`.
The supported properties are:

* nodeId
* nodeLabel
* foreignSource
* foreignId
* ipAddr (or ipAddress)
* all node asset record fields (for example: username, password)

Parameters that support placeholder substitution have a kbd:[{}] icon beside them in the *Configuration and use* section of the monitor documentation.

== Example service definition

The following shows the basic format of a sample service definition.
Note that all service definitions must include the `monitor` section.

[source, xml]
----
<service name="SomeServiceName" interval="300000" user-defined="false" status="on"> <parameter key="key1" value="1" /> <parameter key="key2" value="2" /> <parameter key="key3" value="3" /> </service>

<monitor service="SomeServiceName" class-name="org.opennms.netmgt.poller.monitors.SomeServiceName"/> <1>
----
<1> Required *monitor* section.
