Monarch's analytics engine is completely configurable and uses simple YAML files for describing the events it will capture. You can find documentation for using the Analytics API to pull report data on the API Reference page.


Each event has the following configuration elements:


  • name - The name of the event
  • display - The display name that will show in the admin console's user interface
  • timezone - The timezone to use for time stamping the events. "default" will use the system's timezone, or any in this list are valid.
  • fields - An array of fields which are described below
  • processors - An array of processors which are described below
  • indexes - An array of indexes which are described below


Each field is stored in the event and can be used for building reports.

  • name - The name of the field
  • display - The display name that will show in the admin console's user interface
  • storeAs - The storage name in the analytics database. This is typically shortened in order to preserve space.
  • type - Can be one of the following data types:
    • string - A textual value
    • boolean - A true or false value
    • integer - An integer value
    • decimal - A real number
    • object - A nested object with any structure
    • array - An array of any of the above
    • code - An integer value but used as a count
  • usage - How the field is used by the engine. Valid values are:
    • dimension - A field that can be used for querying or filtering
    • measure - A field that can be graphed in a time series or chart
    • required - A flag that denotes if the field is required in order for the event to be captured
    • defaultValue - The default value to use if a value is not provided
    • refersTo - Indicates that the field relates to an identifier of an entity stored in Monarch (e.g. Application, Client, Service)


Processors are a pre-processing step taken on the event before it is captured. Monarch's packaged processors are described below.

  • name - The name of the processor. Must match one of the names below or a custom processor that you've built.
  • args - The list of arguments to pass to the processor, as string values.


  • name - The name of the index
  • on - The field names to index (do not use their storeAs name). You should consider the order in which to put these. Queries will be faster if the most unique field is first (e.g. age before sex), however, it's not always the most useful index. A covering index more easily optimizes drill down queries (e.g. service to service + operation name).

Adding Your Own Events

Monarch's traffic event is configured in conf/traffic.yaml. In order to add your own event, simply create a new YAML configuration and add it to the analyticsConfigurationFactory bean in conf/context-services.xml. Be careful creating/editing YAML files! The indentation can be tricky. For example, you will likely receive errors if you mix tabs and spaces for indentation. It is recommended you use a smart text editor, like Sublime Text.

Packaged Processors


Arguments: None

This validator simply checks to make sure that all required fields were provided. Also, if the field was not provided but has a default value, the default value is set.

MaxMind-GeoIP2 Processor


  • IP field name (e.g. client_ip)

Determines an approximate latitude and longitude coordinate for an IP address. Monarch uses this for geo-targeting individual API request origins.

This processor uses Maxmind for geo-targeting. The conf/GeoLite2-City.mmdb database file is from the free version of their GeoIP City product and is updated the first Tuesday of each month from Maxmind. You can also purchase/subscribe to their more actuate data set.