Important: This user guide is assumed to be used with TPTP 4.2.2
The Managed Agent Explorer is available as a Tech Preview in TPTP 4.2.2. It allows users to introspect and interact
with managed agents that represent resources instrumented for open standards management like WSDM or JMX resources.
It is possible to add new managed agents that represents managed resources that may be instrumented by other means.
The process to add a new managed agent type is explained here http://www.eclipse.org/tptp/monitoring/documents/design/contributing_to_managed_agent_explorer.htm.
This document provides details on using the Managed Agent explorer with provided Managed Agent types.
1.1 Installation
1.2 Using the Managed Agent Explorer with the Apache Muse WSDM runtime
1.3 Launching the Managed Agent Explorer
1.4 The Managed Agent Explorer view
1.5 Visualization of resource groups (WSDM Service Groups)
1.6 Using the Managed Agent Explorer with JMX
1.7 Summary
The managed agent explorer provides a view to introspect and interact with manageable resources instrumented for different types of managed resources currently WSDM and JMX are the two types for which the necessary plugins are available in TPTP as a Tech Preview. WSDM or Web Services for Distributed Management provides standard mechanisms and semantics for management of resources using web services and management of services using web services as well. The Managed Agent Explorer uses a locally instantiated agent to communicate with a remote resource instrumented for WSDM using SOAP-over-HTTP exchanges. JMX is a open solution for management and monitoring of Java based applications available as part of Java 5. While JMX represents the standard mechanism to be used for instrumenting Java applications, WSDM provides both management abstraction across platforms and programming languages and remote management capability over standard web services mechanisms.
The managed agent explorer provides the following main features:
1. Connect to different resources by providing configuration for that particular resource type
2. View the properties and operations provided by a resource for manageability; refresh on demand
3. Inspect individual properties; Change the property values
4. Invoke operations on the resource; ability to key in parameters and view returned results
5. View the topology of a group of managed resources equivalent to service groups in WSDM and MBean collection within an MBeanServer in JMX.
6. Connect directly with any member of such a displayed group and further inspect/interact with that resource
The Managed Agent Explorer is a Tech Preview for TPTP 4.2.2 and a number of new features are in the works for TPTP 4.3. See the summary section at the bottom for a preview of what is to come. Today, you can use the managed agent explorer to test out the JMX instrumentation you can accomplish using other Build-to-manage tooling available in TPTP 4.2.2. In the future, with planned contributions of tooling towards instrumenting resources for WSDM, the Managed Agent Explorer will be an indispensible testing and visualization tool for such instrumentation capabilities of TPTP.
You will need TPTP 4.2.2. For download information and prerequisites go to http://www.eclipse.org/tptp/home/downloads/newdownloads.php?ver=4.2.2. Once you choose a release to download, Just above the Requirements section you can find the downloads for the Managed Agent Explorer and Monitoring Instrumentation tech previews.
The Apache Muse runtime provides an infrastructure for deploying WSDM based resources/endpoints and an implementation of standard WSDM capabilities. As part of the runtime, utility classes for interacting with WSDM resources, exchanging/inspecting metadata are also available.
The managed agent explorer download contains two plugins org.eclipse.tptp.monitoring.managedagent.wsdm.muse_plugin and org.eclipse.tptp.monitoring.managedagent.wsdm.muse. The first plugin contains the code necessary to adapt the Muse runtime as Managed Resource Agent as explained in this document: Contributing a new managed agent to the Managed Agent Explorer. The latter plugin is empty out of the box and is meant to contain the jar files from the Apache Muse release driver.
You can download the Muse 2.0 release driver here. The ZIP file contains both the Muse jars and the jars required by Muse. All the jars within the modules folder and its subfolders must be copied into this plugin. Assuming that your TPTP install is in the tptp-install folder, navigate to tptp-install/eclipse/plugins/org.eclipse.tptp.monitoring.managedagent.wsdm.muse folder and copy the JARs in the downloaded package into this folder.
Apache Muse no longer ships WSDL4J which is required by the Managed Agent Explorer to parse the metadata received from WSDM resources. You must download and add wsdl4j.jar to the same folder. The name of the JAR is important. You can get WSDL4J from this Sourceforge page. Once you download this ZIP file, extract it in a temporary folder and just copy over the wsdl4j.jar from the lib folder to the tptp-install/eclipse/plugins/org.eclipse.tptp.monitoring.managedagent.wsdm.muse folder.
Due to some changes in the Muse release, two extra steps are required for the Managed Agent Explorer to use the Apache Muse WSDM runtime:
1. Due to some name changes, the Muse jars have an different version suffix at the end. The manifest.mf in the org.eclipse.tptp.monitoring.managedagent.wsdm.muse plugin needs to be updated to include the new JAR names. Also some new packages need to be exported in the manifest. Replace the Manifest.mf file in the META-INF folder within this plugin with this MANIFEST.MF.
2. The manifest.mf in the org.eclipse.tptp.monitoring.managedagent.ui plugin needs to be updated to export some more packages. Replace the Manifest.mf file in the META-INF folder within this plugin with this MANIFEST.MF.
Typically the managed agent explorer is launched by profiling a managed resource. Bring up the Profiling Configurations page as shown below or by using the Run > Profile menu option.
Choose the Managed Resource entry on the left panel. Double click it or bring up the context menu by right clicking on it and then choose New. This will create a new launch configuration for an agent to introspect a managed resource.
Give your new configuration a name. We will first introspect a WSDM resource. Check the WSDM resource option and then click on Edit Options to bring up the configuration page to specify the connection details for the WSDM resource. You may leave the choices in the other two tabs at defaults. The Destination tab allows you to pick a project in which the agent will be persisted and the Common tab allows you to add this configuration as a favorite configuration.
The configuration options for a WSDM resource consists primarily of a Design tab and a Source tab. The main connection detail for a WSDM resource is the Endpoint Reference - a combination of an URI and optionally some well qualified reference properties each of which has a QName and a value. In this tech preview the reference properties can only have values that are of simple types.
You can either type in the URI or pick one from the historic values saved in the drop down. You can add one or more reference properties and provide all the information required for the property QName and the value. Alternately if you have the EPR XML fragment saved somewhere or in the clipboard you can paste it into the Source tab. The Design and Source tabs will stay in Synch so at any time you can switch between data entry into the dialog to directly editing the XML fragment. An illegal XML fragment will be flagged with an error. The Runtime tab allows you to select different WSDM runtimes that the agent can use to communicate with the WSDM resource. In the future, the Managed Agent Explorer will standardize on using the Apache Muse open source reference implementation of the WSDM specifications.
Currently it is expected that you will have by means outside the scope of TPTP 4.2, built manageability endpoints that are built on WSDM. Typically you would do this by hand and with some code to supplement the reference implementation like the ones available in Apache Muse (http://ws.apache.org/muse/). In TPTP 4.3, comprehensive tooling for building WSDM resources or instrumenting applications for WSDM will be available.
Let us first try connecting to a single WSDM resource that represents a deployed object in an application server. Hit the Finish button and then Profile button on the resultant dialog.
The agent will be launched and added to the Profiling Monitors view which will also be automatically brought if not already visible. On expanding the root node you should be able to see the newly added Managed Agent representing the WSDM resource. The URI of the resource is shown; note that there can be two WSDM resources with the same URI but differing in their reference property values.
Double click on the agent or right click to bring up the context menu and choose Open With > Managed Agent Explorer. Note that you can open the managed agent explorer only on managed agents that are active and monitoring. This will bring up the Managed Agent Explorer and show the resource at the root of the tree structure. Expand the tree two levels down to see the Properties and Operations.
Double clicking on the resource node will show all the properties and their values in the Properties panel on the top right. Typically these operations take a few seconds as all the data is collected. You may also click on individual properties to show their values in the Properties Panel. You can also edit the Properties in the value column. The entered values will be reflected on the resource.
Click on an operation to see its input parameters and returned value in the Operations panel on the bottom right. For example, the queryResourceProperties method takes in two parameters and returns a XML fragment. The results row will not let you edit the value. At this time, the explorer does not support data entry of complex data values.
Once you have typed in the arguments you can invoke the operation by hitting the Invoke button. The results of the operation will populate the value column in the last row that represents the returned type and value.
Service Groups in WSDM represent a set of WSDM resources each with their own EPRs grouped together because of some similarity expressed by the membership constriants of the groups. Service Groups themselves are WSDM resources and as such have their own EPR. Connecting to a Service Group requires the same steps as above. However when the agent is opened with the Managed Explorer View, you will see the topology of the group in the Managed Agent Explorer view. Note that Service Groups can be hierarchical and the explorer will show nested service groups in such a case.
To introspect each of the resources that is a member of this service group, you will need to add a Managed Agent for each one of them. One option is to right click the resource, copy the EPR to clipboard and create a new launch configuration as above.
The easier option is to choose the Launch Agent option shown above. This will automatically launch an agent to introspect this resource and show the newly added agent in the Profiling Monitor view on the left. Double clicking on this newly added agent will show the individual resource, its properties and its operations.
The Monitoring Instrumentation UI plug-in includes an implementation for JMX that allows the managed agent explorer to retrieve and view the MBeans registered on a specified MBeanServer. You must install the Monitoring Instrumentation tech preview from TPTP 4.2 for the JMX resource option to show up when creating a new Managed Resource launch configuration.
The first step is to instrument a Java application for JMX. If you wish to use the Build-to-Manage toolkit for Java instrumentation provided in TPTP to perform this JMX instrumentation please look at http://www.eclipse.org/tptp/monitoring/documents/tutorials/tptp_btm_setup.html
Open the Profile�s launch configuration management interface, and create a new launch configuration under Managed Resource:
Select JMX resource under Monitor tab, and press the Edit Options button to configure JMX Service URL address.
If you want to retrieve the MBeans which are created and registered by Monitoring Instrumentation plug-in, you have
to choose Embedded MBeanServer. If you want to view resources on any other MBeanServer, please choose Remote MBeanServer,
and provide a valid address in Service URL text field
Return to the launch configuration page, and press the Profile button at the bottom to launch an agent
to retrieve MBeans information.
All MBeans registered on the specified MBeanServer will be retrieved and listed in the explorer. This is similar to
connecting to a WS-Service Group as explained in the previous section.
Right-click a MBean and select Launch agent to launch a new agent to view the details of this selected MBean.
The Manageable Resource Explorer provides a very interactive mechanism to test and work with resources instrumented for Management through JMX or WSDM. It is can also be extended easily to support other management mechanisms. Moving from a Tech Preview to mainstream component of TPTP 4.3, the following are in the works:
- Support for complex data types
- Ability to view topology and resource information in the same view
- Support for notifications (WS-Notifications) and automatic view updates
- Selective property updates
- Drag and drop support for operation parameters, property values and returned values
- Data Validation and meta-data based restrictions
- Integration with other events views
- Recording of sequence of actions