Icon

Comments have been closed on this page. Please use AppMon & UEM Plugins forum for questions about this plugin.

Overview

 

The Generic Execution Plugin executes any configurable command or web service.
It can be used as a Monitor, Task or Action depending on if a measurement should be received, a task should be regularly performed or a command/web service should be executed in case of an incident.
If used as a monitor it matches the command's/web service's output against a regular expression and simply returns a success state if a match was found.

Name

Generic Execution Plugin

Description

New in Plugin for dynaTrace 4.1:
Arguments can be passed to the command. Argument placeholders are allowed to query the execution environment.

Monitors: {HOST} (with braces) represents the target host.
Actions: {AGENT}, {APPSRV}, {DTSERVER}, {MSG}, {MEASURES}, {PROFILE}, {SEVERITY}, {SOURCE}, {STATE} (0 Open, 1 Closed, 2 Opened then Closed), {START}, {END}, {DURATION}, {RULE}, {RULEDESC}

New in plugin version 5.5.0:

  1. Fixes plugin hanging bug
  2. Plugin allows now to execute commands remotely for Unix/AIX/Linux based servers. No need to have dynaTrace Collector deployed on the server where command should be executed.
  3. Includes functionality of the SSH Action plugin. It is recommended to use the Generic Execution plugin instead of the SSH Action plugin.
  4. Maintains 105 external variables that can be used by the command. It is the same list of maintained variables that is supported by the Extended Email Action plugin.
  5. Performs shell quoting for the special characters in the maintained external variables.
  6. Slight change in syntax of variables: instead of the old style {variable-name} plugin supports ${variable-name} syntax.
  7. Removed the Arguments parameter of the plugin. The Command parameter of the plugin now contains command’s arguments.
  8. Added Date Format parameter to format START_TIME and END_TIME variables. Default values is "yyyy/MM/dd-HH:mm.ss zzz". If Date Format is blank, the default locale format is used.

Below is information about maintained variables which are available when plugin is used as an action, monitor, or task.
Action: maintains 105 predefined variables which have the following syntax ${variable-name} (with dollar-sign and braces). The complete list of maintained variables is located here.
Monitor or Task: ${HOST} (with dollar-sign and braces) represents the target host, ${PORT} (with dollar-sign and braces) represents the target port

New in plugin versions 5.5.1 - 5.5.4:

  1. The Generic Execution plugin can execute any web service now.
  2. Added "Run Web Service?" parameter to the parameters list.
    1. When "Run Web Service?" parameter is set to "false", old Generic Execution parameters are displayed and command will be executed by Action, Monitor, or Task
    2. When "Run Web Service?" parameter is set to "true", parameters related to web service are displayed and web service will be executed by Action, Monitor, or Task
  3. Web Service parameters are shown in the screenshot below. WS WSDL, WS Operation, and WS Parameters are mandatory parameters.
  4. WS Parameter contains key/value pairs depicted on the screenshot below. They are used for substitution of keys with correspondent values. Values can contain any of 111 predefined variables from the list here. Predefined variables should be embedded in the value using the following format: ${variable-name}. Keys are names of simple data types of web service parameters which are passed in the SOAP message.
  5. Plugin recognizes complex and simple data types based on provided wsdl for web services
  6. Example of the SOAP message is attached below:
  7. In order for the plugin to work, please remove outdated jaxws-api.jar, jaxb-api.jar, jaxb-impl.jar, jaxb-xjc.jar, stax-ex.jar, and streambuffer.jar file from the <dt-home>/server/lib/endorsed directory. This should be done for dynaTrace 5.5 and lower.  

New in plugin version 5.5.5

Added "RC Measure" parameter which contains name of the dynamic measure associated with the return value from the executed command. User of the plugin now has ability to draw charts which contains meaningful information about returned values from the executed command. User of the plugin can setup incident rules using base returnCode measure. Incidents will be triggered when dynamic measure will violate at least one threshold which is set in the incident rules for the base measure.

New in plugin version 5.5.6

  1. Optional parameters of the web service which have no values will be skipped in the SOAP message hence making SOAP message shorter.
  2. Cosmetic changes in the plugin.xml file which simplify plugin configuration parameters screen.
  3. Added outputBufferSize parameter to handle size of the stdout and stderr streams. Default value is 2048 bytes.

New in plugin version 5.5.7

  1. Added support for JAX WS web services built with Apache Axis2 and CXF runtimes.  
  2. Added isDotNET parameter to handle .NET built SOAP web services. This parameter should be set to 'true" for .NET web services.
  3. Added "WS Use Prefix" parameter to indicate if prefixes will be used in the payload. When set to "true" prefixes will be added to the payload.

New in plugin version 5.5.7.1

  1. Minor release: added better diagnostics to the plugin.  

New in plugin version 5.5.8

  1. Added support for multiple return values from executed scripts as well as JSON scripts.
    Set the "Returned Measures" parameter with semicolon separated list of returned measures and make script return output record which starts with "***ReturnedMeasures:" and followed by the semicolon separated values in the same order that measures names are listed in the "Returned Measures" parameter.
  2. com.dynatrace.diagnostics.plugin.extended.GenericExecutionPlugin_5.5.8.jar
  3. For details of calling web services from the GE plugin please see the following document.
New in plugin version 5.5.9
  1. Added ability to use regular non-dynamic measures for returned from the command values. In order to use this feature user needs to create a Metric Group Monitor plugin as it is described here and deploy it together with the Generic Execution plugin. Used by the plugin measure names should be unique across multiple metric groups. 
    1. Example of a metric group plugin is here
    2. Example of the script which is executed by the plugin is here.
  2. https://github.com/dynaTrace/Dynatrace-Generic-Execution-Plugin/releases/download/v5.5.9/com.dynatrace.diagnostics.plugin.extended.GenericExecutionPlugin_5.5.9.jar 

This version of the plugin is backward compatible with all previous 5.5.x versions.

New in plugin version 5.5.10

Fixes issue associated with loosing SSH connection over the lifetime of the plugin. 

New in plugin version 5.5.11

Allows to parse multi line output for remote executions

New in plugin version 5.5.13

Added timeout parameter to interrupt scripts which are executed locally. Default timeout is 60 seconds.

New in plugin version 5.5.14
  1. For SOAP Web services added ability to gather returned measures from the SOAP output messages. Names of returned measures and their values are taken from the output message description in the web service WSDL file (see example here). The GE plugin populates these dynamic measures with values taken from the output SOAP message (see example here). In order to get returned measures populated by the plugin, the isWSReturnedMeasures configuration parameter needs to be checked (see example here).
  2. Bug fixes.
New in plugin version 5.5.15
  1. Improved logging for the web services 
New in plugin version 5.5.16
  1. Fixed issue when web service has no input parts;
  2. Improved integration with .NET web services.
New in plugin version 5.5.17
  1. Added new parameter 'isEscapeChars': when true (default) it will escape special characters in supported by the plugin 150+ runtime variables, otherwise runtime variables will be substituted as is in the command. Previous versions of the plugin acted as if the 'isEscapeChars' parameter equals true.
New in plugin version 5.5.18
  1. Added use of the XPath style naming convention for the Web Services parameters:
    1. New parameter 'isXPathSyntax' is setting up style of the parameter-name and parameter-value pairs. If it is 'true' (the default value) then XPath style naming convention is used. Otherwise old style naming convention is used. It is strongly recommended using XPath style naming convention. The old style naming convention is left for compatibility reasons.
    2. Example of the XPath style naming convention is depicted here:


      Corresponded WSDL file where XPath nodes were taking from is here:
    3. Old style naming convention (see example here) has been deprecated. We are supporting it for backward compatibility only. For new configurations please use XPath style naming convention.
  2. Added authentication mechanism for web services calls. The following new authentication parameters need to be setup if authentication is required:
    1. 'Is Authentication Required' needs to be set to 'true';
    2. WS User
    3. WS Password
    4. 'WS Authentication Method' selects authentication method. For this release it is Basic only.

The following screenshot depicts use of new authentication parameters:
 

 

New in plugin version 5.5.19

Added the ${START_TIME} variable to the list of maintained by the Generic Execution plugin variables when it is configured as monitor or task. The ${START_TIME} variable contains timestamp when monitor or task was triggered by its scheduler. Complete list of maintained by the plugin variables when it is monitor or task is: ${HOST}, ${PORT}, and ${START_TIME}.

New in plugin version 5.5.20
  • Added ability to trigger incident when the STDERR stream of the executed by the plugin command is not empty. 
    • If the 'Trigger Incident' indicator is set to 'true' and the STDERR stream is not empty plugin will trigger an incident described by the 'Incident Rule Name' parameter with the message content that is equals to the content of the STDERR stream.
    • If the Extended Mail Action plugin is set as an action for the incident rule that is set in the 'Incident Rule Name' parameter then notification e-mail will be sent when the GE plugin will execute command which has non-empty STDERR stream. The ${MESSAGE} variable, which is maintained by the Extended Mail Action plugin, will have content of the STDERR stream.
    • The following screenshot contains new configuration parameters which are used when incident needs to be triggered:

 

    • If right click on the incident instance in the Incidents dashlet and chose ‘Details...’, the following popup screen will appear:

In this example, the description field of the incident contains information about creator of this incident, i.e. in our case it is the GE plugin, time stamp when incident was created, and executed command. Content of the STDERR stream will be displayed above under the Custom Events header.

    • This feature is supported in the following Dynatrace environments:
      • Dynatrace 6.1.0.8305 and higher.
      • Dynatrace 6.2.0.1239 and higher.
      • In order to use this feature the following line needs to be added to the <DT-HOME>/server.ini file (see screenshot below):
        • -Dcom.dynatrace.diagnostics.triggerActionWithIncident=true

 

In order for this change to take effect the Dynatrace server needs to be re-cycled.

    • This feature is implemented only when command is executed locally by the GE plugin. This limitation will be removed shortly.
New in plugin version 5.5.21
  • Added new configuration parameter 'WS Target Timezone' that sets a timezone that time data will be converted to from a current timezone. Please see this Excel spreadsheet for the list of available time zones.
  • Improved integration with the .NET SOAP web services;
  • Integration with the new infrastructure alerts.
New in plugin version 5.5.22
  • Added compatibility with older plugin releases.
New in plugin version 5.5.23
  • Fixed index out of bounds exception.
New in plugin version 5.5.24
  • Fixed messages for measures with different units.
New in plugin version 5.5.25
  • Fixed issue related to VIOLATION_HEADER fields.
New in plugin version 5.5.27
  • Enabled use of Success Definition for web services;
  • Now output can be captured for web services.
New in plugin version 5.5.28
  • Improved compatibility between Axis based and .NET based SOAP web services.
New in plugin version 5.5.29 
  • The 'Returned Measures' parameter is now multi-line.
New in plugin version 5.5.30 
  • Added support for the following runtime variables:
    • APPLICATION_ALL,
    • VIOLATED_MEASURE_NAME_ALL,
    • VIOLATED_MEASURE_DESCRIPTION_ALL,
    • VIOLATED_MEASURE_VALUE_ALL,
    • VIOLATED_MEASURE_UNIT_ALL,
    • VIOLATED_MEASURE_SPLITTINGS_ALL,
    • VIOLATED_MEASURE_TRESHOLD_UPPER_SEVERE_ALL,
    • VIOLATED_MEASURE_TRESHOLD_LOWER_SEVERE_ALL,
    • VIOLATED_MEASURE_TRESHOLD_UPPER_WARNING_ALL,
    • VIOLATED_MEASURE_TRESHOLD_LOWER_WARNING_ALL,
    • VIOLATED_MEASURE_METRIC_NAME_ALL,
    • VIOLATED_MEASURE_METRIC_DESCRIPTION_ALL,
    • VIOLATED_MEASURE_METRIC_GROUP_ALL,
    • VIOLATED_MEASURE_METRIC_UNIT_ALL,
    • VIOLATED_TRIGGER_VALUE_SOURCE_TYPE_ALL,
    • VIOLATED_TRIGGER_VALUE_SOURCE_NAME_ALL,
    • VIOLATED_TRIGGER_VALUE_SOURCE_HOST_ALL,
    • VIOLATED_TRIGGER_VALUE_ALL.
New in plugin version 5.5.32 
  • Added new ${DYNATRACE_INCIDENTS} runtime variable which represents array of DT incidents and their subsequent violations with triggered values in JSON format. For details, please see next screenshots and correspondent files example-1-json-output.log and example-2-json-output.log:

New in plugin version 5.5.34

  • Fixed issue with Host Name to IP Address Translation.

New in plugin version 5.5.35

  • Added ability of using multiple lines to set executed by the plugin command. This feature works only when the GE plugin executes command locally. The multi-line command field allows to avoid use of single or double quotes for the command arguments which contain white spaces.
    The 'isMultiline' parameter handles the new field. The new field name is the 'Command Multiline'. When the 'isMultiline' parameter is set to 'true' the 'Command Multiline' field is used and content of the 'Command' field is ignored. If the 'isMultiline' parameter is 'false' then the original single line 'Command' field is used.
    Multi-line command field contains single argument per line, i.e. very first line of this field contains executed command, while other lines contain arguments of this command.

New in plugin version 5.5.36

  • Added new predefined runtime variables PURE_PATH_N, where N = 1, 2, 3, 4, 5, ... up to 100. The ${DYNATRACE_INCEDENTS} runtime variable contains full list of the affected PurePaths.

Plug-In Version

5.5.36

 

Compatible with

dynaTrace >= 6.1

Author

Ardeshir Arfaian (ardeshir.arfaian@dynatrace.com), Rob Vollum (rob.vollum@dynatrace.com),
Eugene Turetsky (eugene.turetsky@dynatrace.com) versions 5.5.0+

License

dynaTrace BSD

Support

Not Supported

Downloads

Download plug-in

Generic Execution Plugin v5.5.36 

Key benefits

  • Generic use case scenarios: Execute any web service or shell command.
  • The plugin is very flexible. Can be used as a monitor, task or/and action.
  • Easy customizable to fit to your needs.
  • Integrates with dynaTrace 3+, centrally deploy to globally distributed collectors
  • Open Source: adapt the Generic Execution Plugin to your needs

Key features

  • execute any web service or command
  • configurable as monitor, task or action (in case of an incident)
  • ability to recognize simple and complex data types for web services
  • automatic generation of SOAP messages based on wsdl file for web services
  • pass multiple arguments to command
  • regex match on command's output
  • set timeout for command
  • configurable success condition: match / no match is success
  • chartable success state
  • alerting on success state
  • OS independent
  • depending on settings captures no/last 2048/first 2048 chars of command output

Limitations
  • plugin does not take care of hanging process/child processes

  • no limitations/checks about what command is started and the consequences of this command

Technical overview

  • JAX-WS software stack
  • OS independent

Install Description

  1. Open dynaTrace Server preferences (right click on dynaTrace Server Node in cockpit and then select preferences from context menu).
  2. Import Generic Execution Plugin
  3. Activate Generic Execution Plugin in dynaTrace Server preferences.
  4. Adapt server-wide plug-in properties

    In the server-wide plug-in properties (dynaTrace Server preferences >> Plug-ins) you can edit the default values and set the state. Every newly added Generic Execution Plugin will receive these default values. You can choose between "Edit", "Read" or "Hidden", so the default Settings can be edited, read-only or are not visible in the individual Generic Execution Plugin settings.

Setup Monitor / Task

  1. How to create a Generic Execution Monitor / Generic Execution Task
    1. Open System Profile >> Preferences
    2. Choose "Monitors" or "Tasks" from the configuration panel (Property Navigation)
    3. Choose Add...
    4. Choose Generic Execution Monitor / Task from available Types
    5. Rename your Generic Execution Monitor / Task and adapt description
    6. Confirm.
  2. How to schedule a Generic Execution Monitor / Generic Execution Task
    1. Open System Profile >> Preferences
    2. Choose "Monitors" or "Tasks" from the configuration panel (Property Navigation)
    3. Select the Monitor/Task you wish to edit and click "Edit..." button
    4. Preferences dialog opens.
    5. Select a predefined schedule or create your own schedule if none fits.
    6. Confirm.
  3. How to configure a Generic Execution Monitor / Generic Execution Task
    1. Open System Profile >> Preferences
    2. Choose "Monitors" or "Tasks" from the configuration panel (Property Navigation)
    3. Select the Monitor/Task you wish to edit and click "Edit.." button
    4. Select the "Settings" tab
    5. You can now configure:
      1. Command - The command to execute.
      2. Arguments - Argument(s) which should be passed to command.
      3. Regular Expression - The regular expression the command's output should be matched against.
      4. Capture Output - Defines if the output of the executed command should be captured and returned as message.
      5. Success Definition - Defines condition under which monitor returns success: if regular expression matches or not.
  4. How to centrally deploy a Generic Execution Monitor to different global locations


    In general monitors always run on dynaTrace Collectors. Like presented in the previous screenshot you can decide centrally from your dynaTrace Client (in the monitor's settings) on which Collector a specific Monitor Task should run on.

    Note: Tasks are always executed on the server, Monitors are executed on a collector.

  5. How to test, run, suspend a Generic Execution Monitor / Generic Execution Task

Setup Action

Please see "Actions" in How to Setup Alerting (dynaTrace 3.0 documentation)

Usage

Restart IIS


 


Ping a network address


Click to enlarge result:
 

 
List running windows services

 
 


Start/Stop a windows service

Known Problems

none

 

Contribution

Feel free to contribute any changes on Github

Comments

Please post comments in AppMon & UEM Plugins

Looking for old comments? Find them here (this page is loading very slow!)