Developing a user plugin

Overview

The Plugin Development Environment (PDE) enables you to create bundle specifications for AppMon Plugins: a valid manifest file, a valid plugin.xml file, source file skeletons, and optional libraries, resource files, and bundle dependencies. You also use the PDE to compile and build a Plugin, test it on a connected AppMon Server or Collector, and to deploy it to a Server.

The PDE does not provide an IDE for developing and debugging Plugin source code. You can use your preferred IDE for development. A .project file for Eclipse is generated automatically. See Best Practices and Examples) for details.

OSGi and Eclipse extensions mechanism

AppMon architecture is based on OSGi bundles that use the Eclipse Extensions Mechanism. All Plugins created by the PDE are also bundles of those types. The Eclipse Extensions Mechanism enables you to define Extension Points and Extensions. Extension Points define the interfaces that an application or component provides/ An Extension defines a specific implementation for a specific Extension Point.

The AppMon Plugin architecture provides an Extension Point for defining the configuration parameters of a Plugin, and an Extension Point for the Plugin types Action, Monitor, Task, Agent Metric Group, and Monitor Metric Group. These Extension Points enable you to share an Extension that defines the Plugin configuration among different Plugin types. For example, a configuration Extension for a web service, containing a URI and a set of parameters, can be used by a Monitor that collects performance data for a web service and by an Action that uses a web service to post incident data.

The example Plugin.xml code, below, shows the relations between different Extensions.

The example includes:

  • A Plugin configuration Extension named Signal Generator.
  • A Monitor Extension named Signal Generator Monitor, which uses the Signal Generator configuration because its configId points to the id of the Signal Generator extension.
  • A Monitor Metric Group Extension named Signal Generator Metric Group, for the Monitor Extension Signal Generator Monitor because its monitorId points to the id of the extension Signal Generator Monitor.
<extension point="com.dynatrace.diagnostics.pdk.pluginconfig"
   id="com.dynatrace.diagnostics.plugins.SignalGenerator"
   name="Signal Generator">
	<!-- Definition of configuration parameters -->

</extension>
<extension point="com.dynatrace.diagnostics.pdk.monitor"
   id="com.dynatrace.diagnostics.plugins.SignalGeneratorMonitor"
   name="Signal Generator Monitor">
  <plugin class="sg.SignalGenerator" configid="com.dynatrace.diagnostics.plugins.SignalGenerator" />
 </extension>
 <extension point="com.dynatrace.diagnostics.pdk.monitormetricgroup"
   id="com.dynatrace.diagnostics.plugins.SignalGeneratorMonitorMetricGroup"
   name="Signal Generator Metric Group">
	<metricgroup monitorid="com.dynatrace.diagnostics.plugins.SignalGeneratorMonitor" >
		<!-- Definition of monitor metric group -->

	</metricgroup>
</extension>

Reuse, extend, or develop from scratch?

Before starting to develop a new Plugin, it is always useful to check whether a Plugin that does the job is already available, or an existing Plugin can be altered or extended to fulfill the new requirements. Check the Plugins provided with the AppMon installation, and the Community Downloads Overview. If you find a candidate for alteration or extension among the already installed Plugins, check it out to a folder and revise it. If you find a candidate in the Community, download and extract it to a folder, and add the extracted Plugin to the Plugin development projects. Detailed information about these tasks is provided below.

Note

Some Plugins may not contain source code, because of licensing restrictions. In this case, appropriate source skeletons are created on checkout. These skeletons implement all required interfaces, but do not contain functionality.

If no adequate candidate can be found, create a new Plugin project.

After you complete your work on a Plugin is finished, consider sharing it with the Dynatrace Community. See the Community Downloads Overview for detailed information about how to share your Plugins.

Using the plugin development tab

Develop new Plugins and revise Plugins through the Plugin Development tab of the Dynatrace Server Settings dialog box. To display this tab, select Tools > Manage Plugins in the AppMon Client, then select the tab.

Plugin Development Tab
Plugin Development Tab

The tab displays the following information about each listed Plugin:

  • Plugin: The name of the configuration Extension of the bundle, for example Signal Generator.
  • Types: The names of all Action, Monitor, and Task Extensions of the bundle, for example Signal Generator Monitor.
  • Status: Information about the current state of the Plugin. The status loading failed indicates that the structure of the Plugin files or directories is invalid. You must correct this problem manually with a text editor or File Manager.
  • Path: Displays the root path of the Plugin project in the file system.

You can perform the actions listed in the table below through the Plugin Development tab.

Actions marked with an asterisk ( * ) are performed immediately, and cannot be undone by clicking Cancel.

Action Description
New* Open the Plugin wizard to create a new Plugin.
Open Add an existing Plugin to the list by choosing the directory that contains the extracted Plugin.
Edit* Open the Edit Plugin wizard to change the configuration of the selected Plugin.
Delete* Remove the Plugin from the list, and optionally delete the directory that contains the Plugin files.
Build* Compile and package the Plugin into a single JAR file. This action cleans the build directory and downloads all dependent JAR files to the Client's temp directory. Hidden files are excluded from the build.
Test Test the Plugin on the AppMon Server.
Deploy* Install the built and tested Plugin on the AppMon Server.

To use the Build, Test, and Deploy actions, the Client must be connected to an AppMon Server. All other actions can be performed while the Client is not connected.

Using the New Plugin wizard

Use the New Plugin Wizard to create new Plugin projects, as well as to edit existing Plugin projects.

New Plugins are created automatically in the PDE base folder. You can specify the base folder either the first time you create a Plugin or in the Directories pane of the Client Preferences dialog box.

When you create a new Plugin project, the New Plugin Wizard generates a new Java class skeleton that implements the required interfaces, depending on the selected Plugin type(s): Action, Task, Monitor, or a combination of these.

General configuration

In the first screen of the New Plugin Wizard, select the Plugin type(s):

  • Metric Group Plug In
  • Monitor/Task/Action Plug In: If you select this type, you must also select Task, Action, Monitor, or a combination of these before you can continue.

After the Plugin is created, its type cannot be changed.

New Plugin wizard - general configuration
New Plugin wizard - general configuration

General configuration - metric group

When you select Metric Group Plug In as the Plugin type and click Next, the New Plugin Wizard displays configuration options for this type, with default entries in the fields. Replace these defaults with the information for your Plugin:

  • OSGi ID: A unique identifier for the Plugin's JAR file. Usually the ID is a lowercase, dot-separated string that starts with com or org followed by the company's or organization's short name and the project name. It must not contain special characters like quotes ( " ) or parentheses.
  • Identifier: A descriptive name for the Plugin.
  • Display Name: The name of the Plugin shown in Server Preferences.
  • Version: The version of the Plugin, which can have four components: major, minor, and micro version and a qualifier string. The qualifier string may be, for example, a build number. At least the major version needs to be specified.
  • Provider: The full name of the company or organization that provides this Plugin.
  • Description: Optional text that describes the Plugin.
  • Metric Group type: Select the subtype of this Metric group:
    • An Agent Metric Group defines metrics that are provided directly by the AppMon Agent.
    • A Monitor Metric Group defines additional metrics for an existing Monitor with a known ID.
  • Monitor id : This field becomes available when you select Monitor Metric Group. Enter the identifier of an existing monitor. Use the browse button to pick a Monitor that is currently installed on the server.
General Configuration - Metric Group
General Configuration - Metric Group

General configuration - monitor/task/action plugin

When you select Monitor/Task/Action Plug In as the Plugin type and click Next, the New Plugin Wizard displays configuration options for this type, with default entries in the fields. Replace these defaults with the information for your Plugin:

  • OSGi ID: A unique identifier for the Plugin's JAR file. Usually the ID is a lowercase, dot-separated string that starts with com or org followed by the company's or organization's short name and the project name. It must not contain special characters like quotes ( " ) or parentheses.
  • Identifier: A descriptive name for the Plugin.
  • Display Name: The name of the Plugin shown in the Server Preferences.
  • Version: The version of the Plugin, which can have four components: major, minor, and micro version and a qualifier string. The qualifier string may be, for example, a build number. At least the major version needs to be specified.
  • Provider: The full name of the company or organization that provides this Plugin.
  • Description: Optional text that describes the Plugin.
  • Libraries: A list of libraries packaged with the Plugin. Only JAR files can be added as libraries. The files are copied to the lib subdirectory of the Plugin and are added to the build classpath.
  • Files: A list of resource files packaged with the Plugin. You can add any file here as needed. The files are copied to the res subdirectory of the Plugin.
  • Dependencies: if the Plugin requires other OSGi bundles to work, add them as dependencies. For an AppMon Plugin, you must set com.dynatrace.diagnostics.sdk as a dependency; it is entered in the field by default.

The Please select a dependency dialog box that appears when you click Add has a filter at the top. To display only objects that begin with a specific string, type that string in the filter. Use a wildcard to filter for objects that have the string anywhere in the name. For example, typing \*ja in the filter includes com.dynatrace.diagnostics.javascript_6.0.0.6620 and javax.servlet_2.5.0.v201103041518 in the filtered list.

General configuration - monitor/task/action
General configuration - monitor/task/action

Configure plugin properties

This screen only appears when you have selected Monitor/Task/Action as the Plugin type. The configuration properties are Plugin configuration items of arbitrary size.

Configure Plugin Properties
Configure Plugin Properties

Click Add to create a new property. Define the properties of the Plugin and set the default values.

  • Name: The label for the property that displays in the configuration dialog boxes.
  • Key: A unique identifier for the property. It is used to retrieve the property value from the Plugin source code.
  • Description: Optional text that describes the property.
  • Type: The data type of the property. Supported types are:
    • String
    • Password
    • Boolean
    • Long: Integer numeric values
    • Double: Floating-point numeric values
    • Date
    • List: Set of predefined selectable strings
    • URL
  • Default value: The default value for this Plugin. This default can be overridden in the Server Settings dialog box (see Plugin Management). When you select List as the property type, the Default field becomes a table in which you can type the strings; select a radio button in the Default column to specify which string is the default value.
Configure Property Details
Configure Property Details

You can control the visibility of Plugin properties based on the values of other properties. For example, the Boolean property Authentication controls the visibility of a String property User and a Password property Password so that User and Password are only visible if Authentication is set to true. However, you cannot set visibility through the New Plugin Wizard. You must modify the plugin.xml file to add visibility control.

The following code snippet implements the Authentication example.

<property key="auth" type="boolean" default="false"
          label="Authentication" description ="Use Athentication."/>

<property key="username" type="string" default="" label="Username" description="Enter the username." >
          <visibility>
                <rule key="auth" value="true" />
          </visibility>
</property>

<property key="password" type="password" default="" label="Password" description="Enter the password.">
          <visibility>
          	<rule key="auth" value="true" />
          </visibility>
</property>

Configure plugin type

This screen only appears when you have selected Monitor/Task/Action as the Plugin type.

For each selected Plugin type (Action, Task, or Monitor), you must select a Java class to implement the type-specific interface and provide a name to represent the Plugin type in the AppMon Client. A new class is created if no class with the specific name exists. If you have selected more than one Plugin type (for example, both Task and Monitor), you can use one Java class for all the selected types. The Configure Plugin type properties screen displays fields for each type, as shown in the figure.

Configure Plugin Type Properties
Configure Plugin Type Properties

Enter the information for each Plugin type:

  • ID: The ID is entered automatically. It is the OSGi ID you entered in the General configuration screen, with the type appended.
  • Name: The name of the Plugin and type shown when setting up the Plugin.
  • Class: The fully qualified Java class name (packagename.classname ) for this Plugin type. A simple template file are created if it doesn't already exist. For the package name, the same naming rules apply as for the ID field. The class name is usually written in CamelCase.

Configure metric groups and metrics

This screen only appears for the Plugin types Monitor, Monitor Metric Group, and Agent Metric Group. Use the screen to add metric groups and add metrics to groups. You can also edit the Metric Group names. The names of Metric Groups and metrics must be unique.

If the Plugin type is Monitor Metric Group, then when you add a Metric group, an Add button appears below the Metrics list. Clicking Add enters default values for the metric Name and Unit. Select the new metric and click Edit to define the metric name and properties as described below.

Configure Monitor Metric Groups and Metrics
Configure Monitor Metric Groups and Metrics

If the plugin was configured as Agent Metric Group in step 2, this page looks slightly different. Instead of a generic add button buttons to explicitly add PMI, PerfMon and JMX Metrics are available.

If the Plugin type is Agent Metric Group, then when you add a Metric group, three buttons appear below the Metrics list: Add JMX, Add PMI, and Add Perf Counter. Clicking any of these buttons enters default values for the metric Name and Unit. Select the new metric and click Edit to define the metric name and properties as described below.

Configure Agent Metric Groups and Metrics
Configure Agent Metric Groups and Metrics

Configure metric details

When you click Edit in the Configure Metric Groups and Metrics screen, the Configure metric details dialog box opens. The contents vary depending on the metric type.

These fields are provided for all types of Metrics:

  • Name: The metric name has to be unique within the Metric Group.
  • Unit: The unit in which the measurements are provided. Select the unit from the list.
  • Description: Optional text that describes this metric.

For Monitor Metric Groups, the screen includes a table for defining the Metric Properties, parameters that may be required by the Monitor.

Monitor Metric Details
Monitor Metric Details

For Agent Metric Groups, the fields in the Configure metric details screen depend on the metric type. For JMX and PMI metrics, click Browse Metrics to select an Agent and then select a metric collected by the Agent, to populate the fields.

For JMX Metrics, provide these mandatory details:

  • Domain: Mandatory MBean domain of the object to monitor, for example jboss.*.
  • Key Properties: Properties to find a matching object. You must specify at least one property Key. If Value is left empty, all objects with the specified key match. If you select the Exclude check box, all objects with the specified key are ignored. Optionally, select Include similar MBeans to include MBeans that match the specified properties but also have other properties set.
  • Attribute Name: Attribute of the object to monitor.

For PMI Metrics, provide these mandatory details:

  • Module Path: The path to match the object to monitor, for example beanModule.
  • Performance Counter: The measure name of this object, for example ActivateCount.
  • Statistic Value: The aggregation method, for example count. See the IBM WebSphere PMI documentation for a list of available performance modules, counters, and statistic values.

For PerfCounter Metrics, enter these mandatory details:

  • Performance Object: The object to measure, for example Processor.
  • Performance Counter: The measure name of this object, for example %% Processor Time.
  • Instance: The instance to use to query the Performance Counter, for example _Total.

Testing plugins

After you build the Plugin, you must test it successfully before it deploying it. To test a Plugin, you must specify the Plugin type or role such as Action, Task, or Monitor, and the test location such as Server, embedded, or out-of-process Collector. Optionally specify the test setting configuration for the Plugin configuration parameters.

During the test, the Plugin is transferred to the test location and temporarily installed there. Afterwards, the methods for setup, execution, and tear down are called.

The criteria for passing the test are:

  • The Plugin can be successfully installed.
  • The setup, execution, and tear down do not hang.
  • The setup and execute methods return Success.

Test location restrictions

Testing of Plugin types is restricted to the locations on which the Plugins can be deployed. This means that Monitors can be tested on a Collector (embedded or out of process), Actions can only be tested on the Server, and Tasks can be tested on all AppMon locations. If no appropriate testing location is available, the Test Button is disabled.

Status codes

The runtime status of a Plugin is determined by the returned status code. Plugins should be designed to use the best fitting status code available. All available status codes are in the com.dynatrace.diagnostics.pdk.Status class.

Each of the status categories applies to a different stage of Plugin execution:

  • 100 Success: Return these status codes only if you are sure that the Plugin executed as expected.
  • 200 Internal AppMon Server errors: These status codes are only returned if the AppMon Server has an internal problem. Do not use these status codes in your Plugin.
  • 300 Plugin internal errors: The Plugin code has errors or cannot execute because environmental limitations. For example, the Plugin does not have required permissions).
  • 400 Infrastructure errors: The Plugin code can execute properly, but the target service is not reachable because the infrastructure between the plugin and the target service has errors. For example, a network error occurred.
  • 500 Target service errors: The Plugin code and the infrastructure are working correctly, but the target service did not complete as expected. For example, the target service is not installed on the target machine.

The following table describes all available status codes.

Status Status Code Base Status Code Message Description
Success 100 100 Success Plugin execution was successful.
PartialSuccess 101 100 Partial Success Plugin execution was partially successful.
ErrorDynatraceServer 200 200 Server error And internal AppMon Server error occurred.
ErrorLicense 201 200 License error The license does not support Plugins.
ErrorInternal 300 300 Plugin error A Plugin internal error occurred.
ErrorInternalException 301 300 Plugin exception The Plugin caused an exception.
ErrorInternalResourceUnavailable 302 300 Plugin resource unavailable A necessary Plugin resource is unavailable.
ErrorInternalUnauthorized 303 300 Plugin unauthorized The Plugin does not have all required permissions.
ErrorInternalConfigurationProblem 304 300 Plugin configuration problem The Plugin configuration is invalid.
ErrorInfrastructure 400 400 Infrastructure error Plugin execution failed because of an infrastructure problem.
ErrorInfrastructureUnreachable 401 400 Target service unreachable The Plugin is unable to reach its target service.
ErrorInfrastructureUnauthorized 402 400 Permission error The Plugin does not have all required permissions to communicate with the target service.
ErrorInfrastructureProtocolError 403 400 Protocol error A Plugin protocol error occurred.
ErrorInfrastructureTimeout 404 400 Timeout A timeout occurred before the Plugin reached its target service.
ErrorTargetService 500 500 Target service error A target service error occurred.
ErrorTargetServiceExecutionFailed 501 500 Target service execution failed The Plugin was unable to execute the target service.
ErrorTargetServiceUnauthorized 502 500 Target service unauthorized The target service does not have all required permissions.

Plugin files and directory structure

All Plugin directories contain the following subdirectories and file:

  • build: Directory that contains the built Java classes and the Plugin JAR file.
  • lib: Directory that contains optional libraries.
  • META-INF: Directory that contains the MANIFEST.MF file.
  • res: Optional directory that contains resource files that are packaged with the Plugin.
  • src: Source directory, which contains Java files.
  • plugin.xml: The main Plugin file, which contains general information, properties, Plugin types, and Metric Groups. These items are grouped into Extensions.
Plugin directory structure
Plugin directory structure

If required directories or files are missing, the status on the development page is loading failed (see Plugin development).

Java plugin class file

The Java Plugin class must implement the interface of the respective Plugin type (Task, Action, Monitor).

A Plugin can have multiple types. The Java Plugin class can implement multiple Plugin type interfaces. This feature makes sharing and reusing code easy.

The plugin.xml file

The contents of the plugin.xml file are grouped into Extensions:

  • pluginconfig: This Extension contains Plugin information and properties.
  • task, action, and monitor: These are the extensions for the Plugin types. They link to the pluginconfig Extension and provide the Java class name.
  • monitormetricgroup: This Extension contains a metric group definition, including all metrics and links to a monitor Extension.

Be careful when manually editing this file. Back up the file before opening it for editing. Make sure each extension ID is unique and the references to classes and other extensions are valid.

Plugin license

If a software license applies to a Plugin, the license text may be packaged with the Plugin.

To display this license text in the Plugin Properties in the AppMon Client, add a license element to the information section of the plugin.xml file, as shown in the following example. Only plain text files are supported.

<information>
  <description value="The description of this plugin." />
  ...
  <license value="license.txt" />
</information>

API / PDK documentation download

The API / Plugin Development Kit documentation is available as a JavaDoc Bundle.