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.cjs CHANGED
@@ -172,6 +172,10 @@ function warn(msg) {
172
172
  process.stderr.write(`[risicare] WARNING: ${msg}
173
173
  `);
174
174
  }
175
+ function info(msg) {
176
+ process.stderr.write(`[risicare] INFO: ${msg}
177
+ `);
178
+ }
175
179
 
176
180
  // src/utils/text.ts
177
181
  function cutCodePoints(text, max) {
@@ -642,6 +646,12 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
642
646
  _beforeExitHandler = null;
643
647
  // Retry tracking for failed batches (Audit #5)
644
648
  _retryCounts = /* @__PURE__ */ new Map();
649
+ /**
650
+ * The HTTP requests that the failed rounds of each re-queued span sent, by span id (issue
651
+ * #57). It has the same life as `_retryCounts`: `_forgetRetry` ends both. NaN = a round for
652
+ * which the exporter did not say. Empty for an exporter that does not state it.
653
+ */
654
+ _retryRequests = /* @__PURE__ */ new Map();
645
655
  static MAX_RETRIES = 3;
646
656
  _lastRefusalWarnAt = Number.NEGATIVE_INFINITY;
647
657
  _lastUnackWarnAt = Number.NEGATIVE_INFINITY;
@@ -672,7 +682,8 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
672
682
  queue_full: 0,
673
683
  transport_refused: 0,
674
684
  shutdown_residue: 0,
675
- unacknowledged: 0
685
+ unacknowledged: 0,
686
+ quota_exceeded: 0
676
687
  };
677
688
  exportedSpans = 0;
678
689
  /**
@@ -841,14 +852,21 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
841
852
  if (residue > 0) {
842
853
  this._queue.length = 0;
843
854
  this._recordDropped("shutdown_residue", residue);
844
- warn(
845
- `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.`
846
- );
855
+ if (this._quotaPaused()) {
856
+ warn(
857
+ `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.`
858
+ );
859
+ } else {
860
+ warn(
861
+ `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.`
862
+ );
863
+ }
847
864
  }
848
865
  for (const exporter of this._exporters) {
849
866
  await shutdownExporter(exporter, Math.max(0, shutdownDeadline - Date.now()));
850
867
  }
851
868
  this._retryCounts.clear();
869
+ this._retryRequests.clear();
852
870
  debug(
853
871
  `BatchSpanProcessor shutdown. Exported: ${this.exportedSpans}, Dropped: ${this.droppedSpans}, Failed: ${this.failedExports}`
854
872
  );
@@ -863,6 +881,19 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
863
881
  }
864
882
  _enqueue(span, exportAtBatchSize) {
865
883
  if (this._queue.length >= this._maxQueueSize) {
884
+ if (this._quotaPaused()) {
885
+ const oldest = this._queue.shift();
886
+ if (oldest !== void 0) this._forgetRetry(oldest.spanId);
887
+ this._recordDropped("quota_exceeded");
888
+ for (const exporter of this._exporters) {
889
+ try {
890
+ exporter.noteQuotaDrop?.(1);
891
+ } catch {
892
+ }
893
+ }
894
+ this._queue.push(span);
895
+ return;
896
+ }
866
897
  this._recordDropped("queue_full");
867
898
  if (this.droppedSpans === 1 || this.droppedSpans % 1e3 === 0) {
868
899
  warn(`Span queue full (${this._maxQueueSize}). ${this.droppedSpans} spans dropped so far.`);
@@ -874,6 +905,22 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
874
905
  void this._exportBatch();
875
906
  }
876
907
  }
908
+ /**
909
+ * True when every exporter that delivers is paused for the monthly quota (S-1). An exporter
910
+ * says so with `quotaPaused()`. A custom exporter has none: not paused.
911
+ */
912
+ _quotaPaused() {
913
+ const deciders = this._exporters.filter((e) => e.countsAsDelivery !== false);
914
+ if (deciders.length === 0) return false;
915
+ for (const exporter of deciders) {
916
+ try {
917
+ if (exporter.quotaPaused?.() !== true) return false;
918
+ } catch {
919
+ return false;
920
+ }
921
+ }
922
+ return true;
923
+ }
877
924
  /** A span that ended after the drain ended: counted, with one WARNING for the first. */
878
925
  _lateSpan() {
879
926
  this._recordDropped("shutdown_residue");
@@ -968,9 +1015,11 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
968
1015
  while (this._queue.length > 0 || this._flushing) {
969
1016
  const remaining = deadline - Date.now();
970
1017
  if (remaining <= 0) return finish(false);
1018
+ if (!this._flushing && this._queue.length > 0 && this._quotaPaused()) return finish(false);
971
1019
  if (!this._flushing && this._queue.length > 0) {
972
1020
  const outcome = await raceDeadline(this._exportBatch(), remaining);
973
1021
  if (outcome === DEADLINE) return finish(false);
1022
+ if (outcome === 4 /* Paused */) await new Promise((r) => setTimeout(r, 20));
974
1023
  } else {
975
1024
  await new Promise((r) => setTimeout(r, 1));
976
1025
  }
@@ -983,6 +1032,9 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
983
1032
  rejectedSpans: this.rejectedSpans,
984
1033
  droppedSpans: this.droppedSpans,
985
1034
  droppedSpansByReason: { ...this.droppedSpansByReason },
1035
+ // Spans dropped because the monthly event quota is used up (S-1). The same number as
1036
+ // `droppedSpansByReason.quota_exceeded`, for a reader that wants one key.
1037
+ droppedQuota: this.droppedSpansByReason.quota_exceeded,
986
1038
  failedExports: this.failedExports,
987
1039
  maskErrors: this.maskErrors,
988
1040
  queueSize: this._queue.length,
@@ -1004,6 +1056,12 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
1004
1056
  this.exportedSpans += n;
1005
1057
  return;
1006
1058
  }
1059
+ const quota = Math.min(Math.max(ack.quotaDropped ?? 0, 0), n);
1060
+ if (quota > 0) {
1061
+ this._recordDropped("quota_exceeded", quota);
1062
+ n -= quota;
1063
+ if (n === 0) return;
1064
+ }
1007
1065
  const rejected = Math.min(ack.rejected, n);
1008
1066
  const accepted = Math.min(ack.accepted, n - rejected);
1009
1067
  const unacknowledged = n - accepted - rejected;
@@ -1020,13 +1078,37 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
1020
1078
  }
1021
1079
  }
1022
1080
  }
1023
- /** The requests in one export round, when every exporter that delivers states it. */
1024
- _requestsPerRound() {
1081
+ /** The one exporter that delivers, when there is exactly one. */
1082
+ _soleDeliverer() {
1025
1083
  const delivering = this._exporters.filter((e) => e.countsAsDelivery !== false);
1026
- if (delivering.length !== 1) return void 0;
1027
- const n = delivering[0].attemptsPerExport;
1084
+ return delivering.length === 1 ? delivering[0] : void 0;
1085
+ }
1086
+ /** The most requests in one export round, when every exporter that delivers states it. */
1087
+ _requestsPerRound() {
1088
+ const n = this._soleDeliverer()?.attemptsPerExport;
1028
1089
  return typeof n === "number" && Number.isFinite(n) && n > 0 ? n : void 0;
1029
1090
  }
1091
+ /**
1092
+ * The HTTP requests that the failed round for `batch` really sent (issue #57). `undefined`
1093
+ * when the exporter that delivers does not state it, so that the WARNING keeps its "up to"
1094
+ * text. NaN when the exporter has no record of the round.
1095
+ */
1096
+ _requestsSent(batch) {
1097
+ const exporter = this._soleDeliverer();
1098
+ if (exporter === void 0 || typeof exporter.takeAttempts !== "function") return void 0;
1099
+ try {
1100
+ const n = exporter.takeAttempts(batch);
1101
+ return typeof n === "number" && Number.isFinite(n) && n >= 0 ? n : Number.NaN;
1102
+ } catch (e) {
1103
+ debug(`takeAttempts of ${exporter.name} failed: ${describeThrown(e)}`);
1104
+ return Number.NaN;
1105
+ }
1106
+ }
1107
+ /** End the retry tracking of one span (retry-map drain sites 1 and 2 of 3, and the queue drop). */
1108
+ _forgetRetry(spanId) {
1109
+ this._retryCounts.delete(spanId);
1110
+ this._retryRequests.delete(spanId);
1111
+ }
1030
1112
  /**
1031
1113
  * One export round.
1032
1114
  *
@@ -1038,6 +1120,7 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
1038
1120
  async _exportBatch() {
1039
1121
  if (this._flushing) return 3 /* Busy */;
1040
1122
  if (this._queue.length === 0) return 0 /* Empty */;
1123
+ if (this._quotaPaused()) return 4 /* Paused */;
1041
1124
  this._flushing = true;
1042
1125
  let flight = null;
1043
1126
  try {
@@ -1088,7 +1171,7 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
1088
1171
  this._countDelivered(batch.length - unserializable.size, ack);
1089
1172
  batchExported = true;
1090
1173
  for (const span of batch) {
1091
- this._retryCounts.delete(span.spanId);
1174
+ this._forgetRetry(span.spanId);
1092
1175
  }
1093
1176
  }
1094
1177
  } else {
@@ -1104,16 +1187,21 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
1104
1187
  if (unserializable.size > 0) this._recordDropped("unacknowledged", unserializable.size);
1105
1188
  if (!batchExported) {
1106
1189
  let dropped = 0;
1190
+ const sent = this._requestsSent(batch);
1191
+ const droppedRequests = [];
1107
1192
  const retryable = batch.filter((span) => {
1108
1193
  if (unserializable.has(span)) return false;
1109
1194
  const count = (this._retryCounts.get(span.spanId) ?? 0) + 1;
1195
+ const requests = sent === void 0 ? void 0 : (this._retryRequests.get(span.spanId) ?? 0) + sent;
1110
1196
  if (count > _BatchSpanProcessor.MAX_RETRIES) {
1111
- this._retryCounts.delete(span.spanId);
1197
+ this._forgetRetry(span.spanId);
1198
+ if (requests !== void 0) droppedRequests.push(requests);
1112
1199
  this._recordDropped("transport_refused");
1113
1200
  dropped++;
1114
1201
  return false;
1115
1202
  }
1116
1203
  this._retryCounts.set(span.spanId, count);
1204
+ if (requests !== void 0) this._retryRequests.set(span.spanId, requests);
1117
1205
  return true;
1118
1206
  });
1119
1207
  if (retryable.length > 0) {
@@ -1126,8 +1214,21 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
1126
1214
  this._lastRefusalWarnAt = now;
1127
1215
  const rounds = _BatchSpanProcessor.MAX_RETRIES + 1;
1128
1216
  const perRound = this._requestsPerRound();
1217
+ const stated = droppedRequests.length > 0 && droppedRequests.every((n) => Number.isFinite(n));
1218
+ let requestsText = "";
1219
+ if (stated) {
1220
+ let lo = droppedRequests[0];
1221
+ let hi = lo;
1222
+ for (const n of droppedRequests) {
1223
+ if (n < lo) lo = n;
1224
+ if (n > hi) hi = n;
1225
+ }
1226
+ requestsText = lo === hi ? ` (${hi} HTTP ${hi === 1 ? "request" : "requests"} sent)` : ` (${lo} to ${hi} HTTP requests sent)`;
1227
+ } else if (perRound !== void 0) {
1228
+ requestsText = ` (up to ${rounds * perRound} HTTP requests: ${perRound} in each round)`;
1229
+ }
1129
1230
  warn(
1130
- `${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.`
1231
+ `${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.`
1131
1232
  );
1132
1233
  }
1133
1234
  }
@@ -2390,7 +2491,111 @@ function markCancel(span, error) {
2390
2491
  }
2391
2492
 
2392
2493
  // src/version.ts
2393
- var SDK_VERSION = "0.9.0";
2494
+ var SDK_VERSION = "0.9.2";
2495
+
2496
+ // src/exporters/quota.ts
2497
+ var QUOTA_REASON = "monthly_quota_exceeded";
2498
+ var QUOTA_HEADER = "X-Risicare-Quota";
2499
+ var QUOTA_HEADER_VALUE = "exceeded";
2500
+ var DEFAULT_RETRY_AFTER_S = 300;
2501
+ var MIN_RETRY_AFTER_S = 1;
2502
+ var MAX_RETRY_AFTER_S = 3600;
2503
+ var QUOTA_WARN_WINDOW_MS = 36e5;
2504
+ var MAX_RESETS_AT_CHARS = 40;
2505
+ function asPositiveCount(v) {
2506
+ if (typeof v === "number") return Number.isFinite(v) && v > 0;
2507
+ if (typeof v === "string" && /^[0-9]+$/.test(v)) return Number(v) > 0;
2508
+ return false;
2509
+ }
2510
+ function boundedRetryAfter(value) {
2511
+ let n;
2512
+ if (typeof value === "number") n = value;
2513
+ else if (typeof value === "string" && value.trim() !== "") n = Number(value);
2514
+ else return DEFAULT_RETRY_AFTER_S;
2515
+ if (!Number.isFinite(n)) return DEFAULT_RETRY_AFTER_S;
2516
+ return Math.min(Math.max(n, MIN_RETRY_AFTER_S), MAX_RETRY_AFTER_S);
2517
+ }
2518
+ function boundedResetsAt(value) {
2519
+ if (typeof value !== "string" || value.length === 0) return null;
2520
+ const cut = value.slice(0, MAX_RESETS_AT_CHARS);
2521
+ return /^[ -~]*$/.test(cut) ? cut : null;
2522
+ }
2523
+ function headerSaysExceeded(headers) {
2524
+ try {
2525
+ const value = headers?.get?.(QUOTA_HEADER);
2526
+ return typeof value === "string" && value.trim().toLowerCase() === QUOTA_HEADER_VALUE;
2527
+ } catch {
2528
+ return false;
2529
+ }
2530
+ }
2531
+ function parseJsonDiscard(payload, headers) {
2532
+ const body = payload !== null && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
2533
+ const stored = (asPositiveCount(body.accepted) || asPositiveCount(body.spansAccepted)) === true;
2534
+ if (body.reason === QUOTA_REASON || headerSaysExceeded(headers) && !stored) {
2535
+ return {
2536
+ retryAfterS: boundedRetryAfter(body.retryAfterSeconds),
2537
+ resetsAt: boundedResetsAt(body.resetsAt)
2538
+ };
2539
+ }
2540
+ return null;
2541
+ }
2542
+ var EPISODE_END_ACCEPTS = 3;
2543
+ var QuotaPause = class {
2544
+ constructor(now = () => performance.now()) {
2545
+ this.now = now;
2546
+ }
2547
+ _until = -Infinity;
2548
+ _inEpisode = false;
2549
+ _accepts = 0;
2550
+ _lastWarn = -Infinity;
2551
+ _lastInfo = -Infinity;
2552
+ /**
2553
+ * Spans dropped since the last WARNING: the full queue's (`addDrops`) and the batches that a
2554
+ * probe lost while the WARNING was held back. The WARNING carries the number.
2555
+ */
2556
+ _drops = 0;
2557
+ addDrops(count) {
2558
+ this._drops += count;
2559
+ }
2560
+ paused() {
2561
+ return this.now() < this._until;
2562
+ }
2563
+ remainingS() {
2564
+ return Math.max(0, (this._until - this.now()) / 1e3);
2565
+ }
2566
+ enter(discard, where, dropped) {
2567
+ const t = this.now();
2568
+ this._until = t + discard.retryAfterS * 1e3;
2569
+ this._inEpisode = true;
2570
+ this._accepts = 0;
2571
+ if (t - this._lastWarn >= QUOTA_WARN_WINDOW_MS) {
2572
+ this._lastWarn = t;
2573
+ const since = this._drops;
2574
+ this._drops = 0;
2575
+ warn(
2576
+ `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}.` : "")
2577
+ );
2578
+ } else {
2579
+ this._drops += dropped;
2580
+ debug(`Quota discard again: ${dropped} span(s); paused for ${Math.round(discard.retryAfterS)} s`);
2581
+ }
2582
+ }
2583
+ accepted(where) {
2584
+ if (!this._inEpisode) return;
2585
+ this._accepts++;
2586
+ if (this._accepts < EPISODE_END_ACCEPTS) return;
2587
+ this._inEpisode = false;
2588
+ this._accepts = 0;
2589
+ this._until = -Infinity;
2590
+ const t = this.now();
2591
+ if (t - this._lastInfo >= QUOTA_WARN_WINDOW_MS) {
2592
+ this._lastInfo = t;
2593
+ info(`Risicare: ${where} accepts spans again; the export pause for the quota has ended.`);
2594
+ } else {
2595
+ debug("Quota pause ended (INFO already written this hour)");
2596
+ }
2597
+ }
2598
+ };
2394
2599
 
2395
2600
  // src/exporters/http.ts
2396
2601
  var CAPACITY_REFUSAL_STATUSES = /* @__PURE__ */ new Set([429, 503]);
@@ -2431,8 +2636,23 @@ var HttpExporter = class {
2431
2636
  _calls = /* @__PURE__ */ new Map();
2432
2637
  /** The ack of each finished call, by its batch. Read once by `takeAck(spans)`. */
2433
2638
  _acks = /* @__PURE__ */ new WeakMap();
2639
+ /** The requests that each finished call sent, by its batch. Read once by `takeAttempts(spans)`. */
2640
+ _requests = /* @__PURE__ */ new WeakMap();
2641
+ /** The batch processor dropped span(s) from a full queue in the quota pause (S-1). */
2642
+ noteQuotaDrop(count = 1) {
2643
+ this._quota.addDrops(count);
2644
+ }
2645
+ /** True while the exporter is paused for the monthly event quota (S-1). */
2646
+ quotaPaused() {
2647
+ return this._quota.paused();
2648
+ }
2434
2649
  /** The spans of each finished call that could not be serialized, by its batch. */
2435
2650
  _unserializable = /* @__PURE__ */ new WeakMap();
2651
+ /**
2652
+ * S-1: the paused state after a monthly-quota discard (see `quota.ts`). A discard is not a
2653
+ * failure: it does not touch the circuit breaker.
2654
+ */
2655
+ _quota = new QuotaPause();
2436
2656
  _circuitOpenUntil = 0;
2437
2657
  _circuitBreakerThreshold = 5;
2438
2658
  _circuitBreakerCooldownMs = 6e4;
@@ -2469,6 +2689,18 @@ var HttpExporter = class {
2469
2689
  get attemptsPerExport() {
2470
2690
  return this._maxRetries;
2471
2691
  }
2692
+ /**
2693
+ * Returns the number of HTTP requests that the `export()` call for `spans` sent, and clears
2694
+ * it. This is the number that was sent, not the most that the call may send
2695
+ * (`attemptsPerExport`): a 401 or 403 stops the loop after one request, and an open circuit
2696
+ * breaker sends none. Returns `null` when no call is on record for `spans`. The answer is
2697
+ * kept per batch, as `takeAck` keeps the ack.
2698
+ */
2699
+ takeAttempts(spans) {
2700
+ const n = this._requests.get(spans) ?? null;
2701
+ this._requests.delete(spans);
2702
+ return n;
2703
+ }
2472
2704
  /**
2473
2705
  * Returns the counts of the ack that the `export()` call for `spans` received, and clears
2474
2706
  * them. The answer is kept per batch, not on the instance: two processors that share this
@@ -2513,17 +2745,26 @@ var HttpExporter = class {
2513
2745
  misroute: null,
2514
2746
  noRetry: false,
2515
2747
  status: null,
2516
- error: null
2748
+ error: null,
2749
+ attempts: 0
2517
2750
  };
2518
2751
  this._calls.set(spans, call);
2519
2752
  try {
2520
2753
  return await this._export(spans, call);
2521
2754
  } finally {
2522
2755
  this._calls.delete(spans);
2756
+ this._requests.set(spans, this._endpointHasCredentials ? 0 : call.attempts);
2523
2757
  }
2524
2758
  }
2525
2759
  async _export(spans, call) {
2526
2760
  const cancelled = call.cancel.signal;
2761
+ if (this._quota.paused()) {
2762
+ debug(
2763
+ `Export skipped: monthly quota pause, ${Math.round(this._quota.remainingS())} s left; ${spans.length} span(s) dropped`
2764
+ );
2765
+ this._acks.set(spans, { accepted: 0, rejected: 0, quotaDropped: spans.length });
2766
+ return "success" /* SUCCESS */;
2767
+ }
2527
2768
  const parts = [];
2528
2769
  const bad = [];
2529
2770
  let errorClass = "";
@@ -2552,14 +2793,13 @@ var HttpExporter = class {
2552
2793
  isHalfOpen = true;
2553
2794
  }
2554
2795
  const maxAttempts = isHalfOpen ? 1 : this._maxRetries;
2555
- let attempts = 0;
2556
2796
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
2557
2797
  call.refusalAfterMs = null;
2558
2798
  call.misroute = null;
2559
2799
  call.noRetry = false;
2560
2800
  call.status = null;
2561
2801
  call.error = null;
2562
- attempts++;
2802
+ call.attempts++;
2563
2803
  const result = await this._sendRequest(payload, parts.length, call, spans);
2564
2804
  if (cancelled.aborted) {
2565
2805
  this._acks.delete(spans);
@@ -2581,7 +2821,7 @@ var HttpExporter = class {
2581
2821
  }
2582
2822
  if (call.refusalAfterMs !== null) {
2583
2823
  warn(
2584
- `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.`
2824
+ `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.`
2585
2825
  );
2586
2826
  return "failure" /* FAILURE */;
2587
2827
  }
@@ -2732,6 +2972,11 @@ var HttpExporter = class {
2732
2972
  `HTTP ${response.status} and a body that is not a Risicare ack (content-type: ${response.headers?.get?.("Content-Type") || "none"})`
2733
2973
  );
2734
2974
  }
2975
+ if (ack.quota !== void 0) {
2976
+ this._quota.enter(ack.quota, `The ingest endpoint ${this._safeEndpoint}`, spansSent);
2977
+ } else if (ack.result === "success" /* SUCCESS */) {
2978
+ this._quota.accepted(`the ingest endpoint ${this._safeEndpoint}`);
2979
+ }
2735
2980
  if (ack.result === "success" /* SUCCESS */) this._acks.set(spans, ack.counts);
2736
2981
  if (ack.final) call.noRetry = true;
2737
2982
  return ack.result;
@@ -2798,7 +3043,16 @@ async function checkAck(response, spansSent, scrub) {
2798
3043
  try {
2799
3044
  payload = await response.json();
2800
3045
  } catch {
2801
- return null;
3046
+ payload = void 0;
3047
+ }
3048
+ const discard = parseJsonDiscard(payload, response.headers);
3049
+ if (discard !== null) {
3050
+ return {
3051
+ result: "success" /* SUCCESS */,
3052
+ counts: { accepted: 0, rejected: 0, quotaDropped: spansSent },
3053
+ final: false,
3054
+ quota: discard
3055
+ };
2802
3056
  }
2803
3057
  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
2804
3058
  return null;
@@ -4439,8 +4693,10 @@ function getMetrics() {
4439
4693
  queue_full: 0,
4440
4694
  transport_refused: 0,
4441
4695
  shutdown_residue: 0,
4442
- unacknowledged: 0
4696
+ unacknowledged: 0,
4697
+ quota_exceeded: 0
4443
4698
  },
4699
+ droppedQuota: 0,
4444
4700
  failedExports: 0,
4445
4701
  queueSize: 0,
4446
4702
  queueCapacity: 0,