TimerDecorator

Records time to process filters, handlers, and access token resolvers.

Decorator Usage

{
    "name": string,
    "type": "TimerDecorator",
    "config": {
        "timeUnit": string
    }
}

IG configures a default TimerDecorator named timer. Use timer as the decorator name without explicitly declaring a decorator named timer.

"timeUnit": duration string, optional: Unit of time used in the decorator output. The unit of time can be any unit allowed in the duration field.

Default: ms

Decorated Object Usage

{
    "name": string,
    "type": string,
    "config": object,
    decorator name: boolean
}

"name": string, required except for inline objects: The unique name of the object to decorate.
"type": string, required: The class name of the object to decorate, which must be a filter, handler, or the accessTokenResolver property of OAuth2ResourceServerFilter.

See also Filters, Handlers, and OAuth2ResourceServerFilter
"config": object, required unless empty: The configuration of the object, just like an object that is not decorated.
decorator name: boolean, required: IG looks for the presence of the decorator name field for the TimerDecorator.

To activate the timer, set the value of the decorator name field to true.

To deactivate the TimerDecorator temporarily, set the value to false.

Timer Metrics At the Prometheus Scrape Endpoint

This section describes the timer metrics recorded at the Prometheus Scrape Endpoint. For more information about metrics, see Monitoring Endpoints.

When IG is set up as described in the documentation, the endpoint is http://openig.example.com:8080/openig/metrics/prometheus.

Each timer metric is labelled with the following fully qualified names:

decorated_object
heap
name (decorator name)
route
router

Timer Metrics At the Prometheus Scrape Endpoint
Name	Monitoring Type	Description
`ig_timerdecorator_handler_elapsed_seconds`	`Summary`	Time to process the request and response in the decorated handler.
`ig_timerdecorator_filter_elapsed_seconds`	`Summary`	Time to process the request and response in the decorated filter and its downstream filters and handler.
`ig_timerdecorator_filter_internal_seconds`	`Summary`	Time to process the request and response in the decorated filter.
`ig_timerdecorator_filter_downstream_seconds`	`Summary`	Time to process the request and response in filters and handlers that are downstream of the decorated filter.

Timer Metrics At the Common REST Monitoring Endpoint

This section describes the metrics recorded at the the ForgeRock Common REST Monitoring Endpoint. For more information about metrics, see Monitoring Endpoints.

When IG is set up as described in the documentation, the endpoint is http://openig.example.com:8080/openig/metrics/api?_queryFilter=true.

Metrics are published with an _id in the following pattern:

heap.router-name.route-name.decorator-name.object

Timer Metrics At the Common REST Monitoring Endpoint
Name	Monitoring Type	Description
`elapsed`	`Timer`	Time to process the request and response in the decorated handler, or in the decorated filter and its downstream filters and handler.
`internal`	`Timer`	Time to process the request and response in the decorated filter.
`downstream`	`Timer`	Time to process the request and response in filters and handlers that are downstream of the decorated filter.

Timer Metrics in SLF4J Logs

SLF4J logs are named in this format:

<className>.<decoratorName>.<decoratedObjectName>

If the decorated object is not named, the object path is used in the log.

When a route’s top-level handler is decorated, the timer decorator records the elapsed time for operations traversing the whole route:

2018-09-04T12:16:08,994Z | INFO  | I/O dispatcher 17 | o.f.o.d.t.T.t.top-level-handler | @myroute | Elapsed time: 13 ms

When an individual handler in the route is decorated, the timer decorator records the elapsed time for operations traversing the handler:

2018-09-04T12:44:02,161Z | INFO  | http-nio-8080-exec-8 | o.f.o.d.t.T.t.StaticResponseHandler-1 | @myroute | Elapsed time: 1 ms

Examples

The following example uses the default timer decorator to record the time that TokenIntrospectionAccessTokenResolver takes to process a request:

{
  "accessTokenResolver": {
    "name": "TokenIntrospectionAccessTokenResolver-1",
    "type": "TokenIntrospectionAccessTokenResolver",
    "config": {
      "amService": "AmService-1",
      ...
    },
    "timer": true
  }
}

The following example defines a customized timer decorator in the heap, and uses it to record the time that the SingleSignOnFilter takes to process a request:

{
  "heap": [
    {
      "name": "mytimerdecorator",
      "type": "TimerDecorator",
      "config": {
        "timeUnit": "nano"
      }
    },
    ...
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "SingleSignOnFilter",
          "config": {
            ...
          },
          "mytimerdecorator": true
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

More Information

org.forgerock.openig.decoration.timer.TimerDecorator

IG 7.1.2