JBoss.orgCommunity Documentation
This section describes the "out of the box" additional services that are provided.
The "Call Trace" service is used to return a tree structure tracing the path of a business transaction (as a call/invocation stack) through a Service Oriented Architecture.
The URL for the service’s REST GET request is: <host>/overlord-rtgov/call/trace/instance?type=<type>&value=<value>
The service uses basic authentication, with a default username admin and password overlord.
This service has the following query parameters:
| Parameter | Description |
|---|---|
type | The type of the identify value, e.g. Conversation, Endpoint, Message or Link |
value | The identifier value, e.g. if type is Conversation, then the value would be a globally unique identifier for the business transaction |
The call trace is returned as a JSON representation of the call trace object model. The top level class is org.overlord.rtgov.call.trace.model.CallTrace, details can be found in the API documentation.
As of version 2.0, the report server is deprecated, indicating that it will be removed from the project in a future release. Therefore we suggest that you should not start using it, and if already using it, plan to migrate off this capability in the new future. The capability is being deprecated as more sophisticated analysis and reporting can be achieved through the Kibana/Elasticsearch tools, which are now integrated from RTGov 2.0.
The "Report Server" service is used to generate instances of a report whose definition has previously been deployed to the server. This section will explain how to configure and deploy a report definition, and then how to generate the report instances.
The first step is to specify a JSON representation of the org.overlord.rtgov.reports.ReportDefinition class (see API documentation for details).
[
{
"name" : "SLAReport",
"generator" : {
"@class" : "org.overlord.rtgov.reports.MVELReportGenerator",
"scriptLocation" : "SLAReport.mvel"
}
}
]
The report definition only contains the name of the report, and the definition of the generator. In this case, the org.overlord.rtgov.reports.MVELReportGenerator implementation of the report generator has been used, which also includes a property to define the location of the report script (e.g. SLAReport.mvel). This MVEL SLA report script can be found in the samples/sla/report folder.
JEE Container
The Report Definition is deployed within the JEE container as a WAR file with the following structure:
warfile | |-META-INF | |- beans.xml | |-WEB-INF | |-classes | | |-reports.json | | |-<custom classes/resources> | | | |-lib | |-reports-loader-jee.jar | |-<additional libraries>
As described above, the reports.json file contains the JSON representation of the report definition configuration.
The reports-loader-jee.jar acts as a bootstrapper to load and register the Report Definition.
If custom report generators or scripts are defined, then the associated classes and resources can be defined in the WEB-INF/classes folder or within additional libraries located in the WEB-INF/lib folder.
A maven pom.xml that will create this structure is:
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>....</groupId>
<artifactId>....</artifactId>
<version>....</version>
<packaging>war</packaging>
<name>....</name>
<properties>
<rtgov.version>....</rtgov.version>
</properties>
<dependencies>
<dependency>
<groupId>org.overlord.rtgov.activity-analysis</groupId>
<artifactId>reports-loader-jee</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.overlord.rtgov.activity-analysis</groupId>
<artifactId>reports</artifactId>
<version>${project.version}</version>
<scope>test</scope>
</dependency>
....
</dependencies>
</project>
If deploying in JBoss Application Server, then the following fragment also needs to be included, to define the dependency on the core Overlord Runtime Governance modules:
..... <build> <finalName>slamonitor-epn</finalName> <plugins> <plugin> <artifactId>maven-war-plugin</artifactId> <configuration> <failOnMissingWebXml>false</failOnMissingWebXml> <archive> <manifestEntries> <Dependencies>deployment.overlord-rtgov.war</Dependencies> </manifestEntries> </archive> </configuration> </plugin> </plugins> </build> .....
The URL for the service’s REST GET request is: <host>/overlord-rtgov/report/generate?<parameters>
The service uses basic authentication, with a default username admin and password overlord.
This service has the following query parameters:
| Parameter | Description |
|---|---|
report | The name of the report to be generated. This must match the previously deployed report definition name. |
startDay/Month/Year | The optional start date for the report. If not defined, then the report will use all activities stored up until the end date. |
endDay/Month/Year | The optional end date for the report. If not defined, then the report will use all activities up until the current date. |
timezone | The optional timezone. |
calendar | The optional business calendar name. A default called exists called Default which represents a working week of Monday to Friday, 9am to 5pm, excluding Christmas Day. |
All other query parameters that may be provided will be specific to the report definition being generated.
The operation returns a JSON representation of the org.overlord.rtgov.reports.model.Report class. See the API documentation for further details of the object model.
A custom Business Calendar can be defined as a JSON representation of the org.overlord.rtgov.reports.mode.Calendar class (see API documentation for details). This should be stored in a file whose location is referenced using a property called "calendar.<CalendarName>" in the overlord-rtgov.properties file.
The "Service Dependency" service is used to return a service dependency graph as a SVG image. The graph represents the invocation and usage links between services (and their operations), and provides a color-coded indication of areas that require attention. Where situations have been detected against services or their operations, this will be flagged on the service dependency graph with an appropriate colour reflecting their severity.
The URL for the service’s REST GET request is: <host>/overlord-rtgov/service/dependency/overview?width=<value>
The service uses basic authentication, with a default username admin and password overlord.
This service has the following query parameters:
| Parameter | Description |
|---|---|
width | Represents the optional image width. If the width is below a certain threshold, then a summary version of the dependency graph will be provided without text or tooltips (used to display metrics). |
The severity levels used for the graph nodes and links can be customized by creating a MVEL script. A default script is provided within the overlord-rtgov.war, which can be used as a template. The script is called SeverityAnalyzer.mvel and is located within the /WEB-INF/classes folder of the overlord-rtgov.war archive.
An example of the contents of this script is:
Severity severity=Severity.Normal;
if (summary != null && latest != null && summary.getAverage() > 0) {
double change=latest.getAverage()/summary.getAverage();
if (change > 0) {
if (change > 3.0) {
severity = Severity.Critical;
} else if (change > 2.2) {
severity = Severity.Serious;
} else if (change > 1.8) {
severity = Severity.Error;
} else if (change > 1.4) {
severity = Severity.Warning;
} else if (change > 1.2) {
severity = Severity.Minor;
}
}
}
return (severity);
The script returns a value of type org.overlord.rtgov.service.dependency.presentation.Severity, which is automatically available as an imported class for use by the script.
The script takes four variables:
| Variable | Description |
|---|---|
summary | The summary metric to be evaluated. |
history | The list of recent metrics, merged to produce the summary metric. |
latest | The latest metric. |
component | The service definition component associated with the metric. This variable is not used within the example script above. |
If a customized script is created, then its location can be specified in the MVELSeverityAnalyzer.scriptLocation property in the overlord-rtgov.properties configuration file.
The "Situation Manager" service is used to determine whether situations associated with a particular subject (i.e. service) should be displayed to users via the Situations gadget. The service supports two operations.
The service uses basic authentication, with a default username admin and password overlord.
The ignore operation is used to indicate that situations for a particular subject (i.e. generally a service type) should not be presented to users via the REST service (and therefore the Situations gadget).
The URL for the ignore operation’s POST request is: <host>/overlord-rtgov/situation/manager/ignore
This request supplies a JSON representation of the org.overlord.rtgov.analytics.situation.IgnoreSubject class. See the API documentation for more information.
The operation responds with a status message indicating whether the operation was successful.
Currently wildcards are not supported for subjects.
The observe operation is used to essentially reverse the actions performed by a previous ignore operation, to make situations for a particular subject (i.e. generally a service type) visible again to users via the REST service (and therefore the Situations gadget).
The URL for the observe operation’s POST request is: <host>/overlord-rtgov/situation/manager/observe
This request supplies a JSON representation of the org.overlord.rtgov.analytics.situation.IgnoreSubject class. See the API documentation for more information.
The operation responds with a status message indicating whether the operation was successful.