trapperkeeper-comidi-metrics

trapperkeeper-comidi-metrics is a library that provides Ring middleware to automatically track metrics for requests to all of your comidi HTTP routes.

To get the most value out of this library, use it in concert with trapperkeeper-metrics (to take advantage of the built-in ring-middleware for tracking HTTP metrics) and the Trapperkeeper Status Service (to expose the most useful metrics data from your app via HTTP).

Quick Start

This repo includes an example app that is intended to show how to tie all of those pieces together. The easiest way to get started is probably to run the example app, and then take a peek into the code.

To start the example web app, run:

lein example

Then, in another shell, run:

lein example-data

This will generate some random requests to the web app, and then issue a request to the status endpoint to print some summary data about the metrics.

For more info about the HTTP metrics, see the comidi metrics documentation.

Detailed Info

trapperkeeper-comidi-metrics contains a Ring middleware that can be used in concert with a MetricRegistry (from the dropwizard Metrics library) to automatically track metrics for all of your comidi routes. This can be used in conjunction with the Trapperkeeper Status Service to easily expose debugging / telemetry information via HTTP.

Here's an example of how to use the Ring middleware:

(defn my-routes
  [url-prefix]
  (comidi/context path
    (comidi/context "/v1"
      (comidi/routes
        (comidi/GET ["/foo"] request
          (handle-foo request))
        (comidi/ANY ["/bar/" :bar] [bar]
          (handle-bar bar))))))

(tk/defservice my-web-service
  [[:WebroutingService add-ring-handler get-route]
   [:MetricsService get-metrics-registry]]
  (init [this context]
    (let [path (get-route this)
          metrics-registry (get-metrics-registry)
          routes (my-routes path)
          route-metadata (comidi/route-metadata routes)
          http-metrics (http-metrics/initialize-http-metrics!
                         metrics-registry
                         "localhost"
                         route-metadata)
          handler (-> (comidi/routes->handler routes)
                      (http-metrics/wrap-with-request-metrics http-metrics)
                      (comidi/wrap-with-route-metadata routes))]
      (add-ring-handler this handler)
      (log/info "REQUEST SUMMARY:" (http-metrics/request-summary http-metrics)))
    context))

(Note that http-metrics/wrap-with-request-metrics relies on data from the comidi/wrap-with-route-metadata middleware.)

In the example above, the call to request-summary will return counts of zero for all of the routes, because no requests have been handled yet, but the data structure returned by request-summary will look something like this in a real-world scenario:

{:routes
 {:total {:route-id "total", :count 100, :mean 18, :aggregate 1800},
  :other {:route-id "other", :count 0, :mean 0, :aggregate 0},
  "example-v1-foo"
  {:route-id "example-v1-foo",
   :count 34,
   :mean 10,
   :aggregate 340},
  "example-v1-bar-:bar"
  {:route-id "example-v1-bar-:bar",
   :count 30,
   :mean 18,
   :aggregate 540}},
 :sorted-routes
 [{:route-id "total", :count 100, :mean 18, :aggregate 1800},
  {:route-id "example-v1-bar-:bar",
   :count 30,
   :mean 18,
   :aggregate 540},
  {:route-id "example-v1-foo",
   :count 34,
   :mean 10,
   :aggregate 340},
  {:route-id "other", :count 0, :mean 0, :aggregate 0}]}

For each route in your comidi route tree, initialize-http-metrics! will generate a unique route-id. Then, request-summary can be used to retrieve the metrics data for each route. The return value of request-summary is a map with two keys; :routes, and :sorted-routes. They contain the same data, but :routes contains a nested map whose keys are the route-ids, so that you can look up the data for a specific route, while the value :sorted-routes is a vector sorted by the aggregate amount of time spent handling requests for each route (in descending order).

For each route, the data returned includes a :count of how many requests have been made, a :mean time (in milliseconds) indicating how long it's taken to handle the average request, and an :aggregate time (in milliseconds) showing how much total time has been spent handling requests for that route.

There are two special route ids included: :total, which summarizes all requests across all routes, and :other, which tracks metrics for requests that did not match any of your routes.

For a complete example that illustrates how to expose the HTTP metrics data via the Trapperkeeper Status Service, see the source code for the sample web application.

License

See LICENSE.

Support

We use the Trapperkeeper project on JIRA for tickets on this project, although Github issues are welcome too.