@netgreener/runtime 0.1.13 → 0.1.15
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/TUTORIAL.md +1 -1
- package/dist/aggregator.d.ts +3 -1
- package/dist/aggregator.js +23 -16
- package/dist/cli/checkCli.d.ts +2 -0
- package/dist/cli/checkCli.js +121 -0
- package/dist/cli/helpText.js +1 -0
- package/dist/cli/netgreener.js +7 -0
- package/dist/config.d.ts +1 -1
- package/dist/config.js +1 -1
- package/dist/contract/validate.d.ts +1 -1
- package/dist/contract/validate.js +24 -3
- package/dist/externalApiMeter.d.ts +1 -0
- package/dist/externalApiMeter.js +45 -0
- package/dist/lifecycle.d.ts +4 -2
- package/dist/lifecycle.js +5 -4
- package/dist/runContextEnrichment.js +44 -1
- package/dist/runtime.d.ts +7 -2
- package/dist/runtime.js +59 -17
- package/dist/runtimeControls.d.ts +2 -1
- package/dist/runtimeControls.js +28 -7
- package/dist/sdk/client.d.ts +27 -0
- package/dist/sdk/client.js +7 -0
- package/dist/sdk/index.d.ts +1 -0
- package/dist/taskMeter.js +17 -5
- package/dist/types.d.ts +4 -0
- package/fixtures/external-api-gate/scenarios.v1.json +617 -0
- package/fixtures/release_identity_platforms.json +14 -0
- package/package.json +1 -1
package/TUTORIAL.md
CHANGED
|
@@ -227,7 +227,7 @@ Pass = scripts exit 0; payloads validate; no live upload required.
|
|
|
227
227
|
|
|
228
228
|
1. Deploy / start the API with live env (§4.3).
|
|
229
229
|
2. Call 2–3 real routes (health + one business route).
|
|
230
|
-
3. Stop the process (or wait for `NETGREENER_RUNTIME_FLUSH_MINUTES`, default
|
|
230
|
+
3. Stop the process (or wait for `NETGREENER_RUNTIME_FLUSH_MINUTES`, default 1).
|
|
231
231
|
4. Dashboard → **Project `<PROJECT_ID>`** → newest **Run** → **Runtime Ops** / API Runtime.
|
|
232
232
|
5. Pass = bounded route templates listed (e.g. `GET /health`), not raw customer paths.
|
|
233
233
|
6. Keep a sanitized evidence record (revision, env, run id) — see
|
package/dist/aggregator.d.ts
CHANGED
|
@@ -16,9 +16,11 @@ export declare class ServiceRuntimeAggregator {
|
|
|
16
16
|
cpuTimeMs?: number;
|
|
17
17
|
/** Measured RSS KiB at sample end. */
|
|
18
18
|
peakRssKb?: number;
|
|
19
|
+
completed?: boolean;
|
|
20
|
+
completionDurationMs?: number;
|
|
19
21
|
}): void;
|
|
20
22
|
private recordIntoMap;
|
|
21
|
-
/** Peak RSS (KiB) across units with calls — for
|
|
23
|
+
/** Peak RSS (KiB) across units with calls/activity — for the window RAM estimate. */
|
|
22
24
|
maxPeakRssKb(): number;
|
|
23
25
|
private buildUnitsList;
|
|
24
26
|
hasData(): boolean;
|
package/dist/aggregator.js
CHANGED
|
@@ -57,6 +57,7 @@ export class ServiceRuntimeAggregator {
|
|
|
57
57
|
calls: 0,
|
|
58
58
|
errors: 0,
|
|
59
59
|
durationMsTotal: 0,
|
|
60
|
+
completedDurationMsTotal: 0,
|
|
60
61
|
durationMsMax: 0,
|
|
61
62
|
cpuMsTotal: 0,
|
|
62
63
|
cpuMsMeasured: false,
|
|
@@ -65,13 +66,18 @@ export class ServiceRuntimeAggregator {
|
|
|
65
66
|
target.set(key, unit);
|
|
66
67
|
}
|
|
67
68
|
}
|
|
68
|
-
|
|
69
|
-
|
|
69
|
+
if (sample.completed !== false)
|
|
70
|
+
unit.calls += 1;
|
|
71
|
+
if (sample.completed !== false && sample.error)
|
|
70
72
|
unit.errors += 1;
|
|
71
73
|
// Math.max(0, NaN) === NaN — must reject non-finite before accumulate.
|
|
72
74
|
const ms = nonNegativeFinite(sample.durationMs);
|
|
73
75
|
unit.durationMsTotal += ms;
|
|
74
|
-
|
|
76
|
+
if (sample.completed !== false) {
|
|
77
|
+
const completedMs = nonNegativeFinite(sample.completionDurationMs ?? sample.durationMs);
|
|
78
|
+
unit.completedDurationMsTotal += completedMs;
|
|
79
|
+
unit.durationMsMax = Math.max(unit.durationMsMax, completedMs);
|
|
80
|
+
}
|
|
75
81
|
if (sample.cpuTimeMs !== undefined) {
|
|
76
82
|
unit.cpuMsTotal += nonNegativeFinite(sample.cpuTimeMs);
|
|
77
83
|
unit.cpuMsMeasured = true;
|
|
@@ -82,17 +88,17 @@ export class ServiceRuntimeAggregator {
|
|
|
82
88
|
unit.peakRssKbMax = Math.max(unit.peakRssKbMax, rss);
|
|
83
89
|
}
|
|
84
90
|
}
|
|
85
|
-
/** Peak RSS (KiB) across units with calls — for
|
|
91
|
+
/** Peak RSS (KiB) across units with calls/activity — for the window RAM estimate. */
|
|
86
92
|
maxPeakRssKb() {
|
|
87
93
|
let max = 0;
|
|
88
94
|
for (const u of this.units.values()) {
|
|
89
|
-
if (u.calls > 0 && u.peakRssKbMax > max)
|
|
95
|
+
if ((u.calls > 0 || u.durationMsTotal > 0) && u.peakRssKbMax > max)
|
|
90
96
|
max = u.peakRssKbMax;
|
|
91
97
|
}
|
|
92
98
|
return max;
|
|
93
99
|
}
|
|
94
100
|
buildUnitsList(source, windowEnergyKwh, equalShare, totalDuration, occByUnit, alloc) {
|
|
95
|
-
const list = [...source.values()].filter((u) => u.calls > 0);
|
|
101
|
+
const list = [...source.values()].filter((u) => (u.calls > 0 || u.durationMsTotal > 0));
|
|
96
102
|
if (!list.length)
|
|
97
103
|
return [];
|
|
98
104
|
const energyBudget = nonNegativeFinite(windowEnergyKwh);
|
|
@@ -104,9 +110,9 @@ export class ServiceRuntimeAggregator {
|
|
|
104
110
|
const sorted = list.sort((a, b) => b.durationMsTotal - a.durationMsTotal);
|
|
105
111
|
const totalCalls = list.reduce((sum, unit) => sum + unit.calls, 0);
|
|
106
112
|
const units = sorted.map((u) => {
|
|
107
|
-
const share = equalShare ? u.calls / totalCalls : u.durationMsTotal / totalDuration;
|
|
113
|
+
const share = equalShare ? (totalCalls > 0 ? u.calls / totalCalls : 1 / list.length) : u.durationMsTotal / totalDuration;
|
|
108
114
|
const energy = energyBudget * share;
|
|
109
|
-
const avg = u.calls ? u.
|
|
115
|
+
const avg = u.calls ? u.completedDurationMsTotal / u.calls : 0;
|
|
110
116
|
const cpuSeconds = alloc?.windowCpuSeconds != null
|
|
111
117
|
? nonNegativeFinite(alloc.windowCpuSeconds) * share
|
|
112
118
|
: u.cpuMsMeasured
|
|
@@ -153,7 +159,7 @@ export class ServiceRuntimeAggregator {
|
|
|
153
159
|
}
|
|
154
160
|
hasData() {
|
|
155
161
|
for (const u of this.units.values()) {
|
|
156
|
-
if (u.calls > 0)
|
|
162
|
+
if ((u.calls > 0 || u.durationMsTotal > 0))
|
|
157
163
|
return true;
|
|
158
164
|
}
|
|
159
165
|
return false;
|
|
@@ -161,7 +167,7 @@ export class ServiceRuntimeAggregator {
|
|
|
161
167
|
totalDurationMs() {
|
|
162
168
|
let total = 0;
|
|
163
169
|
for (const u of this.units.values()) {
|
|
164
|
-
if (u.calls > 0)
|
|
170
|
+
if ((u.calls > 0 || u.durationMsTotal > 0))
|
|
165
171
|
total += u.durationMsTotal;
|
|
166
172
|
}
|
|
167
173
|
return total;
|
|
@@ -170,7 +176,7 @@ export class ServiceRuntimeAggregator {
|
|
|
170
176
|
totalMeasuredCpuMs() {
|
|
171
177
|
let total = 0;
|
|
172
178
|
for (const u of this.units.values()) {
|
|
173
|
-
if (u.calls > 0 && u.cpuMsMeasured)
|
|
179
|
+
if ((u.calls > 0 || u.durationMsTotal > 0) && u.cpuMsMeasured)
|
|
174
180
|
total += u.cpuMsTotal;
|
|
175
181
|
}
|
|
176
182
|
return total;
|
|
@@ -178,7 +184,7 @@ export class ServiceRuntimeAggregator {
|
|
|
178
184
|
/** True when any unit recorded measured process CPU (not duration proxy). */
|
|
179
185
|
hasMeasuredCpu() {
|
|
180
186
|
for (const u of this.units.values()) {
|
|
181
|
-
if (u.calls > 0 && u.cpuMsMeasured)
|
|
187
|
+
if ((u.calls > 0 || u.durationMsTotal > 0) && u.cpuMsMeasured)
|
|
182
188
|
return true;
|
|
183
189
|
}
|
|
184
190
|
return false;
|
|
@@ -186,7 +192,7 @@ export class ServiceRuntimeAggregator {
|
|
|
186
192
|
/** True when any unit recorded peak RSS. */
|
|
187
193
|
hasMeasuredRss() {
|
|
188
194
|
for (const u of this.units.values()) {
|
|
189
|
-
if (u.calls > 0 && u.peakRssKbMax > 0)
|
|
195
|
+
if ((u.calls > 0 || u.durationMsTotal > 0) && u.peakRssKbMax > 0)
|
|
190
196
|
return true;
|
|
191
197
|
}
|
|
192
198
|
return false;
|
|
@@ -197,7 +203,7 @@ export class ServiceRuntimeAggregator {
|
|
|
197
203
|
* Occupancy is window-scaled (Python twin) so coverage reconciles to ``window_seconds``.
|
|
198
204
|
*/
|
|
199
205
|
buildV0(opts) {
|
|
200
|
-
const list = [...this.units.values()].filter((u) => u.calls > 0);
|
|
206
|
+
const list = [...this.units.values()].filter((u) => (u.calls > 0 || u.durationMsTotal > 0));
|
|
201
207
|
if (!list.length)
|
|
202
208
|
return null;
|
|
203
209
|
const windowEnergyKwh = nonNegativeFinite(opts.windowEnergyKwh);
|
|
@@ -263,12 +269,12 @@ export class ServiceRuntimeAggregator {
|
|
|
263
269
|
const totalBusy = list.reduce((s, u) => s + u.durationMsTotal, 0);
|
|
264
270
|
const totalCalls = list.reduce((s, u) => s + u.calls, 0);
|
|
265
271
|
for (const [tenantId, tenantMap] of this.byTenant.entries()) {
|
|
266
|
-
const tenantList = [...tenantMap.values()].filter((u) => u.calls > 0);
|
|
272
|
+
const tenantList = [...tenantMap.values()].filter((u) => (u.calls > 0 || u.durationMsTotal > 0));
|
|
267
273
|
if (!tenantList.length)
|
|
268
274
|
continue;
|
|
269
275
|
const tenantBusy = tenantList.reduce((s, u) => s + u.durationMsTotal, 0);
|
|
270
276
|
const tenantShare = totalBusy > 0 ? tenantBusy / totalBusy
|
|
271
|
-
: tenantList.reduce((sum, unit) => sum + unit.calls, 0) / totalCalls;
|
|
277
|
+
: totalCalls > 0 ? tenantList.reduce((sum, unit) => sum + unit.calls, 0) / totalCalls : 0;
|
|
272
278
|
const tenantEnergy = totalBusy > 0
|
|
273
279
|
? windowEnergyKwh * (tenantBusy / totalBusy)
|
|
274
280
|
: windowEnergyKwh * tenantShare;
|
|
@@ -411,6 +417,7 @@ export class ServiceRuntimeAggregator {
|
|
|
411
417
|
dst.calls += src.calls;
|
|
412
418
|
dst.errors += src.errors;
|
|
413
419
|
dst.durationMsTotal += src.durationMsTotal;
|
|
420
|
+
dst.completedDurationMsTotal += src.completedDurationMsTotal;
|
|
414
421
|
dst.durationMsMax = Math.max(dst.durationMsMax, src.durationMsMax);
|
|
415
422
|
dst.cpuMsTotal += src.cpuMsTotal;
|
|
416
423
|
dst.cpuMsMeasured = dst.cpuMsMeasured || src.cpuMsMeasured;
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
/** External usage budgets share the API evaluator with Python. */
|
|
2
|
+
import { loadRuntimeConfig } from '../config.js';
|
|
3
|
+
import { NetGreenerClient } from '../sdk/client.js';
|
|
4
|
+
export function formatCheckHelp() {
|
|
5
|
+
return `Usage: netgreener check --run-id <id> [options]
|
|
6
|
+
|
|
7
|
+
Check an uploaded run's observed token/API usage and estimated costs.
|
|
8
|
+
Options:
|
|
9
|
+
--max-total-tokens <n> Input + output token cap
|
|
10
|
+
--max-input-tokens <n> Input token cap
|
|
11
|
+
--max-output-tokens <n> Output token cap
|
|
12
|
+
--max-external-api-calls <n> Observed outbound call cap
|
|
13
|
+
--max-external-cost-usd <n> Estimated USD cap (configured server pricing)
|
|
14
|
+
--external-provider <key> Scope to provider or provider::model
|
|
15
|
+
--project-id <id> Verify the run belongs to this project
|
|
16
|
+
--run-id <id> Run ID (or NETGREENER_LAST_RUN_ID)
|
|
17
|
+
--output-json Print structured evaluation
|
|
18
|
+
--warn-only Report failures but exit 0
|
|
19
|
+
-h, --help Show help
|
|
20
|
+
|
|
21
|
+
Missing telemetry, incomplete required token coverage, or missing pricing fails.
|
|
22
|
+
Empty telemetry does not prove zero usage. OCR pricing is per call, not page.
|
|
23
|
+
Exit: 0 pass, 1 budget/data failure, 2 configuration/auth/API failure.
|
|
24
|
+
Python resource/baseline flags are not part of this Node command.
|
|
25
|
+
`;
|
|
26
|
+
}
|
|
27
|
+
export async function runCheckCli(argv, env = process.env, fetchImpl = globalThis.fetch.bind(globalThis)) {
|
|
28
|
+
try {
|
|
29
|
+
if (argv.includes('--help') || argv.includes('-h')) {
|
|
30
|
+
process.stdout.write(formatCheckHelp());
|
|
31
|
+
return 0;
|
|
32
|
+
}
|
|
33
|
+
const budgets = {};
|
|
34
|
+
const countFlags = new Map([
|
|
35
|
+
['--max-total-tokens', 'max_total_tokens'],
|
|
36
|
+
['--max-input-tokens', 'max_input_tokens'],
|
|
37
|
+
['--max-output-tokens', 'max_output_tokens'],
|
|
38
|
+
['--max-external-api-calls', 'max_external_api_calls'],
|
|
39
|
+
]);
|
|
40
|
+
let runId = Number(env.NETGREENER_LAST_RUN_ID || 0);
|
|
41
|
+
let projectId = Number(env.NETGREENER_PROJECT_ID || 0);
|
|
42
|
+
let outputJson = false;
|
|
43
|
+
let warnOnly = false;
|
|
44
|
+
for (let i = 0; i < argv.length; i++) {
|
|
45
|
+
const flag = argv[i];
|
|
46
|
+
if (flag === '--output-json') {
|
|
47
|
+
outputJson = true;
|
|
48
|
+
continue;
|
|
49
|
+
}
|
|
50
|
+
if (flag === '--warn-only') {
|
|
51
|
+
warnOnly = true;
|
|
52
|
+
continue;
|
|
53
|
+
}
|
|
54
|
+
if (!countFlags.has(flag) && !['--max-external-cost-usd', '--external-provider', '--run-id', '--project-id'].includes(flag)) {
|
|
55
|
+
throw new Error(`Unknown option: ${flag}`);
|
|
56
|
+
}
|
|
57
|
+
const raw = argv[++i];
|
|
58
|
+
if (raw === undefined || !raw.trim())
|
|
59
|
+
throw new Error(`Missing value for ${flag}`);
|
|
60
|
+
if (flag === '--external-provider') {
|
|
61
|
+
budgets.external_provider = raw;
|
|
62
|
+
continue;
|
|
63
|
+
}
|
|
64
|
+
const value = Number(raw);
|
|
65
|
+
if (!Number.isFinite(value) || value < 0 || (flag !== '--max-external-cost-usd' && !Number.isSafeInteger(value))) {
|
|
66
|
+
throw new Error(`Invalid nonnegative value for ${flag}`);
|
|
67
|
+
}
|
|
68
|
+
if (flag === '--run-id')
|
|
69
|
+
runId = value;
|
|
70
|
+
else if (flag === '--project-id')
|
|
71
|
+
projectId = value;
|
|
72
|
+
else if (flag === '--max-external-cost-usd')
|
|
73
|
+
budgets.max_external_cost_usd = value;
|
|
74
|
+
else
|
|
75
|
+
Object.assign(budgets, { [countFlags.get(flag)]: value });
|
|
76
|
+
}
|
|
77
|
+
if (!Object.keys(budgets).some(key => key.startsWith('max_')))
|
|
78
|
+
throw new Error('Set at least one external usage cap');
|
|
79
|
+
if (!Number.isSafeInteger(runId) || runId <= 0)
|
|
80
|
+
throw new Error('Specify --run-id or NETGREENER_LAST_RUN_ID');
|
|
81
|
+
if (!Number.isSafeInteger(projectId) || projectId < 0)
|
|
82
|
+
throw new Error('Invalid project ID');
|
|
83
|
+
const config = loadRuntimeConfig(env);
|
|
84
|
+
if (!config.token)
|
|
85
|
+
throw new Error('NETGREENER_TOKEN missing');
|
|
86
|
+
const client = new NetGreenerClient({
|
|
87
|
+
baseUrl: `${config.apiUrl}/api/v1`, token: config.token,
|
|
88
|
+
orgId: config.organizationId ?? undefined, fetchImpl,
|
|
89
|
+
});
|
|
90
|
+
if (config.organizationSlug)
|
|
91
|
+
await client.resolveOrgSlug(config.organizationSlug);
|
|
92
|
+
const result = await client.evaluateExternalApiGate(runId, budgets);
|
|
93
|
+
if (result.run_id !== runId || (projectId > 0 && result.project_id !== projectId)) {
|
|
94
|
+
throw new Error('Gate response does not match the requested run/project');
|
|
95
|
+
}
|
|
96
|
+
if (!Array.isArray(result.checks) || !result.checks.length || result.checks.some(c => !c || typeof c.passed !== 'boolean' || (c.passed && (typeof c.actual !== 'number' || !Number.isFinite(c.actual))))) {
|
|
97
|
+
throw new Error('Invalid external gate response');
|
|
98
|
+
}
|
|
99
|
+
if (Object.keys(budgets).filter(key => key.startsWith('max_')).some(key => !result.checks.some(c => c.name === key))) {
|
|
100
|
+
throw new Error('External gate response is missing requested checks');
|
|
101
|
+
}
|
|
102
|
+
const passed = result.checks.every(c => c.passed);
|
|
103
|
+
if (!passed && warnOnly)
|
|
104
|
+
result.warnings = [...(result.warnings || []), 'Gate would have failed (--warn-only)'];
|
|
105
|
+
const exitCode = passed || warnOnly ? 0 : 1;
|
|
106
|
+
if (outputJson) {
|
|
107
|
+
process.stdout.write(JSON.stringify({ ...result, passed: passed || warnOnly, exit_code: exitCode }) + '\n');
|
|
108
|
+
}
|
|
109
|
+
else {
|
|
110
|
+
for (const c of result.checks)
|
|
111
|
+
process.stdout.write(`${c.passed ? 'PASS' : 'FAIL'} ${c.name}: ${c.actual ?? 'unknown'} / ${c.limit} ${c.detail}\n`);
|
|
112
|
+
for (const warning of result.warnings || [])
|
|
113
|
+
process.stdout.write(`Warning: ${warning}\n`);
|
|
114
|
+
}
|
|
115
|
+
return exitCode;
|
|
116
|
+
}
|
|
117
|
+
catch (error) {
|
|
118
|
+
process.stderr.write(`External gate error: ${error instanceof Error ? error.message : String(error)}\n`);
|
|
119
|
+
return 2;
|
|
120
|
+
}
|
|
121
|
+
}
|
package/dist/cli/helpText.js
CHANGED
|
@@ -13,6 +13,7 @@ Commands:
|
|
|
13
13
|
runtime status [--json] Check local runtime configuration (no network)
|
|
14
14
|
analyze <projectDir> Local resource Analyze (manifest + findings)
|
|
15
15
|
run <script> [projectDir] Execute script with process metering (+ optional upload)
|
|
16
|
+
check --run-id <id> [options] Post-run token, API call, and estimated cost gates
|
|
16
17
|
optimize <projectDir> Local proposals; --llm for api_server optimize session
|
|
17
18
|
optimize <projectDir> --apply Safe local patches only (VerificationProvider)
|
|
18
19
|
optimize <projectDir> --llm Shared LLM /optimize/function (token + project-id)
|
package/dist/cli/netgreener.js
CHANGED
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
*
|
|
9
9
|
* Does not flip EXPORT_MODE. Optimize never mutates the tree (see OPTIMIZE_STUB.md).
|
|
10
10
|
*/
|
|
11
|
+
import { formatCheckHelp, runCheckCli } from './checkCli.js';
|
|
11
12
|
import { resolve } from 'node:path';
|
|
12
13
|
import { pathToFileURL } from 'node:url';
|
|
13
14
|
import { runAnalyzeCli } from '../analyze/cli.js';
|
|
@@ -29,6 +30,10 @@ function printHelpFor(topic) {
|
|
|
29
30
|
process.stdout.write(formatRunHelp());
|
|
30
31
|
return 0;
|
|
31
32
|
}
|
|
33
|
+
if (key === 'check') {
|
|
34
|
+
process.stdout.write(formatCheckHelp());
|
|
35
|
+
return 0;
|
|
36
|
+
}
|
|
32
37
|
if (key === 'runtime') {
|
|
33
38
|
process.stdout.write(formatRuntimeHelp());
|
|
34
39
|
return 0;
|
|
@@ -61,6 +66,8 @@ export function runNetgreenerCli(argv) {
|
|
|
61
66
|
if (cmd === 'run') {
|
|
62
67
|
return runRunCli(rest);
|
|
63
68
|
}
|
|
69
|
+
if (cmd === 'check')
|
|
70
|
+
return runCheckCli(rest);
|
|
64
71
|
if (cmd === 'runtime') {
|
|
65
72
|
return runRuntimeCli(rest);
|
|
66
73
|
}
|
package/dist/config.d.ts
CHANGED
|
@@ -20,7 +20,7 @@ export type RuntimeConfig = {
|
|
|
20
20
|
tenantLabelClaim: string | null;
|
|
21
21
|
};
|
|
22
22
|
/** Established v0 flush / TDP bounds (committed Node runtime foundation). */
|
|
23
|
-
export declare const DEFAULT_RUNTIME_FLUSH_MINUTES =
|
|
23
|
+
export declare const DEFAULT_RUNTIME_FLUSH_MINUTES = 1;
|
|
24
24
|
export declare const MIN_RUNTIME_FLUSH_MINUTES = 1;
|
|
25
25
|
export declare const MAX_RUNTIME_FLUSH_MINUTES: number;
|
|
26
26
|
export declare const DEFAULT_ESTIMATE_TDP_WATTS = 65;
|
package/dist/config.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** Established v0 flush / TDP bounds (committed Node runtime foundation). */
|
|
2
|
-
export const DEFAULT_RUNTIME_FLUSH_MINUTES =
|
|
2
|
+
export const DEFAULT_RUNTIME_FLUSH_MINUTES = 1;
|
|
3
3
|
export const MIN_RUNTIME_FLUSH_MINUTES = 1;
|
|
4
4
|
export const MAX_RUNTIME_FLUSH_MINUTES = 24 * 60;
|
|
5
5
|
export const DEFAULT_ESTIMATE_TDP_WATTS = 65;
|
|
@@ -14,7 +14,7 @@ export declare function validateExternalApiV0(value: unknown, path?: string): Co
|
|
|
14
14
|
export declare function validateMeasurementProvenance(value: unknown, path?: string): ContractResult;
|
|
15
15
|
/**
|
|
16
16
|
* Validate a session_metadata fragment Node will upload.
|
|
17
|
-
* Requires
|
|
17
|
+
* Requires runtime resources, external APIs, or MCP observations.
|
|
18
18
|
*/
|
|
19
19
|
export declare function validateRuntimeSessionMetadata(value: unknown): ContractResult;
|
|
20
20
|
export type { ExternalApiV0, MeasurementProvenance, RuntimeSessionMetadata, ServiceRuntimeV0, };
|
|
@@ -202,7 +202,7 @@ export function validateMeasurementProvenance(value, path = 'measurement_provena
|
|
|
202
202
|
}
|
|
203
203
|
/**
|
|
204
204
|
* Validate a session_metadata fragment Node will upload.
|
|
205
|
-
* Requires
|
|
205
|
+
* Requires runtime resources, external APIs, or MCP observations.
|
|
206
206
|
*/
|
|
207
207
|
export function validateRuntimeSessionMetadata(value) {
|
|
208
208
|
const issues = [];
|
|
@@ -211,8 +211,9 @@ export function validateRuntimeSessionMetadata(value) {
|
|
|
211
211
|
}
|
|
212
212
|
const hasRuntime = value.service_runtime_v0 !== undefined;
|
|
213
213
|
const hasExternal = value.external_api_v0 !== undefined;
|
|
214
|
-
|
|
215
|
-
|
|
214
|
+
const hasMcp = value.mcp_tool_v0 !== undefined;
|
|
215
|
+
if (!hasRuntime && !hasExternal && !hasMcp) {
|
|
216
|
+
issues.push(issue('session_metadata', 'expected service_runtime_v0, external_api_v0, or mcp_tool_v0'));
|
|
216
217
|
}
|
|
217
218
|
if (hasRuntime) {
|
|
218
219
|
issues.push(...validateServiceRuntimeV0(value.service_runtime_v0).issues);
|
|
@@ -220,6 +221,26 @@ export function validateRuntimeSessionMetadata(value) {
|
|
|
220
221
|
if (hasExternal) {
|
|
221
222
|
issues.push(...validateExternalApiV0(value.external_api_v0).issues);
|
|
222
223
|
}
|
|
224
|
+
if (hasMcp) {
|
|
225
|
+
const mcp = value.mcp_tool_v0;
|
|
226
|
+
if (!isObject(mcp) || mcp.schema !== 'mcp_tool_v0' || !Array.isArray(mcp.calls) || !mcp.calls.length) {
|
|
227
|
+
issues.push(issue('mcp_tool_v0', 'expected MCP ledger with schema and non-empty calls'));
|
|
228
|
+
}
|
|
229
|
+
else {
|
|
230
|
+
mcp.calls.forEach((call, index) => {
|
|
231
|
+
const path = `mcp_tool_v0.calls[${index}]`;
|
|
232
|
+
if (!isObject(call)) {
|
|
233
|
+
issues.push(issue(path, 'expected object'));
|
|
234
|
+
return;
|
|
235
|
+
}
|
|
236
|
+
requireString(call, 'server', path, issues);
|
|
237
|
+
requireString(call, 'tool', path, issues);
|
|
238
|
+
requireNumber(call, 'duration_ms', path, issues, { nonNegative: true });
|
|
239
|
+
if (typeof call.success !== 'boolean')
|
|
240
|
+
issues.push(issue(`${path}.success`, 'expected boolean'));
|
|
241
|
+
});
|
|
242
|
+
}
|
|
243
|
+
}
|
|
223
244
|
if (value.measurement_provenance !== undefined) {
|
|
224
245
|
issues.push(...validateMeasurementProvenance(value.measurement_provenance).issues);
|
|
225
246
|
}
|
|
@@ -81,6 +81,7 @@ export declare class ExternalApiAggregator {
|
|
|
81
81
|
private providers;
|
|
82
82
|
private byServiceUnit;
|
|
83
83
|
private byTenant;
|
|
84
|
+
private byTenantServiceUnit;
|
|
84
85
|
private excludedHosts;
|
|
85
86
|
setExcludedHosts(hosts: Iterable<string>): void;
|
|
86
87
|
excludesHost(host: string): boolean;
|
package/dist/externalApiMeter.js
CHANGED
|
@@ -673,6 +673,7 @@ export class ExternalApiAggregator {
|
|
|
673
673
|
providers = new Map();
|
|
674
674
|
byServiceUnit = new Map();
|
|
675
675
|
byTenant = new Map();
|
|
676
|
+
byTenantServiceUnit = new Map();
|
|
676
677
|
excludedHosts = new Set();
|
|
677
678
|
setExcludedHosts(hosts) {
|
|
678
679
|
this.excludedHosts = new Set([...hosts].map((h) => h.toLowerCase().trim()).filter(Boolean));
|
|
@@ -819,6 +820,18 @@ export class ExternalApiAggregator {
|
|
|
819
820
|
outputTokens,
|
|
820
821
|
model,
|
|
821
822
|
});
|
|
823
|
+
let routes = this.byTenantServiceUnit.get(bucketId);
|
|
824
|
+
if (!routes) {
|
|
825
|
+
routes = new Map();
|
|
826
|
+
this.byTenantServiceUnit.set(bucketId, routes);
|
|
827
|
+
}
|
|
828
|
+
const unit = routes.has(serviceUnit) || routes.size < 32 ? serviceUnit : '__unknown__';
|
|
829
|
+
let routeBucket = routes.get(unit);
|
|
830
|
+
if (!routeBucket) {
|
|
831
|
+
routeBucket = new Map();
|
|
832
|
+
routes.set(unit, routeBucket);
|
|
833
|
+
}
|
|
834
|
+
this.recordProvider(routeBucket, { provider, host: opts.host, durationMs, error, inputTokens, outputTokens, model });
|
|
822
835
|
}
|
|
823
836
|
}
|
|
824
837
|
providerRow(p) {
|
|
@@ -900,6 +913,11 @@ export class ExternalApiAggregator {
|
|
|
900
913
|
calls: rows.reduce((s, r) => s + r.calls, 0),
|
|
901
914
|
errors: rows.reduce((s, r) => s + r.errors, 0),
|
|
902
915
|
providers: rows,
|
|
916
|
+
by_service_unit: Object.fromEntries([...(this.byTenantServiceUnit.get(tenant) ?? new Map())]
|
|
917
|
+
.map(([unit, providers]) => [unit, {
|
|
918
|
+
service_unit: unit,
|
|
919
|
+
providers: [...providers.values()].map(p => this.providerRow(p)),
|
|
920
|
+
}])),
|
|
903
921
|
};
|
|
904
922
|
}
|
|
905
923
|
const payload = {
|
|
@@ -917,10 +935,12 @@ export class ExternalApiAggregator {
|
|
|
917
935
|
snap.providers = this.providers;
|
|
918
936
|
snap.byServiceUnit = this.byServiceUnit;
|
|
919
937
|
snap.byTenant = this.byTenant;
|
|
938
|
+
snap.byTenantServiceUnit = this.byTenantServiceUnit;
|
|
920
939
|
snap.excludedHosts = new Set(this.excludedHosts);
|
|
921
940
|
this.providers = new Map();
|
|
922
941
|
this.byServiceUnit = new Map();
|
|
923
942
|
this.byTenant = new Map();
|
|
943
|
+
this.byTenantServiceUnit = new Map();
|
|
924
944
|
return snap;
|
|
925
945
|
}
|
|
926
946
|
static mergeProvider(target, source) {
|
|
@@ -1003,6 +1023,30 @@ export class ExternalApiAggregator {
|
|
|
1003
1023
|
ExternalApiAggregator.mergeProvider(dst, src);
|
|
1004
1024
|
}
|
|
1005
1025
|
}
|
|
1026
|
+
for (const [sourceTenant, routes] of snapshot.byTenantServiceUnit) {
|
|
1027
|
+
const tenant = tenantBucketId(sourceTenant, this.byTenant);
|
|
1028
|
+
let targetRoutes = this.byTenantServiceUnit.get(tenant);
|
|
1029
|
+
if (!targetRoutes) {
|
|
1030
|
+
targetRoutes = new Map();
|
|
1031
|
+
this.byTenantServiceUnit.set(tenant, targetRoutes);
|
|
1032
|
+
}
|
|
1033
|
+
for (const [sourceUnit, bucket] of routes) {
|
|
1034
|
+
const unit = targetRoutes.has(sourceUnit) || targetRoutes.size < 32 ? sourceUnit : '__unknown__';
|
|
1035
|
+
let targetBucket = targetRoutes.get(unit);
|
|
1036
|
+
if (!targetBucket) {
|
|
1037
|
+
targetBucket = new Map();
|
|
1038
|
+
targetRoutes.set(unit, targetBucket);
|
|
1039
|
+
}
|
|
1040
|
+
for (const [key, source] of bucket) {
|
|
1041
|
+
const target = targetBucket.get(key);
|
|
1042
|
+
if (target)
|
|
1043
|
+
ExternalApiAggregator.mergeProvider(target, source);
|
|
1044
|
+
else
|
|
1045
|
+
targetBucket.set(key, source);
|
|
1046
|
+
}
|
|
1047
|
+
}
|
|
1048
|
+
}
|
|
1049
|
+
snapshot.byTenantServiceUnit = new Map();
|
|
1006
1050
|
snapshot.providers = new Map();
|
|
1007
1051
|
snapshot.byServiceUnit = new Map();
|
|
1008
1052
|
snapshot.byTenant = new Map();
|
|
@@ -1011,6 +1055,7 @@ export class ExternalApiAggregator {
|
|
|
1011
1055
|
this.providers.clear();
|
|
1012
1056
|
this.byServiceUnit.clear();
|
|
1013
1057
|
this.byTenant.clear();
|
|
1058
|
+
this.byTenantServiceUnit.clear();
|
|
1014
1059
|
}
|
|
1015
1060
|
}
|
|
1016
1061
|
const globalAgg = new ExternalApiAggregator();
|
package/dist/lifecycle.d.ts
CHANGED
|
@@ -5,8 +5,8 @@
|
|
|
5
5
|
* Behavior depends primarily on lifecycle. Detection is best-effort;
|
|
6
6
|
* ``NETGREENER_RUNTIME`` / ``init({ runtime })`` always wins.
|
|
7
7
|
*
|
|
8
|
-
* Does not rewrite the persistent collector pipeline. Ephemeral
|
|
9
|
-
*
|
|
8
|
+
* Does not rewrite the persistent collector pipeline. Ephemeral bounds
|
|
9
|
+
* interval timers to active invocations and prefers thin export when unset.
|
|
10
10
|
*/
|
|
11
11
|
import { type ServerlessPlatformSignal } from './serverlessHints.js';
|
|
12
12
|
export type RuntimeModePreference = 'auto' | 'persistent' | 'ephemeral';
|
|
@@ -19,6 +19,8 @@ export type RuntimeCapabilities = {
|
|
|
19
19
|
/** process.cpuUsage / RSS deltas on instrumented hooks. */
|
|
20
20
|
process_cpu_time: boolean;
|
|
21
21
|
periodic_flush: boolean;
|
|
22
|
+
/** Interval reporting while the host keeps an invocation active. */
|
|
23
|
+
active_invocation_flush?: boolean;
|
|
22
24
|
local_durable_spool: boolean;
|
|
23
25
|
};
|
|
24
26
|
export type ResolvedRuntimeLifecycle = {
|
package/dist/lifecycle.js
CHANGED
|
@@ -5,8 +5,8 @@
|
|
|
5
5
|
* Behavior depends primarily on lifecycle. Detection is best-effort;
|
|
6
6
|
* ``NETGREENER_RUNTIME`` / ``init({ runtime })`` always wins.
|
|
7
7
|
*
|
|
8
|
-
* Does not rewrite the persistent collector pipeline. Ephemeral
|
|
9
|
-
*
|
|
8
|
+
* Does not rewrite the persistent collector pipeline. Ephemeral bounds
|
|
9
|
+
* interval timers to active invocations and prefers thin export when unset.
|
|
10
10
|
*/
|
|
11
11
|
import { detectServerlessPlatformSignals, } from './serverlessHints.js';
|
|
12
12
|
function readModePreference(env, override) {
|
|
@@ -46,6 +46,7 @@ function capabilitiesFor(lifecycle) {
|
|
|
46
46
|
gpu_sampling: false,
|
|
47
47
|
process_cpu_time: true,
|
|
48
48
|
periodic_flush: false,
|
|
49
|
+
active_invocation_flush: true,
|
|
49
50
|
local_durable_spool: false,
|
|
50
51
|
};
|
|
51
52
|
}
|
|
@@ -80,7 +81,7 @@ export function resolveLifecycle(opts = {}) {
|
|
|
80
81
|
}
|
|
81
82
|
else if (hint.detected) {
|
|
82
83
|
lifecycle = 'ephemeral';
|
|
83
|
-
notes.push('auto: serverless host signal → ephemeral lifecycle (
|
|
84
|
+
notes.push('auto: serverless host signal → ephemeral lifecycle (intervals while active; final partial window at invoke end)');
|
|
84
85
|
}
|
|
85
86
|
else {
|
|
86
87
|
lifecycle = 'persistent';
|
|
@@ -95,7 +96,7 @@ export function resolveLifecycle(opts = {}) {
|
|
|
95
96
|
notes.push(`container/platform signal: ${containerPlatform} (lifecycle remains ${lifecycle})`);
|
|
96
97
|
}
|
|
97
98
|
if (lifecycle === 'ephemeral') {
|
|
98
|
-
notes.push('ephemeral:
|
|
99
|
+
notes.push('ephemeral: interval reporting only during active invocations; flush final partial window at invoke/request idle boundary');
|
|
99
100
|
}
|
|
100
101
|
return {
|
|
101
102
|
mode,
|
|
@@ -39,7 +39,7 @@ function resolveCiProvider(env) {
|
|
|
39
39
|
return null;
|
|
40
40
|
}
|
|
41
41
|
function resolveReleaseTagFallback(env) {
|
|
42
|
-
|
|
42
|
+
const tag = firstEnv(env, [
|
|
43
43
|
'NETGREENER_RELEASE_TAG',
|
|
44
44
|
'RELEASE_TAG',
|
|
45
45
|
'IMAGE_TAG',
|
|
@@ -48,14 +48,52 @@ function resolveReleaseTagFallback(env) {
|
|
|
48
48
|
'CONTAINER_IMAGE_TAG',
|
|
49
49
|
'APP_VERSION',
|
|
50
50
|
'CI_COMMIT_TAG',
|
|
51
|
+
'RELEASE_RELEASENAME',
|
|
51
52
|
'BUILD_BUILDNUMBER',
|
|
52
53
|
]);
|
|
54
|
+
if (tag)
|
|
55
|
+
return tag;
|
|
56
|
+
const image = firstEnv(env, [
|
|
57
|
+
'NETGREENER_K8S_IMAGE', 'K8S_CONTAINER_IMAGE', 'CONTAINER_IMAGE', 'DOCKER_IMAGE', 'IMAGE',
|
|
58
|
+
]);
|
|
59
|
+
if (image) {
|
|
60
|
+
const digestAt = image.toLowerCase().lastIndexOf('@sha256:');
|
|
61
|
+
if (digestAt >= 0) {
|
|
62
|
+
const digest = image.slice(digestAt + 1).trim();
|
|
63
|
+
const hex = digest.slice(7).trim();
|
|
64
|
+
return hex.length >= 12 ? `sha256:${hex.slice(0, 12)}` : digest;
|
|
65
|
+
}
|
|
66
|
+
const name = image.split('/').at(-1) || '';
|
|
67
|
+
if (name.includes(':'))
|
|
68
|
+
return name.slice(name.lastIndexOf(':') + 1).trim() || null;
|
|
69
|
+
}
|
|
70
|
+
const digest = firstEnv(env, ['NETGREENER_K8S_IMAGE_DIGEST', 'K8S_IMAGE_DIGEST', 'IMAGE_DIGEST']);
|
|
71
|
+
if (digest?.toLowerCase().startsWith('sha256:') && digest.slice(7).length >= 12) {
|
|
72
|
+
return `sha256:${digest.slice(7, 19)}`;
|
|
73
|
+
}
|
|
74
|
+
if (digest)
|
|
75
|
+
return digest;
|
|
76
|
+
const vercel = firstEnv(env, ['VERCEL_DEPLOYMENT_ID', 'VERCEL_URL']);
|
|
77
|
+
if (vercel)
|
|
78
|
+
return `vercel:${vercel}`;
|
|
79
|
+
const azure = firstEnv(env, ['RELEASE_RELEASEID', 'RELEASE_DEPLOYMENTID']);
|
|
80
|
+
return azure ? `azure:${azure}` : null;
|
|
53
81
|
}
|
|
54
82
|
/**
|
|
55
83
|
* Attach release identity + CI flags onto an existing run_context object.
|
|
56
84
|
* Never overwrites an already-set ``release_tag`` / ``git_sha`` / ``deploy_id``.
|
|
57
85
|
*/
|
|
58
86
|
export function enrichRunContextForAnomaly(ctx, env = process.env) {
|
|
87
|
+
if (!(typeof ctx.deploy_environment === 'string' && ctx.deploy_environment.trim())) {
|
|
88
|
+
const explicit = firstEnv(env, ['NETGREENER_DEPLOY_ENVIRONMENT', 'DEPLOY_ENV', 'NETGREENER_ENV']);
|
|
89
|
+
const tier = explicit || firstEnv(env, ['VERCEL_ENV']);
|
|
90
|
+
const normalized = tier?.toLowerCase();
|
|
91
|
+
const mapped = normalized === 'production' ? 'prod'
|
|
92
|
+
: normalized === 'preview' ? 'staging'
|
|
93
|
+
: normalized === 'development' ? 'dev' : normalized;
|
|
94
|
+
if (mapped)
|
|
95
|
+
ctx.deploy_environment = mapped;
|
|
96
|
+
}
|
|
59
97
|
if (!(typeof ctx.release_tag === 'string' && ctx.release_tag.trim())) {
|
|
60
98
|
const tag = resolveReleaseTagFallback(env);
|
|
61
99
|
if (tag)
|
|
@@ -67,6 +105,7 @@ export function enrichRunContextForAnomaly(ctx, env = process.env) {
|
|
|
67
105
|
'GIT_SHA',
|
|
68
106
|
'GITHUB_SHA',
|
|
69
107
|
'BUILD_SOURCEVERSION',
|
|
108
|
+
'VERCEL_GIT_COMMIT_SHA',
|
|
70
109
|
]);
|
|
71
110
|
if (sha)
|
|
72
111
|
ctx.git_sha = sha.slice(0, 64);
|
|
@@ -75,6 +114,10 @@ export function enrichRunContextForAnomaly(ctx, env = process.env) {
|
|
|
75
114
|
const deployId = firstEnv(env, [
|
|
76
115
|
'NETGREENER_DEPLOY_ID',
|
|
77
116
|
'DEPLOY_ID',
|
|
117
|
+
'VERCEL_DEPLOYMENT_ID',
|
|
118
|
+
'VERCEL_URL',
|
|
119
|
+
'RELEASE_DEPLOYMENTID',
|
|
120
|
+
'RELEASE_RELEASEID',
|
|
78
121
|
'BUILD_BUILDID',
|
|
79
122
|
]);
|
|
80
123
|
if (deployId)
|