Applications, executed on an OSGi platform, need hardware resources (CPU, memory, disk, storage space) and software resources (sockets, threads). As these resources are limited, applications have to share them in order to preserve system quality of service. This is a general fact in OSGi business cases where multiple bundles share the OSGi framework. This is especially the case when the framework is shared by distinct tenants, which are responsible for distinct set of bundles running with their own business logic and lifecycle.

The chapter defines an API for applications to monitor hardware resources consumed by any set of bundles. The bundle is the smallest unit that can be considered as a resource context, the entity that is monitored. Monitored data may enable applications to take decisions on management actions to apply. Resource management actions are mentioned as examples in this chapter, for example, actions on the lifecycle of components, bundles, the framework and the JVM, Java threads, raise of exceptions.

Resource Monitoring Clients use the Resource Monitoring Service service to create Resource Contexts. These clients set bundles or group of bundles to Resource Contexts. They also request every Resource Monitor Factory to create Resource Monitors for a resource type. These Resource Monitors are associated to a single Resource Context.

When activated, Resource Monitors provide the current resource usage per Resource Context. Then, they check whether the current resource usage is compatible with the thresholds held by their associated Resource Listeners. When one of these thresholds is violated, the related Resource Monitor notifies the Resource Listener holding this threshold.

The Resource Monitoring Service manages the set of Resource Contexts. Resource Contexts are persistent between platform restarts. Resource Context Listeners are notified when a Resource Context is created or deleted or when a Resource Context configuration (that is, adding or removing of bundle) is updated.

A ResourceContext instance is a logical entity used to account resource usage. Every Resource Context defines a bundle scope which can be either a single bundle or a set of bundles. Once the bundle scope is defined, resources used by those bundles are monitored through a set of per-resource-type Resource Monitor instances.

Resource Context instances are persistent. The persistence of those instances is directly managed by the Resource Monitoring Service instance.

Each Resource Context is uniquely identified by a name. It can be retrieved through the getName() method. It can not be changed, that is it is definitively set when the Resource Context instance is created.

The Resource Context bundle scope is retrieved through the getBundleIds() method. This bundle scope can be extended through the addBundle(long) method. Bundles can also be removed from a Resource Context through the removeBundle(long,ResourceContext) method. For this last method, a Resource Context instance MAY be specified in order to associate the removed bundle to another Resource Context instance.

Resource Monitor instances are retrieved through getMonitor(String) method or the getMonitors() method. The list of available resource types is retrieved through the Resource Monitoring Service singleton instance.

Resource Monitor instances are added to and removed from a Resource Context instance by calling either addResourceMonitor(ResourceMonitor) method or removeResourceMonitor(ResourceMonitor) method. Both methods SHOULD only be called by ResourceMonitorFactory instances (see createResourceMonitor(ResourceContext) method).

A Resource Context is retrieved through the Resource Monitoring Service service.

A Resource Context instance can be deleted through removeContext(ResourceContext) method. The Resource Context input argument then defines a destination Resource Context instance for the bundles belonging to the to-be-removed Resource Context instance.

The System Resource Context is the Resource Context of the execution environment for the running OSGi bundles. It includes the resources of bundle "0". It is retrieved through the Resource Monitoring Service service.

The name of this context is “system”. See SYSTEM_CONTEXT_NAME.

The Framework Resource Context is a Resource Context monitoring resources of the platform as a whole. It is retrieved through the Resource Monitoring Service service. This Resource Context holds all hosted bundles allowing access to the whole platform resource consumption.

The name of this context is “framework”. See FRAMEWORK_CONTEXT_NAME.

A ResourceMonitor instance monitors a resource type consumed by the bundles of a specific Resource Context instance.

A Resource Context instance holds at most one Resource Monitor instance per monitor-able resource type. Resource Monitor instances are retrieved through their related Resource Context instance. Resource Monitor instances give access to their related Resource Context instance through a call to See getContext() method.

The monitored resource type is retrieved through the getResourceType() method.

The current usage of a resource consumed by a Resource Context instance is given through the getUsage() method. This method returns a Java Object to be casted to the appropriate Java object type depending on the Resource type. The next table provides the expected Java Object type for each specified resource type:

For example, for a MemoryMonitor instance, a call to getUsage() returns a Long java object indicating the amount of memory the related Resource Context instance is consuming.

A Resource Monitor instance is enabled and disabled through enable() and disable() methods. The state (enabled or disabled) of a Resource Monitor is retrieved through a call to isEnabled() method. Enable and disable monitoring mechanisms on-the-fly on localized set of bundles may be crucial for performance issues. See [1] Adaptive Monitoring of End-user OSGi based Home Boxes.

A Resource Monitor instance can also be deleted (delete() method). isDeleted() method returns true if the ResourceMonitor instance has been deleted.

Five types of Resource Monitor are specified:

The support of any Resource Monitor is optional. This list MAY be extended by the solution vendor. The list of the types that are supported on the OSGi platform can be computed by querying ResourceMonitorFactory services. Resource monitoring algorithms may vary with factories, see [2] Memory Monitoring in a Multi-tenant OSGi Execution Environment. They are out of the scope of this specification.

A ResourceMonitorFactory is a service that provides Resource Monitor instances of a specific resource type (for example, CPUMonitor, MemoryMonitor, etc.) for every Resource Context.

Every Resource Monitor Factory service is registered with the org.osgi.resourcemonitoring.ResourceType mandatory property, see RESOURCE_TYPE_PROPERTY. This property indicates which type of Resource Monitor a Resource Monitor Factory is able to create. The type can also be retrieved through a call to getType(). The type MUST be unique (two Resource Monitor Factory services MUST not have the same type).

New Resource Monitor instances are created by a call to createResourceMonitor(ResourceContext). This method returns a new Resource Monitor instance associated to the provided Resource Context instance. The ResourceMonitorFactory MUST call addResourceMonitor(ResourceMonitor) to associate the newly created ResourceMonitor with the provided ResourceContext instance. The newly created Resource Monitor is disabled, that is, it is initially not monitoring the Resource Context resource consumption. It can be activated through a call to enable().

Resource Monitor instances are deleted by calling delete() method.

A Resource Monitor instance MUST only be created through its ResourceMonitorFactory.

Resource Monitor Factory instances should be only used by the Resource Monitoring Service singleton instance. The Resource Monitoring Service singleton instance performs a service lookup on all existing Resource Monitor Factories. It uses a Resource Monitor Factory instance when it has to create a new Resource Context instance and their associated Resource Monitor instances.

A CPUMonitor instance is a Resource Monitor used to monitor the CPU usage of the bundles belonging to a Resource Context.

CPU usage and thresholds are expressed as a cumulative number of nanoseconds (long). The encapsulated value can be retrieved with the getCPUUsage() method.

In case where a threshold is reached, the CPU Monitor instance generates an event triggering Resource Monitoring Clients defined corrective actions (for example, decrease thread priority).

A MemoryMonitor instance monitors and limits the memory used by the bundles of a Resource Context instance.

Memory is accounted as bytes. Memory usage and thresholds are long java objects. The encapsulated value can be retrieved through the getMemoryUsage() method.

When an error threshold is reached, the next memory allocation MAY be prevented by the system and MAY throw a specific Exception in the associated context.

A SocketMonitor instance monitors and limits the number of existing sockets (for example, TCP, UDP) which are considered to be in use (for example, listening for incoming packet, bound, or sending outgoing packets).

A Socket is considered to be in-use state when a native socket file descriptor is created. It leaves this state when this socket file descriptor is deleted.

The number of in-use sockets is a long. The encapsulated value can be retrieved using getSocketUsage() method.

When an ERROR threshold is reached, the next socket file descriptor creation in the associated context MAY throw a SocketException.

A DiskStorageMonitor instance monitors and limits the use of persistent storage within Bundle Persistent Storage Area a Resource Context (the bundles actually belonging to it) consumes.

Disk Storage is expressed as a number of bytes of type long. The encapsulated value can be retrieved using getUsedDiskStorage() method.

An IOException MAY be thrown in the associated context when an ERROR threshold is reached.

A ThreadMonitor instance monitors and limits the number of alive Java Thread objects for a Resource Context instance. A Thread is considered to be alive when it is in the RUNNABLE, BLOCKED, WAITING or TIMED_WAITING thread state.

Usage and thresholds are Java int objects. The encapsulated value can be retrieved using getAliveThreads() method.

When an ERROR threshold is reached, any further thread activation will be prevented in the associated context. An InternalError exception MAY also be thrown in the associated context.

A ResourceListener receives notifications about resource usage for a specific Resource Context and a specific type of resource. A notification will be sent to a Resource Listener when one of its thresholds is violated.

A Resource Listener holds two types of threshold:

Each of them have two levels:

A threshold has the following state diagram, which transitions are associated to events:

Figure 144.2 Threshold state diagram.

A threshold state depends on the current consumption of resource and the type of threshold (upper or lower threshold).

A Resource Listener is registered as an OSGi service. The implementer must provide the two following mandatory properties:

It also has to provide at least one of these four properties when registered as an OSGi service:

These properties are mapped to the four types of threshold values a Resource Listener may support. The service properties are used to notify the associated Resource Monitor when one of these threshold values is modified.

Threshold values can also be retrieved through a set of getter methods. All of these methods returns a Comparable object used by the associated Resource Monitor in order to determine the current state of the current usage.

RESOURCE_CONTEXT and RESOURCE_TYPE properties are used by Resource Monitors to identify their associated Resource Listeners. Once associated, a Resource Monitor retrieves the threshold settings using service properties. When one of its thresholds is reached, the Resource Monitor calls notify(ResourceEvent).

Two examples of resource consumption are explained below, first with in-use sockets monitoring, second with CPU monitoring. The next picture shows the state diagram of the number of in-use state socket over the time.

Figure 144.3 Number of in-use sockets over the time.

In our example, the lower warning threshold and the lower error threshold of the Resource Listener are respectively set to 10 and 5. When the number of in-use sockets decreases under 10, the usage goes from the NORMAL state to the WARNING state and the Resource Listener receives a WARNING event. If the number of in-use state sockets decreases again and goes down to 5, the usage goes from the WARNING state to the ERROR state and the Resource Listener receives a ERROR Resource Event.

The upper threshold is also set. The upper warning threshold and the upper error threshold are respectively set to 100 and 1000 in-use state sockets. When the number of sockets reaches 100, the usage goes from the NORMAL state to the WARNING state and the Resource Listener receives a WARNING Resource Event. If this number is still increasing and exceeds 1000, then the usage goes from the WARNING state to the ERROR state and the Resource Listener receives an ERROR Resource Event.

This is a typical use case for a Java Web server. Indeed, one of the most important quality of service indicator is the number of in-use state sockets a java web server is handling. A low number of in-use state sockets may indicate the java web server encounters network problems. On the contrary, a high number of in-use state socket may be the result of an external network attack or it could also indicates the java web server is overused and its administrator should take actions to load-balance the charge to another java web server instance.

For other resource types, only upper thresholds may be useful. The next diagram shows the CPU consumption a Resource Context is using over the time:

Figure 144.4 CPU consumption (%) over the time – Upper Threshold.

In this example, only the upper threshold is set. The upper warning threshold is set to 50%, the error one is set to 75%. CPU consumption fluctuates between 0 and 50%, the usage is in the NORMAL state. Then it increases and reaches 50%. The usage then goes from the NORMAL state to the WARNING state and the Resource Listener holding the threshold receives a WARNING Resource Event.

Afterwards, CPU consumption decreases under 50%; the usage goes from the WARNING state to the NORMAL state. The related Resource listener receives a NORMAL Resource Event.

It then increases again and exceeds 50%. The usage goes to the WARNING state. CPU consumption is still increasing and exceeds 75%. At this moment, the usage goes from the WARNING state to the ERROR state and the related Resource Listener receives an ERROR Resource Event.

After some seconds in the ERROR state, the Resource Listener implementation stops the bundle in order to preserve the quality of service.

The choice of the type of threshold (lower or upper, or both of them) depends on the type of resource and the needs of the Resource Monitoring Clients providing the Resource Listener. Other resources like the free memory may take advantage of a lower threshold.

A ResourceEvent instance is an event synchronously sent to a Resource Listener when one of its thresholds is reached. This event is notified to a Resource Listener through a call to ResourceListener.notify(ResourceEvent).

A Resource Event has a type among the following ones:

The Resource Listener instance analyzes this event by calling the following methods:

A ResourceContextListener instance receives notifications about Resource Context lifecycle and configuration.

A notification will be sent when:

An application which is interested in notifications has to register a Resource Context Listener instance as an OSGi service. The application may provide a set of properties at registration time to reduce the number of notifications a Resource Listener instance will receive. The available property is:

A Resource Context Listener instance is notified through a call to notify(ResourceContextEvent) method.

A ResourceContextEvent instance is an event sent to Resource Context Listener instances through a call to the notify(ResourceContextEvent) method.

A Resource Context Event has a type among the four following ones:

In the case of a RESOURCE_CONTEXT_CREATED event or a RESOURCE_CONTEXT_REMOVED event, a call to getContext() returns the targeted Resource Context instance.

In the case of a BUNDLE_ADDED type or BUNDLE_REMOVED type, getBundleId() returns the id of the bundle to be added to or removed from. The related Resource Context instance is given by a call to getContext().

The ResourceMonitoringService manages the Resource Context instances. The Resource Monitoring Service is available through the OSGi service registry.

This service holds the existing Resource Context instances. Resource Context instances are created by calling the createContext(String,ResourceContext) method. The caller provides a context name as a string and optionally a template as a ResourceContext object.

The list of existing Resource Context instances can be retrieved through the following methods:

The Resource Monitoring Service singleton manages the persistence of the Resource Context instances. The following properties are stored:

The way the Resource Monitoring Service persists the Resource Context instances is implementation specific. The implementer is free to use any file format and file location it wants. At startup, the Resource Monitoring Service will load the persisted Resource Context instances to restore the state prior to shutdown.

A Resource Monitoring Client uses the Resource Monitoring Service singleton instance to apply Resource Monitoring policies. These entities MAY:

These policies are out of the scope of this specification.

It is recommended that ServicePermission[ResourceMonitoringService|ResourceMonitoringFactory|ResourceListener, REGISTER|GET] be used sparingly and only for bundles that are trusted.