@adwait12345/telemetry-astro

Astro middleware adapter for the Telemetry SDK. Detects bots and crawlers on every server-side request and sends tracking payloads to the Telemetry API — without affecting response time.

Requirements

• Astro 3.0.0 or later
• Astro must be running in SSR mode (output: "server" or output: "hybrid")
  ⚠️ Static (output: "static") pages do not have access to request headers — the middleware will not run
• Node.js 18+ (uses native fetch)
• A Telemetry account with a Project ID and Server Secret

Installation

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

Setup

1. Enable SSR in astro.config.mjs

// astro.config.mjs
import { defineConfig } from "astro/config";
import node from "@astrojs/node";

export default defineConfig({
  output: "server", // or "hybrid" — required for middleware to receive real headers
  adapter: node({ mode: "standalone" }),
});

Note: If you use output: "hybrid", pages default to static. Add export const prerender = false; to any page you want the middleware to run on, or set prerender = false globally.

2. Create src/middleware.ts

// src/middleware.ts
import { telemetryMiddleware } from "@adwait12345/telemetry-astro";

export const onRequest = telemetryMiddleware({
  projectId: import.meta.env.TELEMETRY_PROJECT_ID,
  apiUrl: import.meta.env.TELEMETRY_API_URL,
  serverSecret: import.meta.env.TELEMETRY_SERVER_SECRET,
  debug: false,
});

3. Add environment variables

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

How it works

1. onRequest is called by Astro on every incoming request before the page renders
2. Requests with an empty user-agent are skipped immediately — these are Astro internal server requests (SSR pre-renders, HMR, etc.) and are not real traffic
3. The request is normalized (UA, IP, headers) and passed to detectBot()
4. If a bot is detected (or trackAll: true), a payload is sent to the Telemetry API
5. On Vercel / Cloudflare edge runtimes, waitUntil is used so the send happens after the response — zero latency impact
6. On other runtimes, the send is awaited before next() is called
7. next() is always called — the middleware never blocks or modifies 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 specific paths

export const onRequest = telemetryMiddleware({
  projectId: "...",
  serverSecret: "sk_...",
  ignorePaths: ["/health", /^\/api\//],
});

Track all visitors (not just bots)

export const onRequest = telemetryMiddleware({
  projectId: "...",
  serverSecret: "sk_...",
  trackAll: true,
});

Composing with other Astro middleware

// src/middleware.ts
import { sequence } from "astro:middleware";
import { telemetryMiddleware } from "@adwait12345/telemetry-astro";

const telemetry = telemetryMiddleware({
  projectId: "...",
  serverSecret: "sk_...",
});

async function authMiddleware(context, next) {
  // your auth logic
  return next();
}

export const onRequest = sequence(telemetry, authMiddleware);

Debug mode — see what's being detected

export const onRequest = telemetryMiddleware({
  projectId: "...",
  serverSecret: "sk_...",
  debug: true,
});

With debug: true, you'll see a line like this in your server console for every request:

[Telemetry Astro] / — UA: "Mozilla/5.0 ..." | isBot: false | botName: — | category: — | confidence: low
[Telemetry Astro] /about — UA: "Mozilla/5.0 (compatible; Googlebot..." | isBot: true | botName: Googlebot | category: search | confidence: certain
[Telemetry Astro] Skipping request with no user-agent: /_image

What gets tracked

| Field | Description | |-------|-------------| | projectId | Your project ID | | path | Request path | | method | HTTP method | | userAgent | Full user-agent string | | ip | Client IP (from x-forwarded-for or x-real-ip) | | 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" / "automation-header" / etc. | | referrer | Referrer header | | timestamp | ISO 8601 UTC |

Troubleshooting

Middleware not running / headers not available
Make sure output is set to "server" or "hybrid" in astro.config.mjs. Static pages do not have access to request headers.

Getting false positives for internal requests
The middleware skips requests with no user-agent automatically. If you see internal requests being tracked, enable debug: true to see what user-agent they're sending and add them to ignorePaths.

500 errors from the API
Check that serverSecret is set correctly. The API requires Authorization: Bearer sk_... on all server-side tracking requests.