@astroscope/opentelemetry 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+import { APIContext, MiddlewareHandler, AstroIntegration } from 'astro';
+
+type ExcludePattern = {
+    pattern: RegExp;
+} | {
+    prefix: string;
+} | {
+    exact: string;
+};
+interface OpenTelemetryMiddlewareOptions {
+    /**
+     * Paths to exclude from tracing.
+     * Can be an array of patterns or a function that returns true to exclude.
+     */
+    exclude?: ExcludePattern[] | ((context: APIContext) => boolean);
+}
+
+/**
+ * Creates an OpenTelemetry tracing middleware.
+ *
+ * @example
+ * ```ts
+ * // src/middleware.ts
+ * import { sequence } from 'astro:middleware';
+ * import { createOpenTelemetryMiddleware, RECOMMENDED_EXCLUDES } from '@astroscope/opentelemetry';
+ *
+ * export const onRequest = sequence(
+ *   createOpenTelemetryMiddleware({
+ *     exclude: [...RECOMMENDED_EXCLUDES, { exact: '/health' }],
+ *   }),
+ * );
+ * ```
+ */
+declare function createOpenTelemetryMiddleware(options?: OpenTelemetryMiddlewareOptions): MiddlewareHandler;
+
+/**
+ * Instruments the global fetch to create OpenTelemetry spans for outgoing HTTP requests.
+ * Call this once at application startup (e.g., in your boot.ts onStartup hook).
+ *
+ * @example
+ * ```ts
+ * // src/boot.ts
+ * import { NodeSDK } from "@opentelemetry/sdk-node";
+ * import { instrumentFetch } from "@astroscope/opentelemetry";
+ *
+ * const sdk = new NodeSDK({ ... });
+ *
+ * export function onStartup() {
+ *   sdk.start();
+ *   instrumentFetch();
+ * }
+ * ```
+ */
+declare function instrumentFetch(): void;
+
+interface OpenTelemetryIntegrationOptions {
+    /**
+     * Configure instrumentations.
+     */
+    instrumentations?: {
+        /**
+         * HTTP incoming request instrumentation (middleware).
+         * @default { enabled: true, exclude: RECOMMENDED_EXCLUDES }
+         */
+        http?: {
+            enabled: boolean;
+            exclude?: ExcludePattern[];
+        };
+        /**
+         * Fetch outgoing request instrumentation.
+         * @default { enabled: true }
+         */
+        fetch?: {
+            enabled: boolean;
+        };
+    };
+}
+/**
+ * Astro integration for OpenTelemetry instrumentation.
+ *
+ * This integration automatically:
+ * - Instruments incoming HTTP requests via middleware
+ * - Instruments outgoing fetch requests
+ *
+ * @example
+ * ```ts
+ * // astro.config.ts
+ * import { defineConfig } from "astro/config";
+ * import { opentelemetry } from "@astroscope/opentelemetry";
+ *
+ * export default defineConfig({
+ *   integrations: [opentelemetry()],
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Disable fetch instrumentation
+ * opentelemetry({
+ *   instrumentations: {
+ *     fetch: { enabled: false }
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Custom HTTP excludes
+ * opentelemetry({
+ *   instrumentations: {
+ *     http: {
+ *       enabled: true,
+ *       exclude: [
+ *         ...RECOMMENDED_EXCLUDES,
+ *         { exact: "/health" }
+ *       ]
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare function opentelemetry(options?: OpenTelemetryIntegrationOptions): AstroIntegration;
+
+/**
+ * Vite/Astro dev server paths - only relevant in development.
+ */
+declare const DEV_EXCLUDES: ExcludePattern[];
+/**
+ * Astro internal paths for static assets and image optimization.
+ */
+declare const ASTRO_STATIC_EXCLUDES: ExcludePattern[];
+/**
+ * Common static asset paths.
+ */
+declare const STATIC_EXCLUDES: ExcludePattern[];
+/**
+ * Recommended excludes for OpenTelemetry middleware.
+ * Includes dev paths, Astro internals, and common static assets.
+ *
+ * @example
+ * ```ts
+ * createOpenTelemetryMiddleware({
+ *   exclude: [
+ *     ...RECOMMENDED_EXCLUDES,
+ *     { exact: "/health" }, // your health endpoint
+ *   ],
+ * })
+ * ```
+ */
+declare const RECOMMENDED_EXCLUDES: ExcludePattern[];
+
+export { ASTRO_STATIC_EXCLUDES, DEV_EXCLUDES, type ExcludePattern, type OpenTelemetryIntegrationOptions, type OpenTelemetryMiddlewareOptions, RECOMMENDED_EXCLUDES, STATIC_EXCLUDES, createOpenTelemetryMiddleware, instrumentFetch, opentelemetry };

package/dist/index.js

@@ -0,0 +1,148 @@
+import {
+  createOpenTelemetryMiddleware
+} from "./chunk-7RBJ7XB3.js";
+import {
+  instrumentFetch
+} from "./chunk-BQFWPPEO.js";
+import "./chunk-DPYEL3WF.js";
+
+// src/integration.ts
+import fs from "fs";
+import path from "path";
+
+// src/excludes.ts
+var DEV_EXCLUDES = [
+  { prefix: "/@id/" },
+  { prefix: "/@fs/" },
+  { prefix: "/@vite/" },
+  { prefix: "/src/" },
+  { prefix: "/node_modules/" }
+];
+var ASTRO_STATIC_EXCLUDES = [
+  { prefix: "/_astro/" },
+  { prefix: "/_image" }
+];
+var STATIC_EXCLUDES = [
+  { exact: "/favicon.ico" },
+  { exact: "/robots.txt" },
+  { exact: "/sitemap.xml" },
+  { exact: "/browserconfig.xml" },
+  { exact: "/manifest.json" },
+  { exact: "/manifest.webmanifest" },
+  { prefix: "/.well-known/" }
+];
+var RECOMMENDED_EXCLUDES = [
+  ...DEV_EXCLUDES,
+  ...ASTRO_STATIC_EXCLUDES,
+  ...STATIC_EXCLUDES
+];
+
+// src/integration.ts
+var VIRTUAL_MODULE_ID = "virtual:@astroscope/opentelemetry/config";
+var RESOLVED_VIRTUAL_MODULE_ID = "\0" + VIRTUAL_MODULE_ID;
+function serializeExcludePatterns(patterns) {
+  const items = patterns.map((p) => {
+    if ("pattern" in p) {
+      return `{ pattern: ${p.pattern.toString()} }`;
+    } else if ("prefix" in p) {
+      return `{ prefix: ${JSON.stringify(p.prefix)} }`;
+    } else {
+      return `{ exact: ${JSON.stringify(p.exact)} }`;
+    }
+  });
+  return `[${items.join(", ")}]`;
+}
+function opentelemetry(options = {}) {
+  const httpConfig = options.instrumentations?.http ?? {
+    enabled: true,
+    exclude: RECOMMENDED_EXCLUDES
+  };
+  const fetchConfig = options.instrumentations?.fetch ?? { enabled: true };
+  const httpExclude = httpConfig.exclude ?? (httpConfig.enabled ? RECOMMENDED_EXCLUDES : []);
+  let isBuild = false;
+  let isSSR = false;
+  return {
+    name: "@astroscope/opentelemetry",
+    hooks: {
+      "astro:config:setup": ({
+        command,
+        updateConfig,
+        logger,
+        addMiddleware
+      }) => {
+        isBuild = command === "build";
+        if (httpConfig.enabled) {
+          addMiddleware({
+            entrypoint: "@astroscope/opentelemetry/middleware",
+            order: "pre"
+          });
+        }
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: "@astroscope/opentelemetry/virtual",
+                resolveId(id) {
+                  if (id === VIRTUAL_MODULE_ID) {
+                    return RESOLVED_VIRTUAL_MODULE_ID;
+                  }
+                },
+                load(id) {
+                  if (id === RESOLVED_VIRTUAL_MODULE_ID) {
+                    return `export const excludePatterns = ${serializeExcludePatterns(httpExclude)};`;
+                  }
+                }
+              },
+              // Only add fetch instrumentation plugin if enabled
+              ...fetchConfig.enabled ? [
+                {
+                  name: "@astroscope/opentelemetry/fetch",
+                  configureServer(server) {
+                    if (isBuild) return;
+                    server.httpServer?.once("listening", async () => {
+                      try {
+                        const { instrumentFetch: instrumentFetch2 } = await import("./fetch-RERXGIJA.js");
+                        instrumentFetch2();
+                        logger.info("fetch instrumentation enabled");
+                      } catch (error) {
+                        logger.error(`Error instrumenting fetch: ${error}`);
+                      }
+                    });
+                  },
+                  configResolved(config) {
+                    isSSR = !!config.build?.ssr;
+                  },
+                  writeBundle(outputOptions) {
+                    if (!isSSR) return;
+                    const outDir = outputOptions.dir;
+                    if (!outDir) return;
+                    const entryPath = path.join(outDir, "entry.mjs");
+                    if (!fs.existsSync(entryPath)) return;
+                    let content = fs.readFileSync(entryPath, "utf-8");
+                    const instrumentCode = `import { instrumentFetch } from '@astroscope/opentelemetry';
+instrumentFetch();
+`;
+                    content = instrumentCode + content;
+                    fs.writeFileSync(entryPath, content);
+                    logger.info(
+                      "injected fetch instrumentation into entry.mjs"
+                    );
+                  }
+                }
+              ] : []
+            ]
+          }
+        });
+      }
+    }
+  };
+}
+export {
+  ASTRO_STATIC_EXCLUDES,
+  DEV_EXCLUDES,
+  RECOMMENDED_EXCLUDES,
+  STATIC_EXCLUDES,
+  createOpenTelemetryMiddleware,
+  instrumentFetch,
+  opentelemetry
+};

package/dist/middleware-entrypoint.d.ts

@@ -0,0 +1,9 @@
+import * as astro from 'astro';
+
+/**
+ * Pre-configured middleware for use with the opentelemetry() integration.
+ * Exclude patterns are configured via the integration options.
+ */
+declare const onRequest: astro.MiddlewareHandler;
+
+export { onRequest };

package/dist/middleware-entrypoint.js

@@ -0,0 +1,13 @@
+import {
+  createOpenTelemetryMiddleware
+} from "./chunk-7RBJ7XB3.js";
+import "./chunk-DPYEL3WF.js";
+
+// src/middleware-entrypoint.ts
+import { excludePatterns } from "virtual:@astroscope/opentelemetry/config";
+var onRequest = createOpenTelemetryMiddleware({
+  exclude: excludePatterns
+});
+export {
+  onRequest
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@astroscope/opentelemetry",
+  "version": "0.1.0",
+  "description": "OpenTelemetry tracing middleware for Astro SSR",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware-entrypoint.d.ts",
+      "import": "./dist/middleware-entrypoint.js"
+    },
+    "./components": {
+      "import": "./src/components/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src/components"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smnbbrv/astroscope.git",
+    "directory": "packages/opentelemetry"
+  },
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "opentelemetry",
+    "tracing",
+    "observability",
+    "middleware",
+    "analytics",
+    "performance"
+  ],
+  "author": "smnbbrv",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/smnbbrv/astroscope/issues"
+  },
+  "homepage": "https://github.com/smnbbrv/astroscope/tree/main/packages/opentelemetry#readme",
+  "scripts": {
+    "build": "tsup src/index.ts src/middleware-entrypoint.ts --format esm --dts --external virtual:@astroscope/opentelemetry/config",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint 'src/**/*.{ts,tsx,astro}'",
+    "lint:fix": "eslint 'src/**/*.{ts,tsx,astro}' --fix"
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^1.30.0",
+    "astro": "^5.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.0.0",
+    "@opentelemetry/core": "^1.0.0",
+    "astro": "^5.0.0"
+  }
+}

package/src/components/Trace.astro

@@ -0,0 +1,68 @@
+---
+import { type AttributeValue, SpanStatusCode, context, trace } from '@opentelemetry/api';
+
+interface Props {
+  /**
+   * Whether tracing is enabled for this component.
+   * When false, children render normally without any tracing overhead.
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * The name of the span to create. This will appear in your tracing dashboard
+   * prefixed with "RENDER " (when withTimings is true) or ">> " (streaming mode).
+   */
+  name: string;
+
+  /**
+   * Additional attributes to attach to the span.
+   * Useful for adding context like component props, IDs, or other metadata.
+   */
+  params?: Record<string, AttributeValue>;
+
+  /**
+   * When true, buffers slot content to measure accurate render duration.
+   * This disables streaming for children - use only for single components.
+   * @default false
+   */
+  withTimings?: boolean;
+}
+
+const { name, params = {}, enabled = true, withTimings = false } = Astro.props;
+
+const LIB_NAME = '@astroscope/opentelemetry';
+
+let html: string | undefined;
+
+if (enabled) {
+  const tracer = trace.getTracer(LIB_NAME);
+  const parentContext = context.active();
+
+  if (withTimings) {
+    const span = tracer.startSpan(`RENDER ${name}`, { attributes: params }, parentContext);
+
+    try {
+      html = await context.with(trace.setSpan(parentContext, span), () => Astro.slots.render('default'));
+
+      span.setStatus({ code: SpanStatusCode.OK });
+    } catch (e) {
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: e instanceof Error ? e.message : 'Unknown error',
+      });
+
+      throw e;
+    } finally {
+      span.end();
+    }
+  } else {
+    const span = tracer.startSpan(`>> ${name}`, { attributes: params }, parentContext);
+
+    span.setStatus({ code: SpanStatusCode.OK });
+    span.end();
+  }
+}
+---
+
+{enabled && withTimings ? <Fragment set:html={html} /> : <slot />}

package/src/components/index.ts

@@ -0,0 +1,2 @@
+// @ts-expect-error: Astro types
+export { default as Trace } from './Trace.astro';