@constructive-io/graphql-server 4.10.0 → 4.11.1

package/README.md

@@ -66,6 +66,28 @@ Runs an Express server that wires CORS, uploads, domain parsing, auth, and PostG
 - File uploads via `graphql-upload`
 - GraphiQL and health check endpoints
 - Schema cache flush via `/flush` or database notifications
+- Opt-in observability for memory, DB activity, and Graphile build debugging
+
+## Observability
+
+`@constructive-io/graphql-server` includes an opt-in observability mode for local debugging.
+
+- Master switch: `GRAPHQL_OBSERVABILITY_ENABLED=true`
+- Debug routes: `GET /debug/memory`, `GET /debug/db`
+- Background sampler: periodic NDJSON snapshots under `graphql/server/logs/`
+- CLI helpers:
+  - `pnpm debug:memory:analyze`
+  - `pnpm debug:heap:capture`
+
+Observability only activates when all of the following are true:
+
+- `GRAPHQL_OBSERVABILITY_ENABLED=true`
+- `NODE_ENV=development`
+- the server is bound to a loopback host such as `localhost`, `127.0.0.1`, or `::1`
+
+When those conditions are not met, the debug routes are not mounted and the sampler does not start. This keeps the default runtime surface minimal and prevents the observability layer from being exposed remotely.
+
+For the operational workflow, sampler output, and heap snapshot usage, see [docs/memory-debugging.md](./docs/memory-debugging.md).
 
 ## Routes
 
@@ -74,6 +96,8 @@ Runs an Express server that wires CORS, uploads, domain parsing, auth, and PostG
 - `GET /graphql` / `POST /graphql` -> GraphQL endpoint
 - `POST /graphql` (multipart) -> file uploads
 - `POST /flush` -> clears cached Graphile schema for the current API
+- `GET /debug/memory` -> memory/process/Graphile debug snapshot when observability is enabled
+- `GET /debug/db` -> PostgreSQL activity/locks/pool debug snapshot when observability is enabled
 
 ## Meta API routing
 
@@ -113,6 +137,10 @@ Configuration is merged from defaults, config files, and env vars via `@construc
 | `API_ANON_ROLE`                | Anonymous role name                   | `administrator`                                               |
 | `API_ROLE_NAME`                | Authenticated role name               | `administrator`                                               |
 | `API_DEFAULT_DATABASE_ID`      | Default database ID                   | `hard-coded`                                                  |
+| `GRAPHQL_OBSERVABILITY_ENABLED` | Master switch for debug routes and sampler | `false`                                                  |
+| `GRAPHQL_DEBUG_SAMPLER_ENABLED` | Enables periodic NDJSON sampling when observability is on | `true`                                   |
+| `GRAPHQL_DEBUG_SAMPLER_INTERVAL_MS` | Sampler interval in milliseconds | `10000`                                                       |
+| `GRAPHQL_DEBUG_SAMPLER_DIR`    | Override output directory for sampler logs | `graphql/server/logs`                                     |
 
 ## Testing
 

package/diagnostics/debug-db-snapshot.d.ts

@@ -0,0 +1,19 @@
+import type { ConstructiveOptions } from '@constructive-io/graphql-types';
+export declare const closeDebugDatabasePools: () => Promise<void>;
+export interface DebugDatabaseSnapshot {
+    database: string | null | undefined;
+    pool: {
+        max: number | null;
+        totalCount: number;
+        idleCount: number;
+        waitingCount: number;
+    };
+    activeActivity: unknown[];
+    blockedActivity: unknown[];
+    lockSummary: unknown[];
+    databaseStats: Record<string, unknown> | null;
+    settings: unknown[];
+    notificationQueueUsage: number | null;
+    timestamp: string;
+}
+export declare const getDebugDatabaseSnapshot: (opts: ConstructiveOptions) => Promise<DebugDatabaseSnapshot>;

package/diagnostics/debug-db-snapshot.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDebugDatabaseSnapshot = exports.closeDebugDatabasePools = void 0;
+const pg_cache_1 = require("pg-cache");
+const pg_env_1 = require("pg-env");
+const pg_1 = require("pg");
+const ACTIVE_ACTIVITY_SQL = `
+  select
+    pid,
+    usename,
+    application_name,
+    state,
+    wait_event_type,
+    wait_event,
+    age(now(), xact_start) as xact_age,
+    age(now(), query_start) as query_age,
+    left(query, 500) as query
+  from pg_stat_activity
+  where datname = current_database()
+    and pid <> pg_backend_pid()
+    and (
+      xact_start is not null
+      or wait_event_type is not null
+      or state <> 'idle'
+    )
+  order by xact_start asc nulls last, query_start asc nulls last
+  limit 50
+`;
+const BLOCKED_ACTIVITY_SQL = `
+  with blocked as (
+    select
+      a.pid as blocked_pid,
+      a.usename as blocked_user,
+      a.application_name as blocked_application,
+      a.state as blocked_state,
+      a.wait_event_type,
+      a.wait_event,
+      age(now(), a.query_start) as blocked_for,
+      left(a.query, 500) as blocked_query,
+      pg_blocking_pids(a.pid) as blocker_pids
+    from pg_stat_activity a
+    where a.datname = current_database()
+      and cardinality(pg_blocking_pids(a.pid)) > 0
+  )
+  select
+    b.blocked_pid,
+    b.blocked_user,
+    b.blocked_application,
+    b.blocked_state,
+    b.wait_event_type,
+    b.wait_event,
+    b.blocked_for,
+    b.blocked_query,
+    blocker.pid as blocker_pid,
+    blocker.usename as blocker_user,
+    blocker.application_name as blocker_application,
+    blocker.state as blocker_state,
+    left(blocker.query, 500) as blocker_query
+  from blocked b
+  left join lateral unnest(b.blocker_pids) blocker_pid on true
+  left join pg_stat_activity blocker on blocker.pid = blocker_pid
+  order by b.blocked_for desc
+`;
+const LOCK_SUMMARY_SQL = `
+  select
+    locktype,
+    mode,
+    granted,
+    count(*)::int as count
+  from pg_locks
+  group by locktype, mode, granted
+  order by granted asc, count desc, locktype asc, mode asc
+`;
+const DATABASE_STATS_SQL = `
+  select
+    numbackends,
+    xact_commit,
+    xact_rollback,
+    blks_read,
+    blks_hit,
+    tup_returned,
+    tup_fetched,
+    tup_inserted,
+    tup_updated,
+    tup_deleted,
+    temp_files,
+    temp_bytes,
+    deadlocks,
+    checksum_failures,
+    stats_reset
+  from pg_stat_database
+  where datname = current_database()
+`;
+const SETTINGS_SQL = `
+  select
+    name,
+    setting,
+    unit
+  from pg_settings
+  where name = any(array[
+    'max_connections',
+    'shared_buffers',
+    'work_mem',
+    'maintenance_work_mem',
+    'effective_cache_size',
+    'statement_timeout',
+    'lock_timeout',
+    'idle_in_transaction_session_timeout'
+  ])
+  order by name asc
+`;
+const NOTIFY_QUEUE_SQL = `
+  select pg_notification_queue_usage() as queue_usage
+`;
+const DIAGNOSTICS_STATEMENT_TIMEOUT_MS = 3_000;
+const DIAGNOSTICS_LOCK_TIMEOUT_MS = 500;
+const diagnosticsPools = new Map();
+const buildDiagnosticsConnectionString = (opts) => {
+    const pgConfig = (0, pg_env_1.getPgEnvOptions)(opts.pg);
+    return (0, pg_cache_1.buildConnectionString)(pgConfig.user, pgConfig.password, pgConfig.host, pgConfig.port, pgConfig.database);
+};
+const getDiagnosticsPool = (opts) => {
+    const connectionString = buildDiagnosticsConnectionString(opts);
+    const existing = diagnosticsPools.get(connectionString);
+    if (existing) {
+        return existing;
+    }
+    const pool = new pg_1.Pool({
+        connectionString,
+        max: 1,
+        idleTimeoutMillis: 10_000,
+        connectionTimeoutMillis: 1_500,
+        allowExitOnIdle: true,
+        application_name: 'constructive-debug-snapshot',
+    });
+    diagnosticsPools.set(connectionString, pool);
+    return pool;
+};
+const withDiagnosticsClient = async (opts, fn) => {
+    const diagnosticsPool = getDiagnosticsPool(opts);
+    const client = await diagnosticsPool.connect();
+    try {
+        await client.query('BEGIN');
+        await client.query(`SET LOCAL statement_timeout = '${DIAGNOSTICS_STATEMENT_TIMEOUT_MS}ms'`);
+        await client.query(`SET LOCAL lock_timeout = '${DIAGNOSTICS_LOCK_TIMEOUT_MS}ms'`);
+        const result = await fn(client);
+        await client.query('COMMIT');
+        return result;
+    }
+    catch (error) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch {
+            // Best-effort rollback for diagnostics-only transactions.
+        }
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+};
+const closeDebugDatabasePools = async () => {
+    const pools = [...diagnosticsPools.values()];
+    diagnosticsPools.clear();
+    await Promise.allSettled(pools.map((pool) => pool.end()));
+};
+exports.closeDebugDatabasePools = closeDebugDatabasePools;
+const getDebugDatabaseSnapshot = async (opts) => {
+    const appPool = (0, pg_cache_1.getPgPool)(opts.pg);
+    const { activity, blocked, lockSummary, databaseStats, settings, notifyQueue, } = await withDiagnosticsClient(opts, async (client) => ({
+        activity: await client.query(ACTIVE_ACTIVITY_SQL),
+        blocked: await client.query(BLOCKED_ACTIVITY_SQL),
+        lockSummary: await client.query(LOCK_SUMMARY_SQL),
+        databaseStats: await client.query(DATABASE_STATS_SQL),
+        settings: await client.query(SETTINGS_SQL),
+        notifyQueue: await client.query(NOTIFY_QUEUE_SQL),
+    }));
+    return {
+        database: opts.pg?.database ?? null,
+        pool: {
+            max: appPool.options?.max ?? null,
+            totalCount: appPool.totalCount,
+            idleCount: appPool.idleCount,
+            waitingCount: appPool.waitingCount,
+        },
+        activeActivity: activity.rows,
+        blockedActivity: blocked.rows,
+        lockSummary: lockSummary.rows,
+        databaseStats: databaseStats.rows[0] ?? null,
+        settings: settings.rows,
+        notificationQueueUsage: notifyQueue.rows[0]?.queue_usage ?? null,
+        timestamp: new Date().toISOString(),
+    };
+};
+exports.getDebugDatabaseSnapshot = getDebugDatabaseSnapshot;

package/diagnostics/debug-memory-snapshot.d.ts

@@ -0,0 +1,53 @@
+import v8 from 'node:v8';
+import { getCacheStats } from 'graphile-cache';
+import { getGraphileBuildStats } from '../middleware/observability/graphile-build-stats';
+export interface DebugMemorySnapshot {
+    pid: number;
+    nodeEnv: string | undefined;
+    memory: {
+        heapUsedBytes: number;
+        heapTotalBytes: number;
+        rssBytes: number;
+        externalBytes: number;
+        arrayBuffersBytes: number;
+        heapUsed: string;
+        heapTotal: string;
+        rss: string;
+        external: string;
+        arrayBuffers: string;
+    };
+    cpuUsageMicros: NodeJS.CpuUsage;
+    resourceUsage: NodeJS.ResourceUsage;
+    system: {
+        loadAverage: number[];
+        freeMemoryBytes: number;
+        totalMemoryBytes: number;
+        uptimeSeconds: number;
+    };
+    v8: {
+        heapStatistics: ReturnType<typeof v8.getHeapStatistics>;
+        heapSpaces: Array<{
+            spaceName: string;
+            spaceSizeBytes: number;
+            spaceUsedBytes: number;
+            spaceAvailableBytes: number;
+            physicalSpaceSizeBytes: number;
+        }>;
+    };
+    graphileCache: ReturnType<typeof getCacheStats>;
+    svcCache: {
+        size: number;
+        max: number;
+        ttlMs: number;
+        oldestKeyAgeMs: number | null;
+        keys: string[];
+    };
+    inFlight: {
+        count: number;
+        keys: string[];
+    };
+    graphileBuilds: ReturnType<typeof getGraphileBuildStats>;
+    uptimeMinutes: number;
+    timestamp: string;
+}
+export declare const getDebugMemorySnapshot: () => DebugMemorySnapshot;

package/diagnostics/debug-memory-snapshot.js

@@ -0,0 +1,77 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDebugMemorySnapshot = void 0;
+const node_os_1 = __importDefault(require("node:os"));
+const node_v8_1 = __importDefault(require("node:v8"));
+const server_utils_1 = require("@pgpmjs/server-utils");
+const graphile_cache_1 = require("graphile-cache");
+const graphile_1 = require("../middleware/graphile");
+const graphile_build_stats_1 = require("../middleware/observability/graphile-build-stats");
+const toMB = (bytes) => `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+const getDebugMemorySnapshot = () => {
+    const mem = process.memoryUsage();
+    const heapSpaces = node_v8_1.default.getHeapSpaceStatistics().map((space) => ({
+        spaceName: space.space_name,
+        spaceSizeBytes: space.space_size,
+        spaceUsedBytes: space.space_used_size,
+        spaceAvailableBytes: space.space_available_size,
+        physicalSpaceSizeBytes: space.physical_space_size,
+    }));
+    return {
+        pid: process.pid,
+        nodeEnv: process.env.NODE_ENV,
+        memory: {
+            heapUsedBytes: mem.heapUsed,
+            heapTotalBytes: mem.heapTotal,
+            rssBytes: mem.rss,
+            externalBytes: mem.external,
+            arrayBuffersBytes: mem.arrayBuffers,
+            heapUsed: toMB(mem.heapUsed),
+            heapTotal: toMB(mem.heapTotal),
+            rss: toMB(mem.rss),
+            external: toMB(mem.external),
+            arrayBuffers: toMB(mem.arrayBuffers),
+        },
+        cpuUsageMicros: process.cpuUsage(),
+        resourceUsage: process.resourceUsage(),
+        system: {
+            loadAverage: node_os_1.default.loadavg(),
+            freeMemoryBytes: node_os_1.default.freemem(),
+            totalMemoryBytes: node_os_1.default.totalmem(),
+            uptimeSeconds: node_os_1.default.uptime(),
+        },
+        v8: {
+            heapStatistics: node_v8_1.default.getHeapStatistics(),
+            heapSpaces,
+        },
+        graphileCache: (0, graphile_cache_1.getCacheStats)(),
+        svcCache: {
+            size: server_utils_1.svcCache.size,
+            max: server_utils_1.svcCache.max,
+            ttlMs: server_utils_1.SVC_CACHE_TTL_MS,
+            // Note: with updateAgeOnGet: true, this is "time since last access" not "time since creation"
+            oldestKeyAgeMs: (() => {
+                let minRemaining = Infinity;
+                for (const key of server_utils_1.svcCache.keys()) {
+                    const remaining = server_utils_1.svcCache.getRemainingTTL(key);
+                    if (remaining < minRemaining) {
+                        minRemaining = remaining;
+                    }
+                }
+                return Number.isFinite(minRemaining) ? server_utils_1.SVC_CACHE_TTL_MS - minRemaining : null;
+            })(),
+            keys: [...server_utils_1.svcCache.keys()].slice(0, 200),
+        },
+        inFlight: {
+            count: (0, graphile_1.getInFlightCount)(),
+            keys: (0, graphile_1.getInFlightKeys)(),
+        },
+        graphileBuilds: (0, graphile_build_stats_1.getGraphileBuildStats)(),
+        uptimeMinutes: process.uptime() / 60,
+        timestamp: new Date().toISOString(),
+    };
+};
+exports.getDebugMemorySnapshot = getDebugMemorySnapshot;

package/diagnostics/debug-sampler.d.ts

@@ -0,0 +1,5 @@
+import type { ConstructiveOptions } from '@constructive-io/graphql-types';
+export interface DebugSamplerHandle {
+    stop(): Promise<void>;
+}
+export declare const startDebugSampler: (opts: ConstructiveOptions) => DebugSamplerHandle | null;

package/diagnostics/debug-sampler.js

@@ -0,0 +1,195 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startDebugSampler = void 0;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const logger_1 = require("@pgpmjs/logger");
+const debug_db_snapshot_1 = require("./debug-db-snapshot");
+const debug_memory_snapshot_1 = require("./debug-memory-snapshot");
+const observability_1 = require("./observability");
+const log = new logger_1.Logger('debug-sampler');
+const MAX_TOTAL_BYTES = 1024 * 1024 * 1024; // 1 GB
+const getSamplerIntervalMs = () => {
+    const raw = process.env.GRAPHQL_DEBUG_SAMPLER_INTERVAL_MS;
+    const parsed = raw ? Number.parseInt(raw, 10) : 10_000;
+    return Number.isFinite(parsed) && parsed >= 1_000 ? parsed : 10_000;
+};
+const getSamplerRootDir = () => {
+    if (process.env.GRAPHQL_DEBUG_SAMPLER_DIR) {
+        return node_path_1.default.resolve(process.env.GRAPHQL_DEBUG_SAMPLER_DIR);
+    }
+    return node_path_1.default.resolve(__dirname, '../..', 'logs');
+};
+const createSessionLogDir = () => {
+    const rootDir = getSamplerRootDir();
+    const sessionName = `run-${new Date().toISOString().replace(/[:.]/g, '-')}-pid${process.pid}`;
+    return process.env.GRAPHQL_DEBUG_SAMPLER_DIR
+        ? rootDir
+        : node_path_1.default.join(rootDir, sessionName);
+};
+const appendJsonLine = async (filePath, payload) => {
+    await promises_1.default.mkdir(node_path_1.default.dirname(filePath), { recursive: true });
+    await promises_1.default.appendFile(filePath, `${JSON.stringify(payload)}\n`, 'utf8');
+};
+const getDirSize = async (dirPath) => {
+    let total = 0;
+    const entries = await promises_1.default.readdir(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = node_path_1.default.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            total += await getDirSize(fullPath);
+        }
+        else {
+            const stat = await promises_1.default.stat(fullPath);
+            total += stat.size;
+        }
+    }
+    return total;
+};
+const enforceMaxSize = async (rootDir, currentSessionDir) => {
+    try {
+        const totalSize = await getDirSize(rootDir);
+        if (totalSize <= MAX_TOTAL_BYTES) {
+            return;
+        }
+        const entries = await promises_1.default.readdir(rootDir, { withFileTypes: true });
+        const sessionDirs = await Promise.all(entries
+            .filter((e) => e.isDirectory())
+            .map(async (e) => {
+            const fullPath = node_path_1.default.join(rootDir, e.name);
+            const stat = await promises_1.default.stat(fullPath);
+            return { path: fullPath, mtimeMs: stat.mtimeMs };
+        }));
+        sessionDirs.sort((a, b) => a.mtimeMs - b.mtimeMs);
+        for (const dir of sessionDirs) {
+            if (dir.path === currentSessionDir) {
+                continue;
+            }
+            log.info(`Rolling cleanup: removing old session dir ${dir.path}`);
+            await promises_1.default.rm(dir.path, { recursive: true, force: true });
+            const newSize = await getDirSize(rootDir);
+            if (newSize <= MAX_TOTAL_BYTES) {
+                break;
+            }
+        }
+    }
+    catch (error) {
+        log.error('Failed to enforce max log size', error);
+    }
+};
+const startDebugSampler = (opts) => {
+    if (!(0, observability_1.isGraphqlDebugSamplerEnabled)(opts.server?.host)) {
+        return null;
+    }
+    const intervalMs = getSamplerIntervalMs();
+    const logDir = createSessionLogDir();
+    const memoryLogPath = node_path_1.default.join(logDir, 'debug-memory.ndjson');
+    const dbLogPath = node_path_1.default.join(logDir, 'debug-db.ndjson');
+    const errorLogPath = node_path_1.default.join(logDir, 'debug-sampler-errors.ndjson');
+    let timer = null;
+    let stopped = false;
+    let inFlight = null;
+    let writeFailureLogged = false;
+    const runBackgroundWrite = (promise, scope) => {
+        promise.catch((error) => {
+            // Avoid recursive attempts to write additional error files when the
+            // underlying storage path is broken or unavailable.
+            if (!writeFailureLogged) {
+                writeFailureLogged = true;
+                log.error(`Debug sampler background write failed (${scope})`, error);
+            }
+        });
+    };
+    const recordError = async (scope, error) => {
+        const payload = {
+            scope,
+            timestamp: new Date().toISOString(),
+            pid: process.pid,
+            error: error instanceof Error ? {
+                name: error.name,
+                message: error.message,
+                stack: error.stack,
+            } : {
+                message: String(error),
+            },
+        };
+        await appendJsonLine(errorLogPath, payload);
+    };
+    const sampleOnce = async () => {
+        if (stopped) {
+            return;
+        }
+        try {
+            await appendJsonLine(memoryLogPath, (0, debug_memory_snapshot_1.getDebugMemorySnapshot)());
+        }
+        catch (error) {
+            log.error('Failed to capture debug memory snapshot', error);
+            await recordError('memory', error);
+        }
+        try {
+            await appendJsonLine(dbLogPath, await (0, debug_db_snapshot_1.getDebugDatabaseSnapshot)(opts));
+        }
+        catch (error) {
+            log.error('Failed to capture debug DB snapshot', error);
+            await recordError('db', error);
+        }
+        await enforceMaxSize(getSamplerRootDir(), logDir);
+    };
+    const tick = () => {
+        if (stopped) {
+            return;
+        }
+        if (inFlight) {
+            runBackgroundWrite(recordError('sampler', new Error('Skipped debug sample because previous sample is still running')), 'record-skip');
+            return;
+        }
+        inFlight = sampleOnce()
+            .catch(async (error) => {
+            log.error('Debug sampler tick failed', error);
+            await recordError('sampler', error);
+        })
+            .finally(() => {
+            inFlight = null;
+        });
+    };
+    const lifecyclePayload = {
+        event: 'sampler_started',
+        intervalMs,
+        logDir,
+        pid: process.pid,
+        timestamp: new Date().toISOString(),
+    };
+    runBackgroundWrite(appendJsonLine(memoryLogPath, lifecyclePayload), 'lifecycle-memory-start');
+    runBackgroundWrite(appendJsonLine(dbLogPath, lifecyclePayload), 'lifecycle-db-start');
+    log.info(`Debug sampler writing snapshots every ${intervalMs}ms to ${logDir}`);
+    tick();
+    timer = setInterval(tick, intervalMs);
+    timer.unref();
+    return {
+        async stop() {
+            stopped = true;
+            if (timer) {
+                clearInterval(timer);
+                timer = null;
+            }
+            if (inFlight) {
+                await inFlight;
+            }
+            const payload = {
+                event: 'sampler_stopped',
+                intervalMs,
+                logDir,
+                pid: process.pid,
+                timestamp: new Date().toISOString(),
+            };
+            await Promise.allSettled([
+                appendJsonLine(memoryLogPath, payload),
+                appendJsonLine(dbLogPath, payload),
+            ]);
+        },
+    };
+};
+exports.startDebugSampler = startDebugSampler;

package/diagnostics/observability.d.ts

@@ -0,0 +1,6 @@
+export declare const isDevelopmentObservabilityMode: () => boolean;
+export declare const isLoopbackHost: (value: string | null | undefined) => boolean;
+export declare const isLoopbackAddress: (value: string | null | undefined) => boolean;
+export declare const isGraphqlObservabilityRequested: () => boolean;
+export declare const isGraphqlObservabilityEnabled: (serverHost?: string | null) => boolean;
+export declare const isGraphqlDebugSamplerEnabled: (serverHost?: string | null) => boolean;

package/diagnostics/observability.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGraphqlDebugSamplerEnabled = exports.isGraphqlObservabilityEnabled = exports.isGraphqlObservabilityRequested = exports.isLoopbackAddress = exports.isLoopbackHost = exports.isDevelopmentObservabilityMode = void 0;
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+const LOOPBACK_ADDRESSES = new Set(['127.0.0.1', '::1']);
+const parseBooleanEnv = (value, fallback) => {
+    if (value == null) {
+        return fallback;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(normalized))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(normalized))
+        return false;
+    return fallback;
+};
+const normalizeHost = (value) => {
+    if (!value) {
+        return null;
+    }
+    const trimmed = value.trim().toLowerCase();
+    if (!trimmed) {
+        return null;
+    }
+    if (trimmed.startsWith('[')) {
+        const closingIndex = trimmed.indexOf(']');
+        return closingIndex === -1 ? trimmed : trimmed.slice(0, closingIndex + 1);
+    }
+    const colonCount = trimmed.split(':').length - 1;
+    if (colonCount === 1) {
+        return trimmed.split(':')[0] || null;
+    }
+    return trimmed;
+};
+const normalizeAddress = (value) => {
+    const normalized = normalizeHost(value);
+    if (!normalized) {
+        return null;
+    }
+    return normalized.startsWith('::ffff:') ? normalized.slice(7) : normalized;
+};
+const isDevelopmentObservabilityMode = () => process.env.NODE_ENV === 'development';
+exports.isDevelopmentObservabilityMode = isDevelopmentObservabilityMode;
+const isLoopbackHost = (value) => {
+    const normalized = normalizeHost(value);
+    return normalized != null && LOOPBACK_HOSTS.has(normalized);
+};
+exports.isLoopbackHost = isLoopbackHost;
+const isLoopbackAddress = (value) => {
+    const normalized = normalizeAddress(value);
+    return normalized != null && LOOPBACK_ADDRESSES.has(normalized);
+};
+exports.isLoopbackAddress = isLoopbackAddress;
+const isGraphqlObservabilityRequested = () => parseBooleanEnv(process.env.GRAPHQL_OBSERVABILITY_ENABLED, false);
+exports.isGraphqlObservabilityRequested = isGraphqlObservabilityRequested;
+const isGraphqlObservabilityEnabled = (serverHost) => (0, exports.isDevelopmentObservabilityMode)() &&
+    (0, exports.isGraphqlObservabilityRequested)() &&
+    (0, exports.isLoopbackHost)(serverHost);
+exports.isGraphqlObservabilityEnabled = isGraphqlObservabilityEnabled;
+const isGraphqlDebugSamplerEnabled = (serverHost) => (0, exports.isGraphqlObservabilityEnabled)(serverHost) &&
+    parseBooleanEnv(process.env.GRAPHQL_DEBUG_SAMPLER_ENABLED, true);
+exports.isGraphqlDebugSamplerEnabled = isGraphqlDebugSamplerEnabled;