Add Prometheus metrics endpoint for HTTP observability

.example.env

@@ -85,6 +85,12 @@ MAIL_PASSWORD=
 # Optional - Enable rate limitting for some API routes
 ENABLE_RATE_LIMIT=false
 
+# Optional - Enable metrics endpoint
+METRICS_ENABLED=true
+
+# Optional - Metrics endpoint path
+METRICS_PATH=/metrics
+
 # Optional - The email address that will receive submitted reports
 REPORT_EMAIL=
 

README.md

@@ -122,6 +122,8 @@ You can use files for each of the variables by appending `_FILE` to the name of
 | `SERVER_CNAME_ADDRESS` | The subdomain shown to the user on the setting's page. It's only for display purposes and has no other use. | - | `custom.yoursite.com` |
 | `CUSTOM_DOMAIN_USE_HTTPS` | Use https for links with custom domain. It's on you to generate SSL certificates for those domains manually—at least on this version for now. | `false` | `true` |
 | `ENABLE_RATE_LIMIT` | Enable rate limiting for some API routes. If Redis is enabled uses Redis, otherwise, uses memory. | `false` | `true` |
+| `METRICS_ENABLED` | Enable the metrics endpoint. | `true` | `false` |
+| `METRICS_PATH` | Metrics endpoint path. | `/metrics` | `/internal/metrics` |
 | `MAIL_ENABLED` | Enable emails, which are used for signup, verifying or changing email address, resetting password, and sending reports. If is disabled, all these functionalities will be disabled too. | `false` | `true` | 
 | `MAIL_HOST` | Email server host | - | `your-mail-server.com` |
 | `MAIL_PORT` | Email server port | `587` | `465` (SSL) | 
@@ -138,6 +140,24 @@ You can use files for each of the variables by appending `_FILE` to the name of
 | `REPORT_EMAIL` | The email address that will receive submitted reports | - | `example@yoursite.com` | 
 | `CONTACT_EMAIL` | The support email address to show on the app | - | `example@yoursite.com` | 
 
+## Metrics
+
+Kutt exposes a Prometheus text-format metrics endpoint for black-box monitoring. The payload includes response time statistics, throughput, in-flight requests, and success/error rates per HTTP status code.
+
+Default endpoint:
+
+```
+GET /metrics
+```
+
+Example Kubernetes annotations for Prometheus scraping:
+
+```
+prometheus.io/scrape: "true"
+prometheus.io/path: "/metrics"
+prometheus.io/port: "3000"
+```
+
 ## Themes and customizations
 
 You can add styles, change images, or render custom HTML. Place your content inside the [`/custom`](./custom) folder according to below instructions.
@@ -250,4 +270,3 @@ Download Kutt's extension for web browsers via below links.
 Pull requests are welcome. Open a discussion for feedback, requesting features, or discussing ideas.
 
 Special thanks to [Thomas](https://github.com/trgwii) and [Muthu](https://github.com/MKRhere). Logo design by [Muthu](https://github.com/MKRhere).
-

server/env.js

@@ -69,6 +69,8 @@ const spec = {
   OIDC_SCOPE: str({ default: "openid profile email" }),
   OIDC_EMAIL_CLAIM: str({ default: "email" }),
   ENABLE_RATE_LIMIT: bool({ default: false }),
+  METRICS_ENABLED: bool({ default: true }),
+  METRICS_PATH: str({ default: "/metrics" }),
   REPORT_EMAIL: str({ default: "" }),
   CONTACT_EMAIL: str({ default: "" }),
   NODE_APP_INSTANCE: num({ default: 0 }),

server/server.js

@@ -15,6 +15,7 @@ const locals = require("./handlers/locals.handler");
 const links = require("./handlers/links.handler");
 const routes = require("./routes");
 const utils = require("./utils");
+const metrics = require("./utils/metrics");
 
 
 // run the cron jobs
@@ -41,6 +42,19 @@ app.use(cookieParser());
 app.use(express.json());
 app.use(express.urlencoded({ extended: true }));
 
+if (env.METRICS_ENABLED) {
+  const metricsPath = env.METRICS_PATH.startsWith("/")
+    ? env.METRICS_PATH
+    : `/${env.METRICS_PATH}`;
+  app.use(metrics.middleware({ ignorePaths: [metricsPath] }));
+  app.get(metricsPath, (req, res) => {
+    res
+      .status(200)
+      .type("text/plain; version=0.0.4; charset=utf-8")
+      .send(metrics.prometheusText());
+  });
+}
+
 // use cookie sessions only when OIDC is enabled
 // because only OIDC is using it
 if (env.OIDC_ENABLED) {