risicare 0.9.0 → 0.9.2

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 (93) hide show
  1. package/CHANGELOG.md +1236 -0
  2. package/README.md +18 -0
  3. package/dist/frameworks/instructor.cjs +163 -6
  4. package/dist/frameworks/instructor.cjs.map +1 -1
  5. package/dist/frameworks/instructor.js +163 -6
  6. package/dist/frameworks/instructor.js.map +1 -1
  7. package/dist/frameworks/langchain.cjs +163 -6
  8. package/dist/frameworks/langchain.cjs.map +1 -1
  9. package/dist/frameworks/langchain.js +163 -6
  10. package/dist/frameworks/langchain.js.map +1 -1
  11. package/dist/frameworks/langgraph.cjs +163 -6
  12. package/dist/frameworks/langgraph.cjs.map +1 -1
  13. package/dist/frameworks/langgraph.js +163 -6
  14. package/dist/frameworks/langgraph.js.map +1 -1
  15. package/dist/frameworks/llamaindex.cjs +163 -6
  16. package/dist/frameworks/llamaindex.cjs.map +1 -1
  17. package/dist/frameworks/llamaindex.js +163 -6
  18. package/dist/frameworks/llamaindex.js.map +1 -1
  19. package/dist/index.cjs +274 -18
  20. package/dist/index.cjs.map +1 -1
  21. package/dist/index.d.cts +7 -1
  22. package/dist/index.d.ts +7 -1
  23. package/dist/index.js +274 -18
  24. package/dist/index.js.map +1 -1
  25. package/dist/providers/anthropic/index.cjs +168 -7
  26. package/dist/providers/anthropic/index.cjs.map +1 -1
  27. package/dist/providers/anthropic/index.d.cts +3 -0
  28. package/dist/providers/anthropic/index.d.ts +3 -0
  29. package/dist/providers/anthropic/index.js +168 -7
  30. package/dist/providers/anthropic/index.js.map +1 -1
  31. package/dist/providers/bedrock/index.cjs +168 -7
  32. package/dist/providers/bedrock/index.cjs.map +1 -1
  33. package/dist/providers/bedrock/index.d.cts +3 -0
  34. package/dist/providers/bedrock/index.d.ts +3 -0
  35. package/dist/providers/bedrock/index.js +168 -7
  36. package/dist/providers/bedrock/index.js.map +1 -1
  37. package/dist/providers/cerebras/index.cjs +168 -7
  38. package/dist/providers/cerebras/index.cjs.map +1 -1
  39. package/dist/providers/cerebras/index.d.cts +3 -0
  40. package/dist/providers/cerebras/index.d.ts +3 -0
  41. package/dist/providers/cerebras/index.js +168 -7
  42. package/dist/providers/cerebras/index.js.map +1 -1
  43. package/dist/providers/cohere/index.cjs +168 -7
  44. package/dist/providers/cohere/index.cjs.map +1 -1
  45. package/dist/providers/cohere/index.d.cts +3 -0
  46. package/dist/providers/cohere/index.d.ts +3 -0
  47. package/dist/providers/cohere/index.js +168 -7
  48. package/dist/providers/cohere/index.js.map +1 -1
  49. package/dist/providers/google/index.cjs +168 -7
  50. package/dist/providers/google/index.cjs.map +1 -1
  51. package/dist/providers/google/index.d.cts +3 -0
  52. package/dist/providers/google/index.d.ts +3 -0
  53. package/dist/providers/google/index.js +168 -7
  54. package/dist/providers/google/index.js.map +1 -1
  55. package/dist/providers/groq/index.cjs +168 -7
  56. package/dist/providers/groq/index.cjs.map +1 -1
  57. package/dist/providers/groq/index.d.cts +3 -0
  58. package/dist/providers/groq/index.d.ts +3 -0
  59. package/dist/providers/groq/index.js +168 -7
  60. package/dist/providers/groq/index.js.map +1 -1
  61. package/dist/providers/huggingface/index.cjs +166 -6
  62. package/dist/providers/huggingface/index.cjs.map +1 -1
  63. package/dist/providers/huggingface/index.js +166 -6
  64. package/dist/providers/huggingface/index.js.map +1 -1
  65. package/dist/providers/mistral/index.cjs +168 -7
  66. package/dist/providers/mistral/index.cjs.map +1 -1
  67. package/dist/providers/mistral/index.d.cts +3 -0
  68. package/dist/providers/mistral/index.d.ts +3 -0
  69. package/dist/providers/mistral/index.js +168 -7
  70. package/dist/providers/mistral/index.js.map +1 -1
  71. package/dist/providers/ollama/index.cjs +168 -7
  72. package/dist/providers/ollama/index.cjs.map +1 -1
  73. package/dist/providers/ollama/index.d.cts +3 -0
  74. package/dist/providers/ollama/index.d.ts +3 -0
  75. package/dist/providers/ollama/index.js +168 -7
  76. package/dist/providers/ollama/index.js.map +1 -1
  77. package/dist/providers/openai/index.cjs +168 -7
  78. package/dist/providers/openai/index.cjs.map +1 -1
  79. package/dist/providers/openai/index.d.cts +3 -0
  80. package/dist/providers/openai/index.d.ts +3 -0
  81. package/dist/providers/openai/index.js +168 -7
  82. package/dist/providers/openai/index.js.map +1 -1
  83. package/dist/providers/together/index.cjs +168 -7
  84. package/dist/providers/together/index.cjs.map +1 -1
  85. package/dist/providers/together/index.d.cts +3 -0
  86. package/dist/providers/together/index.d.ts +3 -0
  87. package/dist/providers/together/index.js +168 -7
  88. package/dist/providers/together/index.js.map +1 -1
  89. package/dist/providers/vercel-ai/index.cjs +163 -6
  90. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  91. package/dist/providers/vercel-ai/index.js +163 -6
  92. package/dist/providers/vercel-ai/index.js.map +1 -1
  93. package/package.json +3 -2
package/dist/index.d.cts CHANGED
@@ -566,7 +566,7 @@ declare function getTracer(): Tracer$1 | undefined;
566
566
  declare function getTraceContent(): boolean;
567
567
  /**
568
568
  * Get SDK metrics: exported spans (accepted by the backend), `rejectedSpans`,
569
- * dropped spans and their reasons (`unacknowledged` included), failed exports,
569
+ * dropped spans and their reasons (`unacknowledged` and `quota_exceeded` included; `droppedQuota` is the latter), failed exports,
570
570
  * queue stats, and `failedScores` (`score()` requests that failed since
571
571
  * `init()`).
572
572
  *
@@ -602,7 +602,9 @@ declare function getMetrics(): {
602
602
  transport_refused: number;
603
603
  shutdown_residue: number;
604
604
  unacknowledged: number;
605
+ quota_exceeded: number;
605
606
  };
607
+ droppedQuota: number;
606
608
  failedExports: number;
607
609
  maskErrors: number;
608
610
  queueSize: number;
@@ -615,11 +617,13 @@ declare function getMetrics(): {
615
617
  transport_refused: number;
616
618
  shutdown_residue: number;
617
619
  unacknowledged: number;
620
+ quota_exceeded: number;
618
621
  };
619
622
  sdkState: "shutdown";
620
623
  exportedSpans: number;
621
624
  rejectedSpans: number;
622
625
  droppedSpans: number;
626
+ droppedQuota: number;
623
627
  failedExports: number;
624
628
  maskErrors: number;
625
629
  queueSize: number;
@@ -635,7 +639,9 @@ declare function getMetrics(): {
635
639
  transport_refused: number;
636
640
  shutdown_residue: number;
637
641
  unacknowledged: number;
642
+ quota_exceeded: number;
638
643
  };
644
+ droppedQuota: number;
639
645
  failedExports: number;
640
646
  queueSize: number;
641
647
  queueCapacity: number;
package/dist/index.d.ts CHANGED
@@ -566,7 +566,7 @@ declare function getTracer(): Tracer$1 | undefined;
566
566
  declare function getTraceContent(): boolean;
567
567
  /**
568
568
  * Get SDK metrics: exported spans (accepted by the backend), `rejectedSpans`,
569
- * dropped spans and their reasons (`unacknowledged` included), failed exports,
569
+ * dropped spans and their reasons (`unacknowledged` and `quota_exceeded` included; `droppedQuota` is the latter), failed exports,
570
570
  * queue stats, and `failedScores` (`score()` requests that failed since
571
571
  * `init()`).
572
572
  *
@@ -602,7 +602,9 @@ declare function getMetrics(): {
602
602
  transport_refused: number;
603
603
  shutdown_residue: number;
604
604
  unacknowledged: number;
605
+ quota_exceeded: number;
605
606
  };
607
+ droppedQuota: number;
606
608
  failedExports: number;
607
609
  maskErrors: number;
608
610
  queueSize: number;
@@ -615,11 +617,13 @@ declare function getMetrics(): {
615
617
  transport_refused: number;
616
618
  shutdown_residue: number;
617
619
  unacknowledged: number;
620
+ quota_exceeded: number;
618
621
  };
619
622
  sdkState: "shutdown";
620
623
  exportedSpans: number;
621
624
  rejectedSpans: number;
622
625
  droppedSpans: number;
626
+ droppedQuota: number;
623
627
  failedExports: number;
624
628
  maskErrors: number;
625
629
  queueSize: number;
@@ -635,7 +639,9 @@ declare function getMetrics(): {
635
639
  transport_refused: number;
636
640
  shutdown_residue: number;
637
641
  unacknowledged: number;
642
+ quota_exceeded: number;
638
643
  };
644
+ droppedQuota: number;
639
645
  failedExports: number;
640
646
  queueSize: number;
641
647
  queueCapacity: number;
package/dist/index.js CHANGED
@@ -86,6 +86,10 @@ function warn(msg) {
86
86
  process.stderr.write(`[risicare] WARNING: ${msg}
87
87
  `);
88
88
  }
89
+ function info(msg) {
90
+ process.stderr.write(`[risicare] INFO: ${msg}
91
+ `);
92
+ }
89
93
 
90
94
  // src/utils/text.ts
91
95
  function cutCodePoints(text, max) {
@@ -556,6 +560,12 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
556
560
  _beforeExitHandler = null;
557
561
  // Retry tracking for failed batches (Audit #5)
558
562
  _retryCounts = /* @__PURE__ */ new Map();
563
+ /**
564
+ * The HTTP requests that the failed rounds of each re-queued span sent, by span id (issue
565
+ * #57). It has the same life as `_retryCounts`: `_forgetRetry` ends both. NaN = a round for
566
+ * which the exporter did not say. Empty for an exporter that does not state it.
567
+ */
568
+ _retryRequests = /* @__PURE__ */ new Map();
559
569
  static MAX_RETRIES = 3;
560
570
  _lastRefusalWarnAt = Number.NEGATIVE_INFINITY;
561
571
  _lastUnackWarnAt = Number.NEGATIVE_INFINITY;
@@ -586,7 +596,8 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
586
596
  queue_full: 0,
587
597
  transport_refused: 0,
588
598
  shutdown_residue: 0,
589
- unacknowledged: 0
599
+ unacknowledged: 0,
600
+ quota_exceeded: 0
590
601
  };
591
602
  exportedSpans = 0;
592
603
  /**
@@ -755,14 +766,21 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
755
766
  if (residue > 0) {
756
767
  this._queue.length = 0;
757
768
  this._recordDropped("shutdown_residue", residue);
758
- warn(
759
- `shutdown() gave up with ${residue} span(s) (reason=shutdown_residue): ${queued} still queued and ${inFlight} in an export that shutdown() stopped. ` + (inFlight > 0 ? `The server may have received the ${inFlight} span(s) of the stopped export. ` : "") + `All ${residue} were not confirmed as delivered, and are counted as dropped. The ${timeoutMs} ms shutdown budget expired or the transport stopped accepting. Pass a larger timeout to shutdown(timeoutMs), or raise your container's termination grace period, to lose less.`
760
- );
769
+ if (this._quotaPaused()) {
770
+ warn(
771
+ `shutdown() gave up with ${residue} span(s) (reason=shutdown_residue): ${queued} still queued and ${inFlight} in an export that shutdown() stopped. The monthly event quota is used up and export is paused until the next probe, so these spans could not be sent. A longer shutdown timeout does not help. Upgrade the plan or wait for the quota to reset.`
772
+ );
773
+ } else {
774
+ warn(
775
+ `shutdown() gave up with ${residue} span(s) (reason=shutdown_residue): ${queued} still queued and ${inFlight} in an export that shutdown() stopped. ` + (inFlight > 0 ? `The server may have received the ${inFlight} span(s) of the stopped export. ` : "") + `All ${residue} were not confirmed as delivered, and are counted as dropped. The ${timeoutMs} ms shutdown budget expired or the transport stopped accepting. Pass a larger timeout to shutdown(timeoutMs), or raise your container's termination grace period, to lose less.`
776
+ );
777
+ }
761
778
  }
762
779
  for (const exporter of this._exporters) {
763
780
  await shutdownExporter(exporter, Math.max(0, shutdownDeadline - Date.now()));
764
781
  }
765
782
  this._retryCounts.clear();
783
+ this._retryRequests.clear();
766
784
  debug(
767
785
  `BatchSpanProcessor shutdown. Exported: ${this.exportedSpans}, Dropped: ${this.droppedSpans}, Failed: ${this.failedExports}`
768
786
  );
@@ -777,6 +795,19 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
777
795
  }
778
796
  _enqueue(span, exportAtBatchSize) {
779
797
  if (this._queue.length >= this._maxQueueSize) {
798
+ if (this._quotaPaused()) {
799
+ const oldest = this._queue.shift();
800
+ if (oldest !== void 0) this._forgetRetry(oldest.spanId);
801
+ this._recordDropped("quota_exceeded");
802
+ for (const exporter of this._exporters) {
803
+ try {
804
+ exporter.noteQuotaDrop?.(1);
805
+ } catch {
806
+ }
807
+ }
808
+ this._queue.push(span);
809
+ return;
810
+ }
780
811
  this._recordDropped("queue_full");
781
812
  if (this.droppedSpans === 1 || this.droppedSpans % 1e3 === 0) {
782
813
  warn(`Span queue full (${this._maxQueueSize}). ${this.droppedSpans} spans dropped so far.`);
@@ -788,6 +819,22 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
788
819
  void this._exportBatch();
789
820
  }
790
821
  }
822
+ /**
823
+ * True when every exporter that delivers is paused for the monthly quota (S-1). An exporter
824
+ * says so with `quotaPaused()`. A custom exporter has none: not paused.
825
+ */
826
+ _quotaPaused() {
827
+ const deciders = this._exporters.filter((e) => e.countsAsDelivery !== false);
828
+ if (deciders.length === 0) return false;
829
+ for (const exporter of deciders) {
830
+ try {
831
+ if (exporter.quotaPaused?.() !== true) return false;
832
+ } catch {
833
+ return false;
834
+ }
835
+ }
836
+ return true;
837
+ }
791
838
  /** A span that ended after the drain ended: counted, with one WARNING for the first. */
792
839
  _lateSpan() {
793
840
  this._recordDropped("shutdown_residue");
@@ -882,9 +929,11 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
882
929
  while (this._queue.length > 0 || this._flushing) {
883
930
  const remaining = deadline - Date.now();
884
931
  if (remaining <= 0) return finish(false);
932
+ if (!this._flushing && this._queue.length > 0 && this._quotaPaused()) return finish(false);
885
933
  if (!this._flushing && this._queue.length > 0) {
886
934
  const outcome = await raceDeadline(this._exportBatch(), remaining);
887
935
  if (outcome === DEADLINE) return finish(false);
936
+ if (outcome === 4 /* Paused */) await new Promise((r) => setTimeout(r, 20));
888
937
  } else {
889
938
  await new Promise((r) => setTimeout(r, 1));
890
939
  }
@@ -897,6 +946,9 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
897
946
  rejectedSpans: this.rejectedSpans,
898
947
  droppedSpans: this.droppedSpans,
899
948
  droppedSpansByReason: { ...this.droppedSpansByReason },
949
+ // Spans dropped because the monthly event quota is used up (S-1). The same number as
950
+ // `droppedSpansByReason.quota_exceeded`, for a reader that wants one key.
951
+ droppedQuota: this.droppedSpansByReason.quota_exceeded,
900
952
  failedExports: this.failedExports,
901
953
  maskErrors: this.maskErrors,
902
954
  queueSize: this._queue.length,
@@ -918,6 +970,12 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
918
970
  this.exportedSpans += n;
919
971
  return;
920
972
  }
973
+ const quota = Math.min(Math.max(ack.quotaDropped ?? 0, 0), n);
974
+ if (quota > 0) {
975
+ this._recordDropped("quota_exceeded", quota);
976
+ n -= quota;
977
+ if (n === 0) return;
978
+ }
921
979
  const rejected = Math.min(ack.rejected, n);
922
980
  const accepted = Math.min(ack.accepted, n - rejected);
923
981
  const unacknowledged = n - accepted - rejected;
@@ -934,13 +992,37 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
934
992
  }
935
993
  }
936
994
  }
937
- /** The requests in one export round, when every exporter that delivers states it. */
938
- _requestsPerRound() {
995
+ /** The one exporter that delivers, when there is exactly one. */
996
+ _soleDeliverer() {
939
997
  const delivering = this._exporters.filter((e) => e.countsAsDelivery !== false);
940
- if (delivering.length !== 1) return void 0;
941
- const n = delivering[0].attemptsPerExport;
998
+ return delivering.length === 1 ? delivering[0] : void 0;
999
+ }
1000
+ /** The most requests in one export round, when every exporter that delivers states it. */
1001
+ _requestsPerRound() {
1002
+ const n = this._soleDeliverer()?.attemptsPerExport;
942
1003
  return typeof n === "number" && Number.isFinite(n) && n > 0 ? n : void 0;
943
1004
  }
1005
+ /**
1006
+ * The HTTP requests that the failed round for `batch` really sent (issue #57). `undefined`
1007
+ * when the exporter that delivers does not state it, so that the WARNING keeps its "up to"
1008
+ * text. NaN when the exporter has no record of the round.
1009
+ */
1010
+ _requestsSent(batch) {
1011
+ const exporter = this._soleDeliverer();
1012
+ if (exporter === void 0 || typeof exporter.takeAttempts !== "function") return void 0;
1013
+ try {
1014
+ const n = exporter.takeAttempts(batch);
1015
+ return typeof n === "number" && Number.isFinite(n) && n >= 0 ? n : Number.NaN;
1016
+ } catch (e) {
1017
+ debug(`takeAttempts of ${exporter.name} failed: ${describeThrown(e)}`);
1018
+ return Number.NaN;
1019
+ }
1020
+ }
1021
+ /** End the retry tracking of one span (retry-map drain sites 1 and 2 of 3, and the queue drop). */
1022
+ _forgetRetry(spanId) {
1023
+ this._retryCounts.delete(spanId);
1024
+ this._retryRequests.delete(spanId);
1025
+ }
944
1026
  /**
945
1027
  * One export round.
946
1028
  *
@@ -952,6 +1034,7 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
952
1034
  async _exportBatch() {
953
1035
  if (this._flushing) return 3 /* Busy */;
954
1036
  if (this._queue.length === 0) return 0 /* Empty */;
1037
+ if (this._quotaPaused()) return 4 /* Paused */;
955
1038
  this._flushing = true;
956
1039
  let flight = null;
957
1040
  try {
@@ -1002,7 +1085,7 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
1002
1085
  this._countDelivered(batch.length - unserializable.size, ack);
1003
1086
  batchExported = true;
1004
1087
  for (const span of batch) {
1005
- this._retryCounts.delete(span.spanId);
1088
+ this._forgetRetry(span.spanId);
1006
1089
  }
1007
1090
  }
1008
1091
  } else {
@@ -1018,16 +1101,21 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
1018
1101
  if (unserializable.size > 0) this._recordDropped("unacknowledged", unserializable.size);
1019
1102
  if (!batchExported) {
1020
1103
  let dropped = 0;
1104
+ const sent = this._requestsSent(batch);
1105
+ const droppedRequests = [];
1021
1106
  const retryable = batch.filter((span) => {
1022
1107
  if (unserializable.has(span)) return false;
1023
1108
  const count = (this._retryCounts.get(span.spanId) ?? 0) + 1;
1109
+ const requests = sent === void 0 ? void 0 : (this._retryRequests.get(span.spanId) ?? 0) + sent;
1024
1110
  if (count > _BatchSpanProcessor.MAX_RETRIES) {
1025
- this._retryCounts.delete(span.spanId);
1111
+ this._forgetRetry(span.spanId);
1112
+ if (requests !== void 0) droppedRequests.push(requests);
1026
1113
  this._recordDropped("transport_refused");
1027
1114
  dropped++;
1028
1115
  return false;
1029
1116
  }
1030
1117
  this._retryCounts.set(span.spanId, count);
1118
+ if (requests !== void 0) this._retryRequests.set(span.spanId, requests);
1031
1119
  return true;
1032
1120
  });
1033
1121
  if (retryable.length > 0) {
@@ -1040,8 +1128,21 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
1040
1128
  this._lastRefusalWarnAt = now;
1041
1129
  const rounds = _BatchSpanProcessor.MAX_RETRIES + 1;
1042
1130
  const perRound = this._requestsPerRound();
1131
+ const stated = droppedRequests.length > 0 && droppedRequests.every((n) => Number.isFinite(n));
1132
+ let requestsText = "";
1133
+ if (stated) {
1134
+ let lo = droppedRequests[0];
1135
+ let hi = lo;
1136
+ for (const n of droppedRequests) {
1137
+ if (n < lo) lo = n;
1138
+ if (n > hi) hi = n;
1139
+ }
1140
+ requestsText = lo === hi ? ` (${hi} HTTP ${hi === 1 ? "request" : "requests"} sent)` : ` (${lo} to ${hi} HTTP requests sent)`;
1141
+ } else if (perRound !== void 0) {
1142
+ requestsText = ` (up to ${rounds * perRound} HTTP requests: ${perRound} in each round)`;
1143
+ }
1043
1144
  warn(
1044
- `${dropped} span(s) DISCARDED (reason=transport_refused) after ${rounds} failed export rounds each` + (perRound !== void 0 ? ` (up to ${rounds * perRound} HTTP requests: ${perRound} in each round)` : "") + ` \u2014 the endpoint is not accepting spans and the retry budget is spent. ${this.droppedSpansByReason.transport_refused} span(s) discarded this way so far in this process. This data is gone; check the apiKey and the endpoint.`
1145
+ `${dropped} span(s) DISCARDED (reason=transport_refused) after ${rounds} failed export rounds each` + requestsText + ` \u2014 the endpoint is not accepting spans and the retry budget is spent. ${this.droppedSpansByReason.transport_refused} span(s) discarded this way so far in this process. This data is gone; check the apiKey and the endpoint.`
1045
1146
  );
1046
1147
  }
1047
1148
  }
@@ -2304,7 +2405,111 @@ function markCancel(span, error) {
2304
2405
  }
2305
2406
 
2306
2407
  // src/version.ts
2307
- var SDK_VERSION = "0.9.0";
2408
+ var SDK_VERSION = "0.9.2";
2409
+
2410
+ // src/exporters/quota.ts
2411
+ var QUOTA_REASON = "monthly_quota_exceeded";
2412
+ var QUOTA_HEADER = "X-Risicare-Quota";
2413
+ var QUOTA_HEADER_VALUE = "exceeded";
2414
+ var DEFAULT_RETRY_AFTER_S = 300;
2415
+ var MIN_RETRY_AFTER_S = 1;
2416
+ var MAX_RETRY_AFTER_S = 3600;
2417
+ var QUOTA_WARN_WINDOW_MS = 36e5;
2418
+ var MAX_RESETS_AT_CHARS = 40;
2419
+ function asPositiveCount(v) {
2420
+ if (typeof v === "number") return Number.isFinite(v) && v > 0;
2421
+ if (typeof v === "string" && /^[0-9]+$/.test(v)) return Number(v) > 0;
2422
+ return false;
2423
+ }
2424
+ function boundedRetryAfter(value) {
2425
+ let n;
2426
+ if (typeof value === "number") n = value;
2427
+ else if (typeof value === "string" && value.trim() !== "") n = Number(value);
2428
+ else return DEFAULT_RETRY_AFTER_S;
2429
+ if (!Number.isFinite(n)) return DEFAULT_RETRY_AFTER_S;
2430
+ return Math.min(Math.max(n, MIN_RETRY_AFTER_S), MAX_RETRY_AFTER_S);
2431
+ }
2432
+ function boundedResetsAt(value) {
2433
+ if (typeof value !== "string" || value.length === 0) return null;
2434
+ const cut = value.slice(0, MAX_RESETS_AT_CHARS);
2435
+ return /^[ -~]*$/.test(cut) ? cut : null;
2436
+ }
2437
+ function headerSaysExceeded(headers) {
2438
+ try {
2439
+ const value = headers?.get?.(QUOTA_HEADER);
2440
+ return typeof value === "string" && value.trim().toLowerCase() === QUOTA_HEADER_VALUE;
2441
+ } catch {
2442
+ return false;
2443
+ }
2444
+ }
2445
+ function parseJsonDiscard(payload, headers) {
2446
+ const body = payload !== null && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
2447
+ const stored = (asPositiveCount(body.accepted) || asPositiveCount(body.spansAccepted)) === true;
2448
+ if (body.reason === QUOTA_REASON || headerSaysExceeded(headers) && !stored) {
2449
+ return {
2450
+ retryAfterS: boundedRetryAfter(body.retryAfterSeconds),
2451
+ resetsAt: boundedResetsAt(body.resetsAt)
2452
+ };
2453
+ }
2454
+ return null;
2455
+ }
2456
+ var EPISODE_END_ACCEPTS = 3;
2457
+ var QuotaPause = class {
2458
+ constructor(now = () => performance.now()) {
2459
+ this.now = now;
2460
+ }
2461
+ _until = -Infinity;
2462
+ _inEpisode = false;
2463
+ _accepts = 0;
2464
+ _lastWarn = -Infinity;
2465
+ _lastInfo = -Infinity;
2466
+ /**
2467
+ * Spans dropped since the last WARNING: the full queue's (`addDrops`) and the batches that a
2468
+ * probe lost while the WARNING was held back. The WARNING carries the number.
2469
+ */
2470
+ _drops = 0;
2471
+ addDrops(count) {
2472
+ this._drops += count;
2473
+ }
2474
+ paused() {
2475
+ return this.now() < this._until;
2476
+ }
2477
+ remainingS() {
2478
+ return Math.max(0, (this._until - this.now()) / 1e3);
2479
+ }
2480
+ enter(discard, where, dropped) {
2481
+ const t = this.now();
2482
+ this._until = t + discard.retryAfterS * 1e3;
2483
+ this._inEpisode = true;
2484
+ this._accepts = 0;
2485
+ if (t - this._lastWarn >= QUOTA_WARN_WINDOW_MS) {
2486
+ this._lastWarn = t;
2487
+ const since = this._drops;
2488
+ this._drops = 0;
2489
+ warn(
2490
+ `Risicare: the monthly event quota is used up (monthly_quota_exceeded). ${where} discarded ${dropped} span(s) and will discard new ones until the quota resets (resetsAt=${discard.resetsAt ?? "unknown"}) or the plan changes. The SDK pauses export and sends one batch again in ${Math.round(discard.retryAfterS)} s. Spans that end in the meantime wait in the queue. When it is full the oldest spans are dropped (the most recent are kept) and counted as quota_exceeded in droppedSpansByReason; a batch that is discarded again is dropped and counted the same way. This is not an error and the SDK does not retry the batch. At most one such WARNING an hour.` + (since > 0 ? ` Spans dropped for the quota since the last WARNING: ${since}.` : "")
2491
+ );
2492
+ } else {
2493
+ this._drops += dropped;
2494
+ debug(`Quota discard again: ${dropped} span(s); paused for ${Math.round(discard.retryAfterS)} s`);
2495
+ }
2496
+ }
2497
+ accepted(where) {
2498
+ if (!this._inEpisode) return;
2499
+ this._accepts++;
2500
+ if (this._accepts < EPISODE_END_ACCEPTS) return;
2501
+ this._inEpisode = false;
2502
+ this._accepts = 0;
2503
+ this._until = -Infinity;
2504
+ const t = this.now();
2505
+ if (t - this._lastInfo >= QUOTA_WARN_WINDOW_MS) {
2506
+ this._lastInfo = t;
2507
+ info(`Risicare: ${where} accepts spans again; the export pause for the quota has ended.`);
2508
+ } else {
2509
+ debug("Quota pause ended (INFO already written this hour)");
2510
+ }
2511
+ }
2512
+ };
2308
2513
 
2309
2514
  // src/exporters/http.ts
2310
2515
  var CAPACITY_REFUSAL_STATUSES = /* @__PURE__ */ new Set([429, 503]);
@@ -2345,8 +2550,23 @@ var HttpExporter = class {
2345
2550
  _calls = /* @__PURE__ */ new Map();
2346
2551
  /** The ack of each finished call, by its batch. Read once by `takeAck(spans)`. */
2347
2552
  _acks = /* @__PURE__ */ new WeakMap();
2553
+ /** The requests that each finished call sent, by its batch. Read once by `takeAttempts(spans)`. */
2554
+ _requests = /* @__PURE__ */ new WeakMap();
2555
+ /** The batch processor dropped span(s) from a full queue in the quota pause (S-1). */
2556
+ noteQuotaDrop(count = 1) {
2557
+ this._quota.addDrops(count);
2558
+ }
2559
+ /** True while the exporter is paused for the monthly event quota (S-1). */
2560
+ quotaPaused() {
2561
+ return this._quota.paused();
2562
+ }
2348
2563
  /** The spans of each finished call that could not be serialized, by its batch. */
2349
2564
  _unserializable = /* @__PURE__ */ new WeakMap();
2565
+ /**
2566
+ * S-1: the paused state after a monthly-quota discard (see `quota.ts`). A discard is not a
2567
+ * failure: it does not touch the circuit breaker.
2568
+ */
2569
+ _quota = new QuotaPause();
2350
2570
  _circuitOpenUntil = 0;
2351
2571
  _circuitBreakerThreshold = 5;
2352
2572
  _circuitBreakerCooldownMs = 6e4;
@@ -2383,6 +2603,18 @@ var HttpExporter = class {
2383
2603
  get attemptsPerExport() {
2384
2604
  return this._maxRetries;
2385
2605
  }
2606
+ /**
2607
+ * Returns the number of HTTP requests that the `export()` call for `spans` sent, and clears
2608
+ * it. This is the number that was sent, not the most that the call may send
2609
+ * (`attemptsPerExport`): a 401 or 403 stops the loop after one request, and an open circuit
2610
+ * breaker sends none. Returns `null` when no call is on record for `spans`. The answer is
2611
+ * kept per batch, as `takeAck` keeps the ack.
2612
+ */
2613
+ takeAttempts(spans) {
2614
+ const n = this._requests.get(spans) ?? null;
2615
+ this._requests.delete(spans);
2616
+ return n;
2617
+ }
2386
2618
  /**
2387
2619
  * Returns the counts of the ack that the `export()` call for `spans` received, and clears
2388
2620
  * them. The answer is kept per batch, not on the instance: two processors that share this
@@ -2427,17 +2659,26 @@ var HttpExporter = class {
2427
2659
  misroute: null,
2428
2660
  noRetry: false,
2429
2661
  status: null,
2430
- error: null
2662
+ error: null,
2663
+ attempts: 0
2431
2664
  };
2432
2665
  this._calls.set(spans, call);
2433
2666
  try {
2434
2667
  return await this._export(spans, call);
2435
2668
  } finally {
2436
2669
  this._calls.delete(spans);
2670
+ this._requests.set(spans, this._endpointHasCredentials ? 0 : call.attempts);
2437
2671
  }
2438
2672
  }
2439
2673
  async _export(spans, call) {
2440
2674
  const cancelled = call.cancel.signal;
2675
+ if (this._quota.paused()) {
2676
+ debug(
2677
+ `Export skipped: monthly quota pause, ${Math.round(this._quota.remainingS())} s left; ${spans.length} span(s) dropped`
2678
+ );
2679
+ this._acks.set(spans, { accepted: 0, rejected: 0, quotaDropped: spans.length });
2680
+ return "success" /* SUCCESS */;
2681
+ }
2441
2682
  const parts = [];
2442
2683
  const bad = [];
2443
2684
  let errorClass = "";
@@ -2466,14 +2707,13 @@ var HttpExporter = class {
2466
2707
  isHalfOpen = true;
2467
2708
  }
2468
2709
  const maxAttempts = isHalfOpen ? 1 : this._maxRetries;
2469
- let attempts = 0;
2470
2710
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
2471
2711
  call.refusalAfterMs = null;
2472
2712
  call.misroute = null;
2473
2713
  call.noRetry = false;
2474
2714
  call.status = null;
2475
2715
  call.error = null;
2476
- attempts++;
2716
+ call.attempts++;
2477
2717
  const result = await this._sendRequest(payload, parts.length, call, spans);
2478
2718
  if (cancelled.aborted) {
2479
2719
  this._acks.delete(spans);
@@ -2495,7 +2735,7 @@ var HttpExporter = class {
2495
2735
  }
2496
2736
  if (call.refusalAfterMs !== null) {
2497
2737
  warn(
2498
- `Risicare: the ingest endpoint refused this batch for capacity (HTTP 429/503) after ${attempts} attempt(s). This is a healthy server shedding load, not an outage. This export of the batch failed; the circuit breaker does not count it. Reduce batch size or export rate if it persists.`
2738
+ `Risicare: the ingest endpoint refused this batch for capacity (HTTP 429/503) after ${call.attempts} attempt(s). This is a healthy server shedding load, not an outage. This export of the batch failed; the circuit breaker does not count it. Reduce batch size or export rate if it persists.`
2499
2739
  );
2500
2740
  return "failure" /* FAILURE */;
2501
2741
  }
@@ -2646,6 +2886,11 @@ var HttpExporter = class {
2646
2886
  `HTTP ${response.status} and a body that is not a Risicare ack (content-type: ${response.headers?.get?.("Content-Type") || "none"})`
2647
2887
  );
2648
2888
  }
2889
+ if (ack.quota !== void 0) {
2890
+ this._quota.enter(ack.quota, `The ingest endpoint ${this._safeEndpoint}`, spansSent);
2891
+ } else if (ack.result === "success" /* SUCCESS */) {
2892
+ this._quota.accepted(`the ingest endpoint ${this._safeEndpoint}`);
2893
+ }
2649
2894
  if (ack.result === "success" /* SUCCESS */) this._acks.set(spans, ack.counts);
2650
2895
  if (ack.final) call.noRetry = true;
2651
2896
  return ack.result;
@@ -2712,7 +2957,16 @@ async function checkAck(response, spansSent, scrub) {
2712
2957
  try {
2713
2958
  payload = await response.json();
2714
2959
  } catch {
2715
- return null;
2960
+ payload = void 0;
2961
+ }
2962
+ const discard = parseJsonDiscard(payload, response.headers);
2963
+ if (discard !== null) {
2964
+ return {
2965
+ result: "success" /* SUCCESS */,
2966
+ counts: { accepted: 0, rejected: 0, quotaDropped: spansSent },
2967
+ final: false,
2968
+ quota: discard
2969
+ };
2716
2970
  }
2717
2971
  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
2718
2972
  return null;
@@ -4353,8 +4607,10 @@ function getMetrics() {
4353
4607
  queue_full: 0,
4354
4608
  transport_refused: 0,
4355
4609
  shutdown_residue: 0,
4356
- unacknowledged: 0
4610
+ unacknowledged: 0,
4611
+ quota_exceeded: 0
4357
4612
  },
4613
+ droppedQuota: 0,
4358
4614
  failedExports: 0,
4359
4615
  queueSize: 0,
4360
4616
  queueCapacity: 0,