|
Generated: Wed Apr 20 14:41:06 BST 2005 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
An interface defining access to a monitoring service. The main purpose is to monitor how many requests were done and how much time they took.
The requests are mainly assumed to be identical to the Web Services operations (that was the original idea behind this small project). Therefore and even though, most implementations of this interface aim to Web Services, there is nothing to prevent to use this interface and to implement it for monitoring other things (such as a usual Java method profiling).
In oder to be able to implement smoothly a monitoring service itself as a web service, this interface uses only limited data structures, and if even them are too complex for some client programming languages, it also allows to receive monitored data as XML strings.
The terminology used in this interface starts with a service which is represented (usually) by a Web Service (but it can be any entity that is supposed to be monitored). Then each service consists of one or more requests. A request is (aain, usually) represented by one call from a client to this Web Service. It corresponds with a SOAP operation.
Field Summary | |
static int |
CUMULATED_FOR_REQUESTS
A level indicating that the returned date should be cumulated on a request level. |
static int |
CUMULATED_FOR_SERVICES
A level indicating that the returned date should be cumulated on a service level. |
static java.lang.String |
DATA_INPUT_LENGTH
A name used to identify metadata. |
static java.lang.String |
DATA_OUTPUT_LENGTH
A name used to identify metadata. |
static java.lang.String |
NAME_DELIMITER
A string serving as a delimiter when both a unique name and a display name are returned. |
static int |
NOT_CUMULATED
A level indicating that the returned date should not be cumulated at all. |
static int |
ONLY_RUNNING_SERVICES
A value used in 'periodFrom' and 'periodTo' in the get(int, java.lang.String[], long, long, java.lang.String[])
method to indicate that only records about still running
services should be selected. |
Method Summary | |
java.lang.String[] |
availableAllMetadata()
Return a list of names of all available metadata, disregarding which service they were registered for. |
java.lang.String[] |
availableMetadata(java.lang.String serviceName)
Return a list of names of metadata available for given service. |
java.lang.String[] |
availableServices()
Return a list of names of services this monitoring service has some data about. |
CollectedData[] |
get(int level,
java.lang.String[] serviceNames,
long periodFrom,
long periodTo,
java.lang.String[] metadataNames)
Return data that had been logged here by the log
method. |
java.lang.String |
getAsXML(int level,
java.lang.String[] serviceNames,
long periodFrom,
long periodTo,
java.lang.String[] metadataNames)
|
void |
log(java.lang.String serviceEndpoint,
java.lang.String serviceName,
java.lang.String requestId,
java.lang.String recordId,
java.lang.String sender,
long startedAt,
long elapsedTime,
Metadata[] metadata)
Report (log) run-time information to a monitoring service. |
Field Detail |
public static final java.lang.String DATA_INPUT_LENGTH
public static final java.lang.String DATA_OUTPUT_LENGTH
public static final int NOT_CUMULATED
get
,
Constant Field Valuespublic static final int CUMULATED_FOR_SERVICES
get
,
Constant Field Valuespublic static final int CUMULATED_FOR_REQUESTS
get
,
Constant Field Valuespublic static final int ONLY_RUNNING_SERVICES
get(int, java.lang.String[], long, long, java.lang.String[])
method to indicate that only records about still running
services should be selected.
public static final java.lang.String NAME_DELIMITER
availableServices
,
Constant Field ValuesMethod Detail |
public void log(java.lang.String serviceEndpoint, java.lang.String serviceName, java.lang.String requestId, java.lang.String recordId, java.lang.String sender, long startedAt, long elapsedTime, Metadata[] metadata) throws BionannyException
serviceEndpoint
- is a unique identifier for a service who
makes the reportserviceName
- is a name of the same service; it must be
unique within 'serviceEndpoint' (meaning: two services with two
different endpoints may have the same service name); it has
meaning as a "display name", nothing else; if you use two
different service names within the same serviceEndpoint, there
is no guarantee that both will be rememberedrequestId
- is a unique identifier within a
'serviceEndpoint', specifying the request (usually it means a
name of the requested operation); it may be emptyrecordId
- is a unique identifier of this logging call
(within serviceEndpoint and requestId). It is supposed to be
used only in cases that the current logged information is not
complete and there will be later another 'log' call to complete
the same event. The 'recordId' is here to pair (match) the two
calls together. The semantics of the next call is to replace everything what is the new call but keep things that were recorded by the first call and are empty in the second one. The implementation is allowed (for the optimalization reasons) to keep the unfinished records only until the second call.
Note that this information is not available in the
otherwise symmetric get(int, java.lang.String[], long, long, java.lang.String[])
method.
sender
- identifies who is making this request; it may be
empty startedAt
- in milliseconds, when the logged event
started. This can be empty - in which case the implementation
uses the current time of recording. This is meant mainly for
cases when the same event is logged twice (see parameter
'recordId' above) - once at its beginning and once when it
ends. In such cases may be important to say what was the exact
start of the even because the current time may not be good
enough, especially when the logging is done over the network,
on a different machine. elapsedTime
- in milliseconds how long took to fulfill
this request (or service if the requestId is empty) metadata
- is a set of name/value pairs specifying
additional data related to this request, or service;
some common names are defined in this interface
BionannyException
public CollectedData[] get(int level, java.lang.String[] serviceNames, long periodFrom, long periodTo, java.lang.String[] metadataNames) throws BionannyException
log
method. The returned data can be cumulated on the requested
level. Data can also be selected in order to contain any combination of:
log
implementation)
level
- of cumulation, can be one of: NOT_CUMULATED
, CUMULATED_FOR_SERVICES
, CUMULATED_FOR_REQUESTS
serviceNames
- is a list of services whose data should be
returned; the available service names can be obtained by the
availableServices()
method; if empty then data for all
available services are returnedperiodFrom
- in millisecond from the beginning of Epoch
(1.1.1970), expressed in GMT, specifies a starting point of
interval the data will be returned for; a negative value means
relative period backwards from now; zero means that this
parameter is not specified; a special value is ONLY_RUNNING_SERVICES
- when both 'periodFrom' and 'periodTo'
are set to this value (which is a very small number that is
unlikely to collide with a real period) then the method returns
only services that has been started but has , but possitive,
not yet finishedperiodTo
- in millisecond from the beginning of Epoch
(1.1.1970), expressed in GMT, specifies an ending point of
interval the data will be returned for; a negative value means
relative period from now; zero means that this parameter is not
specified; see also 'periodFrom' about a special value ONLY_RUNNING_SERVICES
metadataNames
- can limit what metadata should be returned
BionannyException
public java.lang.String getAsXML(int level, java.lang.String[] serviceNames, long periodFrom, long periodTo, java.lang.String[] metadataNames) throws BionannyException
BionannyException
public java.lang.String[] availableServices() throws BionannyException
NAME_DELIMITER
BionannyException
public java.lang.String[] availableMetadata(java.lang.String serviceName) throws BionannyException
serviceName
- is one of names returned by availableServices
BionannyException
public java.lang.String[] availableAllMetadata() throws BionannyException
BionannyException
|
Generated: Wed Apr 20 14:41:06 BST 2005 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |