@netgreener/runtime 0.1.8 → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/TUTORIAL.md +120 -29
  3. package/dist/aggregator.d.ts +12 -2
  4. package/dist/aggregator.js +135 -8
  5. package/dist/analyze/buildResourceFindings.d.ts +4 -0
  6. package/dist/analyze/buildResourceFindings.js +17 -0
  7. package/dist/analyze/cli.d.ts +1 -0
  8. package/dist/analyze/cli.js +22 -1
  9. package/dist/analyze/declaredExternalApis.d.ts +31 -0
  10. package/dist/analyze/declaredExternalApis.js +174 -0
  11. package/dist/analyze/index.d.ts +1 -0
  12. package/dist/analyze/index.js +1 -0
  13. package/dist/auto.d.ts +7 -0
  14. package/dist/auto.js +8 -0
  15. package/dist/bullmq.d.ts +2 -2
  16. package/dist/bullmq.js +28 -58
  17. package/dist/carbonLedger.d.ts +28 -0
  18. package/dist/carbonLedger.js +52 -0
  19. package/dist/cgroupV2.d.ts +44 -0
  20. package/dist/cgroupV2.js +174 -0
  21. package/dist/cli/helpText.d.ts +3 -3
  22. package/dist/cli/helpText.js +42 -35
  23. package/dist/cli/netgreener.d.ts +7 -7
  24. package/dist/cli/netgreener.js +23 -16
  25. package/dist/cli/runCli.d.ts +20 -0
  26. package/dist/cli/runCli.js +249 -0
  27. package/dist/cli/runPreload.d.ts +5 -0
  28. package/dist/cli/runPreload.js +43 -0
  29. package/dist/collectorMetadata.d.ts +1 -1
  30. package/dist/collectorMetadata.js +2 -0
  31. package/dist/config.d.ts +2 -0
  32. package/dist/config.js +6 -2
  33. package/dist/exporter.d.ts +7 -2
  34. package/dist/exporter.js +12 -6
  35. package/dist/express.js +17 -6
  36. package/dist/externalApiMeter.d.ts +51 -2
  37. package/dist/externalApiMeter.js +379 -26
  38. package/dist/fastify.js +17 -6
  39. package/dist/index.d.ts +12 -2
  40. package/dist/index.js +11 -1
  41. package/dist/init.d.ts +30 -0
  42. package/dist/init.js +31 -0
  43. package/dist/lifecycle.d.ts +45 -0
  44. package/dist/lifecycle.js +112 -0
  45. package/dist/managedCollectorLauncher.d.ts +37 -0
  46. package/dist/managedCollectorLauncher.js +162 -0
  47. package/dist/mcpToolMeter.d.ts +101 -0
  48. package/dist/mcpToolMeter.js +496 -0
  49. package/dist/n4/deploymentMatrix.d.ts +9 -5
  50. package/dist/n4/deploymentMatrix.js +13 -9
  51. package/dist/n4/missingnessInventory.js +3 -3
  52. package/dist/next.d.ts +89 -0
  53. package/dist/next.js +328 -0
  54. package/dist/nextConfig.d.ts +34 -0
  55. package/dist/nextConfig.js +73 -0
  56. package/dist/nextEntryTransform.d.ts +9 -0
  57. package/dist/nextEntryTransform.js +181 -0
  58. package/dist/occupancyTracker.d.ts +27 -0
  59. package/dist/occupancyTracker.js +87 -0
  60. package/dist/optimize/apply.d.ts +38 -0
  61. package/dist/optimize/apply.js +173 -0
  62. package/dist/optimize/cli.d.ts +26 -0
  63. package/dist/optimize/cli.js +323 -0
  64. package/dist/optimize/index.d.ts +6 -0
  65. package/dist/optimize/index.js +5 -0
  66. package/dist/optimize/llmApply.d.ts +22 -0
  67. package/dist/optimize/llmApply.js +80 -0
  68. package/dist/optimize/llmSession.d.ts +88 -0
  69. package/dist/optimize/llmSession.js +135 -0
  70. package/dist/optimize/provider.d.ts +17 -0
  71. package/dist/optimize/provider.js +119 -0
  72. package/dist/optimize/safePatches.d.ts +18 -0
  73. package/dist/optimize/safePatches.js +247 -0
  74. package/dist/optimize/types.d.ts +79 -0
  75. package/dist/optimize/types.js +6 -0
  76. package/dist/optimize/verification.d.ts +16 -0
  77. package/dist/optimize/verification.js +165 -0
  78. package/dist/processResources.d.ts +5 -0
  79. package/dist/processResources.js +28 -4
  80. package/dist/processRuntime.js +7 -28
  81. package/dist/processTree.d.ts +47 -0
  82. package/dist/processTree.js +148 -0
  83. package/dist/runContextEnrichment.d.ts +11 -0
  84. package/dist/runContextEnrichment.js +92 -0
  85. package/dist/runtime.d.ts +36 -1
  86. package/dist/runtime.js +140 -17
  87. package/dist/sdk/client.d.ts +152 -0
  88. package/dist/sdk/client.js +396 -0
  89. package/dist/sdk/gitUrl.d.ts +6 -0
  90. package/dist/sdk/gitUrl.js +87 -0
  91. package/dist/sdk/index.d.ts +5 -0
  92. package/dist/sdk/index.js +5 -0
  93. package/dist/serverlessHints.d.ts +9 -6
  94. package/dist/serverlessHints.js +10 -7
  95. package/dist/taskMeter.d.ts +14 -0
  96. package/dist/taskMeter.js +53 -0
  97. package/dist/types.d.ts +43 -0
  98. package/examples/aca-container-gate/Dockerfile +20 -0
  99. package/examples/aca-container-gate/azure-container-app.yaml +27 -0
  100. package/examples/aca-container-gate/gate.env +7 -0
  101. package/examples/aca-container-gate/server.mjs +117 -0
  102. package/examples/azure-functions-gate/.funcignore +6 -0
  103. package/examples/azure-functions-gate/README.md +25 -0
  104. package/examples/azure-functions-gate/host.json +15 -0
  105. package/examples/azure-functions-gate/package-lock.json +161 -0
  106. package/examples/azure-functions-gate/package.json +14 -0
  107. package/examples/azure-functions-gate/src/functions/health.js +27 -0
  108. package/examples/express-local-live-smoke.mjs +127 -0
  109. package/examples/extractRunId.mjs +11 -0
  110. package/examples/next-pilot-dry-run.mjs +32 -0
  111. package/examples/serverless-thin-gate.mjs +89 -0
  112. package/fixtures/run-smoke/hello.mjs +4 -0
  113. package/loaders/next-entry-loader.cjs +14 -0
  114. package/package.json +25 -2
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Process-tree CPU/RSS sampling (Linux /proc first; Windows honest unavailable).
3
+ *
4
+ * Aggregates self + descendant PIDs. Never invents cgroup values.
5
+ * Injectable ``readProc`` supports unit tests without a real /proc.
6
+ */
7
+ export declare const CPU_SOURCE_PROCESS_TREE = "process_tree_proc";
8
+ export declare const MEMORY_SOURCE_PROCESS_TREE = "process_tree_rss";
9
+ export type ProcessTreeSample = {
10
+ /** Aggregate user+system CPU milliseconds since boot for the tree. */
11
+ cpuTimeMs: number;
12
+ /** Sum of RSS (KiB) across observed PIDs. */
13
+ rssKb: number;
14
+ /** Root + descendants successfully sampled. */
15
+ pidCount: number;
16
+ provenanceCpu: typeof CPU_SOURCE_PROCESS_TREE;
17
+ provenanceMemory: typeof MEMORY_SOURCE_PROCESS_TREE;
18
+ };
19
+ export type ProcessTreeAvailability = {
20
+ available: boolean;
21
+ reason: string | null;
22
+ platform: string;
23
+ };
24
+ export type ProcessTreeOptions = {
25
+ rootPid?: number;
26
+ procRoot?: string;
27
+ platform?: NodeJS.Platform;
28
+ /** Override /proc reads for tests. */
29
+ readText?: (path: string) => string | null;
30
+ listPids?: () => number[];
31
+ };
32
+ /** Parse ``/proc/<pid>/stat`` utime+stime (fields 14–15, 1/100s ticks). */
33
+ export declare function parseProcStatCpuTicks(statText: string): number | null;
34
+ /** Parse ``/proc/<pid>/stat`` ppid (field after state). */
35
+ export declare function parseProcStatPpid(statText: string): number | null;
36
+ /** Parse ``/proc/<pid>/status`` VmRSS in KiB. */
37
+ export declare function parseProcStatusRssKb(statusText: string): number | null;
38
+ export declare function processTreeAvailability(opts?: ProcessTreeOptions): ProcessTreeAvailability;
39
+ /**
40
+ * Collect descendant PIDs of ``rootPid`` (including root) via ppid links.
41
+ */
42
+ export declare function collectDescendantPids(rootPid: number, opts?: ProcessTreeOptions): number[];
43
+ /**
44
+ * Snapshot aggregate CPU ticks (ms) + RSS for the process tree.
45
+ * CPU uses 100 Hz ticks → ms = ticks * 10.
46
+ */
47
+ export declare function sampleProcessTree(opts?: ProcessTreeOptions): ProcessTreeSample | null;
@@ -0,0 +1,148 @@
1
+ /**
2
+ * Process-tree CPU/RSS sampling (Linux /proc first; Windows honest unavailable).
3
+ *
4
+ * Aggregates self + descendant PIDs. Never invents cgroup values.
5
+ * Injectable ``readProc`` supports unit tests without a real /proc.
6
+ */
7
+ import { readFileSync, readdirSync, existsSync } from 'node:fs';
8
+ import { join } from 'node:path';
9
+ import { platform } from 'node:os';
10
+ export const CPU_SOURCE_PROCESS_TREE = 'process_tree_proc';
11
+ export const MEMORY_SOURCE_PROCESS_TREE = 'process_tree_rss';
12
+ function defaultReadText(path) {
13
+ try {
14
+ return readFileSync(path, 'utf8');
15
+ }
16
+ catch {
17
+ return null;
18
+ }
19
+ }
20
+ function defaultListPids(procRoot) {
21
+ try {
22
+ return readdirSync(procRoot)
23
+ .map((name) => Number(name))
24
+ .filter((n) => Number.isFinite(n) && n > 0);
25
+ }
26
+ catch {
27
+ return [];
28
+ }
29
+ }
30
+ /** Parse ``/proc/<pid>/stat`` utime+stime (fields 14–15, 1/100s ticks). */
31
+ export function parseProcStatCpuTicks(statText) {
32
+ const closeParen = statText.lastIndexOf(')');
33
+ if (closeParen < 0)
34
+ return null;
35
+ const rest = statText.slice(closeParen + 2).trim().split(/\s+/);
36
+ // After ``)``: state(0) ppid(1) … utime(11) stime(12) — 0-based in rest.
37
+ const utime = Number(rest[11]);
38
+ const stime = Number(rest[12]);
39
+ if (!Number.isFinite(utime) || !Number.isFinite(stime))
40
+ return null;
41
+ return utime + stime;
42
+ }
43
+ /** Parse ``/proc/<pid>/stat`` ppid (field after state). */
44
+ export function parseProcStatPpid(statText) {
45
+ const closeParen = statText.lastIndexOf(')');
46
+ if (closeParen < 0)
47
+ return null;
48
+ const rest = statText.slice(closeParen + 2).trim().split(/\s+/);
49
+ const ppid = Number(rest[1]);
50
+ return Number.isFinite(ppid) ? ppid : null;
51
+ }
52
+ /** Parse ``/proc/<pid>/status`` VmRSS in KiB. */
53
+ export function parseProcStatusRssKb(statusText) {
54
+ for (const line of statusText.split(/\r?\n/)) {
55
+ if (!line.startsWith('VmRSS:'))
56
+ continue;
57
+ const n = Number(line.replace(/^VmRSS:\s*/, '').split(/\s+/)[0]);
58
+ return Number.isFinite(n) ? Math.max(0, n) : null;
59
+ }
60
+ return null;
61
+ }
62
+ export function processTreeAvailability(opts = {}) {
63
+ const plat = opts.platform ?? platform();
64
+ if (plat !== 'linux') {
65
+ return {
66
+ available: false,
67
+ reason: 'process_tree_linux_proc_only',
68
+ platform: plat,
69
+ };
70
+ }
71
+ const procRoot = opts.procRoot ?? '/proc';
72
+ if (!existsSync(procRoot) && !opts.listPids) {
73
+ return { available: false, reason: 'proc_unavailable', platform: plat };
74
+ }
75
+ return { available: true, reason: null, platform: plat };
76
+ }
77
+ /**
78
+ * Collect descendant PIDs of ``rootPid`` (including root) via ppid links.
79
+ */
80
+ export function collectDescendantPids(rootPid, opts = {}) {
81
+ const procRoot = opts.procRoot ?? '/proc';
82
+ const readText = opts.readText ?? defaultReadText;
83
+ const allPids = opts.listPids ? opts.listPids() : defaultListPids(procRoot);
84
+ const children = new Map();
85
+ for (const pid of allPids) {
86
+ const stat = readText(join(procRoot, String(pid), 'stat'));
87
+ if (!stat)
88
+ continue;
89
+ const ppid = parseProcStatPpid(stat);
90
+ if (ppid == null)
91
+ continue;
92
+ const list = children.get(ppid) ?? [];
93
+ list.push(pid);
94
+ children.set(ppid, list);
95
+ }
96
+ const out = [];
97
+ const stack = [rootPid];
98
+ const seen = new Set();
99
+ while (stack.length) {
100
+ const pid = stack.pop();
101
+ if (seen.has(pid))
102
+ continue;
103
+ seen.add(pid);
104
+ out.push(pid);
105
+ for (const child of children.get(pid) ?? [])
106
+ stack.push(child);
107
+ }
108
+ return out;
109
+ }
110
+ /**
111
+ * Snapshot aggregate CPU ticks (ms) + RSS for the process tree.
112
+ * CPU uses 100 Hz ticks → ms = ticks * 10.
113
+ */
114
+ export function sampleProcessTree(opts = {}) {
115
+ const avail = processTreeAvailability(opts);
116
+ if (!avail.available)
117
+ return null;
118
+ const rootPid = opts.rootPid ?? process.pid;
119
+ const procRoot = opts.procRoot ?? '/proc';
120
+ const readText = opts.readText ?? defaultReadText;
121
+ const pids = collectDescendantPids(rootPid, opts);
122
+ let ticks = 0;
123
+ let rssKb = 0;
124
+ let pidCount = 0;
125
+ for (const pid of pids) {
126
+ const stat = readText(join(procRoot, String(pid), 'stat'));
127
+ const status = readText(join(procRoot, String(pid), 'status'));
128
+ if (!stat)
129
+ continue;
130
+ const t = parseProcStatCpuTicks(stat);
131
+ if (t == null)
132
+ continue;
133
+ ticks += t;
134
+ const rss = status ? parseProcStatusRssKb(status) : null;
135
+ if (rss != null)
136
+ rssKb += rss;
137
+ pidCount += 1;
138
+ }
139
+ if (pidCount === 0)
140
+ return null;
141
+ return {
142
+ cpuTimeMs: ticks * 10,
143
+ rssKb,
144
+ pidCount,
145
+ provenanceCpu: CPU_SOURCE_PROCESS_TREE,
146
+ provenanceMemory: MEMORY_SOURCE_PROCESS_TREE,
147
+ };
148
+ }
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Enrich run_context for anomaly / optimize evidence (additive).
3
+ *
4
+ * Twin intent of Python ``attach_release_identity`` + CI flags used by
5
+ * ``anomaly_feature_projection._is_ci``. Does not change EXPORT_MODE or upload path.
6
+ */
7
+ /**
8
+ * Attach release identity + CI flags onto an existing run_context object.
9
+ * Never overwrites an already-set ``release_tag`` / ``git_sha`` / ``deploy_id``.
10
+ */
11
+ export declare function enrichRunContextForAnomaly(ctx: Record<string, unknown>, env?: NodeJS.ProcessEnv): Record<string, unknown>;
@@ -0,0 +1,92 @@
1
+ /**
2
+ * Enrich run_context for anomaly / optimize evidence (additive).
3
+ *
4
+ * Twin intent of Python ``attach_release_identity`` + CI flags used by
5
+ * ``anomaly_feature_projection._is_ci``. Does not change EXPORT_MODE or upload path.
6
+ */
7
+ function firstEnv(env, names) {
8
+ for (const name of names) {
9
+ const v = (env[name] || '').trim();
10
+ if (v)
11
+ return v;
12
+ }
13
+ return null;
14
+ }
15
+ function detectCi(env) {
16
+ return Boolean(firstEnv(env, [
17
+ 'CI',
18
+ 'GITHUB_ACTIONS',
19
+ 'GITLAB_CI',
20
+ 'BUILD_BUILDID',
21
+ 'TF_BUILD',
22
+ 'CIRCLECI',
23
+ 'TRAVIS',
24
+ ]));
25
+ }
26
+ function resolveCiProvider(env) {
27
+ if (firstEnv(env, ['GITHUB_ACTIONS']))
28
+ return 'github_actions';
29
+ if (firstEnv(env, ['GITLAB_CI']))
30
+ return 'gitlab_ci';
31
+ if (firstEnv(env, ['TF_BUILD', 'BUILD_BUILDID']))
32
+ return 'azure_devops';
33
+ if (firstEnv(env, ['CIRCLECI']))
34
+ return 'circleci';
35
+ if (firstEnv(env, ['TRAVIS']))
36
+ return 'travis';
37
+ if (firstEnv(env, ['CI']))
38
+ return 'ci';
39
+ return null;
40
+ }
41
+ function resolveReleaseTagFallback(env) {
42
+ return firstEnv(env, [
43
+ 'NETGREENER_RELEASE_TAG',
44
+ 'RELEASE_TAG',
45
+ 'IMAGE_TAG',
46
+ 'DOCKER_IMAGE_TAG',
47
+ 'DOCKER_TAG',
48
+ 'CONTAINER_IMAGE_TAG',
49
+ 'APP_VERSION',
50
+ 'CI_COMMIT_TAG',
51
+ 'BUILD_BUILDNUMBER',
52
+ ]);
53
+ }
54
+ /**
55
+ * Attach release identity + CI flags onto an existing run_context object.
56
+ * Never overwrites an already-set ``release_tag`` / ``git_sha`` / ``deploy_id``.
57
+ */
58
+ export function enrichRunContextForAnomaly(ctx, env = process.env) {
59
+ if (!(typeof ctx.release_tag === 'string' && ctx.release_tag.trim())) {
60
+ const tag = resolveReleaseTagFallback(env);
61
+ if (tag)
62
+ ctx.release_tag = tag.slice(0, 255);
63
+ }
64
+ if (!(typeof ctx.git_sha === 'string' && ctx.git_sha.trim())) {
65
+ const sha = firstEnv(env, [
66
+ 'NETGREENER_GIT_SHA',
67
+ 'GIT_SHA',
68
+ 'GITHUB_SHA',
69
+ 'BUILD_SOURCEVERSION',
70
+ ]);
71
+ if (sha)
72
+ ctx.git_sha = sha.slice(0, 64);
73
+ }
74
+ if (!(typeof ctx.deploy_id === 'string' && ctx.deploy_id.trim())) {
75
+ const deployId = firstEnv(env, [
76
+ 'NETGREENER_DEPLOY_ID',
77
+ 'DEPLOY_ID',
78
+ 'BUILD_BUILDID',
79
+ ]);
80
+ if (deployId)
81
+ ctx.deploy_id = deployId.slice(0, 255);
82
+ }
83
+ if (detectCi(env)) {
84
+ ctx.is_ci = true;
85
+ ctx.ci = true;
86
+ ctx.continuous_integration = true;
87
+ const provider = resolveCiProvider(env);
88
+ if (provider)
89
+ ctx.ci_provider = provider;
90
+ }
91
+ return ctx;
92
+ }
package/dist/runtime.d.ts CHANGED
@@ -1,7 +1,8 @@
1
1
  import { type RuntimeConfig } from './config.js';
2
2
  import { type RunSessionCreatePayload, type UploadResult } from './uploader.js';
3
3
  import { type ObservationExporter } from './exporter.js';
4
- export type FlushKind = 'periodic' | 'shutdown' | 'manual';
4
+ import { type ResolvedRuntimeLifecycle, type RuntimeModePreference } from './lifecycle.js';
5
+ export type FlushKind = 'periodic' | 'shutdown' | 'manual' | 'invoke_end';
5
6
  export type NetGreenerRuntimeOptions = {
6
7
  config?: RuntimeConfig;
7
8
  collector?: string;
@@ -10,12 +11,19 @@ export type NetGreenerRuntimeOptions = {
10
11
  /** MP2: defaults to direct upload exporter (unchanged pipeline). */
11
12
  exporter?: ObservationExporter;
12
13
  onFlush?: (result: UploadResult, payload: RunSessionCreatePayload) => void;
14
+ /**
15
+ * Lifecycle preference (auto | persistent | ephemeral).
16
+ * Default auto — serverless signals → ephemeral flush policy.
17
+ */
18
+ runtimeMode?: RuntimeModePreference;
13
19
  };
14
20
  /**
15
21
  * Process-wide runtime controller: record samples, periodic flush, shutdown flush.
22
+ * Ephemeral lifecycle skips the periodic timer and flushes at invoke/request idle.
16
23
  */
17
24
  export declare class NetGreenerRuntime {
18
25
  readonly config: RuntimeConfig;
26
+ readonly lifecycleInfo: ResolvedRuntimeLifecycle;
19
27
  private readonly aggregator;
20
28
  private readonly collector;
21
29
  private readonly framework;
@@ -26,12 +34,38 @@ export declare class NetGreenerRuntime {
26
34
  private flushing;
27
35
  private started;
28
36
  private outboundInstalled;
37
+ /** In-flight HTTP/task units — gates ephemeral idle flush. */
38
+ private inFlight;
39
+ private invokeFlushScheduled;
40
+ /**
41
+ * Sticky window id until a successful export — preserves idempotency across
42
+ * retry of the same in-memory snapshot (serverless / network retry).
43
+ */
44
+ private stickyWindowId;
29
45
  constructor(opts?: NetGreenerRuntimeOptions);
46
+ get lifecycle(): ResolvedRuntimeLifecycle['lifecycle'];
30
47
  get enabled(): boolean;
31
48
  private ensureOutboundMeter;
32
49
  /** Prefer unwrapped fetch so telemetry uploads are never metered. */
33
50
  private uploadFetch;
34
51
  start(): void;
52
+ /** Mark start of an inbound request/task (ephemeral idle-flush accounting). */
53
+ beginRequest(): void;
54
+ /**
55
+ * Mark end of an inbound request/task. In ephemeral mode, schedules a flush
56
+ * when no requests remain in flight (safe under concurrency).
57
+ *
58
+ * ``deferInvokeFlush`` only skips that idle flush. The Next.js adapter uses
59
+ * it so the upload runs from ``after()`` / ``waitUntil`` after the response
60
+ * closes. Express, Fastify, and Lambda callers keep the default.
61
+ */
62
+ endRequest(opts?: {
63
+ deferInvokeFlush?: boolean;
64
+ }): void;
65
+ /** Explicit serverless invoke-end flush (Lambda finally / platform adapter). */
66
+ flushForInvokeEnd(): Promise<UploadResult | null>;
67
+ /** Test helper: in-flight request counter. */
68
+ _inFlightForTests(): number;
35
69
  stop(): void;
36
70
  recordHttp(sample: {
37
71
  method: string;
@@ -42,6 +76,7 @@ export declare class NetGreenerRuntime {
42
76
  cpuTimeMs?: number;
43
77
  /** Measured RSS KiB at request end. */
44
78
  peakRssKb?: number;
79
+ unitType?: string;
45
80
  }): void;
46
81
  /** Record a background job / worker task sample (BullMQ, cron, scripts). */
47
82
  recordTask(sample: {
package/dist/runtime.js CHANGED
@@ -1,18 +1,45 @@
1
1
  import { hostname } from 'node:os';
2
2
  import { ServiceRuntimeAggregator } from './aggregator.js';
3
+ import { carbonFactorDict } from './carbonLedger.js';
3
4
  import { configReady, loadRuntimeConfig, } from './config.js';
4
5
  import { resolveObservationExporter, } from './exporter.js';
5
6
  import { newRuntimeWindowId } from './windowId.js';
6
7
  import { attachWindowTenantToRunContext, getTenantContext, tenantConfigFromRuntime, } from './tenantContext.js';
8
+ import { enrichRunContextForAnomaly } from './runContextEnrichment.js';
9
+ import { getOccupancyTracker } from './occupancyTracker.js';
7
10
  import { getExternalAggregator, getOriginalFetch, installOutboundInstrumentation, } from './externalApiMeter.js';
11
+ import { buildMcpLatencyV0, getMcpToolLedger, } from './mcpToolMeter.js';
8
12
  import { CPU_SOURCE_PROCESS, MEMORY_SOURCE_PROCESS, } from './processResources.js';
9
13
  import { CPU_SOURCE_DURATION_PROXY } from './n4/missingnessInventory.js';
10
14
  import { buildRuntimeHealthV0, markHooksActive, mergeHealthIntoMetadata, noteExportAttempt, noteExportMode, noteExportResult, noteFlushSkippedInFlight, _resetRuntimeHealthForTests, } from './runtimeHealth.js';
15
+ import { resolveLifecycle, } from './lifecycle.js';
16
+ function vercelDeploymentHosts() {
17
+ const hosts = [];
18
+ for (const key of ['VERCEL_URL', 'VERCEL_BRANCH_URL', 'VERCEL_PROJECT_PRODUCTION_URL']) {
19
+ const raw = String(process.env[key] || '').trim();
20
+ if (!raw)
21
+ continue;
22
+ try {
23
+ const host = (raw.includes('://') ? new URL(raw).hostname : raw.split('/')[0] || '')
24
+ .toLowerCase()
25
+ .replace(/^\*\./, '')
26
+ .replace(/^www\./, '');
27
+ if (host)
28
+ hosts.push(host);
29
+ }
30
+ catch {
31
+ /* ignore a malformed deployment host */
32
+ }
33
+ }
34
+ return hosts;
35
+ }
11
36
  /**
12
37
  * Process-wide runtime controller: record samples, periodic flush, shutdown flush.
38
+ * Ephemeral lifecycle skips the periodic timer and flushes at invoke/request idle.
13
39
  */
14
40
  export class NetGreenerRuntime {
15
41
  config;
42
+ lifecycleInfo;
16
43
  aggregator = new ServiceRuntimeAggregator();
17
44
  collector;
18
45
  framework;
@@ -23,14 +50,30 @@ export class NetGreenerRuntime {
23
50
  flushing = false;
24
51
  started = false;
25
52
  outboundInstalled = false;
53
+ /** In-flight HTTP/task units — gates ephemeral idle flush. */
54
+ inFlight = 0;
55
+ invokeFlushScheduled = false;
56
+ /**
57
+ * Sticky window id until a successful export — preserves idempotency across
58
+ * retry of the same in-memory snapshot (serverless / network retry).
59
+ */
60
+ stickyWindowId = null;
26
61
  constructor(opts = {}) {
27
62
  this.config = opts.config ?? loadRuntimeConfig();
28
63
  this.collector = opts.collector ?? 'express_middleware';
29
64
  this.framework = opts.framework ?? 'express';
30
65
  this.fetchImpl = opts.fetchImpl ?? fetch;
31
- this.exporter = opts.exporter ?? resolveObservationExporter();
66
+ this.lifecycleInfo = resolveLifecycle({ mode: opts.runtimeMode });
67
+ this.exporter =
68
+ opts.exporter ??
69
+ resolveObservationExporter(undefined, {
70
+ lifecycle: this.lifecycleInfo.lifecycle,
71
+ });
32
72
  this.onFlush = opts.onFlush;
33
73
  }
74
+ get lifecycle() {
75
+ return this.lifecycleInfo.lifecycle;
76
+ }
34
77
  get enabled() {
35
78
  return configReady(this.config).ok;
36
79
  }
@@ -38,14 +81,24 @@ export class NetGreenerRuntime {
38
81
  if (this.outboundInstalled || !this.enabled)
39
82
  return;
40
83
  this.outboundInstalled = true;
84
+ const firstPartyHosts = [
85
+ ...String(process.env.NETGREENER_FIRST_PARTY_HOSTS || '')
86
+ .split(',')
87
+ .map((h) => h.trim().toLowerCase().replace(/^\*\./, '').replace(/^www\./, ''))
88
+ .filter(Boolean),
89
+ ...vercelDeploymentHosts(),
90
+ ];
41
91
  try {
42
92
  const apiHost = new URL(this.config.apiUrl).hostname;
93
+ const excluded = [...(apiHost ? [apiHost] : []), ...firstPartyHosts];
43
94
  installOutboundInstrumentation({
44
- excludedHosts: apiHost ? [apiHost] : [],
95
+ excludedHosts: excluded,
45
96
  });
46
97
  }
47
98
  catch {
48
- installOutboundInstrumentation();
99
+ installOutboundInstrumentation({
100
+ excludedHosts: firstPartyHosts,
101
+ });
49
102
  }
50
103
  }
51
104
  /** Prefer unwrapped fetch so telemetry uploads are never metered. */
@@ -64,11 +117,51 @@ export class NetGreenerRuntime {
64
117
  });
65
118
  noteExportMode(this.exporter.mode);
66
119
  this.ensureOutboundMeter();
67
- this.timer = setInterval(() => {
68
- void this.flush('periodic');
69
- }, this.config.flushIntervalMs);
70
- // Do not keep the process alive solely for the timer.
71
- this.timer.unref?.();
120
+ // Persistent path unchanged: periodic flush. Ephemeral must not depend on it.
121
+ if (this.lifecycle === 'persistent' && this.lifecycleInfo.capabilities.periodic_flush) {
122
+ this.timer = setInterval(() => {
123
+ void this.flush('periodic');
124
+ }, this.config.flushIntervalMs);
125
+ // Do not keep the process alive solely for the timer.
126
+ this.timer.unref?.();
127
+ }
128
+ }
129
+ /** Mark start of an inbound request/task (ephemeral idle-flush accounting). */
130
+ beginRequest() {
131
+ this.inFlight += 1;
132
+ }
133
+ /**
134
+ * Mark end of an inbound request/task. In ephemeral mode, schedules a flush
135
+ * when no requests remain in flight (safe under concurrency).
136
+ *
137
+ * ``deferInvokeFlush`` only skips that idle flush. The Next.js adapter uses
138
+ * it so the upload runs from ``after()`` / ``waitUntil`` after the response
139
+ * closes. Express, Fastify, and Lambda callers keep the default.
140
+ */
141
+ endRequest(opts) {
142
+ if (this.inFlight > 0)
143
+ this.inFlight -= 1;
144
+ if (this.lifecycle !== 'ephemeral')
145
+ return;
146
+ if (opts?.deferInvokeFlush)
147
+ return;
148
+ if (this.invokeFlushScheduled)
149
+ return;
150
+ this.invokeFlushScheduled = true;
151
+ void Promise.resolve().then(() => {
152
+ this.invokeFlushScheduled = false;
153
+ if (this.inFlight === 0) {
154
+ void this.flush('invoke_end');
155
+ }
156
+ });
157
+ }
158
+ /** Explicit serverless invoke-end flush (Lambda finally / platform adapter). */
159
+ async flushForInvokeEnd() {
160
+ return this.flush('invoke_end');
161
+ }
162
+ /** Test helper: in-flight request counter. */
163
+ _inFlightForTests() {
164
+ return this.inFlight;
72
165
  }
73
166
  stop() {
74
167
  if (this.timer) {
@@ -88,7 +181,7 @@ export class NetGreenerRuntime {
88
181
  const serviceUnit = `${sample.method.toUpperCase()} ${sample.path}`;
89
182
  this.aggregator.record({
90
183
  serviceUnit,
91
- unitType: 'http_route',
184
+ unitType: sample.unitType || 'http_route',
92
185
  durationMs: sample.durationMs,
93
186
  error: sample.statusCode >= 400,
94
187
  tenantId: getTenantContext()?.tenantId ?? null,
@@ -128,6 +221,7 @@ export class NetGreenerRuntime {
128
221
  if (!hasRuntime && !hasExternal)
129
222
  return null;
130
223
  this.flushing = true;
224
+ let mcpSnapshot = null;
131
225
  noteExportMode(this.exporter.mode);
132
226
  const snapshot = hasRuntime ? this.aggregator.takeSnapshot() : null;
133
227
  const externalSnapshot = hasExternal ? externalAgg.takeSnapshot() : null;
@@ -144,12 +238,20 @@ export class NetGreenerRuntime {
144
238
  : 0;
145
239
  const util = Math.min(1, busySeconds / Math.max(windowSeconds, 0.001));
146
240
  const windowEnergyKwh = (this.config.estimateTdpWatts * util * windowSeconds) / 1000 / 3600;
241
+ const occupancy = getOccupancyTracker().takeWindowSnapshot();
242
+ // Crude window RAM (GiB·h) from peak RSS — allocated by occupancy when present.
243
+ const peakRssKb = snapshot ? snapshot.maxPeakRssKb() : 0;
244
+ const windowRamGbHours = peakRssKb > 0
245
+ ? (peakRssKb / 1024 / 1024) * (windowSeconds / 3600)
246
+ : null;
147
247
  const runtimeV0 = snapshot
148
248
  ? snapshot.buildV0({
149
249
  collector: this.collector,
150
250
  framework: this.framework,
151
251
  windowEnergyKwh,
152
252
  windowSeconds,
253
+ windowRamGbHours,
254
+ occupancy,
153
255
  })
154
256
  : null;
155
257
  if (snapshot && !runtimeV0) {
@@ -159,9 +261,19 @@ export class NetGreenerRuntime {
159
261
  return null;
160
262
  }
161
263
  const externalV0 = externalSnapshot ? externalSnapshot.buildV0() : null;
264
+ const mcpLedger = getMcpToolLedger();
265
+ mcpSnapshot = mcpLedger.hasCalls() ? mcpLedger.takeSnapshot() : null;
266
+ const mcpV0 = mcpSnapshot ? mcpSnapshot.buildV0() : null;
267
+ if (mcpSnapshot && !mcpV0) {
268
+ mcpLedger.mergeSnapshot(mcpSnapshot);
269
+ mcpSnapshot = null;
270
+ }
271
+ const latencyV0 = buildMcpLatencyV0(mcpV0, externalV0 ?? null, windowSeconds);
162
272
  const end = new Date();
163
273
  const start = new Date(end.getTime() - windowSeconds * 1000);
164
- const windowId = newRuntimeWindowId();
274
+ // Reuse sticky id until success so retries do not mint a new window.
275
+ const windowId = this.stickyWindowId ?? newRuntimeWindowId();
276
+ this.stickyWindowId = windowId;
165
277
  // Prefer effective RuntimeConfig over ambient process.env.
166
278
  const tenantConfig = tenantConfigFromRuntime(this.config);
167
279
  const runContext = {
@@ -169,11 +281,15 @@ export class NetGreenerRuntime {
169
281
  runtime_flush_kind: kind,
170
282
  measured_scope: 'process',
171
283
  resource_scope: 'process',
284
+ runtime_lifecycle: this.lifecycleInfo.lifecycle,
285
+ runtime_platform: this.lifecycleInfo.platform,
286
+ runtime_capabilities: this.lifecycleInfo.capabilities,
172
287
  ...(this.config.deployEnvironment
173
288
  ? { deploy_environment: this.config.deployEnvironment }
174
289
  : {}),
175
290
  ...(this.config.releaseTag ? { release_tag: this.config.releaseTag } : {}),
176
291
  };
292
+ enrichRunContextForAnomaly(runContext);
177
293
  attachWindowTenantToRunContext(runContext, {
178
294
  runtimeV0: runtimeV0 ?? undefined,
179
295
  externalV0: externalV0 ?? undefined,
@@ -182,10 +298,13 @@ export class NetGreenerRuntime {
182
298
  });
183
299
  const measuredCpu = snapshot?.hasMeasuredCpu() ?? false;
184
300
  const measuredRss = snapshot?.hasMeasuredRss() ?? false;
301
+ const carbonFactor = carbonFactorDict();
185
302
  const session_metadata = {
186
303
  run_context: runContext,
187
304
  ...(runtimeV0 ? { service_runtime_v0: runtimeV0 } : {}),
188
305
  ...(externalV0 ? { external_api_v0: externalV0 } : {}),
306
+ ...(mcpV0 ? { mcp_tool_v0: mcpV0 } : {}),
307
+ ...(latencyV0 ? { mcp_latency_v0: latencyV0 } : {}),
189
308
  measurement_provenance: {
190
309
  cpu_source: runtimeV0
191
310
  ? measuredCpu
@@ -196,11 +315,7 @@ export class NetGreenerRuntime {
196
315
  energy_model: runtimeV0 ? 'tdp_utilization_estimate' : 'unavailable',
197
316
  gpu_scope: 'none',
198
317
  gpu_source: 'unavailable',
199
- carbon_factor: {
200
- value: 0.4,
201
- unit: 'kg_co2e_per_kwh',
202
- source: 'default_grid_factor',
203
- },
318
+ carbon_factor: carbonFactor,
204
319
  evidence_grades: {
205
320
  schema_version: 1,
206
321
  policy_version: 'r9_v0',
@@ -214,7 +329,7 @@ export class NetGreenerRuntime {
214
329
  metric: 'local_carbon',
215
330
  grade: runtimeV0 ? 'G1' : 'G0',
216
331
  reasons: runtimeV0
217
- ? ['estimated_power_tdp', 'default_grid_factor']
332
+ ? ['estimated_power_tdp', carbonFactor.source]
218
333
  : ['no_runtime_units'],
219
334
  },
220
335
  },
@@ -242,6 +357,12 @@ export class NetGreenerRuntime {
242
357
  this.aggregator.mergeSnapshot(snapshot);
243
358
  if (externalSnapshot)
244
359
  externalAgg.mergeSnapshot(externalSnapshot);
360
+ if (mcpSnapshot)
361
+ getMcpToolLedger().mergeSnapshot(mcpSnapshot);
362
+ // Keep stickyWindowId so the next flush retries the same window id.
363
+ }
364
+ else {
365
+ this.stickyWindowId = null;
245
366
  }
246
367
  this.onFlush?.(result, payload);
247
368
  return result;
@@ -252,6 +373,8 @@ export class NetGreenerRuntime {
252
373
  this.aggregator.mergeSnapshot(snapshot);
253
374
  if (externalSnapshot)
254
375
  externalAgg.mergeSnapshot(externalSnapshot);
376
+ if (mcpSnapshot)
377
+ getMcpToolLedger().mergeSnapshot(mcpSnapshot);
255
378
  const result = {
256
379
  ok: false,
257
380
  error: err instanceof Error ? err.message : String(err),
@@ -260,7 +383,7 @@ export class NetGreenerRuntime {
260
383
  project_id: this.config.projectId,
261
384
  start_time: new Date().toISOString(),
262
385
  end_time: new Date().toISOString(),
263
- runtime_window_id: newRuntimeWindowId(),
386
+ runtime_window_id: this.stickyWindowId ?? newRuntimeWindowId(),
264
387
  session_metadata: {},
265
388
  });
266
389
  return result;