@netgreener/runtime 0.1.8 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/TUTORIAL.md +120 -29
  2. package/dist/aggregator.d.ts +12 -2
  3. package/dist/aggregator.js +135 -8
  4. package/dist/analyze/buildResourceFindings.d.ts +4 -0
  5. package/dist/analyze/buildResourceFindings.js +17 -0
  6. package/dist/analyze/cli.d.ts +1 -0
  7. package/dist/analyze/cli.js +22 -1
  8. package/dist/analyze/declaredExternalApis.d.ts +31 -0
  9. package/dist/analyze/declaredExternalApis.js +174 -0
  10. package/dist/analyze/index.d.ts +1 -0
  11. package/dist/analyze/index.js +1 -0
  12. package/dist/auto.d.ts +7 -0
  13. package/dist/auto.js +8 -0
  14. package/dist/bullmq.d.ts +2 -2
  15. package/dist/bullmq.js +28 -58
  16. package/dist/carbonLedger.d.ts +28 -0
  17. package/dist/carbonLedger.js +52 -0
  18. package/dist/cgroupV2.d.ts +44 -0
  19. package/dist/cgroupV2.js +174 -0
  20. package/dist/cli/helpText.d.ts +3 -3
  21. package/dist/cli/helpText.js +42 -35
  22. package/dist/cli/netgreener.d.ts +7 -7
  23. package/dist/cli/netgreener.js +23 -16
  24. package/dist/cli/runCli.d.ts +20 -0
  25. package/dist/cli/runCli.js +249 -0
  26. package/dist/cli/runPreload.d.ts +5 -0
  27. package/dist/cli/runPreload.js +43 -0
  28. package/dist/collectorMetadata.d.ts +1 -1
  29. package/dist/collectorMetadata.js +2 -0
  30. package/dist/config.d.ts +2 -0
  31. package/dist/config.js +6 -2
  32. package/dist/exporter.d.ts +7 -2
  33. package/dist/exporter.js +12 -6
  34. package/dist/express.js +17 -6
  35. package/dist/externalApiMeter.d.ts +43 -1
  36. package/dist/externalApiMeter.js +267 -5
  37. package/dist/fastify.js +17 -6
  38. package/dist/index.d.ts +10 -2
  39. package/dist/index.js +9 -1
  40. package/dist/init.d.ts +30 -0
  41. package/dist/init.js +31 -0
  42. package/dist/lifecycle.d.ts +45 -0
  43. package/dist/lifecycle.js +112 -0
  44. package/dist/managedCollectorLauncher.d.ts +37 -0
  45. package/dist/managedCollectorLauncher.js +162 -0
  46. package/dist/n4/deploymentMatrix.d.ts +9 -5
  47. package/dist/n4/deploymentMatrix.js +13 -9
  48. package/dist/n4/missingnessInventory.js +3 -3
  49. package/dist/next.d.ts +61 -0
  50. package/dist/next.js +195 -0
  51. package/dist/occupancyTracker.d.ts +27 -0
  52. package/dist/occupancyTracker.js +87 -0
  53. package/dist/optimize/apply.d.ts +38 -0
  54. package/dist/optimize/apply.js +173 -0
  55. package/dist/optimize/cli.d.ts +26 -0
  56. package/dist/optimize/cli.js +323 -0
  57. package/dist/optimize/index.d.ts +6 -0
  58. package/dist/optimize/index.js +5 -0
  59. package/dist/optimize/llmApply.d.ts +22 -0
  60. package/dist/optimize/llmApply.js +80 -0
  61. package/dist/optimize/llmSession.d.ts +88 -0
  62. package/dist/optimize/llmSession.js +135 -0
  63. package/dist/optimize/provider.d.ts +17 -0
  64. package/dist/optimize/provider.js +119 -0
  65. package/dist/optimize/safePatches.d.ts +18 -0
  66. package/dist/optimize/safePatches.js +247 -0
  67. package/dist/optimize/types.d.ts +79 -0
  68. package/dist/optimize/types.js +6 -0
  69. package/dist/optimize/verification.d.ts +16 -0
  70. package/dist/optimize/verification.js +165 -0
  71. package/dist/processResources.d.ts +5 -0
  72. package/dist/processResources.js +28 -4
  73. package/dist/processRuntime.js +7 -28
  74. package/dist/processTree.d.ts +47 -0
  75. package/dist/processTree.js +148 -0
  76. package/dist/runContextEnrichment.d.ts +11 -0
  77. package/dist/runContextEnrichment.js +92 -0
  78. package/dist/runtime.d.ts +29 -1
  79. package/dist/runtime.js +94 -16
  80. package/dist/sdk/client.d.ts +152 -0
  81. package/dist/sdk/client.js +396 -0
  82. package/dist/sdk/gitUrl.d.ts +6 -0
  83. package/dist/sdk/gitUrl.js +87 -0
  84. package/dist/sdk/index.d.ts +5 -0
  85. package/dist/sdk/index.js +5 -0
  86. package/dist/serverlessHints.d.ts +9 -6
  87. package/dist/serverlessHints.js +10 -7
  88. package/dist/taskMeter.d.ts +14 -0
  89. package/dist/taskMeter.js +53 -0
  90. package/dist/types.d.ts +35 -0
  91. package/examples/aca-container-gate/Dockerfile +20 -0
  92. package/examples/aca-container-gate/azure-container-app.yaml +27 -0
  93. package/examples/aca-container-gate/gate.env +7 -0
  94. package/examples/aca-container-gate/server.mjs +117 -0
  95. package/examples/express-local-live-smoke.mjs +127 -0
  96. package/examples/extractRunId.mjs +11 -0
  97. package/examples/next-pilot-dry-run.mjs +32 -0
  98. package/examples/serverless-thin-gate.mjs +89 -0
  99. package/fixtures/run-smoke/hello.mjs +4 -0
  100. package/package.json +23 -2
package/dist/exporter.js CHANGED
@@ -12,15 +12,20 @@ import { createHash } from 'node:crypto';
12
12
  import { sendCollectorEvent, newCollectorEventId, CollectorIpcError, } from './collectorIpc.js';
13
13
  import { uploadRunSession, } from './uploader.js';
14
14
  import { flushModeRequestsThin } from './serverlessHints.js';
15
- function readExportMode(env = process.env) {
15
+ import { resolveLifecycle } from './lifecycle.js';
16
+ function readExportMode(env = process.env, opts) {
16
17
  // Explicit EXPORT_MODE always wins (including explicit ``direct``).
17
18
  const exportRaw = (env.NETGREENER_EXPORT_MODE || '').trim().toLowerCase();
18
19
  if (exportRaw === 'collector' || exportRaw === 'thin' || exportRaw === 'direct') {
19
20
  return exportRaw;
20
21
  }
21
- // Alias: FLUSH_MODE=thin when EXPORT_MODE unset — does not auto-detect platforms.
22
+ // Alias: FLUSH_MODE=thin when EXPORT_MODE unset.
22
23
  if (flushModeRequestsThin(env))
23
24
  return 'thin';
25
+ // Ephemeral lifecycle prefers thin when EXPORT_MODE unset (best_effort_bounded).
26
+ const lifecycle = opts?.lifecycle ?? resolveLifecycle({ env }).lifecycle;
27
+ if (lifecycle === 'ephemeral')
28
+ return 'thin';
24
29
  return 'direct';
25
30
  }
26
31
  function emitTimeoutMs(env = process.env) {
@@ -174,6 +179,7 @@ export class CollectorRunSessionExporter {
174
179
  session_metadata: payload.session_metadata,
175
180
  wall_time_utc: new Date().toISOString(),
176
181
  emitter: 'netgreener_node',
182
+ emitter_pid: process.pid,
177
183
  export_mode: 'collector',
178
184
  },
179
185
  });
@@ -291,14 +297,14 @@ export class CollectorRunSessionExporter {
291
297
  }
292
298
  }
293
299
  }
294
- export function resolveObservationExporter(env = process.env) {
295
- const mode = readExportMode(env);
300
+ export function resolveObservationExporter(env = process.env, opts) {
301
+ const mode = readExportMode(env, opts);
296
302
  if (mode === 'collector')
297
303
  return new CollectorRunSessionExporter();
298
304
  if (mode === 'thin')
299
305
  return new ThinRunSessionExporter();
300
306
  return new DirectRunSessionExporter();
301
307
  }
302
- export function exportModeFromEnv(env = process.env) {
303
- return readExportMode(env);
308
+ export function exportModeFromEnv(env = process.env, opts) {
309
+ return readExportMode(env, opts);
304
310
  }
package/dist/express.js CHANGED
@@ -2,6 +2,8 @@ import { getRuntime, } from './runtime.js';
2
2
  import { getTenantStore, resolveTenantFromHttpRequest, runWithTenantContext, tenantConfigFromRuntime, } from './tenantContext.js';
3
3
  import { runWithRequestAttribution } from './requestContext.js';
4
4
  import { beginProcessResourceSample, endProcessResourceSample, } from './processResources.js';
5
+ import { getOccupancyTracker } from './occupancyTracker.js';
6
+ import { randomUUID } from 'node:crypto';
5
7
  /**
6
8
  * Bounded template for service_unit attribution.
7
9
  * Never fall back to raw customer paths, baseUrl mounts, or query strings.
@@ -50,12 +52,15 @@ export function netgreenerExpressMiddleware(opts = {}) {
50
52
  ...opts,
51
53
  });
52
54
  runtime.start();
53
- const onSignal = () => {
54
- void runtime.shutdown();
55
- };
56
- process.once('beforeExit', onSignal);
57
- process.once('SIGINT', onSignal);
58
- process.once('SIGTERM', onSignal);
55
+ // Persistent only: ephemeral must not depend on process signals for correctness.
56
+ if (runtime.lifecycle === 'persistent') {
57
+ const onSignal = () => {
58
+ void runtime.shutdown();
59
+ };
60
+ process.once('beforeExit', onSignal);
61
+ process.once('SIGINT', onSignal);
62
+ process.once('SIGTERM', onSignal);
63
+ }
59
64
  // Prefer programmatic RuntimeConfig over ambient process.env.
60
65
  const tenantConfig = tenantConfigFromRuntime(runtime.config);
61
66
  return function netgreenerMiddleware(req, res, next) {
@@ -71,7 +76,10 @@ export function netgreenerExpressMiddleware(opts = {}) {
71
76
  const tenantStore = getTenantStore() ?? { current: entryTenant };
72
77
  const started = process.hrtime.bigint();
73
78
  const resourceMark = beginProcessResourceSample();
79
+ const requestId = randomUUID();
80
+ getOccupancyTracker().begin(requestId);
74
81
  let recorded = false;
82
+ runtime.beginRequest();
75
83
  const finish = () => {
76
84
  if (recorded)
77
85
  return;
@@ -81,6 +89,8 @@ export function netgreenerExpressMiddleware(opts = {}) {
81
89
  const resources = endProcessResourceSample(resourceMark);
82
90
  const path = expressRouteTemplate(req);
83
91
  const statusCode = typeof res.statusCode === 'number' ? res.statusCode : 200;
92
+ const serviceUnit = httpServiceUnit(method, req);
93
+ getOccupancyTracker().end(requestId, serviceUnit);
84
94
  // finish/close may run outside the request ALS — re-enter the live store.
85
95
  runWithTenantContext(tenantStore.current, () => {
86
96
  runtime.recordHttp({
@@ -92,6 +102,7 @@ export function netgreenerExpressMiddleware(opts = {}) {
92
102
  peakRssKb: resources.rssKb,
93
103
  });
94
104
  });
105
+ runtime.endRequest();
95
106
  };
96
107
  res.on('finish', finish);
97
108
  res.on('close', finish);
@@ -6,6 +6,7 @@
6
6
  * - global ``fetch`` (primary)
7
7
  * - ``axios`` Axios.prototype.request when axios is resolvable (optional peer)
8
8
  * - ``undici.request`` / Dispatcher.request when undici is resolvable
9
+ * (body teed via ``StreamUsageMeter`` for SSE/JSON usage — Python twin)
9
10
  *
10
11
  * Uploads restore unwrapped ``fetch``. Axios→fetch adapter paths skip the
11
12
  * fetch meter via ALS so the same call is not double-counted.
@@ -25,9 +26,50 @@ export declare function extractUsageFromResponse(response: Response, url: string
25
26
  output: number;
26
27
  model: string | null;
27
28
  }>;
29
+ /**
30
+ * Accumulate SSE/NDJSON usage from a streamed body, then report once on finish.
31
+ * Twin of Python ``_StreamUsageMeter`` — does not steal the body from the caller;
32
+ * wraps read paths so chunks are teed into a bounded buffer.
33
+ */
34
+ export declare class StreamUsageMeter {
35
+ private readonly opts;
36
+ private _buf;
37
+ private _reported;
38
+ private _inTok;
39
+ private _outTok;
40
+ private _model;
41
+ private _error;
42
+ private readonly _finishPromise;
43
+ private _resolveFinish;
44
+ constructor(opts: {
45
+ host: string;
46
+ url: string;
47
+ start: number;
48
+ error: boolean;
49
+ serviceUnit: string | null;
50
+ tenantId: string | null;
51
+ });
52
+ /** Resolves after ``finish`` (for flush / test coordination). */
53
+ whenFinished(): Promise<void>;
54
+ feed(chunk: unknown): void;
55
+ applyUsage(usage: {
56
+ input: number;
57
+ output: number;
58
+ model: string | null;
59
+ }): void;
60
+ finish(extra?: {
61
+ error?: boolean;
62
+ }): void;
63
+ }
64
+ /**
65
+ * Tee usage from a Readable-like body without replacing it (keeps undici helpers).
66
+ * Returns false when the body cannot be instrumented.
67
+ */
68
+ export declare function attachStreamUsageMeter(body: unknown, meter: StreamUsageMeter): boolean;
28
69
  /**
29
70
  * Usage extraction for axios (and similar) bodies already buffered by the client.
30
- * Does not read streams; returns zeros for stream/Buffer/unknown shapes.
71
+ * Does not read streams; returns zeros for stream/Buffer/unknown shapes
72
+ * (stream tokens are recovered via ``attachStreamUsageMeter``).
31
73
  */
32
74
  export declare function usageFromClientBody(data: unknown, url: string, contentType?: string | null): {
33
75
  input: number;
@@ -6,6 +6,7 @@
6
6
  * - global ``fetch`` (primary)
7
7
  * - ``axios`` Axios.prototype.request when axios is resolvable (optional peer)
8
8
  * - ``undici.request`` / Dispatcher.request when undici is resolvable
9
+ * (body teed via ``StreamUsageMeter`` for SSE/JSON usage — Python twin)
9
10
  *
10
11
  * Uploads restore unwrapped ``fetch``. Axios→fetch adapter paths skip the
11
12
  * fetch meter via ALS so the same call is not double-counted.
@@ -336,9 +337,233 @@ export async function extractUsageFromResponse(response, url) {
336
337
  return { input: 0, output: 0, model };
337
338
  }
338
339
  }
340
+ /**
341
+ * Accumulate SSE/NDJSON usage from a streamed body, then report once on finish.
342
+ * Twin of Python ``_StreamUsageMeter`` — does not steal the body from the caller;
343
+ * wraps read paths so chunks are teed into a bounded buffer.
344
+ */
345
+ export class StreamUsageMeter {
346
+ opts;
347
+ _buf = '';
348
+ _reported = false;
349
+ _inTok = 0;
350
+ _outTok = 0;
351
+ _model;
352
+ _error;
353
+ _finishPromise;
354
+ _resolveFinish = () => { };
355
+ constructor(opts) {
356
+ this.opts = opts;
357
+ this._error = opts.error;
358
+ this._model = modelFromUrl(opts.url);
359
+ this._finishPromise = new Promise((resolve) => {
360
+ this._resolveFinish = resolve;
361
+ });
362
+ }
363
+ /** Resolves after ``finish`` (for flush / test coordination). */
364
+ whenFinished() {
365
+ return this._finishPromise;
366
+ }
367
+ feed(chunk) {
368
+ if (this._reported || chunk == null)
369
+ return;
370
+ try {
371
+ let piece = '';
372
+ if (typeof chunk === 'string')
373
+ piece = chunk;
374
+ else if (Buffer.isBuffer(chunk))
375
+ piece = chunk.toString('utf8');
376
+ else if (chunk instanceof Uint8Array)
377
+ piece = Buffer.from(chunk).toString('utf8');
378
+ else if (typeof chunk === 'object' && ArrayBuffer.isView(chunk)) {
379
+ const view = chunk;
380
+ piece = Buffer.from(view.buffer, view.byteOffset, view.byteLength).toString('utf8');
381
+ }
382
+ else
383
+ piece = String(chunk);
384
+ if (!piece)
385
+ return;
386
+ this._buf += piece;
387
+ if (this._buf.length > MAX_USAGE_PARSE_BYTES) {
388
+ this._buf = this._buf.slice(-MAX_USAGE_PARSE_BYTES);
389
+ }
390
+ if (this._buf.includes('\n')) {
391
+ const extracted = usageFromSseText(this._buf);
392
+ if (extracted.input)
393
+ this._inTok = extracted.input;
394
+ if (extracted.output)
395
+ this._outTok = extracted.output;
396
+ if (extracted.model)
397
+ this._model = extracted.model;
398
+ if (this._buf.length > 8192)
399
+ this._buf = this._buf.slice(-4096);
400
+ }
401
+ }
402
+ catch {
403
+ /* never break caller stream */
404
+ }
405
+ }
406
+ applyUsage(usage) {
407
+ if (this._reported)
408
+ return;
409
+ if (usage.input)
410
+ this._inTok = usage.input;
411
+ if (usage.output)
412
+ this._outTok = usage.output;
413
+ if (usage.model)
414
+ this._model = usage.model;
415
+ }
416
+ finish(extra) {
417
+ if (this._reported) {
418
+ this._resolveFinish();
419
+ return;
420
+ }
421
+ this._reported = true;
422
+ if (extra && typeof extra.error === 'boolean')
423
+ this._error = extra.error;
424
+ try {
425
+ if (this._buf) {
426
+ const extracted = usageFromSseText(this._buf);
427
+ if (extracted.input)
428
+ this._inTok = extracted.input;
429
+ if (extracted.output)
430
+ this._outTok = extracted.output;
431
+ if (extracted.model)
432
+ this._model = extracted.model;
433
+ }
434
+ }
435
+ catch {
436
+ /* zeros already held */
437
+ }
438
+ this._buf = '';
439
+ // recordMeteredCall is defined later in this module; called only at runtime after init.
440
+ recordMeteredCall({
441
+ host: this.opts.host,
442
+ url: this.opts.url,
443
+ durationMs: performance.now() - this.opts.start,
444
+ error: this._error,
445
+ usage: { input: this._inTok, output: this._outTok, model: this._model },
446
+ serviceUnit: this.opts.serviceUnit,
447
+ tenantId: this.opts.tenantId,
448
+ });
449
+ this._resolveFinish();
450
+ }
451
+ }
452
+ /**
453
+ * Tee usage from a Readable-like body without replacing it (keeps undici helpers).
454
+ * Returns false when the body cannot be instrumented.
455
+ */
456
+ export function attachStreamUsageMeter(body, meter) {
457
+ if (!body || typeof body !== 'object')
458
+ return false;
459
+ const stream = body;
460
+ if (stream._netgreenerUsageMeterAttached)
461
+ return true;
462
+ stream._netgreenerUsageMeterAttached = true;
463
+ let attached = false;
464
+ const asyncIter = stream[Symbol.asyncIterator];
465
+ if (typeof asyncIter === 'function') {
466
+ stream[Symbol.asyncIterator] = async function* netgreenerUsageAsyncIter() {
467
+ // undici returns an AsyncIterator (not always an AsyncIterable). Drive
468
+ // ``next()`` directly so ``body.text()`` / ``dump()`` keep working.
469
+ const iterator = asyncIter.call(stream);
470
+ try {
471
+ while (true) {
472
+ const step = await iterator.next();
473
+ if (step.done)
474
+ break;
475
+ meter.feed(step.value);
476
+ yield step.value;
477
+ }
478
+ }
479
+ catch (err) {
480
+ meter.finish({ error: true });
481
+ throw err;
482
+ }
483
+ finally {
484
+ meter.finish();
485
+ }
486
+ };
487
+ attached = true;
488
+ }
489
+ let wrappedConsumeHelper = false;
490
+ for (const method of ['text', 'json', 'arrayBuffer', 'dump']) {
491
+ const orig = stream[method];
492
+ if (typeof orig !== 'function')
493
+ continue;
494
+ const bound = orig.bind(stream);
495
+ wrappedConsumeHelper = true;
496
+ stream[method] = async (...args) => {
497
+ try {
498
+ const result = await bound(...args);
499
+ if (method === 'text' && typeof result === 'string') {
500
+ meter.feed(result);
501
+ }
502
+ else if (method === 'json' &&
503
+ result &&
504
+ typeof result === 'object' &&
505
+ !Array.isArray(result)) {
506
+ const extracted = usageFromPayload(result);
507
+ meter.applyUsage({
508
+ input: extracted.input,
509
+ output: extracted.output,
510
+ model: extracted.model,
511
+ });
512
+ }
513
+ else if (method === 'arrayBuffer' && result instanceof ArrayBuffer) {
514
+ meter.feed(Buffer.from(result));
515
+ }
516
+ return result;
517
+ }
518
+ catch (err) {
519
+ meter.finish({ error: true });
520
+ throw err;
521
+ }
522
+ finally {
523
+ meter.finish();
524
+ }
525
+ };
526
+ attached = true;
527
+ }
528
+ if (typeof stream.on === 'function') {
529
+ const originalOn = stream.on.bind(stream);
530
+ const wrapListener = (event, listener) => {
531
+ // Preserve ``this`` — undici ``body.text()`` end handlers use ``this[kConsume]``.
532
+ if (event === 'data') {
533
+ return function (chunk, ...rest) {
534
+ meter.feed(chunk);
535
+ return listener.call(this, chunk, ...rest);
536
+ };
537
+ }
538
+ if (event === 'end' || event === 'close') {
539
+ return function (...args) {
540
+ // When text/json/dump are wrapped, those helpers finish after feed.
541
+ // Finishing here races await resume (microtasks) and drops SSE tokens.
542
+ if (!wrappedConsumeHelper)
543
+ meter.finish();
544
+ return listener.call(this, ...args);
545
+ };
546
+ }
547
+ if (event === 'error') {
548
+ return function (...args) {
549
+ meter.finish({ error: true });
550
+ return listener.call(this, ...args);
551
+ };
552
+ }
553
+ return listener;
554
+ };
555
+ stream.on = ((event, listener) => originalOn(event, wrapListener(event, listener)));
556
+ if (typeof stream.addListener === 'function') {
557
+ stream.addListener = stream.on;
558
+ }
559
+ attached = true;
560
+ }
561
+ return attached;
562
+ }
339
563
  /**
340
564
  * Usage extraction for axios (and similar) bodies already buffered by the client.
341
- * Does not read streams; returns zeros for stream/Buffer/unknown shapes.
565
+ * Does not read streams; returns zeros for stream/Buffer/unknown shapes
566
+ * (stream tokens are recovered via ``attachStreamUsageMeter``).
342
567
  */
343
568
  export function usageFromClientBody(data, url, contentType) {
344
569
  const model = modelFromUrl(url);
@@ -761,6 +986,9 @@ let originalFetch = null;
761
986
  let restoreAxios = null;
762
987
  let restoreUndici = null;
763
988
  const pendingUsageParses = [];
989
+ function trackStreamMeter(meter) {
990
+ pendingUsageParses.push(meter.whenFinished());
991
+ }
764
992
  function recordMeteredCall(opts) {
765
993
  try {
766
994
  globalAgg.record({
@@ -964,11 +1192,28 @@ function installAxiosWrap() {
964
1192
  /* ignore */
965
1193
  }
966
1194
  const responseType = String(resp?.config?.responseType || cfg.responseType || '').toLowerCase();
967
- const streaming = responseType === 'stream';
1195
+ const ctype = headerContentType(resp?.headers);
1196
+ const streaming = responseType === 'stream' ||
1197
+ (ctype || '').toLowerCase().includes('text/event-stream') ||
1198
+ (ctype || '').toLowerCase().includes('application/stream+json');
1199
+ if (streaming && resp?.data && typeof resp.data === 'object') {
1200
+ const meter = new StreamUsageMeter({
1201
+ host,
1202
+ url,
1203
+ start,
1204
+ error,
1205
+ serviceUnit: serviceUnitAtStart,
1206
+ tenantId: tenantIdAtStart,
1207
+ });
1208
+ if (attachStreamUsageMeter(resp.data, meter)) {
1209
+ trackStreamMeter(meter);
1210
+ return result;
1211
+ }
1212
+ }
968
1213
  let usage = { input: 0, output: 0, model: modelFromUrl(url) };
969
- if (!streaming && resp) {
1214
+ if (resp) {
970
1215
  try {
971
- usage = usageFromClientBody(resp.data, url, headerContentType(resp.headers));
1216
+ usage = usageFromClientBody(resp.data, url, ctype);
972
1217
  }
973
1218
  catch {
974
1219
  /* zeros */
@@ -1047,7 +1292,24 @@ function installUndiciWrap() {
1047
1292
  if (typeof status === 'number' && status >= 400)
1048
1293
  error = true;
1049
1294
  }
1050
- // Do not consume undici body streams — call/error/duration only (tokens via fetch/axios JSON).
1295
+ const body = result && typeof result === 'object'
1296
+ ? result.body
1297
+ : undefined;
1298
+ if (!threw && body != null) {
1299
+ const meter = new StreamUsageMeter({
1300
+ host,
1301
+ url,
1302
+ start,
1303
+ error,
1304
+ serviceUnit: serviceUnitAtStart,
1305
+ tenantId: tenantIdAtStart,
1306
+ });
1307
+ if (attachStreamUsageMeter(body, meter)) {
1308
+ trackStreamMeter(meter);
1309
+ return result;
1310
+ }
1311
+ }
1312
+ // No body / attach failed — record call/error/duration without tokens.
1051
1313
  recordMeteredCall({
1052
1314
  host,
1053
1315
  url,
package/dist/fastify.js CHANGED
@@ -3,6 +3,8 @@ import { enterTenantStore, resolveTenantFromHttpRequest, runWithTenantContext, s
3
3
  import { enterRequestAttribution } from './requestContext.js';
4
4
  import { UNKNOWN_ROUTE_TEMPLATE } from './express.js';
5
5
  import { beginProcessResourceSample, endProcessResourceSample, } from './processResources.js';
6
+ import { getOccupancyTracker } from './occupancyTracker.js';
7
+ import { randomUUID } from 'node:crypto';
6
8
  const MAX_ROUTE_TEMPLATE_LEN = 512;
7
9
  const REQ_STATE = Symbol.for('netgreener.fastify.requestState');
8
10
  /**
@@ -72,12 +74,14 @@ export function netgreenerFastifyPlugin(opts = {}) {
72
74
  ...opts,
73
75
  });
74
76
  runtime.start();
75
- const onSignal = () => {
76
- void runtime.shutdown();
77
- };
78
- process.once('beforeExit', onSignal);
79
- process.once('SIGINT', onSignal);
80
- process.once('SIGTERM', onSignal);
77
+ if (runtime.lifecycle === 'persistent') {
78
+ const onSignal = () => {
79
+ void runtime.shutdown();
80
+ };
81
+ process.once('beforeExit', onSignal);
82
+ process.once('SIGINT', onSignal);
83
+ process.once('SIGTERM', onSignal);
84
+ }
81
85
  const tenantConfig = tenantConfigFromRuntime(runtime.config);
82
86
  const plugin = async function netgreenerFastify(fastify) {
83
87
  if (!runtime.enabled)
@@ -92,13 +96,17 @@ export function netgreenerFastifyPlugin(opts = {}) {
92
96
  resolveServiceUnit,
93
97
  serviceUnit: resolveServiceUnit(),
94
98
  });
99
+ const requestId = randomUUID();
100
+ getOccupancyTracker().begin(requestId);
95
101
  setRequestState(req, {
96
102
  tenantStore,
97
103
  method,
98
104
  started: process.hrtime.bigint(),
99
105
  resourceMark: beginProcessResourceSample(),
100
106
  recorded: false,
107
+ requestId,
101
108
  });
109
+ runtime.beginRequest();
102
110
  if (typeof done === 'function') {
103
111
  ;
104
112
  done();
@@ -119,6 +127,8 @@ export function netgreenerFastifyPlugin(opts = {}) {
119
127
  const statusCode = typeof reply?.statusCode === 'number'
120
128
  ? reply.statusCode
121
129
  : 200;
130
+ const serviceUnit = httpServiceUnit(state.method, req);
131
+ getOccupancyTracker().end(state.requestId, serviceUnit);
122
132
  runWithTenantContext(state.tenantStore.current, () => {
123
133
  runtime.recordHttp({
124
134
  method: state.method,
@@ -129,6 +139,7 @@ export function netgreenerFastifyPlugin(opts = {}) {
129
139
  peakRssKb: resources.rssKb,
130
140
  });
131
141
  });
142
+ runtime.endRequest();
132
143
  if (typeof done === 'function')
133
144
  done();
134
145
  };
package/dist/index.d.ts CHANGED
@@ -5,23 +5,31 @@
5
5
  * N2: outbound fetch meter · N3: BullMQ worker + process/cron runtime
6
6
  * Does not modify Python CLI/runtime capability.
7
7
  */
8
- export type { AllocationReconciliationV0, EvidenceGrades, ExternalApiModelBucket, ExternalApiProvider, ExternalApiTenantBucket, ExternalApiV0, MeasurementProvenance, RunContext, RuntimeSessionMetadata, ServiceRuntimeTenantBucket, ServiceRuntimeUnit, ServiceRuntimeV0, TenantId, } from './types.js';
8
+ export type { AllocationReconciliationV0, AttributionDetailV0, EvidenceGrades, ExternalApiModelBucket, ExternalApiProvider, ExternalApiTenantBucket, ExternalApiV0, MeasurementProvenance, RunContext, RuntimeSessionMetadata, ServiceRuntimeTenantBucket, ServiceRuntimeUnit, ServiceRuntimeV0, TenantId, } from './types.js';
9
9
  export { validateExternalApiV0, validateMeasurementProvenance, validateRuntimeSessionMetadata, validateServiceRuntimeV0, type ContractIssue, type ContractResult, } from './contract/index.js';
10
10
  export { loadRuntimeConfig, configReady, type RuntimeConfig } from './config.js';
11
11
  export { COMPATIBLE_COLLECTOR_METADATA, COLLECTOR_METADATA_NOTES, isCompatibleCollectorMetadata, type CompatibleCollectorMetadata, } from './collectorMetadata.js';
12
12
  export { validateObservationEnvelope, classifyObservationDelivery, projectSemanticEnvelopeToProtobufView, validateObservationProtobufView, validateObservationDualView, } from './contract/observation-v1.mjs';
13
13
  export { ServiceRuntimeAggregator } from './aggregator.js';
14
- export { beginProcessResourceSample, endProcessResourceSample, currentRssKb, type ProcessResourceMark, type ProcessResourceSample, } from './processResources.js';
14
+ export { DEFAULT_GRID_KG_CO2E_PER_KWH, carbonFactorDict, defaultGridFactor, energyKwhToCarbonG, energyKwhToCarbonKg, type CarbonFactor, } from './carbonLedger.js';
15
+ export { beginProcessResourceSample, endProcessResourceSample, currentRssKb, _resetRssSampleCacheForTests, type ProcessResourceMark, type ProcessResourceSample, } from './processResources.js';
16
+ export { CgroupV2Reader, resolveCgroupV2Path, snapshotDelta, type CgroupV2Snapshot, type CgroupV2Provenance, } from './cgroupV2.js';
17
+ export { sampleProcessTree, processTreeAvailability, collectDescendantPids, CPU_SOURCE_PROCESS_TREE, MEMORY_SOURCE_PROCESS_TREE, type ProcessTreeSample, } from './processTree.js';
18
+ export { startManagedCollector, normalizedCollectorMode, childEnvForManagedCollector, reserveTcpEndpoint, type ManagedCollectorHandle, type CollectorMode, } from './managedCollectorLauncher.js';
19
+ export { OccupancyTracker, getOccupancyTracker, type OccupancyWindowSnapshot, } from './occupancyTracker.js';
15
20
  export { buildRuntimeHealthV0, mergeHealthIntoMetadata, markHooksActive, type RuntimeHealthV0, type RuntimeHealthStatus, } from './runtimeHealth.js';
16
21
  export { newRuntimeWindowId } from './windowId.js';
17
22
  export { uploadRunSession, type RunSessionCreatePayload, type UploadResult, } from './uploader.js';
18
23
  export { resolveObservationExporter, exportModeFromEnv, DirectRunSessionExporter, ThinRunSessionExporter, CollectorRunSessionExporter, type ExportMode, type ExportResult, type ObservationExporter, type ObservationBatchDocument, } from './exporter.js';
19
24
  export { detectServerlessPlatformSignals, flushModeRequestsThin, type ServerlessPlatformHint, type ServerlessPlatformSignal, } from './serverlessHints.js';
25
+ export { resolveLifecycle, isEphemeralLifecycle, type RuntimeModePreference, type RuntimeLifecycle, type RuntimePlatform, type RuntimeCapabilities, type ResolvedRuntimeLifecycle, } from './lifecycle.js';
26
+ export { NetGreener, type NetGreenerInitOptions } from './init.js';
20
27
  export { sendCollectorEvent, encodeCollectorFrame, normalizeCollectorEndpoint, type CollectorIpcAck, } from './collectorIpc.js';
21
28
  export { NetGreenerRuntime, getRuntime, _resetRuntimeForTests, type FlushKind, type NetGreenerRuntimeOptions, } from './runtime.js';
22
29
  export { netgreenerExpressMiddleware, getExpressRuntime, type ExpressRequest, type ExpressResponse, type ExpressNext, } from './express.js';
23
30
  export { netgreenerFastifyPlugin, getFastifyRuntime, fastifyRouteTemplate, bindFastifyTenant, type FastifyLike, type FastifyRequestLike, type FastifyReplyLike, } from './fastify.js';
24
31
  export { applyNetGreenerNestHooks, detectNestHttpAdapter, getNestRuntime, netgreenerNestExpressMiddleware, netgreenerNestFastifyPlugin, type NestApplicationLike, type NestHttpAdapterKind, } from './nest.js';
32
+ export { UNKNOWN_NEXT_ROUTE_TEMPLATE, flushNetGreenerNext, getNextRuntime, nextRouteTemplate, registerNetGreenerNext, scheduleNetGreenerFlush, withNetGreenerRoute, type NetGreenerNextOptions, type NextRequestLike, type NextRouteContext, } from './next.js';
25
33
  export { attachWindowTenantToRunContext, getTenantContext, loadTenantConfig, normalizeTenantId, resolveTenantFromHttpRequest, resolveTenantFromTaskData, runWithTenantContext, setTenantContext, tenantConfigFromRuntime, type TenantConfig, type TenantContext, } from './tenantContext.js';
26
34
  export { ExternalApiAggregator, buildExternalV0, clearExternalAggregator, getExternalAggregator, installOutboundInstrumentation, providerForHost, usageFromClientBody, _resetOutboundInstrumentationForTests, } from './externalApiMeter.js';
27
35
  export { attributionServiceUnit, getRequestAttribution, runWithRequestAttribution, } from './requestContext.js';
package/dist/index.js CHANGED
@@ -10,17 +10,25 @@ export { loadRuntimeConfig, configReady } from './config.js';
10
10
  export { COMPATIBLE_COLLECTOR_METADATA, COLLECTOR_METADATA_NOTES, isCompatibleCollectorMetadata, } from './collectorMetadata.js';
11
11
  export { validateObservationEnvelope, classifyObservationDelivery, projectSemanticEnvelopeToProtobufView, validateObservationProtobufView, validateObservationDualView, } from './contract/observation-v1.mjs';
12
12
  export { ServiceRuntimeAggregator } from './aggregator.js';
13
- export { beginProcessResourceSample, endProcessResourceSample, currentRssKb, } from './processResources.js';
13
+ export { DEFAULT_GRID_KG_CO2E_PER_KWH, carbonFactorDict, defaultGridFactor, energyKwhToCarbonG, energyKwhToCarbonKg, } from './carbonLedger.js';
14
+ export { beginProcessResourceSample, endProcessResourceSample, currentRssKb, _resetRssSampleCacheForTests, } from './processResources.js';
15
+ export { CgroupV2Reader, resolveCgroupV2Path, snapshotDelta, } from './cgroupV2.js';
16
+ export { sampleProcessTree, processTreeAvailability, collectDescendantPids, CPU_SOURCE_PROCESS_TREE, MEMORY_SOURCE_PROCESS_TREE, } from './processTree.js';
17
+ export { startManagedCollector, normalizedCollectorMode, childEnvForManagedCollector, reserveTcpEndpoint, } from './managedCollectorLauncher.js';
18
+ export { OccupancyTracker, getOccupancyTracker, } from './occupancyTracker.js';
14
19
  export { buildRuntimeHealthV0, mergeHealthIntoMetadata, markHooksActive, } from './runtimeHealth.js';
15
20
  export { newRuntimeWindowId } from './windowId.js';
16
21
  export { uploadRunSession, } from './uploader.js';
17
22
  export { resolveObservationExporter, exportModeFromEnv, DirectRunSessionExporter, ThinRunSessionExporter, CollectorRunSessionExporter, } from './exporter.js';
18
23
  export { detectServerlessPlatformSignals, flushModeRequestsThin, } from './serverlessHints.js';
24
+ export { resolveLifecycle, isEphemeralLifecycle, } from './lifecycle.js';
25
+ export { NetGreener } from './init.js';
19
26
  export { sendCollectorEvent, encodeCollectorFrame, normalizeCollectorEndpoint, } from './collectorIpc.js';
20
27
  export { NetGreenerRuntime, getRuntime, _resetRuntimeForTests, } from './runtime.js';
21
28
  export { netgreenerExpressMiddleware, getExpressRuntime, } from './express.js';
22
29
  export { netgreenerFastifyPlugin, getFastifyRuntime, fastifyRouteTemplate, bindFastifyTenant, } from './fastify.js';
23
30
  export { applyNetGreenerNestHooks, detectNestHttpAdapter, getNestRuntime, netgreenerNestExpressMiddleware, netgreenerNestFastifyPlugin, } from './nest.js';
31
+ export { UNKNOWN_NEXT_ROUTE_TEMPLATE, flushNetGreenerNext, getNextRuntime, nextRouteTemplate, registerNetGreenerNext, scheduleNetGreenerFlush, withNetGreenerRoute, } from './next.js';
24
32
  export { attachWindowTenantToRunContext, getTenantContext, loadTenantConfig, normalizeTenantId, resolveTenantFromHttpRequest, resolveTenantFromTaskData, runWithTenantContext, setTenantContext, tenantConfigFromRuntime, } from './tenantContext.js';
25
33
  export { ExternalApiAggregator, buildExternalV0, clearExternalAggregator, getExternalAggregator, installOutboundInstrumentation, providerForHost, usageFromClientBody, _resetOutboundInstrumentationForTests, } from './externalApiMeter.js';
26
34
  export { attributionServiceUnit, getRequestAttribution, runWithRequestAttribution, } from './requestContext.js';
package/dist/init.d.ts ADDED
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Single NetGreener init surface — one product, lifecycle-aware delivery.
3
+ *
4
+ * Prefer ``import '@netgreener/runtime/auto'`` or ``NetGreener.init()``.
5
+ * Does not create a separate Vercel/Lambda product.
6
+ */
7
+ import { type NetGreenerRuntime, type NetGreenerRuntimeOptions } from './runtime.js';
8
+ import type { UploadResult } from './uploader.js';
9
+ import type { RuntimeModePreference } from './lifecycle.js';
10
+ export type NetGreenerInitOptions = NetGreenerRuntimeOptions & {
11
+ /**
12
+ * Lifecycle preference. Default ``auto`` (serverless signals → ephemeral).
13
+ * Most apps never need to set this.
14
+ */
15
+ runtime?: RuntimeModePreference;
16
+ };
17
+ export declare const NetGreener: {
18
+ /**
19
+ * Initialize (or return) the process singleton and start metering.
20
+ * Safe to call multiple times — subsequent calls reuse the singleton.
21
+ */
22
+ init(opts?: NetGreenerInitOptions): NetGreenerRuntime;
23
+ /**
24
+ * Flush at a serverless invoke boundary (Lambda handler finally, etc.).
25
+ * Fail-open: errors are returned, never thrown to the caller by design
26
+ * of ``flush`` (catch returns UploadResult).
27
+ */
28
+ flushForInvokeEnd(): Promise<UploadResult | null>;
29
+ };
30
+ export default NetGreener;