Level: Intermediate Balan Subramanian (bsubram@us.ibm.com), Advisory software engineer, IBM
Hariharan Narayanan (harihnar@in.ibm.com), Application Developer,
IBM
04 Dec 2007 Explore how you can use the Web Services Distributed Management (WSDM) standard and the Managed Agent Explorer (MAX) together to create an endpoint and monitor a system in the network using the created endpoint. This article demonstrates how to use a set of WSDM endpoints that helps monitor a computer and its major components to show the various advanced features of the MAX.
Introduction
The Web Services Distributed Management (WSDM) open standard is supported
by two open source projects: a reference implementation in the Apache Muse project and
tooling in the Eclipse TPTP project. Existing developerWorks’ articles referenced in Resources explain how to build WSDM endpoints either directly interfacing with the Apache run time or using the tooling integrated in the Eclipse IDE. The intent of the tooling is to support a complete build-deploy-test cycle for the development of WSDM endpoints while relieving you from the details of Web services and the Apache Muse run time. This enables an iterative approach to development of endpoints.
As introduced in Part 1 of this series, the Managed Agent Explorer (MAX) is an invaluable tool in the testing of the endpoints that you build either with the Eclipse tooling or independently with Apache Muse. This article helps you explore advanced features that MAX provides such as:
- Filtering members of a service group
- Sorting members of a service group and properties/operations of a resource
- Traversing relationships and introspecting related endpoints
- Subscribing for notifications
- Monitoring a WSDM resource for state changes
WSDM endpoints for monitoring a computer
This article demonstrates how to use a set of WSDM endpoints that helps monitor a computer and its major components to show the various advanced features of the MAX. The endpoints provide information on the processors in the system, processes running, memory details, network card details, and so on. You learn how to use MAX capabilities to perform various operations such as killing a process and setting the memory threshold for a process.
See Resources for links to developerWorks articles on basic tooling features. To see a
set of endpoints as a .war file that you can download and deploy into an application
server like Apache Tomcat see Download. This set of endpoints will work only on
Windows® machines because they use command line system commands to gather the
required information. They have been tested only on Windows XP. Deploying this .war file is as simple as downloading and placing it in the webapps folder of your Apache Tomcat installation.
Figure 1 shows the endpoint deployed in Apache Tomcat v 6.0 and opened in MAX as
discussed in "Connecting to
deployed endpoints" in Part 1 of this series. The URL you need for the WSDM Managed
Agent Configuration dialog is "http://localhost:8080/System/services/AllEndpoints; you use this dialog to connect to a deployed endpoint. If your Eclipse tooling is not on the same machine as where you deployed the endpoint, replace localhost with the IP address or hostname of the machine where the tooling is installed. Similarly, if you installed Apache Tomcat by providing your own custom configuration, change the port number appropriately.
You can move around the individual views in the perspective to arrange the Managed
Agent Explorer view under the Profiling Monitor view as shown in Figure 1. Eclipse also allows you to save the layout for a particular perspective.
Figure 1. Viewing the endpoint for the components of a computer
As seen in Figure 1, all the resources of different types are listed in MAX. MAX does
not allow you to view the properties and operations of a particular resource in a
service group without connecting to it explicitly. The agent for that particular
resource type must be launched and the launched agent must be opened in MAX to see the
corresponding properties, operations, and so on, for that resource type. An example of
this is shown in Figure 2, where an agent is launched for the resource type Computer.
Figure 2. Launching an agent on a resource
After launching the agent, a corresponding node representing the managed agent appears
in the Profiling Monitors view as shown in Figure 3.
Figure 3. Launched agent
Sorting resources, properties and operations
Initially, the resource types displayed in the Resource Topology tree are unsorted and
appear in the same order as in the SOAP response received from the service group
endpoint. Similarly, when looking at a resource endpoint, the properties and operations
are not sorted, and they appear in the same order as in the WSDL representing the endpoint
(MAX gets the WSDL through metadata exchange). To sort the resource types under a parent
resource type, or to sort the properties, operations, and so on, under a resource type,
a sort facility is provided in MAX. Use the button that appears second from the right on
the Resource Topology view, as shown in Figure 4, for sorting.
Figure 4. Sorting resources in the MAX
The resources are sorted alphabetically in an ascending order. Figure 5 shows the
resources after they are sorted.
Figure 5. Resources sorted alphabetically
The same button can be used to unsort the resources or properties, operations, and so
on, and display them as they would appear in the WSDL file. Open the other agent by
double-clicking on it in the Profiling Monitors view. Click Sort again and the sorted list of properties is shown as in Figure 6.
Figure 6. Resource properties and operations sorted alphabetically
Filtering resources
Without filtering it would be very difficult to use MAX to look at a group of
resources. For example, as shown in Figure 5, it is difficult to use MAX just to display
the network adapters or memory details separately. To help with this, there is a
facility for filtering the resources based on various criteria, including:
- Resource name/caption
- Capabilities implemented by a resource type
- Endpoint Reference (EPR) of the resource
To use the filtering capability, open the agent that represents the service group and notice that
Filter (next to Sort) is now enabled. Use
this button, as shown in Figure 7, for filtering. The Filter button is disabled when
only one resource is displayed in the Resource Topology tree and is automatically enabled as more resources are added.
Figure 7. Bringing up the filtering window
Figure 8 shows the filter view. You can create many named filters and apply them selectively. Your filtering criteria may use one of the tabs shown or a combination of all of them.
Figure 8. Filtering view
Filtering by resource name
Let’s filter the resources so that only the CPU resources are shown. On machines with
multiple processors, each processor will be represented as a separate CPU resource.
- Type
a name for the filter in the Name field.
- In the Resource Name tab,
type the name of the resource. For the example shown in Figure 9, it is
http://192.168.1.20:8080/System/services/CPU.
- Select Apply.
The filter you just created is saved and is available for further filtering
operations. Now you'll see why you need to provide the full URL for the resource name.
Figure 9. Creating a filter
When you select Apply, the filter is applied to the members of the service
group,
so that only the members that satisfy the filter criteria are shown, as in Figure 10.
Figure 10. Filtered members of the service group
Unfortunately, MAX does not resolve the caption of the resource (provided through the
WSDM Description capability) when showing the members of a service group. While
MAX resolves the caption of the resource when connecting directly to it, it uses the
default mechanism of showing the URL portion of the EPR of each member of the service
group. This may be rectified in the next version of the Managed Agent Explorer. For now, you must provide the URL portion of the EPR for the resource name. The good news is that different resource instances typically have the same URL with different resource IDs, which means that you can use this filtering option to show only resource instances of a particular type.
The next time you open the Filter view, the filters you have created appear in the
Existing Filters drop-down box, as shown in Figure 11. You can create new filters by
clicking Create New. You can delete a filter by choosing that filter in the drop-down box and clicking Delete.
Figure 11. Existing filters, creating and deleting filters
To remove a filter, you cannot simply choose None
from the Existing
Filters drop-down menu. Instead, you must refresh the Resource Topology view by
opening the agent again in the Managed Agent Explorer. You can do this by double
clicking on the agent in the Profiling Monitors view, as shown in Figure 12.
Figure 12. Refreshing the managed agent in the Managed Agent Explorer
In a similar manner, you can create filters for processes, network adapters, and other components of the computer system that are represented as resources and appear as members of the service group currently being looked at.
Filtering by implemented capabilities
Because a WSDM resource is an aggregation of capabilities, filtering resources based on
implemented capabilities is a natural next step. Capabilities have well-defined and
often standard capability URIs to identify them; therefore, they are more powerful than
filtering by resource name. You can use MAX to filter through a list of resources based
on the capabilities they implement. However, there is a bug in the latest version of the
tooling on Eclipse TPTP (moving soon to the Eclipse COSMOS project) that prevents this
function from working properly. In the .zip file in Download,
there is a patch in the form of a .jar file. You must install the patch in your
installation of the Eclipse TPTP tooling before this function can be used. To install
the patch:
- Close Eclipse if you have it open.
- Download the org.eclipse.tptp.monitoring.managedagent.wsdm_4.3.0.v200706010100.jar
file available in the .zip file in Download.
- Navigate to the eclipse\plugins subfolder of your installation and copy the downloaded
.jar file into this folder. There will already be a .jar file of that name in this
folder, so choose to overwrite it.
- Restart the tooling.
To filter by one or more capabilities, create a new filter. Let’s call this filter
ShowOnlyWSDMResourcesThatProvideOperationalStatus. Then, switch to the
Capabilities tab.
Figure 13. Filtering window showing Capabilities tab
Initially, the Add button is disabled. But, when you start typing in the text field for
Namespace URI, this button is enabled. To add a capability type, enter the namespace URI
in the text field and click Add. The namespace URI of the capability is not the
namespace of the capability, but is defined in the relevant specification and identifies that capability distinctly. For example, for the MUWS (Management Using Web Services) OperationalStatus capability, the namespace where it is defined is http://docs.oasis-open.org/wsdm/muws2-2.xsd; however, according to the specification document, the capability URI is http://docs.oasis-open.org/wsdm/muws/capabilities/OperationalStatus. You must use the latter when filtering by capabilities.
When you click Add, the capability URI is added to the capabilities list, as shown in Figure 14.
Figure 14. Specifying capability URIs for filtering by capabilities
To ensure that only WSDM resources are shown, add the WSDM MUWS Identity
capability to the filter as part of the criteria. Type the capability URI
http://docs.oasis-open.org/wsdm/muws/capabilities/Identity and click Add. If you want to remove a capability URI, select an item from the list and click Remove.
If more than one capability URI is added, the Match All Capabilities check-box is
enabled. If this box is checked, the member resource is matched against all the
capabilities listed. If not, an implementation match of at least one capability will
suffice for the resource to show up in the filtered view. For this example, select the
check-box and click Apply.
Figure 15. Executing the capabilities based filter
When the filter process is complete you will see only the network adapter resources in
the Resource Topology view, as shown in Figure 16.
Figure 16. Filtered resources
To clear the filter, open the corresponding agent node in the Profiling Monitors view. The filter is ignored and all the resources in the group will be shown.
Filtering by endpoint reference
If you want to filter by endpoint reference, use the Endpoint Reference tab shown in
Figure 17. You will create a filter called ShowOnlyMyResource and construct an EPR for a
particular resource by providing the URL and the reference parameter. WSDM resources
built with Apache Muse use a particular convention for the reference parameter, as shown
in Figure 16 in the table of reference properties. This table is used to add more
reference properties to construct an EPR to distinctly identify an instance of a resource. To add a property, click Add Property. A row is added to the table. When a cell is clicked, it becomes editable and, thus, the necessary value can be entered. To remove a property, click on that row and click Remove Property.
Figure 17. Creating an endpoint reference-based filter
Why is this useful? You may be looking for a particular resource whose EPR is always
constant. In the example endpoint, the resource IDs are added in sequence; however, in practice, the resource IDs have some semantic meaning that helps identify the resource uniquely over time. For example, the identification may be the MAC address of the network adapter (which is truly unique). So if you want to check whether a network address with a particular MAC address is on this system, you can use an EPR filter. You can save the named filter and apply it against any service group (which may have a thousand members) that you view through MAX.
Also, if you know that the resource IDs are assigned sequentially for each resource
type, as in this example, you can use an EPR filter to verify whether there is a third
network adapter. Because the test machine has three adapters, upon executing the filter,
the third network adapter resource alone is shown in the Resource Topology view, as shown in Figure 18.
Figure 18. Results of applying the filter
If you checked the Match All Criteria check-box, as shown at the bottom of Figure 17,
MAX requires the filtered managed resources to match all the criteria specified such as
resource name, capabilities, and EPR. If this box is not checked, each resource can satisfy any of the criteria specified.
Relationships between endpoints
WSDM allows relationships to be defined for any endpoint. These relationships can be
represented as first-class endpoints themselves or through the relationship capability
provided by an endpoint. MAX allows you to traverse relationships that an endpoint
participates in when looking at that endpoint. A single endpoint might participate in relationships with multiple endpoints, in multiple relationships with another endpoint, or a combination of the two.
Open the agent that represents the collection of endpoints in the Managed Agent
Explorer by double-clicking on it or open it using the context menu in the Profiling
Monitors view. The collection of endpoints appears in the Resource Topology view. Then,
scroll down to the Computer resource, right-click on it, and choose to Launch
Agent.
Open the agent representing the Computer resource by double-clicking on it or using its
context menu. Figure 19 shows the Computer resource’s details shown in the Resource
Topology view.
Figure 19. Computer resource
Next, expand the Relationships node. As shown in Figure 20, the Computer endpoint has
a number of relationships of two types: Hardware Component and Software Component. The
Computer endpoint has the Hardware Component relationship with multiple endpoints
(typically, the processor, memory, storage, NIC, and so on).
Figure 20. Relationship types for the Computer endpoint
Let’s open some of the Hardware Component relationships. Each relationship has two
roles in this example (there can be more than two roles in a relationship). As shown in
Figure 21, Host Computer is a role in all Hardware Component relationships. The name of the other role can vary.
Figure 21. Roles in relationships
Now navigate to the related endpoint by choosing that role, right-click on it, and
choose Launch Agent, as shown in Figure 22. If you try this on the Host Computer role, you will not find an option to launch an agent because that role refers to the endpoint you are currently looking at in MAX. What you want to do here is navigate to the endpoint that plays the selected role in that particular relationship.
Figure 22. Launching an agent for a related endpoint
Let’s open the Software Component relationship and launch an agent on the Operating
System role. A new agent is added for the Operating System endpoint in the Profiling
Monitors view, as shown in Figure 23.
Figure 23. New agent for operating system endpoint
Now open this new agent, which represents the operating system in the Managed Agent
Explorer, and expand the Relationships node. You will see a number of relationships
called Hosted Process, as shown in Figure 24. This is because you chose to model each process as an individual endpoint and created a relationship between each process and the operating system endpoint.
Figure 24. Relationships of the operating system endpoint
Scroll down until you find the Hosted By relationship. This relationship has two roles:
the OS and the Host Machine, as shown in Figure 25. Can you guess which endpoint the
Host Machine role contains? It is the same endpoint you started with at the beginning of this section on relationships, the Computer endpoint.
Figure 25. HostedBy relationship of the operating system endpoint
Launch an agent for the Host Machine role’s endpoint. A new agent is launched and the
previous agent for the Computer endpoint is terminated, as shown in Figure 26.
Figure 26. New agent and terminated agent for Computer endpoint
Notifications from endpoints
The Managed Agent Explorer can consume WS-Notifications from the resource and reflect them suitably on the UI. The resource may send different payloads through WS-Notifications. Examples are property change notifications and service group membership change notifications. MAX will use some of these notifications to reflect changes in the UI and the others, which are not currently handled by MAX, will be placed in the Eclipse PDE error log as information messages.
Property change notifications
First, let’s look at property change notifications. When you are looking at a resource
in MAX, you can subscribe for change notifications of individual properties. For
example, let’s assume you want to monitor the memory usage on the machine and be
notified of changes in available memory. The memory is modeled as a logical endpoint.
You can filter through the service group using Memory for the resource name to find the
endpoint for memory and then launch an agent for it. Ultimately, your workspace will
look like Figure 27. The current value of the AvailablePhysicalMemory property is shown in the Details view.
Figure 27. Memory endpoint
Now right-click on the property you want to monitor, AvailablePhysicalMemory,
and choose Subscribe, as shown in Figure 28.
Figure 28. Subscribing to a property
Once subscribed, the node is decorated with a mail icon and turns blue immediately. Clicking on it will restore it back to black.
Figure 29. Indication of subscription
Now every time the value changes, the endpoint will send a notification to the
workbench and MAX will reflect that notification by changing the color of the property
to blue and getting the latest value of the property from the notification. You can see
the new value of the property by clicking on the property node. For example, start a program like Internet Explorer, which is sure to consume some memory. Soon you will see a property change, and you can click on the property to see the new value. If you have already selected the property node, you will see the values change in the Details view.
Figure 30. New values for available physical memory
You can unsubscribe to notifications of property changes of a particular property by
right-clicking on the property and choosing Unsubscribe. The unsubscribe option is available only if you had previously subscribed for changes in that property’s value.
Figure 31. Unsubscribing for property change notifications
The endpoint you are looking at must implement WS-ResourceLifetime for unsusbcribe to work successfully.
Topic-based notifications
WSDM endpoints/resources also provide topics for notifications. Each property
automatically has a corresponding topic available for a consumer to use to subscribe to
property change notifications of that property. In addition, a resource may provide a
number of topics to give indications of different things happening in the resource. For
example, the Memory endpoint provides notifications when memory falls below a threshold. Note that the calculation of whether the available memory is below the threshold is done by the endpoint itself.
Open the Operations node of the Memory endpoint and click on the setMemoryThreshold
operation, as shown in Figure 32. As you can see in the Details view, this operation
requires one parameter that represents the threshold that indicates low memory. Click on
this parameter in the Details view and then enter a value in the Value Editor. You can
first look at the current value of the property AvailablePhysicalMemory and enter something slightly below it. For
example, enter 740. Then, press Apply. Note that this only saves the
parameter; it does not invoke the operation.
Figure 32. Setting the memory threshold
Now choose the setMemoryThreshold operation in the Resource Topology view and
press Invoke or right-click on the operation and choose Invoke, as shown
in Figure 33. This sets the threshold on the endpoint.
Figure 33. Invoking the operation
Now open the Topics node. You will see topics corresponding to each property of the
endpoint, but you will also see a LowMemory topic. Right-click on it and choose
Subscribe, as shown in Figure 34. As before, a mail decorator appears to indicate that you are subscribed to that topic.
Figure 34. Subscribing to the topic
Open the Eclipse PDE Error log. You can do this by selecting Window > Show View
> Other from the menu bar and choosing Error Log under PDE Runtime in the
window that opens, as shown in Figure 35.
Figure 35. Opening PDE Error Log
Now do something to cause the available memory to drop below the threshold. For
example, open some Internet Explorer windows. The endpoint is built so that it will
send notifications whenever the available memory drops below the threshold. If it is already below the threshold and drops further or it is above the threshold and increases, no notification is sent. When the endpoint sends notifications over the course of its lifetime, MAX captures them and places the notifications in the error log as informational messages. You can click on the event in the error log, as shown in Figure 36, and see brief details.
Figure 36. Informational notification
message in error log
Double-click on the entry in the error log to see details of the information message.
You will see the actual WS-Notification XML in the details window, as shown in Figure 37.
Figure 37. Details of the notification
You can subscribe to multiple topics on an endpoint. You can also subscribe to all
topics that an endpoint provides by right-clicking on the root endpoint node in the
Resource Topology and choosing Subscribe.
Summary
This article introduced you to some advanced features MAX provides for sorting,
filtering, and monitoring WSDM endpoints. You learned how you can use MAX as a basic introspection and monitoring tool for WSDM endpoints and how MAX visualizes service groups and relationships. As an example, a powerful endpoint that demonstrates many of WSDMs features is included with and used in this article.
Future articles in this series will teach you how to exploit the code behind the MAX UI for your own interactions with WSDM endpoints and how to extend MAX to suit your needs. In addition, they will take you through the various concepts of building the included sample endpoint and show you how to build such endpoints using advanced features in the WSDM tooling.
Download | Description | Name | Size | Download method |
|---|
| Code sample | ac-manexp2source.zip | 11KB | HTTP |
|---|
Resources
About the authors  | 
| | Balan leads the Autonomic Computing component development team, which delivers multiple components including a run time and Eclipse tooling for Web Services Distributed Management (WSDM), policy, eventing, and task automation components. He is a committer to the Eclipse TPTP and COSMOS open source projects and contributor with the Apache Muse open source project. |
| 
| | Hariharan L. Narayanan has been with IBM for the past two years and is working on Eclipse-related technologies. He is currently contributing to the open source development for the Managed Agent Explorer component in the Test Performance Tools Platform (TPTP) project.
|
Rate this page
| 
