Framework Measurement

The Framework Measurement module provides a universal model for measuring important runtime parameters, such as startup time, used memory and count of active threads, of bundles as well as of the framework itself.

The framework loads the Framework Measurement module only if one of the system properties for turning measuring on is true.

Contents:

• Measurement Methods
• Framework Measurement Interface
• Framework Measurement Implementations
  • Default Framework Measurement
  • Native Framework Measurement
    • Windows, Linux and QNX
    • Symbian Series 80
  • Configuring Measured Parameters and Their Display
  • Custom Framework Measurement
• Periodic Memory Measurement
• Setup
• References

Measurement Methods

Basically, the Framework Measurement module supports two ways of measurement:

• Triggering a specific measurement event - The Framework Measurement module will launch measurement for the specified event type. Initially, three measurement event types are supported:
  • End of JVM startup - The JVM process has just started successfully.
  • Begin shutdown - The JVM process is to be shut down.
  • Memory - Memory measurement should be done.
• Logging values of measured parameters - Bundles are able to log directly measured parameter. Optionally, logged measurements can be displayed in the native environment of the device.

Framework Measurement Interface

Framework Measurement is represented by the com.prosyst.mbs.framework.measurement.FrameworkMeasurement interface.

Framework Measurement Implementations

ProSyst provides two implementations of the Framework Measurement module - default and native.

Default Framework Measurement

Default Framework Measurement prints the results to the standard output. It is able to perform memory measurements – presently only used heap memory measurements. It also provides information about the number of active threads, and performs periodic memory measurements (see "Periodic Memory Measurement").

Native Framework Measurement

Native Framework Measurement sends the measurements to a native agent, which measures some parameters on OS native level. In addition to the heap memory measurements, that Default Framework Measurement is capable to perform, the native agent is able to measure framework process memory and flash memory.

Native Framework Measurement provides information about the number of the active threads and performs periodic memory measurements similarly to Default Framework Measurement.

The parameters that the Native Framework Measurement will check are specified by means of system properties as described in "Configuring Measured Parameters and Their Display".

Windows, Linux and QNX

To successfully make the framework use the Native Framework Measurement:

1. Include the lib/runtimes/<os_name> directory in your system path:
2. Set the mbs.measurements.class system property to com.prosyst.mbs.impl.framework.module.measurement.NativeFrameworkMeasurementImpl in the command line or in the JVM-specific framework starting script located in the bin/vms/<vm_name> directory.

Symbian Series 80

The OSGi Logger is a native implementation of the Framework Measurement module for Series 80 devices like Nokia 9500 Communicator. The OSGi Logger application launches an mBS image on the Series 80 device and then displays the logged measurements on the device screen.

Note that the OSGi Logger cannot be used on the Series 80 SDK.

Prerequisites: First of all, to be able to use the OSGi Logger, you have to transfer on the device the mBS image whose performance parameters will be measured (see "Deployment on Symbian Devices"). Note that the mBS image should have at least the following system properties configured in the .j9 launch script:

• mbs.measurements.class should be set to com.prosyst.mbs.impl.framework.module.measurement.NativeFrameworkMeasurementImpl
• mbs.measurements.full should be set to true

For more information about the measurement system properties, refer to the "Setup" section and the "System Properties" document.

The OSGi Logger application consists of the following components:

• Symbian native GUI - Provides a shortcut to the OSGi Logger from the application desk
• Measurement shared library - Implements the Framework Measurement module by measuring resource consumption straight from the OS
• Configuration file - Contains the path to the mBS storage and .j9 launch script

Basically to deploy the OSGi Logger on the Series 80 device, you have to do the following:

1. Copy the content from the following directories to the device file system:
   
   

   Source on the PC Destination on the Device Description <mbs_install_dir>/lib/runtimes/symbian/7.0s/ <environment>/system/apps/OSGiLogger C:\system\apps\OSGiLogger Contains the OSGi Logger native GUI <mbs_install_dir>/lib/runtimes/symbian/7.0s/ <environment>/system/libs/measurement.* C:\system\libs Contains the measurement shared library.

2. Create a directory, called OSGiLogger, on the C: Series 80 drive to hold the configuration file.
3. Create the configuration file for the OSGiLogger directory. It should be called osgilogger.cfg and should contain the location of the mBS storage, the mBS .j9 launch file and to a log file to write measured data into. The osgilogger.cfg should have the following format:
   
   

   LOG-FILE=C:\osgi\log.txt DIRECTORY=C:\osgi\bin\vms\j9\storage J9-SCRIPT=C:\osgi\bin\vms\j9\server.j9

   Listing 1: An example osgilogger.cfg file
4. Transfer the osgilogger.cfg to the C:\OSGiLogger directory on the device.

Tip: For convenience, you can create a .sis installation file for installing the OSGi Logger application to the device.

After the OSGi Logger is placed on the device, the OSGiLogger shortcut appears on application desk.

Tip: If the OSGi Logger has been deployed on the device by simply copying its components, restart the device to have the OSGiLogger shortcut displayed on the application desk.

Use the OSGiLogger shortcut to start the measurement process. The content of the measurement log is displayed on the screen. To save it, press the Save command button. To scroll the content, use Up and Down. To exit the logger, use the Exit command button.

Configuring Measured Parameters and Their Display

The Framework Measurement implementations accept a number of system properties related to the parameters they measure. For more information about measurement system properties, refer to the "System Properties" document.

Custom Framework Measurement

If you want to develop a custom implementation of the Framework Measurement module, implement the interface, add the implementation class file to the classpath and set the mbs.measurements.class system property to the name of the implementation class.

Tip: Most common measurement types, that can be implemented in the trigger method, are provided as FrameworkMeasurement fields and can be optionally configured as system properties.

Periodic Memory Measurement

Both implementations of the Framework Measurement module start a thread, which periodically triggers measurement of consumed memory. The measurement period in minutes can be configured with the mbs.measurements.period system property. The default period is 10 minutes.

Setup

The operation of the Framework Measurement module in the framework can be configured by a number of system properties. These system properties must be specified in the command line or in the framework starting script as the framework loads the module prior to reading the content of its properties file (i.e. default.prs by default).

The framework loads the Framework Measurement module only if one of the following system properties is set to true in the command line or in the framework starting script:

• mbs.measurements.full
• mbs.measurements.setup
• mbs.measurements.intermediate

For more information about the full collection of measurement system properties, refer to the "System Properties" document.

References

• Framework Measurement API
• Deployment on Symbian Devices
• System Properties

Framework Architecture