Hono Prometheus metrics middleware

[alexgleason]

I just wanted to share this Prometheus metrics middleware I made, in case others find this useful. It uses prom-client, and I'm running it in Deno.

I am able to capture a cool graph like this:

metricsMiddleware

import { MiddlewareHandler } from '@hono/hono';
import { Counter } from 'prom-client';

export const httpRequestCounter = new Counter({
  name: 'http_requests_total',
  help: 'Total number of HTTP requests',
  labelNames: ['method'],
});

export const httpResponseCounter = new Counter({
  name: 'http_responses_total',
  help: 'Total number of HTTP responses',
  labelNames: ['status', 'path'],
});

/** Prometheus metrics middleware that tracks HTTP requests by methods and responses by status code. */
export const metricsMiddleware: MiddlewareHandler = async (c, next) => {
  // HTTP Request.
  const { method } = c.req;
  httpRequestCounter.inc({ method });

  // Wait for other handlers to run.
  await next();

  // HTTP Response.
  const { status } = c.res;
  // Get a parameterized path name like `/posts/:id` instead of `/posts/1234`.
  // Tries to find actual route names first before falling back on potential middleware handlers like `app.use('*')`.
  const path = c.req.matchedRoutes.find((r) => r.method !== 'ALL')?.path ?? c.req.routePath;
  httpResponseCounter.inc({ status, path });
};

Hono app and /metrics endpoint

import { Hono } from '@hono/hono';
import { register } from 'prom-client';

import { metricsMiddleware } from './metricsMiddleware.ts';

const app = new Hono();

app.use('*', metricsMiddleware);

app.get('/metrics', async (c) => {
  const metrics = await register.metrics();

  const headers: HeadersInit = {
    'Content-Type': register.contentType,
  };

  return c.text(metrics, 200, headers);
});

export default app;

PromQL queries

The screenshot at the top uses Grafana to combine 2xx and non-2xx responses into a single graph.

Success Responses

Sums all 2xx responses into a single time series.

sum(rate(http_responses_total{status=~"2.."}[5m]))

Error Responses

Sums all non-2xx responses into a single time series. This is actually wrong since it also captures 3xx and 4xx. You could adjust it as needed, maybe by capturing status=~"5.." instead, and creating separate lines for 3xx and 4xx.

sum(rate(http_responses_total{status!~"2.."}[5m]))

Responses by Endpoint

The middleware actually captures metrics for each endpoint, so you could create a detailed graph where each endpoint has a separate line. Eg:

rate(http_responses_total[5m])

It will result in a graph looking something like this:

(Notice how the legend at the bottom uses nice parameterized paths for each endpoint)

Requests by Method

I find this one to be less useful, but it's still cool!

rate(http_requests_total[5m])

[alexgleason]

I improved this graph a lot already.

Now you can hover your mouse to see specific Response endpoints by status code:

Here's the Grafana panel JSON:

{
  "datasource": {
    "uid": "edps32o5ztgjkb",
    "type": "prometheus"
  },
  "description": "Responses sent back to users from the server. Organized by status code.",
  "fieldConfig": {
    "defaults": {
      "custom": {
        "drawStyle": "line",
        "lineInterpolation": "linear",
        "barAlignment": 0,
        "lineWidth": 1,
        "fillOpacity": 25,
        "gradientMode": "none",
        "spanNulls": false,
        "insertNulls": false,
        "showPoints": "auto",
        "pointSize": 5,
        "stacking": {
          "mode": "normal",
          "group": "A"
        },
        "axisPlacement": "auto",
        "axisLabel": "",
        "axisColorMode": "text",
        "axisBorderShow": false,
        "scaleDistribution": {
          "type": "linear"
        },
        "axisCenteredZero": false,
        "hideFrom": {
          "tooltip": false,
          "viz": false,
          "legend": false
        },
        "thresholdsStyle": {
          "mode": "off"
        }
      },
      "color": {
        "mode": "palette-classic"
      },
      "mappings": [],
      "thresholds": {
        "mode": "absolute",
        "steps": [
          {
            "color": "green",
            "value": null
          },
          {
            "color": "red",
            "value": 80
          }
        ]
      }
    },
    "overrides": [
      {
        "matcher": {
          "id": "byFrameRefID",
          "options": "Server Errors"
        },
        "properties": [
          {
            "id": "color",
            "value": {
              "fixedColor": "semi-dark-red",
              "mode": "shades"
            }
          }
        ]
      },
      {
        "matcher": {
          "id": "byFrameRefID",
          "options": "Client Errors"
        },
        "properties": [
          {
            "id": "color",
            "value": {
              "fixedColor": "dark-blue",
              "mode": "shades"
            }
          }
        ]
      },
      {
        "matcher": {
          "id": "byFrameRefID",
          "options": "Redirects"
        },
        "properties": [
          {
            "id": "color",
            "value": {
              "fixedColor": "semi-dark-yellow",
              "mode": "shades"
            }
          }
        ]
      },
      {
        "matcher": {
          "id": "byFrameRefID",
          "options": "Success"
        },
        "properties": [
          {
            "id": "color",
            "value": {
              "fixedColor": "semi-dark-green",
              "mode": "shades"
            }
          }
        ]
      }
    ]
  },
  "gridPos": {
    "h": 10,
    "w": 24,
    "x": 0,
    "y": 0
  },
  "id": 10,
  "options": {
    "tooltip": {
      "mode": "single",
      "sort": "none",
      "maxHeight": 600
    },
    "legend": {
      "showLegend": false,
      "displayMode": "table",
      "placement": "right",
      "calcs": [],
      "width": 225
    }
  },
  "pluginVersion": "11.0.0",
  "targets": [
    {
      "datasource": {
        "type": "prometheus",
        "uid": "edps32o5ztgjkb"
      },
      "editorMode": "code",
      "expr": "rate(http_responses_total{status=~\"5..\"}[5m])",
      "hide": false,
      "instant": false,
      "legendFormat": "{{path}} ({{status}})",
      "range": true,
      "refId": "Server Errors"
    },
    {
      "datasource": {
        "type": "prometheus",
        "uid": "edps32o5ztgjkb"
      },
      "editorMode": "code",
      "expr": "rate(http_responses_total{status=~\"4..\"}[5m])",
      "hide": false,
      "instant": false,
      "legendFormat": "{{path}} ({{status}})",
      "range": true,
      "refId": "Client Errors"
    },
    {
      "datasource": {
        "type": "prometheus",
        "uid": "edps32o5ztgjkb"
      },
      "editorMode": "code",
      "expr": "rate(http_responses_total{status=~\"3..\"}[5m])",
      "hide": false,
      "instant": false,
      "legendFormat": "{{path}} ({{status}})",
      "range": true,
      "refId": "Redirects"
    },
    {
      "datasource": {
        "type": "prometheus",
        "uid": "edps32o5ztgjkb"
      },
      "editorMode": "code",
      "expr": "rate(http_responses_total{status=~\"2..\"}[5m])",
      "instant": false,
      "interval": "",
      "legendFormat": "{{path}} ({{status}})",
      "range": true,
      "refId": "Success"
    }
  ],
  "title": "HTTP Responses",
  "type": "timeseries"
}