@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.
- package/CHANGELOG.md +12 -0
- package/TUTORIAL.md +120 -29
- package/dist/aggregator.d.ts +12 -2
- package/dist/aggregator.js +135 -8
- package/dist/analyze/buildResourceFindings.d.ts +4 -0
- package/dist/analyze/buildResourceFindings.js +17 -0
- package/dist/analyze/cli.d.ts +1 -0
- package/dist/analyze/cli.js +22 -1
- package/dist/analyze/declaredExternalApis.d.ts +31 -0
- package/dist/analyze/declaredExternalApis.js +174 -0
- package/dist/analyze/index.d.ts +1 -0
- package/dist/analyze/index.js +1 -0
- package/dist/auto.d.ts +7 -0
- package/dist/auto.js +8 -0
- package/dist/bullmq.d.ts +2 -2
- package/dist/bullmq.js +28 -58
- package/dist/carbonLedger.d.ts +28 -0
- package/dist/carbonLedger.js +52 -0
- package/dist/cgroupV2.d.ts +44 -0
- package/dist/cgroupV2.js +174 -0
- package/dist/cli/helpText.d.ts +3 -3
- package/dist/cli/helpText.js +42 -35
- package/dist/cli/netgreener.d.ts +7 -7
- package/dist/cli/netgreener.js +23 -16
- package/dist/cli/runCli.d.ts +20 -0
- package/dist/cli/runCli.js +249 -0
- package/dist/cli/runPreload.d.ts +5 -0
- package/dist/cli/runPreload.js +43 -0
- package/dist/collectorMetadata.d.ts +1 -1
- package/dist/collectorMetadata.js +2 -0
- package/dist/config.d.ts +2 -0
- package/dist/config.js +6 -2
- package/dist/exporter.d.ts +7 -2
- package/dist/exporter.js +12 -6
- package/dist/express.js +17 -6
- package/dist/externalApiMeter.d.ts +51 -2
- package/dist/externalApiMeter.js +379 -26
- package/dist/fastify.js +17 -6
- package/dist/index.d.ts +12 -2
- package/dist/index.js +11 -1
- package/dist/init.d.ts +30 -0
- package/dist/init.js +31 -0
- package/dist/lifecycle.d.ts +45 -0
- package/dist/lifecycle.js +112 -0
- package/dist/managedCollectorLauncher.d.ts +37 -0
- package/dist/managedCollectorLauncher.js +162 -0
- package/dist/mcpToolMeter.d.ts +101 -0
- package/dist/mcpToolMeter.js +496 -0
- package/dist/n4/deploymentMatrix.d.ts +9 -5
- package/dist/n4/deploymentMatrix.js +13 -9
- package/dist/n4/missingnessInventory.js +3 -3
- package/dist/next.d.ts +89 -0
- package/dist/next.js +328 -0
- package/dist/nextConfig.d.ts +34 -0
- package/dist/nextConfig.js +73 -0
- package/dist/nextEntryTransform.d.ts +9 -0
- package/dist/nextEntryTransform.js +181 -0
- package/dist/occupancyTracker.d.ts +27 -0
- package/dist/occupancyTracker.js +87 -0
- package/dist/optimize/apply.d.ts +38 -0
- package/dist/optimize/apply.js +173 -0
- package/dist/optimize/cli.d.ts +26 -0
- package/dist/optimize/cli.js +323 -0
- package/dist/optimize/index.d.ts +6 -0
- package/dist/optimize/index.js +5 -0
- package/dist/optimize/llmApply.d.ts +22 -0
- package/dist/optimize/llmApply.js +80 -0
- package/dist/optimize/llmSession.d.ts +88 -0
- package/dist/optimize/llmSession.js +135 -0
- package/dist/optimize/provider.d.ts +17 -0
- package/dist/optimize/provider.js +119 -0
- package/dist/optimize/safePatches.d.ts +18 -0
- package/dist/optimize/safePatches.js +247 -0
- package/dist/optimize/types.d.ts +79 -0
- package/dist/optimize/types.js +6 -0
- package/dist/optimize/verification.d.ts +16 -0
- package/dist/optimize/verification.js +165 -0
- package/dist/processResources.d.ts +5 -0
- package/dist/processResources.js +28 -4
- package/dist/processRuntime.js +7 -28
- package/dist/processTree.d.ts +47 -0
- package/dist/processTree.js +148 -0
- package/dist/runContextEnrichment.d.ts +11 -0
- package/dist/runContextEnrichment.js +92 -0
- package/dist/runtime.d.ts +36 -1
- package/dist/runtime.js +140 -17
- package/dist/sdk/client.d.ts +152 -0
- package/dist/sdk/client.js +396 -0
- package/dist/sdk/gitUrl.d.ts +6 -0
- package/dist/sdk/gitUrl.js +87 -0
- package/dist/sdk/index.d.ts +5 -0
- package/dist/sdk/index.js +5 -0
- package/dist/serverlessHints.d.ts +9 -6
- package/dist/serverlessHints.js +10 -7
- package/dist/taskMeter.d.ts +14 -0
- package/dist/taskMeter.js +53 -0
- package/dist/types.d.ts +43 -0
- package/examples/aca-container-gate/Dockerfile +20 -0
- package/examples/aca-container-gate/azure-container-app.yaml +27 -0
- package/examples/aca-container-gate/gate.env +7 -0
- package/examples/aca-container-gate/server.mjs +117 -0
- package/examples/azure-functions-gate/.funcignore +6 -0
- package/examples/azure-functions-gate/README.md +25 -0
- package/examples/azure-functions-gate/host.json +15 -0
- package/examples/azure-functions-gate/package-lock.json +161 -0
- package/examples/azure-functions-gate/package.json +14 -0
- package/examples/azure-functions-gate/src/functions/health.js +27 -0
- package/examples/express-local-live-smoke.mjs +127 -0
- package/examples/extractRunId.mjs +11 -0
- package/examples/next-pilot-dry-run.mjs +32 -0
- package/examples/serverless-thin-gate.mjs +89 -0
- package/fixtures/run-smoke/hello.mjs +4 -0
- package/loaders/next-entry-loader.cjs +14 -0
- 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
|
-
|
|
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.
|
|
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:
|
|
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
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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
|
-
|
|
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',
|
|
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;
|