com.sap.util.monitor.jarm
Interface IMonitor

All Known Implementing Classes:

TaskMonitor

public interface IMonitor

Interface for all monitoring objects. A monitoring object provides mechanism for passing information concerning requests and components. Internally this information is used to provide (accumulated) information about threads, requests and components.

  General concept:
  - Request: main monitoring unit
  - Task: a request could be processed in several threads which run
          asynchronously; the work done by one thread is called a task;
          (in the current version there is a 1:1 relation between
           request and task -> one request is processed by one task)
  - Component: a component is the smallest unit of monitoring;
               a task is made up of several components which could be nested;

               in order to reduce monitoring overhead a component should
               need in average a reasonable amount of execution time
               (several ms)
  - Action: if it should be indicated which part of a component is currently
            processed an 'action' call should be done; neither monitoring
            data is stored nor timestamp information is collected,
            the 'action' is just shown in the thread overview
 

Some examples to describe the usage of the methods described below (assume: the class 'TaskMonitor' implements this interface):

1. Nested Components Example

    ...
    myMonitor = TaskMonitor.getRequestMonitor("MyUser", "MyRequest");
    myMonitor.startComponent("Component A");
     ...
     myMonitor.startComponent("Component B");
     ...
       myMonitor.startComponent("Component C");
       ...
       myMonitor.endComponent("Component C");
     ...
     myMonitor.endComponent("Component B");
     ...
     myMonitor.startComponent("Component D");
     ...
     myMonitor.endComponent("Component D");
     ...
    myMonitor.endComponent("Component A");
    int outputDataLen = response.calcDataLen();       // data length could be
    myMonitor.endRequest("MyRequest", outputDataLen); // provided optionally
  

-------------------------------------------------------------------

2. Usage of components which provides no monitoring information

    ...
    myMonitor = TaskMonitor.getRequestMonitor("MyUser", "MyRequest");
    myMonitor.startComponent("Component A");
     ...
     myMonitor.startComponent("ForeignComponent 1");
     ForeignComponent_A(...);  // sync call
     int outputDatalen = response.calcDataLen(); // data length could be
                                                // provided optionally
     myMonitor.endComponent("ForeignComponent 1", outputDataLen);
     ...
    outputDataLen = response.calcDataLen();   // data length could be
    myMonitor.endRequest(outputDataLen);      // provided optionally
  

--------------------------------------------------------------------

3. Usage of requests in different layers

Here it is shown how monitoring could be implemented in different layers (e.g. a I2EE server and a Bean)

    ...
    i2eeMonitor = TaskMonitor.getRequestMonitor("MyUser", "I2EERequest 1");
    i2eeMonitor.startComponent("I2EEComponent A");
     ...
     i2eeMonitor.startComponent("I2EE Bean 1");
     -  -   -   -   -   -   -  -  -  -  -  -  -  -  -  -  -  -  -  -
     ...
     beanMonitor = TaskMonitor.getRequestMonitor("MyUser", "BeanRequest 1");
                   // because there is already a monitor object (i2eeMonitor)
                   // this object is returned -> beanMonitor == i2eeMonitor
                   // if this would run in an i2ee which is not instrumented
                   // a new object would have been returned;
     beanMonitor.startComponent("beanComponent 1");
     ...
     beanMonitor.endComponent("beanComponent 1");
     beanMonitor.endRequest("BeanRequest 1");
                 // internally this call is skipped because the request's name
                 // is "I2EERequest 1"
     // be aware that instrumenting the bean is not dependant on the
     // surrounding layer (exception: there must be different names for
     // requests and components -> define namespaces); additionally like
     // all the other examples it does not matter whether monitoring is
     // on or off; if monitoring is off you get a dummy object which supports
     // IMonitor also
     ...
     -  -  -   -   -  -  -   -   -   -   -   -   -   -   -   -   -   -
     i2eeMonitor.endComponent("I2EE Bean 1");
                 // because of this coding even without instrumenting the
                 // bean you will collect monitoring information
                 // about the bean
     ...
    i2eeMonitor.endComponent("I2EEComponent A");
    outputDataLen = response.calcDataLen();
    myMonitor.endRequest("I2EERequest 1", outputDataLen);
  

--------------------------------------------------------------------

Method Summary

void	compAction(int compLevel, java.lang.String compName, java.lang.String action) Indicates a specific action of a component. The method is executed only if compLevel is lower or equal the current component monitoring level.
void	compAction(java.lang.String compName, java.lang.String action) Indicates a specific action of a component. Component monitor level = 0 (ConfMonitor.COMPLEVELBASIC)
void	endComponent(int compLevel, java.lang.String compName) Indicates the end of a component. The method is executed only if compLevel is lower or equal the current component monitoring level.
void	endComponent(int compLevel, java.lang.String compName, int dataLength) same functionality than endComponent(String); additionally the amount of data which is returned by the component is provided. The method is executed only if compLevel is lower or equal the current component monitoring level.
void	endComponent(int compLevel, java.lang.String compName, int dataLength, java.lang.Object compProps) same functionality than endComponent(String, int); additionally component specific properties are provided. the component specific properties could only be handled if the parameter jarm/comp/properties/switch=on (default) and if there is there is an implementation of ICompProperties for this component provided The method is executed only if compLevel is lower or equal the current component monitoring level.
void	endComponent(int compLevel, java.lang.String compName, java.lang.Object compProps) same functionality than endComponent(String); additionally component specific properties are provided. the component specific properties could only be handled if the parameter jarm/comp/properties/switch=on (default) and if there is there is an implementation of ICompProperties for this component provided. The method is executed only if compLevel is lower or equal the current component monitoring level.
void	endComponent(java.lang.String compName) Indicates the end of a component. Component monitor level = 0 (ConfMonitor.COMPLEVELBASIC)
void	endComponent(java.lang.String compName, int dataLength) same functionality than endComponent(String); additionally the amount of data which is returned by the component is provided. Component monitor level = 0 (ConfMonitor.COMPLEVELBASIC)
void	endComponent(java.lang.String compName, int dataLength, java.lang.Object compProps) same functionality than endComponent(String, int); additionally component specific properties are provided. the component specific properties could only be handled if the parameter jarm/comp/properties/switch=on (default) and if there is there is an implementation of ICompProperties for this component provided. Component monitor level = 0 (ConfMonitor.COMPLEVELBASIC)
void	endComponent(java.lang.String compName, java.lang.Object compProps) same functionality than endComponent(String); additionally component specific properties are provided. the component specific properties could only be handled if the parameter jarm/comp/properties/switch=on (default) and if there is there is an implementation of ICompProperties for this component provided. Component monitor level = 0 (ConfMonitor.COMPLEVELBASIC)
RequestOverview	endRequest(int retOverview, java.lang.String reqName) same functionality than endRequest(reqName); additionally the collected data for the request is returned if retOverview = true
RequestOverview	endRequest(int retOverview, java.lang.String reqName, int dataLength) same functionality than endRequest(String reqName, int dataLength); additionally the collected data for the request is returned
void	endRequest(java.lang.String reqName) if the name of the current request is identical to reqName the request is closed; otherwise the call is skipped.
void	endRequest(java.lang.String reqName, int dataLength) same functionality than endRequest(String reqName); additionally the amount of data which is returned by the request is provided
int	getComponentLevel() The component level for the request is returned.
boolean	getMonitorSwitch() Indicates whether monitoring is switched on or off for this request
java.lang.String	getReqName() Delivers the name of the request
long	getReqTS() Delivers the start timestamp of the request
boolean	getTraceSwitch() Indicates whether tracing is switched on or off for this request
java.lang.String	getUser() Delivers the user name of the request
boolean	isJarmActiveForRequest() Indicates whether monitoring or tracing is switched on or off for this request
void	setComponentLevel(int compLevel) The component monitor level for the request is set. The level could only be set right at the beginning of a request before the first component is started.
void	setDescription(java.lang.String descr) Set description for request (text string); if the description is already set for the request it could not be overwritten
void	setUser(java.lang.String userName) If the user name was not known when the request was started it could be set by this call afterwards; if a user name is already bound to the request the call is skipped
void	startComponent(int compLevel, java.lang.String compName) Indicates the start of a component. The method is executed only if compLevel is lower or equal the current component monitoring level.
void	startComponent(java.lang.String compName) Indicates the start of a component. Component monitor level = 0 (ConfMonitor.COMPLEVELBASIC)

Method Detail

endRequest

public void endRequest(java.lang.String reqName)

if the name of the current request is identical to reqName the request is closed; otherwise the call is skipped.

Parameters:

reqName - logical name of the request

endRequest

public void endRequest(java.lang.String reqName,
                       int dataLength)

same functionality than endRequest(String reqName); additionally the amount of data which is returned by the request is provided

Parameters:

reqName - logical name of the request

dataLength - amount of data in bytes which is returned from request

See Also:

endRequest(String)

endRequest

public RequestOverview endRequest(int retOverview,
                                  java.lang.String reqName)

same functionality than endRequest(reqName); additionally the collected data for the request is returned if retOverview = true

Parameters:

retOverview - ConfMonitor.REQOVERVIEWALL <-> return all collected monitoring data; ConfMonitor.REQOVERVIEWNONE <-> 'null' is returned ConfMonitor.REQOVERVIEWHEADER <-> only heeader information is returned, but no data about tasks or single components

reqName - logical name of the request

Returns:

monitor data collected for this request or 'null' if retOverview = ConfMonitor.REQOVERVIEWNONE, monitoring is switched off or reqName doesn't match the current request name

See Also:

endRequest(String)

endRequest

public RequestOverview endRequest(int retOverview,
                                  java.lang.String reqName,
                                  int dataLength)

same functionality than endRequest(String reqName, int dataLength); additionally the collected data for the request is returned

Parameters:

retOverview - ConfMonitor.REQOVERVIEWALL <-> return all collected monitoring data; ConfMonitor.REQOVERVIEWNONE <-> 'null' is returned ConfMonitor.REQOVERVIEWHEADER <-> only heeader information is returned, but no data about tasks or single components

reqName - logical name of the request

dataLength - amount of data in bytes which is returned from request

Returns:

monitor data collected for this request or 'null' if retOverview = ConfMonitor.REQOVERVIEWNONE, monitoring is switched off or reqName doesn't match the current request name

See Also:

endRequest(String, int)

startComponent

public void startComponent(java.lang.String compName)

Indicates the start of a component.
Component monitor level = 0 (ConfMonitor.COMPLEVELBASIC)

Parameters:

compName - logical name of the current component.

startComponent

public void startComponent(int compLevel,
                           java.lang.String compName)

Indicates the start of a component.
The method is executed only if compLevel is lower or equal the current component monitoring level.

Parameters:

compLevel - component monitor level; 0 (ConfMonitor.COMPLEVELBASIC), 1 (ConfMonitor.COMPLEVELMEDIUM), 2 (ConfMonitor.COMPLEVELDETAIL.

compName - logical name of the current component.

endComponent

public void endComponent(java.lang.String compName)

Indicates the end of a component.
Component monitor level = 0 (ConfMonitor.COMPLEVELBASIC)

Parameters:

compName - logical name of the current component.

endComponent

public void endComponent(java.lang.String compName,
                         int dataLength)

same functionality than endComponent(String); additionally the amount of data which is returned by the component is provided.
Component monitor level = 0 (ConfMonitor.COMPLEVELBASIC)

Parameters:

compName - logical name of the current component.

dataLength - amount of data in bytes which is returned by the component

See Also:

endComponent(String)

endComponent

public void endComponent(java.lang.String compName,
                         java.lang.Object compProps)

same functionality than endComponent(String); additionally component specific properties are provided.
the component specific properties could only be handled if the parameter jarm/comp/properties/switch=on (default) and if there is there is an implementation of ICompProperties for this component provided.
Component monitor level = 0 (ConfMonitor.COMPLEVELBASIC)

Parameters:

compName - logical name of the current component.

compProps - component specific properties

endComponent

public void endComponent(java.lang.String compName,
                         int dataLength,
                         java.lang.Object compProps)

same functionality than endComponent(String, int); additionally component specific properties are provided.
the component specific properties could only be handled if the parameter jarm/comp/properties/switch=on (default) and if there is there is an implementation of ICompProperties for this component provided.
Component monitor level = 0 (ConfMonitor.COMPLEVELBASIC)

Parameters:

compName - logical name of the current component.

dataLength - amount of data in bytes which is returned by the component

compProps - component specific properties

endComponent

public void endComponent(int compLevel,
                         java.lang.String compName)

Indicates the end of a component.
The method is executed only if compLevel is lower or equal the current component monitoring level.

Parameters:

compLevel - component monitor level; 0 (ConfMonitor.COMPLEVELBASIC), 1 (ConfMonitor.COMPLEVELMEDIUM), 2 (ConfMonitor.COMPLEVELDETAIL.

compName - logical name of the current component.

endComponent

public void endComponent(int compLevel,
                         java.lang.String compName,
                         int dataLength)

same functionality than endComponent(String); additionally the amount of data which is returned by the component is provided.
The method is executed only if compLevel is lower or equal the current component monitoring level.

Parameters:

compLevel - component monitor level; 0 (ConfMonitor.COMPLEVELBASIC), 1 (ConfMonitor.COMPLEVELMEDIUM), 2 (ConfMonitor.COMPLEVELDETAIL.

compName - logical name of the current component.

dataLength - amount of data in bytes which is returned by the component

See Also:

endComponent(String)

endComponent

public void endComponent(int compLevel,
                         java.lang.String compName,
                         java.lang.Object compProps)

same functionality than endComponent(String); additionally component specific properties are provided.
the component specific properties could only be handled if the parameter jarm/comp/properties/switch=on (default) and if there is there is an implementation of ICompProperties for this component provided.
The method is executed only if compLevel is lower or equal the current component monitoring level.

Parameters:

compLevel - component monitor level; 0 (ConfMonitor.COMPLEVELBASIC), 1 (ConfMonitor.COMPLEVELMEDIUM), 2 (ConfMonitor.COMPLEVELDETAIL.

compName - logical name of the current component.

compProps - component specific properties

endComponent

public void endComponent(int compLevel,
                         java.lang.String compName,
                         int dataLength,
                         java.lang.Object compProps)

same functionality than endComponent(String, int); additionally component specific properties are provided.
the component specific properties could only be handled if the parameter jarm/comp/properties/switch=on (default) and if there is there is an implementation of ICompProperties for this component provided The method is executed only if compLevel is lower or equal the current component monitoring level.

Parameters:

compLevel - component monitor level; 0 (ConfMonitor.COMPLEVELBASIC), 1 (ConfMonitor.COMPLEVELMEDIUM), 2 (ConfMonitor.COMPLEVELDETAIL.

compName - logical name of the current component.

dataLength - amount of data in bytes which is returned by the component

compProps - component specific properties

compAction

public void compAction(java.lang.String compName,
                       java.lang.String action)

Indicates a specific action of a component.
Component monitor level = 0 (ConfMonitor.COMPLEVELBASIC)

Parameters:

compName - logical name of the current component.

action - action currently done by the component.

compAction

public void compAction(int compLevel,
                       java.lang.String compName,
                       java.lang.String action)

Indicates a specific action of a component.
The method is executed only if compLevel is lower or equal the current component monitoring level.

Parameters:

compLevel - component monitor level; 0 (ConfMonitor.COMPLEVELBASIC), 1 (ConfMonitor.COMPLEVELMEDIUM), 2 (ConfMonitor.COMPLEVELDETAIL.

compName - logical name of the current component.

action - action currently done by the component.

isJarmActiveForRequest

public boolean isJarmActiveForRequest()

Indicates whether monitoring or tracing is switched on or off for this request

Returns:

true <-> monitoring or tracing is switched on (request still active)
false <-> neither monitoring nor tracing is switched on for this request or request already ended

getMonitorSwitch

public boolean getMonitorSwitch()

Indicates whether monitoring is switched on or off for this request

Returns:

true <-> monitoring is switched on (request still active)
false <-> monitoring is switched off for this request or request already ended

getTraceSwitch

public boolean getTraceSwitch()

Indicates whether tracing is switched on or off for this request

Returns:

true <-> tracing is switched on (request still active)
false <-> tracing is not switched on for this request or request already ended

getComponentLevel

public int getComponentLevel()

The component level for the request is returned. The level depends on the parameters IConfMonitor.COMPLEVEL and IConfMonitor.COMPTRACELEVEL. If monitoring is switched on and tracing is switched off IConfMonitor.COMPLEVEL is used. Vice versa it's IConfMonitor.COMPTRACELEVEL. If monitoring and tracing is switched on the most detailed level is used. At the beginning of a request before the first component is started the level could be overwritten by IMonitor.setComponentLevel().
After the first component is started the level is fixed for the whole request.

Returns:

component monitor level; 0 (ConfMonitor.COMPLEVELBASIC), 1 (ConfMonitor.COMPLEVELMEDIUM), 2 (ConfMonitor.COMPLEVELDETAIL.

getUser

public java.lang.String getUser()

Delivers the user name of the request

Returns:

name of user who executes the request; if name is null, ConfMonitor.UNDEFNAME is returned

getReqName

public java.lang.String getReqName()

Delivers the name of the request

Returns:

name of the request; if name is null, ConfMonitor.UNDEFNAME is returned

getReqTS

public long getReqTS()

Delivers the start timestamp of the request

Returns:

start timestamp of the request as it was measured with System.currentTimeMillis()

setUser

public void setUser(java.lang.String userName)

If the user name was not known when the request was started it could be set by this call afterwards; if a user name is already bound to the request the call is skipped

Parameters:

userName - name of user who executes the request

setDescription

public void setDescription(java.lang.String descr)

Set description for request (text string); if the description is already set for the request it could not be overwritten

Parameters:

descr - description

setComponentLevel

public void setComponentLevel(int compLevel)

The component monitor level for the request is set.
The level could only be set right at the beginning of a request before the first component is started. Otherwise the call is ignored. After the first component call the level is fixed for the whole request.

Parameters:

compLevel; - 0 (ConfMonitor.COMPLEVELBASIC), 1 (ConfMonitor.COMPLEVELMEDIUM), 2 (ConfMonitor.COMPLEVELDETAIL.