-
Home
- Studio
Working with Macros
Macros for Monitors
All Monitors
The macros listed below can be used in the configuration of any Monitor type, in addition to all user-defined macros in the Template.
| Macro | Description |
|---|---|
| %{USERNAME} | Username defined in the monitor's credentials. |
| %{HOSTNAME} or %{HOST_NAME} | Name of the targeted host. |
| %{HOST_FQDN} | Fully qualified domain name of the targeted host. |
| %{HOST_IPADDRESS} | IP address of the targeted host. |
| %{HOST_DOMAIN} | Domain of the targeted host. |
| %{HOST_SNMPCOMMUNITY} | SNMP community set for the SNMP Agent on the targeted host. |
| %{HOST_SYSTEMTYPE} | Operating system type of the targeted host. |
| %{TEMPLATE_ID} | PATROL ID of the Template triggering the alert. |
| %{TEMPLATE_LABEL} | Display name of the Template triggering the alert. |
| %{TEMPLATE_NAME} | Name of the Template where the monitor is defined. |
| %{TEMPLATE_CLASS} | Template's application class name. |
| %{TEMPLATE_TYPE} | Type of the Template triggering the alert (Template). |
| %{TEMPLATE_CONTACT} | Contact information in case of a Template failure. |
| %{TEMPLATE_DESCRIPTION} | Description of the Template as provided in the Web interface. |
| %{TEMPLATE_COLLECTIONERRORS} | List of collection errors that occurred between the current collect and the previous one. |
| %{<user-defined>} | Any macro defined by the user at the Template level. |
Command Line
These macros are available to customize the content of the Command Line field in the Monitor page.
| Macro | Description |
|---|---|
%{FILE: <filename>} |
File or script path. |
%{LASTTIME: <date-time-format>} |
Last collector execution time. Refer to the Date and Time Formats for Macros section for more additional formatting information. |
| %{PASSWORD} | Unencrypted password of the targeted host. |
| %{PASSWORD_BASE64} | Password of the targeted host, encoded using Base64. |
| %{PASSWORD_JSON} | Password of the targeted host, JSON encoded. |
| %{PASSWORD_PSLENCRYPT} | Password of the targeted host, encoded using PSL encrypt() function. |
| %{PASSWORD_URL} | Password of the targeted host, URL encoded. |
%{<prefix>PASSWORD} or %{PASSWORD<suffix>} |
Unencrypted user defined passwords. Here <prefix> and <suffix> can be any alpha-numeric character. |
| %{TIME} | Current collector execution time in HH:MM:SS format. |
%{TIME: <date-time-format>} |
Current collector execution time in the specified format. Refer to the Date and Time Formats for Macros section for more details. |
File
These macros are available to customize the content of the File Path field in the Monitor page.
| Macro | Description |
|---|---|
| %{TIME} | Current collector execution time in HH:MM:SS format. |
%{TIME: <date-time-format>} |
Current collector execution time in the specified format. Refer to the Date and Time Formats for Macros section for more details. |
Folder
These macros are available to customize the content of the File Path field in the Monitor page.
| Macro | Description |
|---|---|
| %{TIME} | Current collector execution time in HH:MM:SS format. |
%{TIME: <date-time-format>} |
Current collector execution time in the specified format. Refer to the Date and Time Formats for Macros section for more details. |
HTTP Request
These macros are available to customize the content of the URL, HTTP Request Header, or HTTP Request Body fields in their respective Monitor page.
| Macro | Description |
|---|---|
| %{DATE} | Current date in the YYYY-MM-DD format, available only for HTTP Request Body. |
| %{PASSWORD} | Unencrypted password of the targeted host. |
| %{PASSWORD_BASE64} | Password of the targeted host, encoded using Base64. |
| %{PASSWORD_JSON} | Password of the targeted host, JSON encoded. |
| %{PASSWORD_PSLENCRYPT} | Password of the targeted host, encoded using PSL encrypt() function. |
| %{PASSWORD_URL} | Password of the targeted host, URL encoded. |
%{<prefix>PASSWORD} or %{PASSWORD<suffix>} |
Unencrypted user defined passwords. Here <prefix> and <suffix> can be any alpha-numeric character. |
| %{TIME} | Current collector execution time in HH:MM:SS format, available only for HTTP Request Body. |
%{TIME: <date-time-format>} |
Current collector execution time in the specified format, available only for HTTP Request Body. Refer to the Date and Time Formats for Macros section for more details. |
| %{TOKEN} | Access token obtained from the HTTP Request that performs the authentication, available for HTTP Request Header and HTTP Request Body. |
Nagios Plugin
These macros are available to customize the content of the Nagios Plugin Command field in the Monitor page.
| Macro | Description |
|---|---|
%{FILE: <filename>} |
File or script path. |
| %{PASSWORD} | Unencrypted password of the targeted host. |
| %{PASSWORD_BASE64} | Password of the targeted host, encoded using Base64. |
| %{PASSWORD_JSON} | Password of the targeted host, JSON encoded. |
| %{PASSWORD_PSLENCRYPT} | Password of the targeted host, encoded using PSL encrypt() function. |
| %{PASSWORD_URL} | Password of the targeted host, URL encoded. |
PSL Script
These macros are available to customize the content of the PSL Command or Script field in the Monitor page.
| Macro | Description |
|---|---|
| %{PASSWORD} | Unencrypted password of the targeted host. |
| %{PASSWORD_BASE64} | Password of the targeted host, encoded using Base64. |
| %{PASSWORD_JSON} | Password of the targeted host, JSON encoded. |
| %{PASSWORD_PSLENCRYPT} | Password of the targeted host, encoded using PSL encrypt() function. |
| %{PASSWORD_URL} | Password of the targeted host, URL encoded. |
String Search
These macros are available to customize the string or regex in Search for Lines That and optional AND/OR combination fields in the Monitor page.
| Macro | Description |
|---|---|
| %{DATE} | Current date in the YYYY-MM-DD format. |
| %{TIME} | Current collector execution time in HH:MM:SS format. |
%{TIME: <date-time-format>} |
Current collector execution time in the specified format. Refer to the Date and Time Formats for Macros section for more details. |
Macros for Alert Messages
You can use macros to customize the content of alert messages. For example: %{PARAMETER_VALUE} is replaced by the actual current value of the parameter that triggered the alert. Each macro listed in the tables below contains information about the problem that triggered the alert.
Tip: Macro syntax supports white spaces.
Warning: Macros are case sensitive and should then always be written in uppercase.
General Macros
The macros listed in the table below can be used on any object.
| Macro | Description |
|---|---|
| %{CREDENTIALS} | Label of the credentials used by the monitor. |
| %{COMMA} | Inserts a comma. |
| %{CONVERTED_UNIT} | Converted unit, if convert units is selected. |
| %{CONVERTED_VALUE_UNIT} | Converted value (rounded to 2 decimal value) followed by the converted unit, if any. This converted value is provided before any rescaling, but after calculating sum, min, max, etc. |
| %{CONVERTED_VALUE} | Converted (if convert units is selected) or extracted value, before any rescaling, but after calculating sum, min, max, etc. |
| %{DATE} | Current date in the YYYY-MM-DD format. |
| %{EOL} | Inserts carriage return. |
| %{EXTRACTED_LINE} | Content of the extracted line (X_DYNAMIC and X_NAGIOSPERF classes only). |
| %{HOST_DOMAIN} | Domain of the targeted host. |
| %{HOST_FQDN} | Fully qualified domain name of the targeted host. |
| %{HOST_IPADDRESS} | IP address of the targeted host. |
| %{HOST_NAME} or %{HOSTNAME} | Name of the targeted host. |
| %{HOST_SNMPCOMMUNITY} | SNMP community set for the SNMP Agent on the targeted host. |
| %{HOST_SYSTEMTYPE} | Operating system type of the targeted host. |
| %{INFORMATION} | Provides additional information about the problem/alert. |
| %{INFORMATION_ONELINE} | Provides additional information about the problem/alert in a single line. |
| %{OBJECT_CLASS} | Class name of the object to which the alert action belongs. |
| %{OBJECT_ID} | PATROL ID of the object triggering the alert. |
| %{OBJECT_LABEL} | Display name of the object triggering the alert. |
| %{OBJECT_TYPE} | Type of the object triggering the alert (“Process”, “String”, etc.). |
| %{PARAMETER_ALARM1MAX} | Alarm1 maximum range of the parameter triggering the alert. |
| %{PARAMETER_ALARM1MIN} | Alarm1 minimum range of the parameter triggering the alert. |
| %{PARAMETER_ALARM1NTIMES} | Number of consecutive times the parameter triggering the alert must have a value within the alarm1 range before the alert occurs. |
| %{PARAMETER_ALARM1TYPE} | Alarm alert type of the parameter triggering the alert (OK, WARN, ALARM). |
| %{PARAMETER_ALARM2MAX} | Alarm2 maximum range of the parameter triggering the alert. |
| %{PARAMETER_ALARM2MIN} | Alarm2 minimum range of the parameter triggering the alert. |
| %{PARAMETER_ALARM2NTIMES} | Number of consecutive times the parameter triggering the alert must have a value within the alarm2 range before the alert occurs. |
| %{PARAMETER_ALARM2TYPE} | Alarm2 alert type of the parameter triggering the alert (OK, WARN, ALARM). |
| %{PARAMETER_BORDERMAX} | Border maximum range of the parameter triggering the alert. |
| %{PARAMETER_BORDERMIN} | Border minimum range of the parameter triggering the alert. |
| %{PARAMETER_BORDERNTIMES} | Number of consecutive times the parameter triggering the alert must have a value outside the border range before the alert occurs. |
| %{PARAMETER_BORDERTYPE} | Border alert type of the parameter triggering the alert (OK, WARN, ALARM). |
| %{PARAMETER_NAME} | Name of the parameter triggering the alert. |
| %{PARAMETER_STATUS} | Status of the parameter. |
| %{PARAMETER_TITLE} | Title of the parameter. |
| %{PARAMETER_UNITS} | Units of the parameter. |
| %{PARAMETER_VALUE} | Value of the parameter triggering the alert. |
| %{PARENT_CLASS} | Class name of the parent object to which the alert action belongs. |
| %{PARENT_ID} | PATROL identifier of the object's parent. |
| %{PARENT_LABEL} | Display name of the object’s parent. |
| %{PARENT_TYPE} | Type of the object’s parent. (“File”, “CommandLine”, etc.). |
| %{PASSWORD} | Encrypted password of the targeted host. |
| %{RESULT} | Query result received for the monitored object during data collection, when available. |
| %{SEMICOLON} | Inserts a semicolon. |
| %{STATUS_INFORMATION} | Provides additional information about the Status, as reported by the StatusInformation parameter (where available). |
| %{TIME} | Time in HH:MM:SS format. |
%{TIME: <date-time-format>} |
Time in the specified format. Refer to the Date and Time Formats for Macros section for more details. |
| %{USERNAME} | Username defined in the monitor's credentials. |
| %{VALUE} | The current value of the parameter triggering the alert. |
| %{<variable path>} | Value of the PATROL Agent namespace variable relative to the parameter that triggered the alert (ex: %{/hostname}, %{../sid}, %{/osName}, %{../osCommand}). |
Monitor-Specific Macros
The macros listed below can be used in alert messages and are specific to their respective object type.
| Macro | Description |
|---|---|
| Command Line | |
| %{COMMAND_LINE} | Command line being executed and analyzed. |
| %{EXIT_STATUS_CODE} | Exit status returned by the system after executing the command. |
| Database Monitor | |
| %{DATABASE_NAME} | Name of the database the SQL query is sent to. May be the database name for SQL Server, or the Oracle SID for Oracle. |
| %{DATABASE_TYPE} | Type of the database. |
| %{QUERY} | SQL statement sent for execution. |
| Dynamic Object | |
| %{RESULT} | Returns the output of the dynamic object. |
| Dynamic Value Map | |
| %{RETAINED_VALUE} | Value retained by the collect and mapped to a status. |
| %{MAPPED_STATUS_INFORMATION} | Provides additional information about the Status of the value mapping result, as reported by the StatusInformation parameter. |
| File | |
| %{FILENAME} | Name of the monitored file as entered in the GUI. |
| %{MONITORED_FILE} | Current file being monitored. |
| File System | |
| %{FILESYSTEM} | Name of the monitored file system. |
| Folder | |
| %{FOLDER} | Folder being monitored. |
| %{OLDEST_FILES_IN_FOLDER} | Name of the oldest file in the folder. |
| Host | |
| %{AVAILABILITY_CHECKS} | List of configured availability checks, separated by commas. |
| %{CREDENTIALS_LIST} | List of credentials, separated by commas. |
| %{SIGNATURE_FILES} | List of signatures files, separated by commas. |
| %{TCP_PORT} | Port number used for the TCP availability check. |
| Multi-Parameter Formula | |
| %{FORMULA} | User-defined formula used to calculate the parameter value. |
| Numeric Value Extraction | |
| %{DELTA} | Difference between the values extracted during the latest collect and the previous one. |
| %{EXTRACTED_VALUE} | Value of the parameter as extracted from the source. |
| %{FORMATTED_VALUE} | Value of the parameter after user-specified format is applied. |
| Process | |
| %{COMMAND_LINE} | Process command line being searched for, as entered in the GUI. |
| %{MATCHING_PROCESSES} | List of all matching processes. |
| %{PID_FILE} | Path to the PID file whose corresponding process is being monitored. |
| %{PROCESS_NAME} | Process name being searched for, as entered in the GUI. |
| %{USER_ID} | Process user ID being searched for, as entered in the GUI. |
| %{WORST_PROCESS_COMMANDLINE} | Command line of the first worst process. |
| %{WORST_PROCESS_NAME} | Name of the first worst process. |
| %{WORST_PROCESS_PID} | PID of the first worst process. |
| %{WORST_PROCESS_PPID} | PPID of the first worst process. |
| %{WORST_PROCESS_STATE} | State of the first worst process. |
| %{WORST_PROCESS_USERNAME} | Username of the first worst process. |
| %{WORST_PROCESSES} | List of worst processes, semicolon delimited, containing PID, process name, username, PPID, state and command line. |
| SNMP Polling | |
| %{CONTENT} | Value of the OID being polled. |
| %{OID} | SNMP OID being polled. |
| SNMP Polling macros | |
| %{CONTENT} | Content of the received trap. |
| %{ENTERPRISE_ID} | Enterprise ID (OID) of the SNMP traps being looked for. |
| %{FOUND_IP} | Actual originating IP address of the trap that has been received. |
| %{FOUND_TRAP_NUMBER} | Actual SNMP trap number that has been received and matches the entered criteria. |
| %{TRAP_NUMBER} | SNMP Trap numbers (specific numbers) being looked for. |
| String Search Macros | |
| %{LAST_MATCHING_LINE} | Last line that matches with the string search criteria. |
| %{LAST_MATCHING_LINES} | Last 10 lines that match with the string search criteria. |
| %{STRING1} | First regular expression being searched for. |
| %{STRING2} | Second regular expressions being searched for. |
| Template | |
| %{TEMPLATE_NAME} | Name of the Template related to the parameter triggering the alert. |
| %{TEMPLATE_CLASS} | Template's application class name. |
| %{TEMPLATE_COLLECTIONERRORS} | List of collection errors that occurred between the current collect and the previous one. |
| %{TEMPLATE_CONTACT} | Contact information in case of a Template failure. |
| %{TEMPLATE_DESCRIPTION} | Description of the Template as provided in the Web interface. |
| %{TEMPLATE_ID} | PATROL ID of the Template triggering the alert. |
| %{TEMPLATE_LABEL} | Display name of the Template triggering the alert. |
| %{TEMPLATE_TYPE} | Type of the Template triggering the alert (Template). |
| Value Map Macros | |
| %{RETAINED_VALUE} | Value retained by the collect and mapped to a status. |
| %{MAPPED_STATUS_INFORMATION} | Provides additional information about the status of the value mapping result, as reported by the Status Information parameter. |
| WBEM Query Macros | |
| %{NAMESPACE} | Namespace of the WBEM query. |
| %{QUERY} | WBEM statement sent for execution. |
| Web Request Macros | |
| %{HTTP_METHOD} | GET or POST depending on what was selected in the GUI. |
| %{URL} | URL being tested. |
| WMI Macros | |
| %{NAMESPACE} | Namespace of the WMI query. |
| %{QUERY} | WMI statement sent for execution. |
| Windows Event Macros | |
| %{CONTENT} | Message content of the last matching event. |
| %{EVENT_ID} | ID of the Windows events being searched for. |
| %{EVENT_LOG} | Name of the Windows event log being monitored. |
| %{MATCHING_EVENTS} | List of matching events. |
| %{PROVIDER} | Windows Event source whose new entries are monitored. |
| %{RECORD_NUMBER} | Last matching event record number. |
| Windows Performance Macros | |
| %{PERFORMANCE_COUNTER} | Windows performance counter being monitored. |
| %{PERFORMANCE_INSTANCE} | Windows performance object instances being monitored. |
| %{PERFORMANCE_OBJECT} | Windows performance object name being monitored. |
| Windows Service Macro | |
| %{SERVICE_NAME} | Name of the monitored Windows service. |
User-defined Macros
You can use any macro in any monitors as long as it is defined and used in the same Template. For example, if you declare a PATH macro in a Template, all the Monitors (typically File, Folder or Command Lines) in this Template can use this %{PATH} macro.
Escape Special Character in Macros
When using macros, you will probably need to make sure special characters are properly encoded. These are the format to use depending on the process you are using:
- %{SOURCE_ESC_REGEX}
- %{SOURCE_ESC_URL}
- %{SOURCE_ESC_PSLSTRING}
- %{SOURCE_ESC_JSON}
Here %{SOURCE} is any of the standard macro available for Monitors or Alert Messages listed above, except for:
- %{DATE}
- %{TIME}
- %{TIME:
<date-time-format>} - %{LASTTIME:
<date-time-format>} - %{FILE:
<filename>} - %{PASSWORD_BASE64}
- %{PASSWORD_JSON}
- %{PASSWORD_PSLENCRYPT}
- %{PASSWORD_URL}
For example, in a String Search you may want to search for the target host's IP address along with an error string as a regular expression. So, you may Search for Lines That:
[Ee]rror %{HOST_IPADDRESS_ESC_REGEX}
Similarly, an Alert Message triggered from a parameter may have to be JSON-ready. So you can use %{MESSAGE_ESC_JSON} in the custom alert message.
Date and Time Formats for Macros
These are the date and time formats available for %{TIME:…} and %{LASTTIME:…} macros for the Command Line, Folder and File Monitors as well as for all Alert Actions.
| Format | Description |
|---|---|
| %% | is replaced by a single % character. |
| %a | is replaced by the locale's abbreviated weekday name (Sun, Mon, Tue, Wed, Thu, Fri or Sat). |
| %A | is replaced by the locale's full weekday name (Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday). |
| %b | is replaced by the locale's abbreviated month name (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov or Dec). |
| %B | is replaced by the locale's full month name (January, February, March, April, May, June, July, August, September, October, November or December). |
| %c | is replaced by the locale's date and time representation (mm/dd/yy hh:mm:ss). |
| %C | is replaced by the century (a year divided by 100 and truncated to an integer) as a decimal number (00-99). |
| %d | is replaced by the day of the month as a decimal number (01-31). |
| %D | is equivalent to %m/%d/%y (mm/dd/yy). |
| %e | is replaced by the day of month as a decimal number (1-31); single digits are preceded by a blank. |
| %h | is replaced by the locale's abbreviated name of the month. |
| %H | is replaced by the hour (24-hour clock) as a decimal number (00-23). |
| %I | is replaced by the hour (12-hour clock) as a decimal number (01-12). |
| %j | is replaced by the day of the year as a decimal number (001-366). |
| %k | is replaced by the hour (24-hour clock) as a decimal number (0-23); single digits are preceded by a blank. |
| %l | is replaced by the hour (12-hour clock) as a decimal number (1-12); single digits are preceded by a blank. |
| %m | is replaced by the month as a decimal number (01-12). |
| %M | is replaced by the minute as a decimal number (00-59). |
| %n | is replaced by a newline. |
| %p | is replaced by locale's equivalent of AM (ante meridiem) or PM (post meridiem) as appropriate. |
| %r | is equivalent to %I:%M:%S %p (hh:mm:ss AM/PM). |
| %R | is equivalent to %H:%M (hh:mm). |
| %S | is replaced by the second as a decimal number (00-60). |
| %t | is replaced by a tab. |
| %T | is equivalent to %H:%M:%S (hh:mm:ss). |
| %u | is replaced by the weekday (Monday as the first day of the week) as a decimal number (1-7). |
| %U | is replaced by the week number of the year (the first Sunday as the first day of week 1) as a decimal number (00-53). |
| %V | is replaced by the week number of the year (the first Monday as the first day of week 1) as a decimal number (00-53). |
| %w | is replaced by the weekday (Sunday as the first day of the week) as a decimal number (0-6). |
| %W | is replaced by the week number of the year (the first Monday as the first day of week 1) as a decimal number (00-53). |
| %x | is replaced by the locale's date representation. In the default locale, it is equivalent to %m/%d/%y (mm/dd/yy). |
| %X | is replaced by the locale's time representation. In the default locale, it is equivalent to %H:%M:%S (hh:mm:ss). |
| %y | is replaced by the year without century as a decimal number (00-99). |
| %Y | is replaced by the year with century as a decimal number. |
| %Z | is replaced by the time zone name. |
| %Ec | is replaced by an alternative appropriate date and time representation . |
| %EC | is replaced by the name of the base year (period) in the locale's alternative representation. |
| %Ex | is replaced by the locale's alternative date representation. |
| %EX | is replaced by the locale's alternative time representation. |
| %Ey | is equivalent to the offset from %EC (year only) in the locale's alternative representation. |
| %EY | is replaced by the alternative representation of the year in full. |
| %Od | is replaced by the day of the month using the locale's alternative numeric symbols. |
| %Oe | is equivalent to %Od. |
| %OH | is replaced by the hour (24-hour clock) using the locale's alternative numeric symbols. |
| %OI | is replaced by the hour (12-hour clock) using the locale's alternative numeric symbols. |
| %Om | is replaced by the month using the locale's alternative numeric symbols. |
| %OM | is replaced by the minutes using the locale's alternative numeric symbols. |
| %OS | is replaced by the seconds using the locale's alternative numeric symbols. |
| %OU | is replaced by the week of the year (Sunday as the first day of the week) using the locale's alternative numeric symbols. |
| %Ow | is replaced by the day of week (Sunday=0) using the locale's alternative numeric symbols. |
| %OW | is replaced by the week of the year (Monday as the first day of the week) using the locale's alternative numeric symbols. |
| %Oy | is replaced by the year (offset from %C) in the locale's alternative representation and using the locale's alternative numeric symbols. |
Search Results for {{siteSearch | truncate:'50'}}
{{resultArray.length}}
No results.