@netgreener/runtime 0.1.14 → 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/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/lifecycle.d.ts +4 -2
- package/dist/lifecycle.js +5 -4
- 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 +2 -0
- package/dist/sdk/client.js +4 -0
- package/dist/taskMeter.js +17 -5
- 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;
|
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
|
}
|
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,
|
package/dist/runtime.d.ts
CHANGED
|
@@ -19,7 +19,7 @@ export type NetGreenerRuntimeOptions = {
|
|
|
19
19
|
};
|
|
20
20
|
/**
|
|
21
21
|
* Process-wide runtime controller: record samples, periodic flush, shutdown flush.
|
|
22
|
-
* Ephemeral
|
|
22
|
+
* Ephemeral timers run only during active invocations; idle flush sends the tail.
|
|
23
23
|
*/
|
|
24
24
|
export declare class NetGreenerRuntime {
|
|
25
25
|
readonly config: RuntimeConfig;
|
|
@@ -31,6 +31,8 @@ export declare class NetGreenerRuntime {
|
|
|
31
31
|
private readonly exporter;
|
|
32
32
|
private readonly onFlush?;
|
|
33
33
|
private timer;
|
|
34
|
+
private stopControls?;
|
|
35
|
+
private readonly windowCheckpoints;
|
|
34
36
|
private flushing;
|
|
35
37
|
private started;
|
|
36
38
|
private outboundInstalled;
|
|
@@ -46,9 +48,10 @@ export declare class NetGreenerRuntime {
|
|
|
46
48
|
private ensureOutboundMeter;
|
|
47
49
|
/** Prefer unwrapped fetch so telemetry uploads are never metered. */
|
|
48
50
|
private uploadFetch;
|
|
51
|
+
private scheduleWindow;
|
|
49
52
|
start(): void;
|
|
50
53
|
/** Mark start of an inbound request/task (ephemeral idle-flush accounting). */
|
|
51
|
-
beginRequest(): void;
|
|
54
|
+
beginRequest(checkpoint?: () => void): () => void;
|
|
52
55
|
/**
|
|
53
56
|
* Mark end of an inbound request/task. In ephemeral mode, schedules a flush
|
|
54
57
|
* when no requests remain in flight (safe under concurrency).
|
|
@@ -84,6 +87,8 @@ export declare class NetGreenerRuntime {
|
|
|
84
87
|
tenantId?: string | null;
|
|
85
88
|
cpuTimeMs?: number;
|
|
86
89
|
peakRssKb?: number;
|
|
90
|
+
completed?: boolean;
|
|
91
|
+
completionDurationMs?: number;
|
|
87
92
|
}): void;
|
|
88
93
|
private exportPendingWindow;
|
|
89
94
|
flush(kind?: FlushKind): Promise<UploadResult | null>;
|
package/dist/runtime.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { meteringAllowed, startRuntimeControls } from './runtimeControls.js';
|
|
1
|
+
import { meteringAllowed, runtimeWindowIntervalMs, startRuntimeControls } from './runtimeControls.js';
|
|
2
2
|
import { hostname } from 'node:os';
|
|
3
3
|
import { ServiceRuntimeAggregator } from './aggregator.js';
|
|
4
4
|
import { carbonFactorDict } from './carbonLedger.js';
|
|
@@ -35,7 +35,7 @@ function vercelDeploymentHosts() {
|
|
|
35
35
|
}
|
|
36
36
|
/**
|
|
37
37
|
* Process-wide runtime controller: record samples, periodic flush, shutdown flush.
|
|
38
|
-
* Ephemeral
|
|
38
|
+
* Ephemeral timers run only during active invocations; idle flush sends the tail.
|
|
39
39
|
*/
|
|
40
40
|
export class NetGreenerRuntime {
|
|
41
41
|
config;
|
|
@@ -47,6 +47,8 @@ export class NetGreenerRuntime {
|
|
|
47
47
|
exporter;
|
|
48
48
|
onFlush;
|
|
49
49
|
timer = null;
|
|
50
|
+
stopControls;
|
|
51
|
+
windowCheckpoints = new Set();
|
|
50
52
|
flushing = false;
|
|
51
53
|
started = false;
|
|
52
54
|
outboundInstalled = false;
|
|
@@ -103,6 +105,17 @@ export class NetGreenerRuntime {
|
|
|
103
105
|
uploadFetch() {
|
|
104
106
|
return getOriginalFetch() ?? this.fetchImpl;
|
|
105
107
|
}
|
|
108
|
+
scheduleWindow(milliseconds) {
|
|
109
|
+
if (this.timer)
|
|
110
|
+
clearInterval(this.timer);
|
|
111
|
+
this.timer = null;
|
|
112
|
+
// Serverless timers exist only while an invocation is active. Never wait
|
|
113
|
+
// for this timer to deliver a short invocation's final partial window.
|
|
114
|
+
if (this.lifecycle === 'ephemeral' && this.inFlight === 0)
|
|
115
|
+
return;
|
|
116
|
+
this.timer = setInterval(() => { void this.flush('periodic'); }, milliseconds);
|
|
117
|
+
this.timer.unref?.();
|
|
118
|
+
}
|
|
106
119
|
start() {
|
|
107
120
|
if (this.started)
|
|
108
121
|
return;
|
|
@@ -115,7 +128,7 @@ export class NetGreenerRuntime {
|
|
|
115
128
|
pauseAt = Date.now();
|
|
116
129
|
pauseCpu = process.cpuUsage();
|
|
117
130
|
}
|
|
118
|
-
startRuntimeControls(this.config, this.uploadFetch(), (enabled) => {
|
|
131
|
+
this.stopControls = startRuntimeControls(this.config, this.uploadFetch(), (enabled) => {
|
|
119
132
|
if (!enabled) {
|
|
120
133
|
pauseAt = Date.now();
|
|
121
134
|
pauseCpu = process.cpuUsage();
|
|
@@ -127,7 +140,7 @@ export class NetGreenerRuntime {
|
|
|
127
140
|
this.aggregator.excludePausedTime(Date.now() - pauseAt);
|
|
128
141
|
pauseCpu = null;
|
|
129
142
|
}
|
|
130
|
-
});
|
|
143
|
+
}, milliseconds => this.scheduleWindow(milliseconds));
|
|
131
144
|
markHooksActive({
|
|
132
145
|
processKind: this.framework,
|
|
133
146
|
exportMode: this.exporter.mode,
|
|
@@ -135,17 +148,25 @@ export class NetGreenerRuntime {
|
|
|
135
148
|
noteExportMode(this.exporter.mode);
|
|
136
149
|
this.ensureOutboundMeter();
|
|
137
150
|
// Persistent path unchanged: periodic flush. Ephemeral must not depend on it.
|
|
138
|
-
|
|
139
|
-
this.timer = setInterval(() => {
|
|
140
|
-
void this.flush('periodic');
|
|
141
|
-
}, this.config.flushIntervalMs);
|
|
142
|
-
// Do not keep the process alive solely for the timer.
|
|
143
|
-
this.timer.unref?.();
|
|
144
|
-
}
|
|
151
|
+
this.scheduleWindow(runtimeWindowIntervalMs(this.config));
|
|
145
152
|
}
|
|
146
153
|
/** Mark start of an inbound request/task (ephemeral idle-flush accounting). */
|
|
147
|
-
beginRequest() {
|
|
154
|
+
beginRequest(checkpoint) {
|
|
155
|
+
if (checkpoint)
|
|
156
|
+
this.windowCheckpoints.add(checkpoint);
|
|
157
|
+
if (this.lifecycle === 'ephemeral' && this.inFlight === 0 && !this.pendingPayload &&
|
|
158
|
+
!this.aggregator.hasData() && !getExternalAggregator().hasData() && !getMcpToolLedger().hasCalls()) {
|
|
159
|
+
// A reused serverless instance may have been suspended for hours. Start
|
|
160
|
+
// the new invocation's resource window here rather than including idle time.
|
|
161
|
+
this.aggregator.resetWindow();
|
|
162
|
+
this.cpuWindowMark = beginProcessResourceSample();
|
|
163
|
+
getOccupancyTracker().takeWindowSnapshot();
|
|
164
|
+
}
|
|
148
165
|
this.inFlight += 1;
|
|
166
|
+
if (this.lifecycle === 'ephemeral' && this.inFlight === 1)
|
|
167
|
+
this.scheduleWindow(runtimeWindowIntervalMs(this.config));
|
|
168
|
+
return () => { if (checkpoint)
|
|
169
|
+
this.windowCheckpoints.delete(checkpoint); };
|
|
149
170
|
}
|
|
150
171
|
/**
|
|
151
172
|
* Mark end of an inbound request/task. In ephemeral mode, schedules a flush
|
|
@@ -160,6 +181,10 @@ export class NetGreenerRuntime {
|
|
|
160
181
|
this.inFlight -= 1;
|
|
161
182
|
if (this.lifecycle !== 'ephemeral')
|
|
162
183
|
return;
|
|
184
|
+
if (this.inFlight === 0 && this.timer) {
|
|
185
|
+
clearInterval(this.timer);
|
|
186
|
+
this.timer = null;
|
|
187
|
+
}
|
|
163
188
|
if (opts?.deferInvokeFlush)
|
|
164
189
|
return;
|
|
165
190
|
if (this.invokeFlushScheduled)
|
|
@@ -181,6 +206,8 @@ export class NetGreenerRuntime {
|
|
|
181
206
|
return this.inFlight;
|
|
182
207
|
}
|
|
183
208
|
stop() {
|
|
209
|
+
this.stopControls?.();
|
|
210
|
+
this.stopControls = undefined;
|
|
184
211
|
if (this.timer) {
|
|
185
212
|
clearInterval(this.timer);
|
|
186
213
|
this.timer = null;
|
|
@@ -218,6 +245,8 @@ export class NetGreenerRuntime {
|
|
|
218
245
|
this.aggregator.record({
|
|
219
246
|
serviceUnit: sample.serviceUnit,
|
|
220
247
|
unitType: 'task',
|
|
248
|
+
completed: sample.completed,
|
|
249
|
+
completionDurationMs: sample.completionDurationMs,
|
|
221
250
|
durationMs: sample.durationMs,
|
|
222
251
|
error: Boolean(sample.error),
|
|
223
252
|
tenantId: sample.tenantId ?? getTenantContext()?.tenantId ?? null,
|
|
@@ -264,20 +293,32 @@ export class NetGreenerRuntime {
|
|
|
264
293
|
}
|
|
265
294
|
}
|
|
266
295
|
const externalAgg = getExternalAggregator();
|
|
296
|
+
const mcpLedger = getMcpToolLedger();
|
|
297
|
+
for (const checkpoint of this.windowCheckpoints) {
|
|
298
|
+
try {
|
|
299
|
+
checkpoint();
|
|
300
|
+
}
|
|
301
|
+
catch { /* Telemetry must not interrupt customer work. */ }
|
|
302
|
+
}
|
|
303
|
+
if (((this.started && this.lifecycle === 'persistent' && kind !== 'manual') || this.inFlight > 0) && !this.aggregator.hasData()) {
|
|
304
|
+
this.aggregator.record({ serviceUnit: 'Process resources', unitType: 'process', completed: false,
|
|
305
|
+
durationMs: Math.max(0.001, Date.now() - this.aggregator.windowStartedMs()),
|
|
306
|
+
peakRssKb: endProcessResourceSample(this.cpuWindowMark).rssKb });
|
|
307
|
+
}
|
|
267
308
|
const hasRuntime = this.aggregator.hasData();
|
|
268
309
|
const hasExternal = externalAgg.hasData();
|
|
269
|
-
if (!hasRuntime && !hasExternal)
|
|
310
|
+
if (!hasRuntime && !hasExternal && !mcpLedger.hasCalls())
|
|
270
311
|
return null;
|
|
271
312
|
this.flushing = true;
|
|
272
313
|
let mcpSnapshot = null;
|
|
273
314
|
noteExportMode(this.exporter.mode);
|
|
315
|
+
const windowStartedMs = this.aggregator.windowStartedMs();
|
|
274
316
|
const snapshot = hasRuntime ? this.aggregator.takeSnapshot() : null;
|
|
317
|
+
if (!hasRuntime)
|
|
318
|
+
this.aggregator.resetWindow();
|
|
275
319
|
const externalSnapshot = hasExternal ? externalAgg.takeSnapshot() : null;
|
|
276
320
|
const previousCpuMark = this.cpuWindowMark;
|
|
277
321
|
try {
|
|
278
|
-
const windowStartedMs = snapshot
|
|
279
|
-
? snapshot.windowStartedMs()
|
|
280
|
-
: Date.now() - 1000;
|
|
281
322
|
const windowSeconds = Math.max(0.001, (Date.now() - windowStartedMs) / 1000);
|
|
282
323
|
const windowCpuSeconds = endProcessResourceSample(this.cpuWindowMark).cpuTimeMs / 1000;
|
|
283
324
|
this.cpuWindowMark = beginProcessResourceSample();
|
|
@@ -309,7 +350,6 @@ export class NetGreenerRuntime {
|
|
|
309
350
|
return null;
|
|
310
351
|
}
|
|
311
352
|
const externalV0 = externalSnapshot ? externalSnapshot.buildV0() : null;
|
|
312
|
-
const mcpLedger = getMcpToolLedger();
|
|
313
353
|
mcpSnapshot = mcpLedger.hasCalls() ? mcpLedger.takeSnapshot() : null;
|
|
314
354
|
const mcpV0 = mcpSnapshot ? mcpSnapshot.buildV0() : null;
|
|
315
355
|
if (mcpSnapshot && !mcpV0) {
|
|
@@ -325,6 +365,8 @@ export class NetGreenerRuntime {
|
|
|
325
365
|
const runContext = {
|
|
326
366
|
client: 'netgreener_node_runtime',
|
|
327
367
|
runtime_flush_kind: kind,
|
|
368
|
+
reporting_interval_seconds: runtimeWindowIntervalMs(this.config) / 1000,
|
|
369
|
+
reporting_window_kind: kind === 'periodic' ? 'interval' : 'partial',
|
|
328
370
|
measured_scope: 'process',
|
|
329
371
|
resource_scope: 'process',
|
|
330
372
|
runtime_lifecycle: this.lifecycleInfo.lifecycle,
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { RuntimeConfig } from './config.js';
|
|
2
2
|
export declare function meteringAllowed(config?: RuntimeConfig): boolean;
|
|
3
|
+
export declare function runtimeWindowIntervalMs(config: RuntimeConfig): number;
|
|
3
4
|
export declare function applyRuntimeControls(config: RuntimeConfig, enabled: boolean, orgId?: number): void;
|
|
4
5
|
export declare function refreshRuntimeControls(config: RuntimeConfig, fetchImpl: typeof fetch): Promise<void>;
|
|
5
|
-
export declare function startRuntimeControls(config: RuntimeConfig, fetchImpl: typeof fetch, onChange?: (enabled: boolean) => void): void;
|
|
6
|
+
export declare function startRuntimeControls(config: RuntimeConfig, fetchImpl: typeof fetch, onChange?: (enabled: boolean) => void, onIntervalChange?: (milliseconds: number) => void): () => void;
|
package/dist/runtimeControls.js
CHANGED
|
@@ -12,7 +12,7 @@ function stateFor(config) {
|
|
|
12
12
|
if (!state) {
|
|
13
13
|
const claim = jwtPayloadUnverified(`Bearer ${config.token}`)?.org_id;
|
|
14
14
|
const id = config.organizationId ?? Number(claim);
|
|
15
|
-
state = { enabled: true, orgId: Number.isSafeInteger(id) && Number(id) > 0 ? Number(id) : null, refreshing: false, listeners: new Set() };
|
|
15
|
+
state = { enabled: true, orgId: Number.isSafeInteger(id) && Number(id) > 0 ? Number(id) : null, refreshing: false, listeners: new Set(), windowSeconds: null, intervalListeners: new Set() };
|
|
16
16
|
states.set(key, state);
|
|
17
17
|
}
|
|
18
18
|
return state;
|
|
@@ -20,6 +20,10 @@ function stateFor(config) {
|
|
|
20
20
|
export function meteringAllowed(config) {
|
|
21
21
|
return (config ? stateFor(config) : activeKey ? states.get(activeKey) : undefined)?.enabled ?? true;
|
|
22
22
|
}
|
|
23
|
+
export function runtimeWindowIntervalMs(config) {
|
|
24
|
+
const seconds = stateFor(config).windowSeconds;
|
|
25
|
+
return seconds == null ? config.flushIntervalMs : seconds * 1000;
|
|
26
|
+
}
|
|
23
27
|
export function applyRuntimeControls(config, enabled, orgId) {
|
|
24
28
|
const state = stateFor(config);
|
|
25
29
|
if (orgId != null && Number.isSafeInteger(orgId) && orgId > 0)
|
|
@@ -46,6 +50,14 @@ export async function refreshRuntimeControls(config, fetchImpl) {
|
|
|
46
50
|
const data = await response.json();
|
|
47
51
|
if (data.org_id === state.orgId && typeof data.metering_enabled === 'boolean') {
|
|
48
52
|
applyRuntimeControls(config, data.metering_enabled);
|
|
53
|
+
const seconds = data.effective_runtime_window_seconds ?? data.runtime_window_seconds;
|
|
54
|
+
if (seconds === null || (typeof seconds === 'number' && Number.isInteger(seconds) && seconds >= 30 && seconds <= 86400)) {
|
|
55
|
+
if (state.windowSeconds !== seconds) {
|
|
56
|
+
state.windowSeconds = seconds;
|
|
57
|
+
for (const listener of state.intervalListeners)
|
|
58
|
+
listener();
|
|
59
|
+
}
|
|
60
|
+
}
|
|
49
61
|
}
|
|
50
62
|
}
|
|
51
63
|
catch {
|
|
@@ -55,15 +67,24 @@ export async function refreshRuntimeControls(config, fetchImpl) {
|
|
|
55
67
|
state.refreshing = false;
|
|
56
68
|
}
|
|
57
69
|
}
|
|
58
|
-
export function startRuntimeControls(config, fetchImpl, onChange) {
|
|
70
|
+
export function startRuntimeControls(config, fetchImpl, onChange, onIntervalChange) {
|
|
59
71
|
if (config.dryRun || !config.enabled)
|
|
60
|
-
return;
|
|
72
|
+
return () => { };
|
|
61
73
|
activeKey = accountKey(config);
|
|
62
74
|
const state = stateFor(config);
|
|
63
75
|
if (onChange)
|
|
64
76
|
state.listeners.add(onChange);
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
state.timer
|
|
77
|
+
const intervalListener = onIntervalChange ? () => onIntervalChange(runtimeWindowIntervalMs(config)) : undefined;
|
|
78
|
+
if (intervalListener)
|
|
79
|
+
state.intervalListeners.add(intervalListener);
|
|
80
|
+
if (!state.timer) {
|
|
81
|
+
state.timer = setInterval(() => { void refreshRuntimeControls(config, fetchImpl); }, 30_000);
|
|
82
|
+
state.timer.unref?.();
|
|
83
|
+
}
|
|
84
|
+
return () => {
|
|
85
|
+
if (onChange)
|
|
86
|
+
state.listeners.delete(onChange);
|
|
87
|
+
if (intervalListener)
|
|
88
|
+
state.intervalListeners.delete(intervalListener);
|
|
89
|
+
};
|
|
69
90
|
}
|
package/dist/sdk/client.d.ts
CHANGED
|
@@ -122,6 +122,8 @@ export declare class NetGreenerClient {
|
|
|
122
122
|
format?: string;
|
|
123
123
|
}): Promise<Record<string, unknown>>;
|
|
124
124
|
quoteCredits(orgId: number, payload: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
125
|
+
/** Debit a server-priced quantity; reuse operation_id for retries of the same work. */
|
|
126
|
+
debitOrgCredits(orgId: number, payload: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
125
127
|
estimateRun(payload: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
126
128
|
estimateProject(projectId: number, payload: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
127
129
|
getRunEstimate(runId: number): Promise<Record<string, unknown>>;
|
package/dist/sdk/client.js
CHANGED
|
@@ -285,6 +285,10 @@ export class NetGreenerClient {
|
|
|
285
285
|
async quoteCredits(orgId, payload) {
|
|
286
286
|
return this.request('POST', `/billing/organizations/${orgId}/credit-quote`, payload);
|
|
287
287
|
}
|
|
288
|
+
/** Debit a server-priced quantity; reuse operation_id for retries of the same work. */
|
|
289
|
+
async debitOrgCredits(orgId, payload) {
|
|
290
|
+
return this.request('POST', `/billing/organizations/${orgId}/credit-debit`, payload);
|
|
291
|
+
}
|
|
288
292
|
async estimateRun(payload) {
|
|
289
293
|
return this.request('POST', '/runs/estimate', payload);
|
|
290
294
|
}
|
package/dist/taskMeter.js
CHANGED
|
@@ -11,23 +11,35 @@ export function recordMeteredTask(runtime, sample) {
|
|
|
11
11
|
if (!runtime.enabled) {
|
|
12
12
|
return sample.fn();
|
|
13
13
|
}
|
|
14
|
-
const
|
|
15
|
-
|
|
14
|
+
const lifetimeStarted = performance.now();
|
|
15
|
+
let started = lifetimeStarted;
|
|
16
|
+
let resourceMark = beginProcessResourceSample();
|
|
16
17
|
const taskId = String(sample.taskId || '').trim() || randomUUID();
|
|
17
18
|
getOccupancyTracker().begin(taskId);
|
|
18
19
|
let error = false;
|
|
19
|
-
|
|
20
|
-
const finalize = () => {
|
|
20
|
+
const checkpoint = (completed = false) => {
|
|
21
21
|
const resources = endProcessResourceSample(resourceMark);
|
|
22
22
|
getOccupancyTracker().end(taskId, sample.serviceUnit);
|
|
23
|
+
const now = performance.now();
|
|
23
24
|
runtime.recordTask({
|
|
24
25
|
serviceUnit: sample.serviceUnit,
|
|
25
|
-
durationMs:
|
|
26
|
+
durationMs: now - started,
|
|
27
|
+
completed,
|
|
28
|
+
...(completed ? { completionDurationMs: now - lifetimeStarted } : {}),
|
|
26
29
|
error,
|
|
27
30
|
tenantId: sample.tenantId,
|
|
28
31
|
cpuTimeMs: resources.cpuTimeMs,
|
|
29
32
|
peakRssKb: resources.rssKb,
|
|
30
33
|
});
|
|
34
|
+
started = now;
|
|
35
|
+
resourceMark = beginProcessResourceSample();
|
|
36
|
+
if (!completed)
|
|
37
|
+
getOccupancyTracker().begin(taskId);
|
|
38
|
+
};
|
|
39
|
+
const unregister = runtime.beginRequest(() => checkpoint());
|
|
40
|
+
const finalize = () => {
|
|
41
|
+
unregister();
|
|
42
|
+
checkpoint(true);
|
|
31
43
|
runtime.endRequest();
|
|
32
44
|
};
|
|
33
45
|
try {
|
package/package.json
CHANGED