Using G2 custom monitors, you can build and manage independent monitoring solutions without relying on the platform. Remote Script Executor executes shell, PowerShell, and Python scripts on Linux and Windows workstations.

Key features include:

  • User-defined external arguments support the script through custom attributes.
  • Monitor level script execution: Ability to pull more metrics in a single script execution.
  • Ability to execute different types of scripts through custom script options apart from default options.
  • Ability to use credentials attached to the device in the script using the dynamic macro support.

Constraint:

Windows workstation monitoring using a Linux Gateway is not supported.

Step 1: Create Metrics

Define metrics metadata that correlates with your script output and matches the monitor you define in the next step.

  1. Select a client from the All Clients list.
  2. Go to Setup > Monitoring > Metrics.
  3. From METRICS, click + Add.
  4. From Create Metric, enter the values for the fields described in the following tables and click Save.

Metric specification

FieldDescription
Metric Scope(required) Partner- or client-specific metric specification:
  • Partner Metric Metric has partner scope.
  • Client Specific Metric Metric has client scope.
Adaptor Type(required) Application. Select from the supported agent or gateway adapters.
Name(required) Unique metric name. The recommended naming convention is: ___. For example, apache_tomcat_webapps_count.
Tag NameUser-defined tags for filtering.
Display Name(required) Name to display, such as **System Drive Free Space**.
DescriptionDescription of the metric.
Data Point type(required) Type of data point specification:
  • Counter Delta - It calculates delta on top of metric value. If the result is less than zero then it returns zero

    Counter Delta = (Current poll value - Prev poll value)
  • Counter Rate - It calculates rate on top of metric value. If the result is less than zero then it returns zero.

    Counter Rate = (Current poll value - Prev poll value) / (Current poll time - Prev poll time)
  • Derive Delta - Not related to RSE. No support in both agent and gateway.
  • Derive Rate - Not related to RSE. No support in both agent and gateway
  • Gauge - It returns a direct metric value, which is returning from the script.
  • Rate - It calculates rate on top of metric value. If the result is less than zero then it returns a negative value.

    Rate = (Current poll value - Prev poll value) / (Current poll time - Prev poll time)
  • Delta - It calculates delta on top of metric value. If the result is less than zero then it returns a negative value.

    Delta = (Current poll value - Prev poll value)
  • None - Same as Gauge
UnitsMetric unit specification associated with the data point type. Click the drop-down menu to select from the available units.
Unit Multiplication FactorFactor to multiply the data point value by.
Datapoint value conversionDatapoint value conversion specification:
  • Value Populate metric using datapoint value.
  • Enumerated Map Map the datapoint to a state-description pair:
    • State Descriptions
      Click the plus icon to add state-description pairs for each datapoint value:
      • State State represented by the value.
      • Description Description associated with the state.
    • Use formatted value in: Render the value in an Alert or Graph.
Metric ProcessingMetric processing specification:
  • Graph
  • Notification
  • Graph and Notification
  • None
When selecting Notification or Graph and Notification, enter the following additional metric processing specification:
  • Warning if value Conditions where the metric value represents a warning status.
  • Critical if value Conditions where the metric value represents a critical status.
  • Subject Metric attributes to display as the alert subject.1
  • Description Metric attributes to display as the alert description.1

[1] See the Metric token reference for a list of the tokens that can be used in the Subject and Description fields.

Step 2: Create a Monitor

A custom Remote Script Executor monitor is a collection of Remote Script Executor metrics. You can create a template based on the Remote Script Executor monitor.

Macros are used to pass dynamic arguments to scripts. Use the static and dynamic macros listed in the following tables to make native and custom attributes available to the monitor.

You must create metrics in Step 1: Create metrics before creating a monitor.

  1. Select a client from the All Clients list.
  2. Go to Setup > Monitoring > Monitors
  3. Click + Create New.
  4. On the CREATE A MONITOR page, enter the fields listed in the following table and click Save. The newly created monitor is added to the list of monitors.

Monitor specification

MethodDescription
Monitor Scope(required) Partner- or client-specific monitor specification:
  • Partner Monitor Monitor has partner scope.
  • Client Specific Monitor Monitor has client scope.
Adapter Type(required) Application. Select from the supported agent or gateway adapters.
Name(required) Unique monitor name.
Description(required) Description of the monitor
Metrics(required) Click +Add to add metrics. Search for the previously defined metrics and click Add Metrics.
Configuration ParametersClick +Add to add configuration parameters. Search for the parameter and click Add to add it to the monitor:
  • Using available configuration parameters, you can specify the scripting language type and the platform to execute the script.
  • If you select the **Custom** value in configuration parameters, add the parameter: `custom.script.execution.path`.

Static macros

Use static macros to override the resource values. See the Static macro reference for a list of static macros.

Dynamic macros

MacroDescription
${customattributes.serviceName}Get custom attributes of the device - If you want to use an argument in any script, apply the custom attributes on the device.

For an example, you have a custom attribute on the device with `Key: serviceName` and `Value: oracledb`. During runtime, the Value: oracledb replaces the macro: `${customattributes.serviceName}` in the script.
${credentials.CredentialName.credentialField}Get the credentials added to the device - You can use (macros) credentials in the script to avoid storing the original username and password in plain text. When you run the script, the macros replace the original credentials.

For an example, if you define a credential set with a name JMXCred and added it to a device. You can use the macro ${credentials.JMXCred.username} in your script and macro will replace the original credentials in your script at runtime.
${credential.type.all}Use this macro to get all credential sets (assigned on the device) into the script.
${credential.type.name}Use this MACRO( ${credential.type.name}) to get specific credentials in the script.

For an example, If the device has SSH, WMI and Database credentials and if user want to get only database credentails inside the script then need to use ${credential.type.database} inside the script. Similarly user can get any type of credentails into the script by replacing .name with the credentails type.
Example: ${credential.type.SSH}, ${credential.type.SNMP}, ${credential.type.VMWARE} etc.

Below are the supported credential types:

Credential TypesMarcosSample Output
VMWARE${credential.type.VMWARE}
[{
"uuid":"xB35mBgN354UGM3zQFZBQSaJ",
"type":"VMWARE",
"name":"sample-vmware",
"timeoutMs":10000,
"transportType":"HTTPS",
"appName":null,
"domain":null,
"username":"testuser",
"password":"xxxxxx",
"port":443
}]
SSH${credential.type.SSH}
[{
"uuid": "NwKGzg6qqSF29Sdy5hRJrAyH",
"type": "SSH",
"name": "sample-ssh",
"timeoutMs": 10000,
"transportType": "HTTP",
"appName": null,
"userName": "testuser",
"password": "xxxxxx",
"port": 22,
"privkey": null,
"passPhrasePasswd": null,
"privKeyFileName": null,
"sshAuthType": "PASSWORD"
    }]

The following are the remaining credential types:
SNMP, XEN, WINDOWS, JMX, HTTP, Database, CIM, NETAPP, NETAPPCLUSTER, HYPERFLEX, PURESTORAGE, FTP, CISCOUCS, EMCCLARIION, EMCVNX, EMCVNXE, EMCVMAX, IBM, HPEVA, REMOTE_CLI, TELNET, XTREMIO, VIPTELA, EMCVPLEX, EMCRPA, NUTANIX, HITACHIVSP, AZURESTACK, APPLICATION, and CITRIX_CVDA.

Script execution path for configuration parameters in Linux and Windows

The following runtime executables should be available in your Path variable for the corresponding operating system.

Script TypeLinuxWindows
BashbashNot Applicable
ShellshNot Applicable
PowershellNot Applicablepowershell.exe
Pythonpythonpython.exe
PerlPerlNot Applicable

If your runtime is not set as an environment variable, provide the runtime absolute path in custom.script.execution.path. For example, if python is not set, set custom.script.execution.path to /usr/lib/python.

Step 3: Create a Template

A template is an instance of a monitor and is applied to devices.

  1. Select a client from the All Clients list.
  2. Go to Setup > Monitoring >Templates.
  3. From Templates, click + Add.
  4. From MONITOR TEMPLATE, provide details for the following parameters and click Save.
MethodDescription
Select Template Scope(required) Partner- or client-specific monitor specification:
  • Partner Monitor Monitor has partner scope.
  • Client Specific Monitor Monitor has client scope.
Collector TypeSelect Agent
Monitor TypeSelect G2 Monitors
Applicable forSelect Device
Template NameName of the template
DescriptionSummary of the template
GenerationGeneration that the template belongs to
TagsUser-defined tags for filtering
PrerequisitesEssential things to consider when using this template
StatusActive or end-of-life template
NotesInformation that you want to add to the template
Template Family NameCategory that applies to the application, such as Windows Server, Storage Server, or Network Server
Deployment TypeOne of the following methods to use to apply the template to the resource:
  • Custom
  • Optional
  • Standard

After adding the template, add component thresholds and component filters by editing metric values. For more information, see Add Filter, Component Filters and Define Threshold

Step 4: Assign a Template

  1. From the left pane, click Infrastructure. The Infrastructure screen of the selected client is displayed.
  2. From the Resources tab, select the required resource from the list of resources. Or, use the search option to find the resource.
  3. Click the resource name to view details.
  4. From the left pane, click Monitors.
  5. From the Templates tab, click +Assign Templates.
  6. From Apply Templates, select the templates.
    The selected Templates section displays the chosen templates.
  7. Click Assign. The template gets assigned to the selected device.

After assigning the template to a resource for monitoring, click Get Latest Metric Values to view the latest metric information.

Step 5: View Graphs

The Agent monitors the system using the assigned templates and displays the results in a graphical format.

  1. From the left pane, click Infrastructure.
  2. From the Resources tab, select the required resource from the list of resources. Or, use the search option to find the resource.
  3. Click the resource name to view details.
  4. From the left pane, click Metrics. The Metrics page displays graphs generated by all monitoring templates assigned to a device.
  5. Search with the template name to filter the graphs.

Scripts Folder and Permissions

By default, all the Remote Script Executor (RSE) custom monitor scripts are downloaded to a predefined location in your system. The system user (Windows) and Root/Non-Root User (Linux) hold all the required permissions (Read, Write, and Execute) in the downloaded folders.

The following table provides the default folder locations and users for Windows and Linux:

Operating SystemDefault Folder LocationDefault User
Windows
  • 32 bit – %programfiles%\OpsRamp\Agent\plugins\rse
  • 64 bit – %programfiles(x86)%\OpsRamp\Agent\plugins\rse
System User
Linux/opt/opsramp/agent/plugins/rseRoot/Non-Root User
  • Default permission set for all executable files in this folder is 744.
  • Default permission set for other files in this folder is 644.

Script File Integrity Check

OpsRamp will verify for the custom script for file integrity and ensure that the file checksum remains the same before performing the monitor script execution. If the G2 based custom monitor script on the resource is changed, OpsRamp will redownload the original monitor script from the source for security reasons and continue the monitoring.

During this process, a critical alert about the “File checksum mismatch” will be generated on the resource, and users will be notified about the script modification on the resource.

Remote Script Executor example

Script

#!/bin/bash

CPU=$(top -bn1 | grep load | awk ‘{printf "%.2f\t\t\n", $(NF-2)}’)
MEMORY=$(free -m | awk ‘NR==2{printf "%.2f\t\t", $3*100/$2 }’)
DISK=`df -h | awk ‘$NF=="/"{ print $5}’ | sed ‘s/%//g’`

printf "{\"disk.utilization\" : %s , \"memory.utilization\" : %s , \"cpu.usage\" : %s}" "$DISK" "$MEMORY" "$CPU"

Output :

{"disk.utilization" : 23 , "memory.utilization" : 24.28 , "cpu.usage" : 0.64 }

Standard JSON output format

Format 1
{
"Metric1": 98,
"Metric2": 70,
"Metric3": 80
}
Format 2
{
"Metric1": 98,
"Metric2": "STATE",
"Metric3": 80
}
}
Format 3
{
    "MetricName1": {
        "components": {
            "component1": 70,
            "component2": 98
        }
    },
    "MetricName2": {
        "components": {
            "component1": 77,
            "component2": 98
        }
    }
}
Format 4
alertTokens: Using alertTokens, you can add more information to the alert Subject and Description.

{
    "MetricName1": {
        "components": {
            "component1": "STATE",
            "component2": 98
        },
        "alertTokens": {
            "token1": "value",
            "token2": "value2"
        }
    },
    "MetricName2": {
        "components": {
            "component1": 77,
            "component2": 98
        },
        "alertTokens": {
            "token1": "value",
            "token2": "value2"
        }
    }
}
Format 5

{
    "MetricName1": 254,
    "MetricName2": {
        "components": {
            "comp1": 90,
            "comp2": 60
        }
    },
    "MetricName3": {
        "components": {
            "component1": "STATE",
            "component2": 98
        },
        "alertTokens": {
            "token1": "value",
            "token2": "value2"
        }
    }
}
Format 6
component level alertTokens: We can specify alertToken value for each component separately as mentioned for metricName4
Note: This format supports from Agent V12 and above

{
    "MetricName1": 254,
    "MetricName2": {
        "components": {
            "comp1": 90,
            "comp2": 60
        }
    },
    "MetricName3": {
        "components": {
            "component1": "STATE",
            "component2": 98
        },
        "alertTokens": {
            "token1": "value",
            "token2": "value2"
        }
    },
     "MetricName4": {
        "components": {
            "component1": 10,
            "component2": 20
        },
        "alertTokens": {
            "token1": { 
		        "component1": "comp1 token1 value", 
		        "component2": "comp2 token1 value" 
		        },
            "token2": { 
		        "component1": "comp1 token2 value",
		        "component2": "comp2 token2 value" 
		        }
        }
    }
}

Multiple Custom Script Arguments in Macro

Refer the document Multiple Custom Script Arguments for more details.

Generate Alert Tokens in RSE

Refer the document Generate Alert Tokens in RSE for more details.

Next Steps