Custom Metrics · inspectIT Ocelot Documentation

One of the main benefits of inspectIT Ocelot is that it givers you complete freedom in what data you want to capture and how you want to capture it. You can easily define custom performance and business metrics depending on your needs.

In this section we explain how you can define custom OpenCensus metrics and views. We only show how to define the structure of both, not how the data is collected. For details on the data collection please see the instrumentation section.

All metrics are defined under the inspectit.metrics.definitions property. This is best explained by giving a simple example which comes from the default configuration of inspectIT Ocelot:

inspectit:
  metrics:
    definitions:
      '[method/duration]':
        unit: ms
        description: "the duration from method entry to method exit"
        views:
          '[method/duration/sum]':
            aggregation: SUM
            tags:
              method_name : true
          '[method/duration/count]':
            aggregation: COUNT
            tags:
              method_name: true

This snippet defines a metric with the name method/duration and the two views method/duration/sum and method/duration/count. Note that the special quoting syntax '[...]' is required because of the slashes in the names. As the name suggests, the first view stores the total sum of all observed response times whereas the second one stores the number of observations. These two views therefore allow us to compute the average, for example for creating dashboards.

The configuration options given above are only a subset of the available options. The full set of options for metrics is shown below:

Config Property	Default	Description
`enabled`	`true`	When a metric is not enabled, it and all of it's views will not be registered at the OpenCensus library.
`unit`	-	Required. A textual representation of the unit of the data represented by the metric.
`description`	Generated based on name and unit	A textual description of the purpose of the metric.
`type`	`DOUBLE`	Specifies whether the metric data is given as integer (`LONG`) or floating point number (`DOUBLE`).

For a metric to be exposed it is necessary to define views in OpenCensus. This can be done through the views config property shown in the sample YAML above.

If you do not explicitly define any view for a metric you defined, inspectIT Ocelot will automatically generate one: The view will have the same name as the metric and will simply expose the last recorded value. As soon as you specify at least one view for a metric yourself, inspectIT will not add the default view.

All configuration options for customizing views are given below:

Config Property	Default	Description
`enabled`	`true`	When set to `false`, the view will not be registered at the OpenCensus library.
`description`	Generated based on name and aggregation	A textual description of the purpose of this view.
`aggregation`	`LAST_VALUE`	Specifies how the measurement data is aggregated in this view. Possible values are `LAST_VALUE`, `COUNT`, `SUM` and `HISTOGRAM`. These correspond to the OpenCensus Aggregations.
`bucket-boundaries`	-	Required if aggregation is `HISTOGRAM`. A list of the boundaries of the histogram buckets. E.g. `[7.5,42]` defines three histogram buckets split at `7.5` and `42`.
`with-common-tags`	`true`	If true, all common tags will be used for this view. Individual tags can still be disabled via the `tags` option.
`tags`	`{}`	Specifies which tags should be used for this view. `tags` is a map containing tag names as key and either `true` or false as value. For example the value `{service: false, my_tag: true}` would remove the common tag `service` from the view and add the user tag `my_tag` to it.

Due to a limitation of the current OpenCensus library, it is not possible to remove or alter views and metrics once they have been registered. However you can still add new views and metrics through dynamic configuration updates after the agent has already started.