Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"name": "@toolctrl/metrics",
|
||||
"version": "0.0.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"sideEffects": false,
|
||||
"exports": {
|
||||
".": "./src/index.ts"
|
||||
},
|
||||
"scripts": {
|
||||
"test": "vitest run src",
|
||||
"typecheck": "tsc -p tsconfig.json --noEmit"
|
||||
},
|
||||
"dependencies": {
|
||||
"prom-client": "^15.1.3"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^25.6.0",
|
||||
"typescript": "^5.3.2",
|
||||
"vitest": "^3.2.4"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,102 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { isMetricsEnabled, redactMetricsToken, validateMetricsTokenAuth } from "./auth.js";
|
||||
|
||||
describe("isMetricsEnabled", () => {
|
||||
it("treats literal 'true' as enabled", () => {
|
||||
expect(isMetricsEnabled({ METRICS_ENABLED: "true" })).toBe(true);
|
||||
expect(isMetricsEnabled({ METRICS_ENABLED: "false" })).toBe(false);
|
||||
expect(isMetricsEnabled({ METRICS_ENABLED: undefined })).toBe(false);
|
||||
expect(isMetricsEnabled({ METRICS_ENABLED: " true " })).toBe(false); // strict literal
|
||||
});
|
||||
});
|
||||
|
||||
describe("validateMetricsTokenAuth", () => {
|
||||
const token = "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789";
|
||||
|
||||
it("returns 403 when metrics are disabled", () => {
|
||||
expect(
|
||||
validateMetricsTokenAuth({
|
||||
metricsEnabled: false,
|
||||
configuredToken: token,
|
||||
authorizationHeader: `Bearer ${token}`,
|
||||
}),
|
||||
).toEqual({ ok: false, status: 403, code: "metrics_disabled" });
|
||||
});
|
||||
|
||||
it("returns 500 when metrics are enabled but no token configured", () => {
|
||||
expect(
|
||||
validateMetricsTokenAuth({
|
||||
metricsEnabled: true,
|
||||
configuredToken: " ",
|
||||
authorizationHeader: `Bearer x`,
|
||||
}),
|
||||
).toEqual({ ok: false, status: 500, code: "token_misconfigured" });
|
||||
});
|
||||
|
||||
it("returns 401 missing_token when header is absent", () => {
|
||||
expect(
|
||||
validateMetricsTokenAuth({
|
||||
metricsEnabled: true,
|
||||
configuredToken: token,
|
||||
authorizationHeader: undefined,
|
||||
}),
|
||||
).toEqual({ ok: false, status: 401, code: "missing_token" });
|
||||
});
|
||||
|
||||
it("returns 401 missing_token for malformed bearer header", () => {
|
||||
expect(
|
||||
validateMetricsTokenAuth({
|
||||
metricsEnabled: true,
|
||||
configuredToken: token,
|
||||
authorizationHeader: "Basic something",
|
||||
}),
|
||||
).toEqual({ ok: false, status: 401, code: "missing_token" });
|
||||
});
|
||||
|
||||
it("returns 401 invalid_token for wrong bearer value", () => {
|
||||
expect(
|
||||
validateMetricsTokenAuth({
|
||||
metricsEnabled: true,
|
||||
configuredToken: token,
|
||||
authorizationHeader: `Bearer ${"x".repeat(token.length)}`,
|
||||
}),
|
||||
).toEqual({ ok: false, status: 401, code: "invalid_token" });
|
||||
});
|
||||
|
||||
it("returns ok for matching bearer", () => {
|
||||
expect(
|
||||
validateMetricsTokenAuth({
|
||||
metricsEnabled: true,
|
||||
configuredToken: token,
|
||||
authorizationHeader: `Bearer ${token}`,
|
||||
}),
|
||||
).toEqual({ ok: true });
|
||||
});
|
||||
|
||||
it("rejects tokens differing in length without leaking which side is longer", () => {
|
||||
const result = validateMetricsTokenAuth({
|
||||
metricsEnabled: true,
|
||||
configuredToken: token,
|
||||
authorizationHeader: `Bearer ${token}abc`,
|
||||
});
|
||||
expect(result).toEqual({ ok: false, status: 401, code: "invalid_token" });
|
||||
});
|
||||
});
|
||||
|
||||
describe("redactMetricsToken", () => {
|
||||
it("renders unset for empty / whitespace tokens", () => {
|
||||
expect(redactMetricsToken(undefined)).toBe("<unset>");
|
||||
expect(redactMetricsToken(null)).toBe("<unset>");
|
||||
expect(redactMetricsToken("")).toBe("<unset>");
|
||||
expect(redactMetricsToken(" ")).toBe("<unset>");
|
||||
});
|
||||
|
||||
it("masks short tokens entirely", () => {
|
||||
expect(redactMetricsToken("short")).toBe("***");
|
||||
expect(redactMetricsToken("12345678")).toBe("***");
|
||||
});
|
||||
|
||||
it("masks long tokens but keeps a short prefix/suffix", () => {
|
||||
expect(redactMetricsToken("abcdef1234567890abcdef")).toBe("abcd…ef");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,104 @@
|
||||
export type MetricsTokenAuthResult =
|
||||
| { ok: true }
|
||||
| { ok: false; status: 401; code: "missing_token" | "invalid_token" }
|
||||
| { ok: false; status: 403; code: "metrics_disabled" }
|
||||
| { ok: false; status: 500; code: "token_misconfigured" };
|
||||
|
||||
export type MetricsTokenAuthOptions = {
|
||||
/** The raw value of the `Authorization` header, if any. */
|
||||
authorizationHeader?: string | null | undefined;
|
||||
/** The configured metrics token. When empty + enabled => 500 (operator must configure). */
|
||||
configuredToken?: string | null | undefined;
|
||||
/** Master switch; mirrors `METRICS_ENABLED=true`. */
|
||||
metricsEnabled: boolean;
|
||||
};
|
||||
|
||||
/**
|
||||
* Reads `METRICS_ENABLED` from a plain env record. Mirrors the existing
|
||||
* project convention of treating the literal string "true" as enabled.
|
||||
*/
|
||||
export function isMetricsEnabled(env: Record<string, string | undefined>): boolean {
|
||||
return env.METRICS_ENABLED === "true";
|
||||
}
|
||||
|
||||
/**
|
||||
* Constant-time check that the inbound bearer token matches the configured
|
||||
* token. Returns a discriminated result that callers map onto framework-
|
||||
* specific responses (Hono context, React Router Response).
|
||||
*
|
||||
* Security notes:
|
||||
* - Empty / whitespace tokens are rejected.
|
||||
* - The comparison is timing-safe (`crypto.timingSafeEqual`).
|
||||
* - The token MUST NEVER be logged. See `redactMetricsToken` for the
|
||||
* audit-safe representation.
|
||||
*/
|
||||
export function validateMetricsTokenAuth(options: MetricsTokenAuthOptions): MetricsTokenAuthResult {
|
||||
if (!options.metricsEnabled) {
|
||||
return { ok: false, status: 403, code: "metrics_disabled" };
|
||||
}
|
||||
|
||||
const configured = options.configuredToken?.trim() ?? "";
|
||||
if (configured.length === 0) {
|
||||
return { ok: false, status: 500, code: "token_misconfigured" };
|
||||
}
|
||||
|
||||
const presented = extractBearerToken(options.authorizationHeader);
|
||||
if (!presented) {
|
||||
return { ok: false, status: 401, code: "missing_token" };
|
||||
}
|
||||
|
||||
if (!timingSafeEqualStrings(presented, configured)) {
|
||||
return { ok: false, status: 401, code: "invalid_token" };
|
||||
}
|
||||
|
||||
return { ok: true };
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns an audit-safe, non-reversible representation of a metrics token for
|
||||
* logging. Empty / missing tokens render as `"<unset>"`.
|
||||
*/
|
||||
export function redactMetricsToken(token: string | undefined | null): string {
|
||||
if (!token) {
|
||||
return "<unset>";
|
||||
}
|
||||
const trimmed = token.trim();
|
||||
if (trimmed.length === 0) {
|
||||
return "<unset>";
|
||||
}
|
||||
if (trimmed.length <= 8) {
|
||||
return "***";
|
||||
}
|
||||
return `${trimmed.slice(0, 4)}…${trimmed.slice(-2)}`;
|
||||
}
|
||||
|
||||
function extractBearerToken(header: string | null | undefined): string | undefined {
|
||||
if (!header) {
|
||||
return undefined;
|
||||
}
|
||||
const match = /^Bearer\s+(\S+)\s*$/i.exec(header.trim());
|
||||
if (!match) {
|
||||
return undefined;
|
||||
}
|
||||
const candidate = match[1]?.trim() ?? "";
|
||||
return candidate.length > 0 ? candidate : undefined;
|
||||
}
|
||||
|
||||
function timingSafeEqualStrings(a: string, b: string): boolean {
|
||||
if (a.length !== b.length) {
|
||||
return false;
|
||||
}
|
||||
// Encode as utf8 first so multi-byte tokens compare correctly without
|
||||
// relying on the Buffer code path which is not always available in
|
||||
// edge-runtime targets.
|
||||
const aBytes = new TextEncoder().encode(a);
|
||||
const bBytes = new TextEncoder().encode(b);
|
||||
if (aBytes.length !== bBytes.length) {
|
||||
return false;
|
||||
}
|
||||
let diff = 0;
|
||||
for (let i = 0; i < aBytes.length; i += 1) {
|
||||
diff |= aBytes[i]! ^ bBytes[i]!;
|
||||
}
|
||||
return diff === 0;
|
||||
}
|
||||
@@ -0,0 +1,64 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { HISTOGRAM_BUCKETS_SECONDS, createDefaultMetrics } from "./defaults.js";
|
||||
import { createMetricsRegistry } from "./registry.js";
|
||||
|
||||
describe("createDefaultMetrics", () => {
|
||||
it("registers every canonical metric on the registry", async () => {
|
||||
const registry = createMetricsRegistry({ serviceName: "api", collectDefaultProcessMetrics: false });
|
||||
const metrics = createDefaultMetrics(registry);
|
||||
// Touch each metric so the registry has at least one sample to render.
|
||||
metrics.httpRequestsTotal.labels({ method: "GET", route: "/v1/x", status: "200" }).inc();
|
||||
metrics.httpRequestDurationSeconds.labels({ method: "GET", route: "/v1/x", status: "200" }).observe(0.05);
|
||||
metrics.prismaQueryDurationSeconds.labels({ model: "User", action: "findMany" }).observe(0.01);
|
||||
metrics.redisCommandDurationSeconds.labels({ command: "GET" }).observe(0.001);
|
||||
metrics.queueJobsActive.labels({ queue: "email" }).set(2);
|
||||
metrics.queueJobsWaiting.labels({ queue: "email" }).set(5);
|
||||
metrics.queueJobsEnqueuedTotal.labels({ queue: "email", priority: "critical" }).inc();
|
||||
metrics.queueJobsCompletedTotal.labels({ queue: "email", job_name: "send" }).inc();
|
||||
metrics.queueJobsFailedTotal.labels({ queue: "email", job_name: "send", error_type: "Error" }).inc();
|
||||
metrics.queueJobDurationSeconds.labels({ queue: "email", job_name: "send" }).observe(0.5);
|
||||
metrics.outboxDispatchTotal.labels({ event_type: "workflow.trigger.event", status: "ok" }).inc();
|
||||
metrics.webSsrLoaderDurationSeconds.labels({ route: "root", status: "ok" }).observe(0.02);
|
||||
metrics.aiTokensConsumedTotal.labels({ provider: "openai", model: "gpt-4", tenant_bucket: "other" }).inc(1234);
|
||||
metrics.stripeWebhookEventsTotal.labels({ event_type: "invoice.paid", status: "received" }).inc();
|
||||
metrics.mailSentTotal.labels({ provider: "mailjet", status: "delivered" }).inc();
|
||||
metrics.webhookDeliveryAttemptsTotal.labels({ status: "success" }).inc();
|
||||
metrics.csrfTokenRotationTotal.inc();
|
||||
metrics.subscriptionActive.labels({ plan_id: "pro" }).set(42);
|
||||
metrics.activeTenants.set(10);
|
||||
metrics.activeUsers24h.set(123);
|
||||
|
||||
const text = await registry.metrics();
|
||||
const expected = [
|
||||
"http_requests_total",
|
||||
"http_request_duration_seconds",
|
||||
"prisma_query_duration_seconds",
|
||||
"redis_command_duration_seconds",
|
||||
"queue_jobs_active",
|
||||
"queue_jobs_waiting",
|
||||
"queue_jobs_enqueued_total",
|
||||
"queue_jobs_completed_total",
|
||||
"queue_jobs_failed_total",
|
||||
"queue_job_duration_seconds",
|
||||
"outbox_dispatch_total",
|
||||
"web_ssr_loader_duration_seconds",
|
||||
"ai_tokens_consumed_total",
|
||||
"stripe_webhook_events_total",
|
||||
"mail_sent_total",
|
||||
"webhook_delivery_attempts_total",
|
||||
"csrf_token_rotation_total",
|
||||
"subscription_active",
|
||||
"active_tenants",
|
||||
"active_users_24h",
|
||||
];
|
||||
for (const name of expected) {
|
||||
expect(text).toContain(name);
|
||||
}
|
||||
});
|
||||
|
||||
it("uses the shared histogram bucket spread for latency metrics", () => {
|
||||
expect(HISTOGRAM_BUCKETS_SECONDS[0]).toBe(0.005);
|
||||
expect(HISTOGRAM_BUCKETS_SECONDS[HISTOGRAM_BUCKETS_SECONDS.length - 1]).toBe(10);
|
||||
expect(HISTOGRAM_BUCKETS_SECONDS).toEqual([...HISTOGRAM_BUCKETS_SECONDS].sort((a, b) => a - b));
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,174 @@
|
||||
import { Counter, Gauge, Histogram } from "prom-client";
|
||||
import type { MetricsRegistry } from "./registry.js";
|
||||
|
||||
/**
|
||||
* Latency-histogram buckets in seconds. The spread covers 5ms - 10s, which is
|
||||
* the realistic range for both HTTP requests (top of bucket: timeout / 504)
|
||||
* and queue jobs (top of bucket: slow exports). Keep them in sync across the
|
||||
* api + worker + web registries so Grafana panels can mix them.
|
||||
*/
|
||||
export const HISTOGRAM_BUCKETS_SECONDS: readonly number[] = [
|
||||
0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10,
|
||||
] as const;
|
||||
|
||||
export type LatencyHistogramOptions = {
|
||||
name: string;
|
||||
help: string;
|
||||
labelNames: readonly string[];
|
||||
buckets?: readonly number[];
|
||||
};
|
||||
|
||||
export type DefaultMetrics = {
|
||||
httpRequestsTotal: Counter<"method" | "route" | "status">;
|
||||
httpRequestDurationSeconds: Histogram<"method" | "route" | "status">;
|
||||
prismaQueryDurationSeconds: Histogram<"model" | "action">;
|
||||
redisCommandDurationSeconds: Histogram<"command">;
|
||||
queueJobsActive: Gauge<"queue">;
|
||||
queueJobsWaiting: Gauge<"queue">;
|
||||
queueJobsEnqueuedTotal: Counter<"queue" | "priority">;
|
||||
queueJobsCompletedTotal: Counter<"queue" | "job_name">;
|
||||
queueJobsFailedTotal: Counter<"queue" | "job_name" | "error_type">;
|
||||
queueJobDurationSeconds: Histogram<"queue" | "job_name">;
|
||||
outboxDispatchTotal: Counter<"event_type" | "status">;
|
||||
webSsrLoaderDurationSeconds: Histogram<"route" | "status">;
|
||||
aiTokensConsumedTotal: Counter<"provider" | "model" | "tenant_bucket">;
|
||||
stripeWebhookEventsTotal: Counter<"event_type" | "status">;
|
||||
mailSentTotal: Counter<"provider" | "status">;
|
||||
webhookDeliveryAttemptsTotal: Counter<"status">;
|
||||
csrfTokenRotationTotal: Counter<string>;
|
||||
subscriptionActive: Gauge<"plan_id">;
|
||||
activeTenants: Gauge<string>;
|
||||
activeUsers24h: Gauge<string>;
|
||||
};
|
||||
|
||||
/**
|
||||
* Registers the canonical metric set for any service registry. Calling this
|
||||
* twice on the same registry would throw — callers wire the result into a
|
||||
* service-scoped singleton.
|
||||
*/
|
||||
export function createDefaultMetrics(registry: MetricsRegistry): DefaultMetrics {
|
||||
return {
|
||||
httpRequestsTotal: new Counter({
|
||||
name: "http_requests_total",
|
||||
help: "Total HTTP requests served by this service.",
|
||||
labelNames: ["method", "route", "status"] as const,
|
||||
registers: [registry],
|
||||
}),
|
||||
httpRequestDurationSeconds: new Histogram({
|
||||
name: "http_request_duration_seconds",
|
||||
help: "HTTP request duration in seconds.",
|
||||
labelNames: ["method", "route", "status"] as const,
|
||||
buckets: [...HISTOGRAM_BUCKETS_SECONDS],
|
||||
registers: [registry],
|
||||
}),
|
||||
prismaQueryDurationSeconds: new Histogram({
|
||||
name: "prisma_query_duration_seconds",
|
||||
help: "Prisma query duration in seconds.",
|
||||
labelNames: ["model", "action"] as const,
|
||||
buckets: [...HISTOGRAM_BUCKETS_SECONDS],
|
||||
registers: [registry],
|
||||
}),
|
||||
redisCommandDurationSeconds: new Histogram({
|
||||
name: "redis_command_duration_seconds",
|
||||
help: "Redis command duration in seconds.",
|
||||
labelNames: ["command"] as const,
|
||||
buckets: [...HISTOGRAM_BUCKETS_SECONDS],
|
||||
registers: [registry],
|
||||
}),
|
||||
queueJobsActive: new Gauge({
|
||||
name: "queue_jobs_active",
|
||||
help: "BullMQ jobs currently being processed per queue.",
|
||||
labelNames: ["queue"] as const,
|
||||
registers: [registry],
|
||||
}),
|
||||
queueJobsWaiting: new Gauge({
|
||||
name: "queue_jobs_waiting",
|
||||
help: "BullMQ jobs waiting to be processed per queue.",
|
||||
labelNames: ["queue"] as const,
|
||||
registers: [registry],
|
||||
}),
|
||||
queueJobsEnqueuedTotal: new Counter({
|
||||
name: "queue_jobs_enqueued_total",
|
||||
help: "BullMQ jobs enqueued per queue / priority (critical|high|normal|low|other).",
|
||||
labelNames: ["queue", "priority"] as const,
|
||||
registers: [registry],
|
||||
}),
|
||||
queueJobsCompletedTotal: new Counter({
|
||||
name: "queue_jobs_completed_total",
|
||||
help: "BullMQ jobs that completed successfully per queue / job_name.",
|
||||
labelNames: ["queue", "job_name"] as const,
|
||||
registers: [registry],
|
||||
}),
|
||||
queueJobsFailedTotal: new Counter({
|
||||
name: "queue_jobs_failed_total",
|
||||
help: "BullMQ jobs that failed terminally per queue / job_name / error_type.",
|
||||
labelNames: ["queue", "job_name", "error_type"] as const,
|
||||
registers: [registry],
|
||||
}),
|
||||
queueJobDurationSeconds: new Histogram({
|
||||
name: "queue_job_duration_seconds",
|
||||
help: "BullMQ job duration in seconds.",
|
||||
labelNames: ["queue", "job_name"] as const,
|
||||
buckets: [...HISTOGRAM_BUCKETS_SECONDS],
|
||||
registers: [registry],
|
||||
}),
|
||||
outboxDispatchTotal: new Counter({
|
||||
name: "outbox_dispatch_total",
|
||||
help: "Transactional outbox dispatch attempts per event_type / status.",
|
||||
labelNames: ["event_type", "status"] as const,
|
||||
registers: [registry],
|
||||
}),
|
||||
webSsrLoaderDurationSeconds: new Histogram({
|
||||
name: "web_ssr_loader_duration_seconds",
|
||||
help: "React Router SSR loader duration in seconds.",
|
||||
labelNames: ["route", "status"] as const,
|
||||
buckets: [...HISTOGRAM_BUCKETS_SECONDS],
|
||||
registers: [registry],
|
||||
}),
|
||||
aiTokensConsumedTotal: new Counter({
|
||||
name: "ai_tokens_consumed_total",
|
||||
help: "AI provider tokens consumed. tenant_bucket holds the top-N tenant id or 'other' to cap cardinality.",
|
||||
labelNames: ["provider", "model", "tenant_bucket"] as const,
|
||||
registers: [registry],
|
||||
}),
|
||||
stripeWebhookEventsTotal: new Counter({
|
||||
name: "stripe_webhook_events_total",
|
||||
help: "Stripe webhook events processed per event_type / status.",
|
||||
labelNames: ["event_type", "status"] as const,
|
||||
registers: [registry],
|
||||
}),
|
||||
mailSentTotal: new Counter({
|
||||
name: "mail_sent_total",
|
||||
help: "Mail-provider send attempts per provider / status.",
|
||||
labelNames: ["provider", "status"] as const,
|
||||
registers: [registry],
|
||||
}),
|
||||
webhookDeliveryAttemptsTotal: new Counter({
|
||||
name: "webhook_delivery_attempts_total",
|
||||
help: "Outbound webhook delivery attempts per status (success / retry / dlq).",
|
||||
labelNames: ["status"] as const,
|
||||
registers: [registry],
|
||||
}),
|
||||
csrfTokenRotationTotal: new Counter({
|
||||
name: "csrf_token_rotation_total",
|
||||
help: "CSRF token rotations performed.",
|
||||
registers: [registry],
|
||||
}),
|
||||
subscriptionActive: new Gauge({
|
||||
name: "subscription_active",
|
||||
help: "Active subscriptions per plan_id.",
|
||||
labelNames: ["plan_id"] as const,
|
||||
registers: [registry],
|
||||
}),
|
||||
activeTenants: new Gauge({
|
||||
name: "active_tenants",
|
||||
help: "Total active (non-deleted) tenants.",
|
||||
registers: [registry],
|
||||
}),
|
||||
activeUsers24h: new Gauge({
|
||||
name: "active_users_24h",
|
||||
help: "Unique users that signed in within the last 24 hours.",
|
||||
registers: [registry],
|
||||
}),
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
export {
|
||||
type DefaultMetrics,
|
||||
type LatencyHistogramOptions,
|
||||
HISTOGRAM_BUCKETS_SECONDS,
|
||||
createDefaultMetrics,
|
||||
} from "./defaults.js";
|
||||
export { type MetricsRegistry, createMetricsRegistry } from "./registry.js";
|
||||
export {
|
||||
type MetricsTokenAuthResult,
|
||||
type MetricsTokenAuthOptions,
|
||||
isMetricsEnabled,
|
||||
validateMetricsTokenAuth,
|
||||
redactMetricsToken,
|
||||
} from "./auth.js";
|
||||
@@ -0,0 +1,35 @@
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { createMetricsRegistry } from "./registry.js";
|
||||
import { createDefaultMetrics } from "./defaults.js";
|
||||
|
||||
describe("createMetricsRegistry", () => {
|
||||
it("attaches the service default label", async () => {
|
||||
const registry = createMetricsRegistry({ serviceName: "api", collectDefaultProcessMetrics: false });
|
||||
expect(registry.serviceName).toBe("api");
|
||||
expect(registry.defaultMetricsAttached).toBe(false);
|
||||
const metrics = createDefaultMetrics(registry);
|
||||
metrics.httpRequestsTotal.labels({ method: "GET", route: "/v1/foo", status: "200" }).inc();
|
||||
const text = await registry.metrics();
|
||||
expect(text).toContain('http_requests_total{method="GET",route="/v1/foo",status="200",service="api"} 1');
|
||||
});
|
||||
|
||||
it("emits prom-client default process metrics when enabled", async () => {
|
||||
const registry = createMetricsRegistry({ serviceName: "worker", collectDefaultProcessMetrics: true });
|
||||
expect(registry.defaultMetricsAttached).toBe(true);
|
||||
const text = await registry.metrics();
|
||||
expect(text).toMatch(/process_cpu_seconds_total/);
|
||||
expect(text).toMatch(/service="worker"/);
|
||||
});
|
||||
|
||||
it("merges custom default labels with service", async () => {
|
||||
const registry = createMetricsRegistry({
|
||||
serviceName: "web",
|
||||
collectDefaultProcessMetrics: false,
|
||||
defaultLabels: { revision: "abc123" },
|
||||
});
|
||||
const metrics = createDefaultMetrics(registry);
|
||||
metrics.activeTenants.set(7);
|
||||
const text = await registry.metrics();
|
||||
expect(text).toContain('active_tenants{service="web",revision="abc123"} 7');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,54 @@
|
||||
import { Registry, collectDefaultMetrics } from "prom-client";
|
||||
|
||||
export type MetricsRegistry = Registry & {
|
||||
readonly serviceName: string;
|
||||
/**
|
||||
* Indicates whether the prom-client default Node.js process metrics
|
||||
* (`process_cpu_seconds_total`, `process_resident_memory_bytes`, etc.) have
|
||||
* been attached to this registry. Tests rely on this flag to assert that
|
||||
* each service registers default metrics exactly once.
|
||||
*/
|
||||
readonly defaultMetricsAttached: boolean;
|
||||
};
|
||||
|
||||
export type CreateMetricsRegistryOptions = {
|
||||
serviceName: string;
|
||||
/**
|
||||
* When true (default), enables prom-client's `collectDefaultMetrics()` which
|
||||
* adds standard Node.js process metrics. Pass `false` in unit tests when you
|
||||
* want a deterministic registry without GC / event-loop noise.
|
||||
*/
|
||||
collectDefaultProcessMetrics?: boolean;
|
||||
/**
|
||||
* Extra constant labels applied to every metric on this registry. Use
|
||||
* sparingly — high-cardinality labels (request id, tenant id) MUST NOT be
|
||||
* set here. Service name + revision is the intended use.
|
||||
*/
|
||||
defaultLabels?: Record<string, string | number>;
|
||||
};
|
||||
|
||||
/**
|
||||
* Returns a service-scoped Prometheus registry with default labels.
|
||||
*
|
||||
* Each app (api / worker / web SSR) creates its own registry so metric
|
||||
* collisions between services are impossible and so a single Prometheus job
|
||||
* can scrape any one endpoint without leakage from the others.
|
||||
*/
|
||||
export function createMetricsRegistry(options: CreateMetricsRegistryOptions): MetricsRegistry {
|
||||
const { serviceName, collectDefaultProcessMetrics = true, defaultLabels } = options;
|
||||
|
||||
const registry = new Registry();
|
||||
registry.setDefaultLabels({
|
||||
service: serviceName,
|
||||
...defaultLabels,
|
||||
});
|
||||
|
||||
if (collectDefaultProcessMetrics) {
|
||||
collectDefaultMetrics({ register: registry, prefix: "" });
|
||||
}
|
||||
|
||||
return Object.assign(registry, {
|
||||
serviceName,
|
||||
defaultMetricsAttached: collectDefaultProcessMetrics,
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"extends": "../../tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"allowJs": false,
|
||||
"allowImportingTsExtensions": false,
|
||||
"lib": ["ES2022"],
|
||||
"module": "NodeNext",
|
||||
"moduleResolution": "NodeNext",
|
||||
"noEmit": true,
|
||||
"types": ["node"]
|
||||
},
|
||||
"include": ["src/**/*.ts"]
|
||||
}
|
||||
Reference in new issue
Block a user