@nixxie-cms/telemetry 1.0.1

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Nixxie International DMCC
+Portions Copyright (c) 2023 Thinkmill Labs Pty Ltd and contributors
+(this software is derived from the KeystoneJS project, https://keystonejs.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @nixxie-cms/telemetry
+
+Observability for Nixxie CMS: a zero-dependency **Prometheus** metrics registry plus optional
+**OpenTelemetry** tracing. Complements `@nixxie-cms/health`.
+
+```ts
+import { createTelemetry } from '@nixxie-cms/telemetry'
+
+export const telemetry = createTelemetry({
+  serviceName: 'my-app',
+  tracing: { otlpEndpoint: process.env.OTLP_ENDPOINT }, // optional
+})
+
+export default config({
+  server: {
+    extendExpressApp: app => {
+      app.use(telemetry.httpMiddleware())
+      app.get('/metrics', telemetry.metricsHandler())
+    },
+  },
+})
+```
+
+Custom metrics:
+
+```ts
+const published = telemetry.metrics.counter('posts_published_total', 'Posts published')
+published.inc({ author: 'alice' })
+
+await telemetry.span('rebuild-search-index', async () => {
+  // traced when OpenTelemetry is enabled, a plain call otherwise
+})
+```
+
+Tracing requires `@opentelemetry/sdk-node` and `@opentelemetry/api` (loaded lazily). Metrics need
+nothing extra.

package/dist/declarations/src/index.d.ts

@@ -0,0 +1,39 @@
+import { MetricsRegistry } from "./metrics.js";
+import type { MetricLabels, TelemetryConfig } from "./types.js";
+/**
+ * Observability for Nixxie CMS: a zero-dependency Prometheus metrics registry plus optional
+ * OpenTelemetry tracing (loaded lazily when `@opentelemetry/*` is installed).
+ *
+ * Telemetry is set up at process start and wired into Express yourself — it is intentionally not
+ * placed on `context.services` (that slot would collide with the core `telemetry` boolean flag).
+ */
+export declare class Telemetry {
+    readonly metrics: MetricsRegistry;
+    readonly serviceName: string;
+    private config;
+    private sdk;
+    private tracer;
+    constructor(config?: TelemetryConfig);
+    /** Initialise tracing (if enabled). Safe to call once at startup. */
+    start(): Promise<void>;
+    /** Run `fn` inside a span. No-ops (just runs `fn`) when tracing is disabled. */
+    span<T>(name: string, fn: () => Promise<T> | T, attributes?: MetricLabels): Promise<T>;
+    /** Prometheus text exposition of all metrics. */
+    exposeMetrics(): string;
+    /**
+     * Express handler serving metrics. Mount in `extendExpressApp`:
+     * `app.get('/metrics', telemetry.metricsHandler())`
+     */
+    metricsHandler(): (req: unknown, res: any) => void;
+    /**
+     * Express middleware recording request count + duration histograms, labelled by method/route/status.
+     */
+    httpMiddleware(): (req: any, res: any, next: () => void) => void;
+    /** Shut tracing down cleanly. */
+    shutdown(): Promise<void>;
+}
+export declare function createTelemetry(config?: TelemetryConfig): Telemetry;
+export { MetricsRegistry } from "./metrics.js";
+export type { Metric } from "./metrics.js";
+export type { TelemetryConfig, MetricLabels } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/declarations/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"../../../src","sources":["index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,qBAAiB;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,mBAAe;AAE5D;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB,QAAQ,CAAC,OAAO,kBAAwB;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,MAAM,CAAK;gBAEP,MAAM,GAAE,eAAoB;IAKxC,qEAAqE;IAC/D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB5B,gFAAgF;IAC1E,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC;IAgB5F,iDAAiD;IACjD,aAAa,IAAI,MAAM;IAIvB;;;OAGG;IACH,cAAc,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI;IAOlD;;OAEG;IACH,cAAc,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI;IAqBhE,iCAAiC;IAC3B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC;AAED,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,CAEnE;AAED,OAAO,EAAE,eAAe,EAAE,qBAAiB;AAC3C,YAAY,EAAE,MAAM,EAAE,qBAAiB;AACvC,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,mBAAe"}

package/dist/declarations/src/metrics.d.ts

@@ -0,0 +1,27 @@
+import type { MetricLabels } from "./types.js";
+type MetricKind = 'counter' | 'gauge' | 'histogram';
+declare class Metric {
+    readonly name: string;
+    readonly help: string;
+    readonly kind: MetricKind;
+    private buckets;
+    private series;
+    constructor(name: string, kind: MetricKind, help: string, buckets?: number[]);
+    private seriesFor;
+    inc(labels?: MetricLabels, amount?: number): void;
+    set(value: number, labels?: MetricLabels): void;
+    observe(value: number, labels?: MetricLabels): void;
+    expose(): string;
+}
+/** Minimal Prometheus-compatible metrics registry (no dependencies). */
+export declare class MetricsRegistry {
+    private metrics;
+    counter(name: string, help?: string): Metric;
+    gauge(name: string, help?: string): Metric;
+    histogram(name: string, help?: string, buckets?: number[]): Metric;
+    private getOrCreate;
+    /** Render the full registry in Prometheus text exposition format. */
+    expose(): string;
+}
+export type { Metric };
+//# sourceMappingURL=metrics.d.ts.map

package/dist/declarations/src/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"../../../src","sources":["metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAe;AAE3C,KAAK,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,CAAA;AAsBnD,cAAM,MAAM;IACV,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,MAAM,CAA4B;gBAE9B,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE;IAO5E,OAAO,CAAC,SAAS;IAoBjB,GAAG,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,MAAM,SAAI,GAAG,IAAI;IAI5C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI;IAI/C,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI;IASnD,MAAM,IAAI,MAAM;CAmBjB;AAED,wEAAwE;AACxE,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAA4B;IAE3C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAO,GAAG,MAAM;IAI1C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAO,GAAG,MAAM;IAIxC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAO,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM;IAIhE,OAAO,CAAC,WAAW;IAenB,qEAAqE;IACrE,MAAM,IAAI,MAAM;CAGjB;AAED,YAAY,EAAE,MAAM,EAAE,CAAA"}

package/dist/declarations/src/types.d.ts

@@ -0,0 +1,13 @@
+export type TelemetryConfig = {
+    /** Logical service name attached to traces and the `service` metric label. */
+    serviceName?: string;
+    /**
+     * Enable OpenTelemetry tracing. Requires `@opentelemetry/api` and `@opentelemetry/sdk-node`.
+     * Provide an OTLP endpoint to export spans, or `true` for a no-op/console setup.
+     */
+    tracing?: boolean | {
+        otlpEndpoint?: string;
+    };
+};
+export type MetricLabels = Record<string, string | number>;
+//# sourceMappingURL=types.d.ts.map

package/dist/declarations/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"../../../src","sources":["types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG;IAC5B,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC9C,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAA"}

package/dist/nixxie-cms-telemetry.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "./declarations/src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibml4eGllLWNtcy10ZWxlbWV0cnkuY2pzLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuL2RlY2xhcmF0aW9ucy9zcmMvaW5kZXguZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSJ9

package/dist/nixxie-cms-telemetry.cjs.js

@@ -0,0 +1,221 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _defineProperty = require('@babel/runtime/helpers/defineProperty');
+
+const DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+function labelKey(labels) {
+  if (!labels) return '';
+  return Object.keys(labels).sort().map(k => `${k}="${String(labels[k]).replace(/"/g, '\\"')}"`).join(',');
+}
+class Metric {
+  constructor(name, kind, help, buckets) {
+    _defineProperty(this, "series", new Map());
+    this.name = name;
+    this.kind = kind;
+    this.help = help;
+    this.buckets = buckets !== null && buckets !== void 0 ? buckets : DEFAULT_BUCKETS;
+  }
+  seriesFor(labels) {
+    const key = labelKey(labels);
+    let s = this.series.get(key);
+    if (!s) {
+      s = this.kind === 'histogram' ? {
+        labels,
+        value: 0,
+        buckets: this.buckets,
+        bucketCounts: new Array(this.buckets.length).fill(0),
+        sum: 0,
+        count: 0
+      } : {
+        labels,
+        value: 0
+      };
+      this.series.set(key, s);
+    }
+    return s;
+  }
+  inc(labels, amount = 1) {
+    this.seriesFor(labels).value += amount;
+  }
+  set(value, labels) {
+    this.seriesFor(labels).value = value;
+  }
+  observe(value, labels) {
+    var _s$sum, _s$count;
+    const s = this.seriesFor(labels);
+    s.sum = ((_s$sum = s.sum) !== null && _s$sum !== void 0 ? _s$sum : 0) + value;
+    s.count = ((_s$count = s.count) !== null && _s$count !== void 0 ? _s$count : 0) + 1;
+    this.buckets.forEach((b, i) => {
+      if (value <= b) s.bucketCounts[i] += 1;
+    });
+  }
+  expose() {
+    const lines = [`# HELP ${this.name} ${this.help}`, `# TYPE ${this.name} ${this.kind}`];
+    for (const s of this.series.values()) {
+      const base = labelKey(s.labels);
+      if (this.kind === 'histogram') {
+        this.buckets.forEach((b, i) => {
+          const l = [base, `le="${b}"`].filter(Boolean).join(',');
+          lines.push(`${this.name}_bucket{${l}} ${s.bucketCounts[i]}`);
+        });
+        const inf = [base, 'le="+Inf"'].filter(Boolean).join(',');
+        lines.push(`${this.name}_bucket{${inf}} ${s.count}`);
+        lines.push(`${this.name}_sum${base ? `{${base}}` : ''} ${s.sum}`);
+        lines.push(`${this.name}_count${base ? `{${base}}` : ''} ${s.count}`);
+      } else {
+        lines.push(`${this.name}${base ? `{${base}}` : ''} ${s.value}`);
+      }
+    }
+    return lines.join('\n');
+  }
+}
+
+/** Minimal Prometheus-compatible metrics registry (no dependencies). */
+class MetricsRegistry {
+  constructor() {
+    _defineProperty(this, "metrics", new Map());
+  }
+  counter(name, help = name) {
+    return this.getOrCreate(name, 'counter', help);
+  }
+  gauge(name, help = name) {
+    return this.getOrCreate(name, 'gauge', help);
+  }
+  histogram(name, help = name, buckets) {
+    return this.getOrCreate(name, 'histogram', help, buckets);
+  }
+  getOrCreate(name, kind, help, buckets) {
+    let m = this.metrics.get(name);
+    if (!m) {
+      m = new Metric(name, kind, help, buckets);
+      this.metrics.set(name, m);
+    } else if (m.kind !== kind) {
+      // Returning a counter when a histogram was requested (or vice-versa) produces malformed
+      // Prometheus output (NaN/undefined bucket lines). Fail fast on the conflicting registration.
+      throw new Error(`Metric "${name}" is already registered as a ${m.kind}; cannot redefine it as a ${kind}`);
+    }
+    return m;
+  }
+
+  /** Render the full registry in Prometheus text exposition format. */
+  expose() {
+    return [...this.metrics.values()].map(m => m.expose()).join('\n\n') + '\n';
+  }
+}
+
+/**
+ * Observability for Nixxie CMS: a zero-dependency Prometheus metrics registry plus optional
+ * OpenTelemetry tracing (loaded lazily when `@opentelemetry/*` is installed).
+ *
+ * Telemetry is set up at process start and wired into Express yourself — it is intentionally not
+ * placed on `context.services` (that slot would collide with the core `telemetry` boolean flag).
+ */
+class Telemetry {
+  constructor(config = {}) {
+    var _config$serviceName;
+    _defineProperty(this, "metrics", new MetricsRegistry());
+    this.config = config;
+    this.serviceName = (_config$serviceName = config.serviceName) !== null && _config$serviceName !== void 0 ? _config$serviceName : 'nixxie';
+  }
+
+  /** Initialise tracing (if enabled). Safe to call once at startup. */
+  async start() {
+    if (!this.config.tracing) return;
+    try {
+      const {
+        NodeSDK
+      } = require('@opentelemetry/sdk-node');
+      const api = require('@opentelemetry/api');
+      let traceExporter;
+      const endpoint = typeof this.config.tracing === 'object' ? this.config.tracing.otlpEndpoint : undefined;
+      if (endpoint) {
+        const {
+          OTLPTraceExporter
+        } = require('@opentelemetry/exporter-trace-otlp-http');
+        traceExporter = new OTLPTraceExporter({
+          url: endpoint
+        });
+      }
+      this.sdk = new NodeSDK({
+        serviceName: this.serviceName,
+        traceExporter
+      });
+      this.sdk.start();
+      this.tracer = api.trace.getTracer(this.serviceName);
+    } catch {
+      throw new Error('Tracing requires @opentelemetry/sdk-node and @opentelemetry/api. Run: npm install @opentelemetry/sdk-node @opentelemetry/api');
+    }
+  }
+
+  /** Run `fn` inside a span. No-ops (just runs `fn`) when tracing is disabled. */
+  async span(name, fn, attributes) {
+    if (!this.tracer) return await fn();
+    return this.tracer.startActiveSpan(name, async span => {
+      try {
+        if (attributes) span.setAttributes(attributes);
+        return await fn();
+      } catch (err) {
+        span.recordException(err);
+        span.setStatus({
+          code: 2,
+          message: err === null || err === void 0 ? void 0 : err.message
+        });
+        throw err;
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /** Prometheus text exposition of all metrics. */
+  exposeMetrics() {
+    return this.metrics.expose();
+  }
+
+  /**
+   * Express handler serving metrics. Mount in `extendExpressApp`:
+   * `app.get('/metrics', telemetry.metricsHandler())`
+   */
+  metricsHandler() {
+    return (_req, res) => {
+      res.setHeader('Content-Type', 'text/plain; version=0.0.4');
+      res.end(this.exposeMetrics());
+    };
+  }
+
+  /**
+   * Express middleware recording request count + duration histograms, labelled by method/route/status.
+   */
+  httpMiddleware() {
+    const requests = this.metrics.counter('http_requests_total', 'Total HTTP requests');
+    const duration = this.metrics.histogram('http_request_duration_seconds', 'HTTP request duration in seconds');
+    return (req, res, next) => {
+      const start = process.hrtime.bigint();
+      res.on('finish', () => {
+        var _ref, _req$route$path, _req$route;
+        const labels = {
+          method: req.method,
+          route: (_ref = (_req$route$path = (_req$route = req.route) === null || _req$route === void 0 ? void 0 : _req$route.path) !== null && _req$route$path !== void 0 ? _req$route$path : req.path) !== null && _ref !== void 0 ? _ref : 'unknown',
+          status: res.statusCode
+        };
+        requests.inc(labels);
+        duration.observe(Number(process.hrtime.bigint() - start) / 1e9, labels);
+      });
+      next();
+    };
+  }
+
+  /** Shut tracing down cleanly. */
+  async shutdown() {
+    if (this.sdk) await this.sdk.shutdown();
+  }
+}
+function createTelemetry(config) {
+  return new Telemetry(config);
+}
+
+exports.MetricsRegistry = MetricsRegistry;
+exports.Telemetry = Telemetry;
+exports.createTelemetry = createTelemetry;

package/dist/nixxie-cms-telemetry.esm.js

@@ -0,0 +1,215 @@
+import _defineProperty from '@babel/runtime/helpers/esm/defineProperty';
+
+const DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+function labelKey(labels) {
+  if (!labels) return '';
+  return Object.keys(labels).sort().map(k => `${k}="${String(labels[k]).replace(/"/g, '\\"')}"`).join(',');
+}
+class Metric {
+  constructor(name, kind, help, buckets) {
+    _defineProperty(this, "series", new Map());
+    this.name = name;
+    this.kind = kind;
+    this.help = help;
+    this.buckets = buckets !== null && buckets !== void 0 ? buckets : DEFAULT_BUCKETS;
+  }
+  seriesFor(labels) {
+    const key = labelKey(labels);
+    let s = this.series.get(key);
+    if (!s) {
+      s = this.kind === 'histogram' ? {
+        labels,
+        value: 0,
+        buckets: this.buckets,
+        bucketCounts: new Array(this.buckets.length).fill(0),
+        sum: 0,
+        count: 0
+      } : {
+        labels,
+        value: 0
+      };
+      this.series.set(key, s);
+    }
+    return s;
+  }
+  inc(labels, amount = 1) {
+    this.seriesFor(labels).value += amount;
+  }
+  set(value, labels) {
+    this.seriesFor(labels).value = value;
+  }
+  observe(value, labels) {
+    var _s$sum, _s$count;
+    const s = this.seriesFor(labels);
+    s.sum = ((_s$sum = s.sum) !== null && _s$sum !== void 0 ? _s$sum : 0) + value;
+    s.count = ((_s$count = s.count) !== null && _s$count !== void 0 ? _s$count : 0) + 1;
+    this.buckets.forEach((b, i) => {
+      if (value <= b) s.bucketCounts[i] += 1;
+    });
+  }
+  expose() {
+    const lines = [`# HELP ${this.name} ${this.help}`, `# TYPE ${this.name} ${this.kind}`];
+    for (const s of this.series.values()) {
+      const base = labelKey(s.labels);
+      if (this.kind === 'histogram') {
+        this.buckets.forEach((b, i) => {
+          const l = [base, `le="${b}"`].filter(Boolean).join(',');
+          lines.push(`${this.name}_bucket{${l}} ${s.bucketCounts[i]}`);
+        });
+        const inf = [base, 'le="+Inf"'].filter(Boolean).join(',');
+        lines.push(`${this.name}_bucket{${inf}} ${s.count}`);
+        lines.push(`${this.name}_sum${base ? `{${base}}` : ''} ${s.sum}`);
+        lines.push(`${this.name}_count${base ? `{${base}}` : ''} ${s.count}`);
+      } else {
+        lines.push(`${this.name}${base ? `{${base}}` : ''} ${s.value}`);
+      }
+    }
+    return lines.join('\n');
+  }
+}
+
+/** Minimal Prometheus-compatible metrics registry (no dependencies). */
+class MetricsRegistry {
+  constructor() {
+    _defineProperty(this, "metrics", new Map());
+  }
+  counter(name, help = name) {
+    return this.getOrCreate(name, 'counter', help);
+  }
+  gauge(name, help = name) {
+    return this.getOrCreate(name, 'gauge', help);
+  }
+  histogram(name, help = name, buckets) {
+    return this.getOrCreate(name, 'histogram', help, buckets);
+  }
+  getOrCreate(name, kind, help, buckets) {
+    let m = this.metrics.get(name);
+    if (!m) {
+      m = new Metric(name, kind, help, buckets);
+      this.metrics.set(name, m);
+    } else if (m.kind !== kind) {
+      // Returning a counter when a histogram was requested (or vice-versa) produces malformed
+      // Prometheus output (NaN/undefined bucket lines). Fail fast on the conflicting registration.
+      throw new Error(`Metric "${name}" is already registered as a ${m.kind}; cannot redefine it as a ${kind}`);
+    }
+    return m;
+  }
+
+  /** Render the full registry in Prometheus text exposition format. */
+  expose() {
+    return [...this.metrics.values()].map(m => m.expose()).join('\n\n') + '\n';
+  }
+}
+
+/**
+ * Observability for Nixxie CMS: a zero-dependency Prometheus metrics registry plus optional
+ * OpenTelemetry tracing (loaded lazily when `@opentelemetry/*` is installed).
+ *
+ * Telemetry is set up at process start and wired into Express yourself — it is intentionally not
+ * placed on `context.services` (that slot would collide with the core `telemetry` boolean flag).
+ */
+class Telemetry {
+  constructor(config = {}) {
+    var _config$serviceName;
+    _defineProperty(this, "metrics", new MetricsRegistry());
+    this.config = config;
+    this.serviceName = (_config$serviceName = config.serviceName) !== null && _config$serviceName !== void 0 ? _config$serviceName : 'nixxie';
+  }
+
+  /** Initialise tracing (if enabled). Safe to call once at startup. */
+  async start() {
+    if (!this.config.tracing) return;
+    try {
+      const {
+        NodeSDK
+      } = require('@opentelemetry/sdk-node');
+      const api = require('@opentelemetry/api');
+      let traceExporter;
+      const endpoint = typeof this.config.tracing === 'object' ? this.config.tracing.otlpEndpoint : undefined;
+      if (endpoint) {
+        const {
+          OTLPTraceExporter
+        } = require('@opentelemetry/exporter-trace-otlp-http');
+        traceExporter = new OTLPTraceExporter({
+          url: endpoint
+        });
+      }
+      this.sdk = new NodeSDK({
+        serviceName: this.serviceName,
+        traceExporter
+      });
+      this.sdk.start();
+      this.tracer = api.trace.getTracer(this.serviceName);
+    } catch {
+      throw new Error('Tracing requires @opentelemetry/sdk-node and @opentelemetry/api. Run: npm install @opentelemetry/sdk-node @opentelemetry/api');
+    }
+  }
+
+  /** Run `fn` inside a span. No-ops (just runs `fn`) when tracing is disabled. */
+  async span(name, fn, attributes) {
+    if (!this.tracer) return await fn();
+    return this.tracer.startActiveSpan(name, async span => {
+      try {
+        if (attributes) span.setAttributes(attributes);
+        return await fn();
+      } catch (err) {
+        span.recordException(err);
+        span.setStatus({
+          code: 2,
+          message: err === null || err === void 0 ? void 0 : err.message
+        });
+        throw err;
+      } finally {
+        span.end();
+      }
+    });
+  }
+
+  /** Prometheus text exposition of all metrics. */
+  exposeMetrics() {
+    return this.metrics.expose();
+  }
+
+  /**
+   * Express handler serving metrics. Mount in `extendExpressApp`:
+   * `app.get('/metrics', telemetry.metricsHandler())`
+   */
+  metricsHandler() {
+    return (_req, res) => {
+      res.setHeader('Content-Type', 'text/plain; version=0.0.4');
+      res.end(this.exposeMetrics());
+    };
+  }
+
+  /**
+   * Express middleware recording request count + duration histograms, labelled by method/route/status.
+   */
+  httpMiddleware() {
+    const requests = this.metrics.counter('http_requests_total', 'Total HTTP requests');
+    const duration = this.metrics.histogram('http_request_duration_seconds', 'HTTP request duration in seconds');
+    return (req, res, next) => {
+      const start = process.hrtime.bigint();
+      res.on('finish', () => {
+        var _ref, _req$route$path, _req$route;
+        const labels = {
+          method: req.method,
+          route: (_ref = (_req$route$path = (_req$route = req.route) === null || _req$route === void 0 ? void 0 : _req$route.path) !== null && _req$route$path !== void 0 ? _req$route$path : req.path) !== null && _ref !== void 0 ? _ref : 'unknown',
+          status: res.statusCode
+        };
+        requests.inc(labels);
+        duration.observe(Number(process.hrtime.bigint() - start) / 1e9, labels);
+      });
+      next();
+    };
+  }
+
+  /** Shut tracing down cleanly. */
+  async shutdown() {
+    if (this.sdk) await this.sdk.shutdown();
+  }
+}
+function createTelemetry(config) {
+  return new Telemetry(config);
+}
+
+export { MetricsRegistry, Telemetry, createTelemetry };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nixxie-cms/telemetry",
+  "version": "1.0.1",
+  "license": "MIT",
+  "main": "dist/nixxie-cms-telemetry.cjs.js",
+  "module": "dist/nixxie-cms-telemetry.esm.js",
+  "exports": {
+    ".": {
+      "types": "./dist/nixxie-cms-telemetry.cjs.js",
+      "module": "./dist/nixxie-cms-telemetry.esm.js",
+      "default": "./dist/nixxie-cms-telemetry.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.24.7"
+  },
+  "devDependencies": {
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "peerDependencies": {
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "optionalDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-node": "^0.57.0"
+  },
+  "preconstruct": {
+    "entrypoints": [
+      "index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nixxiecms/nixxie/tree/main/packages/telemetry"
+  }
+}

package/src/index.ts

@@ -0,0 +1,115 @@
+import { MetricsRegistry } from './metrics'
+import type { MetricLabels, TelemetryConfig } from './types'
+
+/**
+ * Observability for Nixxie CMS: a zero-dependency Prometheus metrics registry plus optional
+ * OpenTelemetry tracing (loaded lazily when `@opentelemetry/*` is installed).
+ *
+ * Telemetry is set up at process start and wired into Express yourself — it is intentionally not
+ * placed on `context.services` (that slot would collide with the core `telemetry` boolean flag).
+ */
+export class Telemetry {
+  readonly metrics = new MetricsRegistry()
+  readonly serviceName: string
+  private config: TelemetryConfig
+  private sdk: any
+  private tracer: any
+
+  constructor(config: TelemetryConfig = {}) {
+    this.config = config
+    this.serviceName = config.serviceName ?? 'nixxie'
+  }
+
+  /** Initialise tracing (if enabled). Safe to call once at startup. */
+  async start(): Promise<void> {
+    if (!this.config.tracing) return
+    try {
+      const { NodeSDK } = require('@opentelemetry/sdk-node')
+      const api = require('@opentelemetry/api')
+      let traceExporter: any
+      const endpoint =
+        typeof this.config.tracing === 'object' ? this.config.tracing.otlpEndpoint : undefined
+      if (endpoint) {
+        const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http')
+        traceExporter = new OTLPTraceExporter({ url: endpoint })
+      }
+      this.sdk = new NodeSDK({ serviceName: this.serviceName, traceExporter })
+      this.sdk.start()
+      this.tracer = api.trace.getTracer(this.serviceName)
+    } catch {
+      throw new Error(
+        'Tracing requires @opentelemetry/sdk-node and @opentelemetry/api. Run: npm install @opentelemetry/sdk-node @opentelemetry/api'
+      )
+    }
+  }
+
+  /** Run `fn` inside a span. No-ops (just runs `fn`) when tracing is disabled. */
+  async span<T>(name: string, fn: () => Promise<T> | T, attributes?: MetricLabels): Promise<T> {
+    if (!this.tracer) return await fn()
+    return this.tracer.startActiveSpan(name, async (span: any) => {
+      try {
+        if (attributes) span.setAttributes(attributes)
+        return await fn()
+      } catch (err: any) {
+        span.recordException(err)
+        span.setStatus({ code: 2, message: err?.message })
+        throw err
+      } finally {
+        span.end()
+      }
+    })
+  }
+
+  /** Prometheus text exposition of all metrics. */
+  exposeMetrics(): string {
+    return this.metrics.expose()
+  }
+
+  /**
+   * Express handler serving metrics. Mount in `extendExpressApp`:
+   * `app.get('/metrics', telemetry.metricsHandler())`
+   */
+  metricsHandler(): (req: unknown, res: any) => void {
+    return (_req, res) => {
+      res.setHeader('Content-Type', 'text/plain; version=0.0.4')
+      res.end(this.exposeMetrics())
+    }
+  }
+
+  /**
+   * Express middleware recording request count + duration histograms, labelled by method/route/status.
+   */
+  httpMiddleware(): (req: any, res: any, next: () => void) => void {
+    const requests = this.metrics.counter('http_requests_total', 'Total HTTP requests')
+    const duration = this.metrics.histogram(
+      'http_request_duration_seconds',
+      'HTTP request duration in seconds'
+    )
+    return (req, res, next) => {
+      const start = process.hrtime.bigint()
+      res.on('finish', () => {
+        const labels: MetricLabels = {
+          method: req.method,
+          route: req.route?.path ?? req.path ?? 'unknown',
+          status: res.statusCode,
+        }
+        requests.inc(labels)
+        duration.observe(Number(process.hrtime.bigint() - start) / 1e9, labels)
+      })
+      next()
+    }
+  }
+
+  /** Shut tracing down cleanly. */
+  async shutdown(): Promise<void> {
+    if (this.sdk) await this.sdk.shutdown()
+  }
+}
+
+export function createTelemetry(config?: TelemetryConfig): Telemetry {
+  return new Telemetry(config)
+}
+
+export { MetricsRegistry } from './metrics'
+export type { Metric } from './metrics'
+export type { TelemetryConfig, MetricLabels } from './types'

package/src/metrics.ts

@@ -0,0 +1,134 @@
+import type { MetricLabels } from './types'
+
+type MetricKind = 'counter' | 'gauge' | 'histogram'
+
+const DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
+
+function labelKey(labels?: MetricLabels): string {
+  if (!labels) return ''
+  return Object.keys(labels)
+    .sort()
+    .map(k => `${k}="${String(labels[k]).replace(/"/g, '\\"')}"`)
+    .join(',')
+}
+
+type Series = {
+  labels: MetricLabels | undefined
+  value: number
+  // histogram-only
+  buckets?: number[]
+  bucketCounts?: number[]
+  sum?: number
+  count?: number
+}
+
+class Metric {
+  readonly name: string
+  readonly help: string
+  readonly kind: MetricKind
+  private buckets: number[]
+  private series = new Map<string, Series>()
+
+  constructor(name: string, kind: MetricKind, help: string, buckets?: number[]) {
+    this.name = name
+    this.kind = kind
+    this.help = help
+    this.buckets = buckets ?? DEFAULT_BUCKETS
+  }
+
+  private seriesFor(labels?: MetricLabels): Series {
+    const key = labelKey(labels)
+    let s = this.series.get(key)
+    if (!s) {
+      s =
+        this.kind === 'histogram'
+          ? {
+              labels,
+              value: 0,
+              buckets: this.buckets,
+              bucketCounts: new Array(this.buckets.length).fill(0),
+              sum: 0,
+              count: 0,
+            }
+          : { labels, value: 0 }
+      this.series.set(key, s)
+    }
+    return s
+  }
+
+  inc(labels?: MetricLabels, amount = 1): void {
+    this.seriesFor(labels).value += amount
+  }
+
+  set(value: number, labels?: MetricLabels): void {
+    this.seriesFor(labels).value = value
+  }
+
+  observe(value: number, labels?: MetricLabels): void {
+    const s = this.seriesFor(labels)
+    s.sum = (s.sum ?? 0) + value
+    s.count = (s.count ?? 0) + 1
+    this.buckets.forEach((b, i) => {
+      if (value <= b) s.bucketCounts![i] += 1
+    })
+  }
+
+  expose(): string {
+    const lines: string[] = [`# HELP ${this.name} ${this.help}`, `# TYPE ${this.name} ${this.kind}`]
+    for (const s of this.series.values()) {
+      const base = labelKey(s.labels)
+      if (this.kind === 'histogram') {
+        this.buckets.forEach((b, i) => {
+          const l = [base, `le="${b}"`].filter(Boolean).join(',')
+          lines.push(`${this.name}_bucket{${l}} ${s.bucketCounts![i]}`)
+        })
+        const inf = [base, 'le="+Inf"'].filter(Boolean).join(',')
+        lines.push(`${this.name}_bucket{${inf}} ${s.count}`)
+        lines.push(`${this.name}_sum${base ? `{${base}}` : ''} ${s.sum}`)
+        lines.push(`${this.name}_count${base ? `{${base}}` : ''} ${s.count}`)
+      } else {
+        lines.push(`${this.name}${base ? `{${base}}` : ''} ${s.value}`)
+      }
+    }
+    return lines.join('\n')
+  }
+}
+
+/** Minimal Prometheus-compatible metrics registry (no dependencies). */
+export class MetricsRegistry {
+  private metrics = new Map<string, Metric>()
+
+  counter(name: string, help = name): Metric {
+    return this.getOrCreate(name, 'counter', help)
+  }
+
+  gauge(name: string, help = name): Metric {
+    return this.getOrCreate(name, 'gauge', help)
+  }
+
+  histogram(name: string, help = name, buckets?: number[]): Metric {
+    return this.getOrCreate(name, 'histogram', help, buckets)
+  }
+
+  private getOrCreate(name: string, kind: MetricKind, help: string, buckets?: number[]): Metric {
+    let m = this.metrics.get(name)
+    if (!m) {
+      m = new Metric(name, kind, help, buckets)
+      this.metrics.set(name, m)
+    } else if (m.kind !== kind) {
+      // Returning a counter when a histogram was requested (or vice-versa) produces malformed
+      // Prometheus output (NaN/undefined bucket lines). Fail fast on the conflicting registration.
+      throw new Error(
+        `Metric "${name}" is already registered as a ${m.kind}; cannot redefine it as a ${kind}`
+      )
+    }
+    return m
+  }
+
+  /** Render the full registry in Prometheus text exposition format. */
+  expose(): string {
+    return [...this.metrics.values()].map(m => m.expose()).join('\n\n') + '\n'
+  }
+}
+
+export type { Metric }

package/src/types.ts

@@ -0,0 +1,11 @@
+export type TelemetryConfig = {
+  /** Logical service name attached to traces and the `service` metric label. */
+  serviceName?: string
+  /**
+   * Enable OpenTelemetry tracing. Requires `@opentelemetry/api` and `@opentelemetry/sdk-node`.
+   * Provide an OTLP endpoint to export spans, or `true` for a no-op/console setup.
+   */
+  tracing?: boolean | { otlpEndpoint?: string }
+}
+
+export type MetricLabels = Record<string, string | number>