Skip to content

Toro Cloud Dev Center


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 Only1. 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.

Viewing monitor rules

Viewing monitor rules

Creating a new monitor rule

To create a new monitor rule using the Throttling & Monitoring Rules dialog:

Creating a new monitor rule

Creating a new monitor rule

  1. Go to the Monitor Rules tab.
  2. Click the green, '+' labled, circular button next to the search text field.
  3. Populate the appearing form with the configuration you want for your rule.
  4. Click Save.

Updating a monitor rule

To update an existing monitor rule using the Throttling & Monitoring Rules dialog:

Updating an existing monitor rule

Updating an existing monitor rule

  1. Go to the Monitor Rules tab.
  2. Select the rule you want to update from the list of existing rules.
  3. Click the edit button located between the add and delete button.
  4. Update the appearing form with the configuration you want for your rule.
  5. 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.

Enabling a monitor rule

Enabling a monitor rule

Removing a monitor rule

To delete an existing monitor rule using the Throttling & Monitoring Rules dialog:

Deleting a monitor rule

Deleting a monitor rule

  1. Go to the Monitor Rules tab.
  2. Select the rule you want to update from the list of existing rules.
  3. Click the delete button located below the edit button (or use the delete menu item as shown in the screenshot above).
  4. Confirm your action.

  1. Not to be confused with Marketplace users.