Monitor rules
Martini uses monitor rules so it knows which service invocations to log, and how to monetize these invocations. Only service invocations that have matched with a monitor rule will be logged to the database and Solr.
Properties
Monitor rules are defined through the following configurable properties:
Name | Required | Default value | Description |
---|---|---|---|
Name | true | "name" |
A unique identifier for the rule. |
Description | false | A description of what the rule is for. | |
Enabled | false | false |
Indicates whether the rule is active or inactive; no checks are done for inactive rules. |
Priority | true | 0 |
Influences the order by which Martini checks matches for rules; the lower the number, the higher the priority. An invocation may only match one rule, and in the event that many rules are applicable, Martini will choose the rule with the highest priority. |
Callback Service | false | The service to be executed when a rule is matched. | |
Filter | true | Generic |
A filter for qualifying which service invocations to log. Options are: Generic , Endpoint and HTTP . Endpoint matches invocations made through Martini endpoints only; HTTP for invocations made through HTTP requests only; and Generic for both. |
URL Patterns | false | Only appears when using the HTTP filter. Matches Http request using ant-style patterns |
|
Endpoint Types | false | Only appears when using the Endpoint filter. Collection of endpoint types the invocation should originate from in order to match the rule. An empty list of types means the rule is applicable to all endpoints, regardless of type. |
|
Endpoint Names | false | Only appears when using the Endpoint filter. Martini endpoints (identified by name) the invocation should originate from in order to match the rule. An empty list of types means the rule is applicable to all endpoints, regardless of name. |
|
Cost | false | 0 |
The numeric cost of a matched service invoke. Although possible, this doesn't have to be a monetary value. This can be any number used to compute usage. |
Users | true | Everyone |
Group of users the rule is applicable to. Options are: Everyone , Anonymous Users Only , Martini Users Only 1. Selecting Everyone means even requests from Marketplace users would be included. |
Packages | false | Martini packages the rule is applicable to. An empty package list means the rule is applicable to all packages. | |
Services | false | Services the rule is applicable to. An empty service list means the rule is applicable to all services. |
Callback service
A callback service gets invoked when a matching rule is found. It runs before the requested service (that which matched the rule), and can determine whether or not the requested service can be invoked.
The callback service's return value is used in determining whether or not to allow a service invocation. To help implement your logic, you can use the parameters/inputs Martini will pre-populate for the callback service (like what it does for endpoint invocations).
The requested service will get invoked only when:
- the returned value of the callback service is
true
; or - the configured return type is
void
.
The requested service will NOT get invoked when:
- the returned value of the callback service is
false
; or - an exception is thrown by the callback service.
Exception on callback service during HTTP invocation
When an exception is thrown on a callback service triggered by an HTTP invocation, Martini will send the exception back as the server's HTTP response.
HTTP invocation parameters
Name | Type | Description |
---|---|---|
ruleEngine |
io.toro.martini.rengine.RuleEngine |
The engine that was used for rule evaluation. |
request |
javax.servlet.http.HttpServletRequest |
The request involved in invoking the target service. |
response |
javax.servlet.http.HttpServletResponse |
The response involved in invoking the target service. |
monitorService |
io.toro.martini.monitor.MonitorService |
Monitor Service object. |
invokeDocumentBuilder |
io.toro.martini.monitor.HttpInvokeDocument.Builder |
The precreated HttpInvokeDocument builder. The builder properties are already populated by default. Users can modify the builder properties to their liking to customize the data that will be stored in the invoke document database. |
martiniPackage |
io.toro.martini.ipackage.MartiniPackage |
The Martini Package involved in invoking the target service. |
packageServiceMeta |
io.toro.martini.service.PackageServiceMeta |
Martini Package metadata involved in invoking the target service. |
ruleMetadata |
io.toro.martini.monitor.MonitorRuleMetadata |
The rule metadata that was matched. |
fact |
io.toro.martini.monitor.HttpFact |
The input of the rule engine. |
invokeKind |
java.lang.String |
The type of invocation. Value is always http . |
packageName |
java.lang.String |
The Martini Package name involved in invoking the target service. |
serviceName |
java.lang.String |
The target service that will be invoked. |
user |
java.security.Principal |
Authenticated user used for invoking the target service. |
userGroup |
java.util.Set<java.lang.String> |
The user group(s) the authenticated user belongs to. |
Endpoint invocation parameters
Name | Type | Description |
---|---|---|
ruleEngine |
io.toro.martini.rengine.RuleEngine |
The engine that was used for rule evaluation. |
invokeDocumentBuilder |
io.toro.martini.monitor.EndpointInvokeDocument.Builder |
The pre-created EndpointInvokeDocument builder. The builder properties are already populated by default. Users can modify the builder properties to their liking to customize the data that will be stored in the invoke document database. |
monitorService |
io.toro.martini.monitor.MonitorService |
Monitor Service object. |
endpoint |
io.toro.martini.endpoint.Endpoint |
The endpoint that was responsible for invoking the target service. |
endpointName |
java.lang.String |
The endpoint name that was responsible for invoking the target service. |
endpointType |
java.lang.String |
The endpoint type that was responsible for invoking the target service. |
martiniPackage |
io.toro.martini.ipackage.MartiniPackage |
The Martini Package involved in invoking the target service. |
packageServiceMeta |
io.toro.martini.service.PackageServiceMeta |
Martini Package metadata involved in invoking the target service. |
ruleMetadata |
io.toro.martini.monitor.MonitorRuleMetadata |
The rule metadata that was matched. |
fact |
io.toro.martini.monitor.EndpointFact |
The input of the rule engine. |
invokeKind |
java.lang.String |
The type of invocation. Value is always endpoint . |
packageName |
java.lang.String |
The Martini Package name involved in invoking the target service. |
serviceName |
java.lang.String |
The target service that will be invoked. |
user |
java.security.Principal |
User used for invoking the target service. |
userGroup |
java.util.Set<java.lang.String> |
The user group the user belongs to. |
Viewing monitor rules
To view an instance's rules, open the Throttling & Monitoring Rules dialog. To open the dialog, right click on your instance and then click Throttling and Monetization from the context menu. Select the Monitor Rules tab to view existing monitor rules.
Creating a new monitor rule
To create a new monitor rule using the Throttling & Monitoring Rules dialog:
- Go to the Monitor Rules tab.
- Click the green, '+' labled, circular button next to the search text field.
- Populate the appearing form with the configuration you want for your rule.
- Click Save.
Updating a monitor rule
To update an existing monitor rule using the Throttling & Monitoring Rules dialog:
- Go to the Monitor Rules tab.
- Select the rule you want to update from the list of existing rules.
- Click the edit button located between the add and delete button.
- Update the appearing form with the configuration you want for your rule.
- Click Save.
Enabling or disabling a monitor rule
Aside from toggling the Enabled checkbox in the form, you can also use the context menu to enable or disable a monitor rule. To do this, right click the monitor rule you want to enable or disable, and then select Enable or Disable from the appearing context menu.
Removing a monitor rule
To delete an existing monitor rule using the Throttling & Monitoring Rules dialog:
- Go to the Monitor Rules tab.
- Select the rule you want to update from the list of existing rules.
- Click the delete button located below the edit button (or use the delete menu item as shown in the screenshot above).
- Confirm your action.
-
Not to be confused with Marketplace users. ↩