@adwait12345/telemetry-express

Express middleware adapter for the Telemetry SDK. Detects bots and crawlers on every incoming request and sends tracking payloads to the Telemetry API.

Requirements

• Express 4.x or later
• Node.js 18+ (uses native fetch)
• A Telemetry account with a Project ID and Server Secret

Installation

npm install @adwait12345/telemetry-express @adwait12345/telemetry-core
# or
pnpm add @adwait12345/telemetry-express @adwait12345/telemetry-core

Setup

import express from "express";
import { telemetryMiddleware } from "@adwait12345/telemetry-express";

const app = express();

app.use(
  telemetryMiddleware({
    projectId: process.env.TELEMETRY_PROJECT_ID!,
    apiUrl: process.env.TELEMETRY_API_URL,
    serverSecret: process.env.TELEMETRY_SERVER_SECRET!,
    debug: false,
  })
);

app.get("/", (req, res) => {
  res.send("Hello world");
});

app.listen(3000);

# .env
TELEMETRY_PROJECT_ID=your-project-id
TELEMETRY_API_URL=https://telemetry-uqd3.onrender.com
TELEMETRY_SERVER_SECRET=sk_...

How it works

1. The middleware runs synchronously on every request
2. The request is normalized (UA, IP, headers, HTTP version) and passed to detectBot()
3. Express exposes the real httpVersion from the raw request — this improves detection accuracy (HTTP/1.0 is flagged as a bot signal)
4. If a bot is detected (or trackAll: true), a fire-and-forget send is triggered
5. next() is called immediately — the send does not block the response

Configuration options

| Option | Type | Default | Description | |--------|------|---------|-------------| | projectId | string | required | Your Telemetry project ID | | serverSecret | string | required | Your server secret key for API auth | | apiUrl | string | hosted service | Override the API endpoint | | trackAll | boolean | false | Track all requests, not just bots | | trackSearchBots | boolean | true | Include Googlebot, Bingbot etc. | | ignorePaths | (string \| RegExp)[] | — | Paths to skip entirely | | customBots | Array<{name, pattern, category?}> | — | Add custom bot definitions | | debug | boolean | false | Log detection results to the console | | authorizationHeader | string | — | Fully custom Authorization header value | | headers | Record<string, string> | — | Extra headers on every telemetry request |

Examples

Skip health check and static routes

app.use(
  telemetryMiddleware({
    projectId: "...",
    serverSecret: "sk_...",
    ignorePaths: ["/health", "/ping", /^\/static\//],
  })
);

Track all visitors

app.use(
  telemetryMiddleware({
    projectId: "...",
    serverSecret: "sk_...",
    trackAll: true,
  })
);

Add custom bot definitions

app.use(
  telemetryMiddleware({
    projectId: "...",
    serverSecret: "sk_...",
    customBots: [
      { name: "MyInternalCrawler", pattern: /my-crawler\/\d+/i, category: "scraper" },
    ],
  })
);

What gets tracked

| Field | Description | |-------|-------------| | projectId | Your project ID | | path | Request path (from req.originalUrl) | | method | HTTP method | | userAgent | Full user-agent string | | ip | Client IP (from req.ip or x-forwarded-for) | | isBot | true / false | | botName | Named bot e.g. "GPTBot", or null | | botCategory | e.g. "ai-crawler", "search", "scraper" | | confidence | "certain" / "high" / "medium" / "low" | | detectionMethod | "ua-match" / "header-anomaly" / "http10" / "automation-header" | | referrer | Referrer header | | timestamp | ISO 8601 UTC |