risicare 0.9.2 → 0.11.0

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 (73) hide show
  1. package/CHANGELOG.md +254 -0
  2. package/README.md +194 -58
  3. package/dist/frameworks/instructor.cjs +383 -117
  4. package/dist/frameworks/instructor.cjs.map +1 -1
  5. package/dist/frameworks/instructor.js +383 -117
  6. package/dist/frameworks/instructor.js.map +1 -1
  7. package/dist/frameworks/langchain.cjs +396 -130
  8. package/dist/frameworks/langchain.cjs.map +1 -1
  9. package/dist/frameworks/langchain.js +396 -130
  10. package/dist/frameworks/langchain.js.map +1 -1
  11. package/dist/frameworks/langgraph.cjs +396 -130
  12. package/dist/frameworks/langgraph.cjs.map +1 -1
  13. package/dist/frameworks/langgraph.js +396 -130
  14. package/dist/frameworks/langgraph.js.map +1 -1
  15. package/dist/frameworks/llamaindex.cjs +396 -130
  16. package/dist/frameworks/llamaindex.cjs.map +1 -1
  17. package/dist/frameworks/llamaindex.js +396 -130
  18. package/dist/frameworks/llamaindex.js.map +1 -1
  19. package/dist/index.cjs +1136 -240
  20. package/dist/index.cjs.map +1 -1
  21. package/dist/index.d.cts +151 -26
  22. package/dist/index.d.ts +151 -26
  23. package/dist/index.js +1132 -240
  24. package/dist/index.js.map +1 -1
  25. package/dist/providers/anthropic/index.cjs +467 -137
  26. package/dist/providers/anthropic/index.cjs.map +1 -1
  27. package/dist/providers/anthropic/index.js +467 -137
  28. package/dist/providers/anthropic/index.js.map +1 -1
  29. package/dist/providers/bedrock/index.cjs +409 -128
  30. package/dist/providers/bedrock/index.cjs.map +1 -1
  31. package/dist/providers/bedrock/index.js +409 -128
  32. package/dist/providers/bedrock/index.js.map +1 -1
  33. package/dist/providers/cerebras/index.cjs +414 -133
  34. package/dist/providers/cerebras/index.cjs.map +1 -1
  35. package/dist/providers/cerebras/index.js +414 -133
  36. package/dist/providers/cerebras/index.js.map +1 -1
  37. package/dist/providers/cohere/index.cjs +414 -133
  38. package/dist/providers/cohere/index.cjs.map +1 -1
  39. package/dist/providers/cohere/index.js +414 -133
  40. package/dist/providers/cohere/index.js.map +1 -1
  41. package/dist/providers/google/index.cjs +414 -133
  42. package/dist/providers/google/index.cjs.map +1 -1
  43. package/dist/providers/google/index.js +414 -133
  44. package/dist/providers/google/index.js.map +1 -1
  45. package/dist/providers/groq/index.cjs +414 -133
  46. package/dist/providers/groq/index.cjs.map +1 -1
  47. package/dist/providers/groq/index.js +414 -133
  48. package/dist/providers/groq/index.js.map +1 -1
  49. package/dist/providers/huggingface/index.cjs +414 -133
  50. package/dist/providers/huggingface/index.cjs.map +1 -1
  51. package/dist/providers/huggingface/index.js +414 -133
  52. package/dist/providers/huggingface/index.js.map +1 -1
  53. package/dist/providers/mistral/index.cjs +414 -133
  54. package/dist/providers/mistral/index.cjs.map +1 -1
  55. package/dist/providers/mistral/index.js +414 -133
  56. package/dist/providers/mistral/index.js.map +1 -1
  57. package/dist/providers/ollama/index.cjs +414 -133
  58. package/dist/providers/ollama/index.cjs.map +1 -1
  59. package/dist/providers/ollama/index.js +414 -133
  60. package/dist/providers/ollama/index.js.map +1 -1
  61. package/dist/providers/openai/index.cjs +452 -135
  62. package/dist/providers/openai/index.cjs.map +1 -1
  63. package/dist/providers/openai/index.js +452 -135
  64. package/dist/providers/openai/index.js.map +1 -1
  65. package/dist/providers/together/index.cjs +414 -133
  66. package/dist/providers/together/index.cjs.map +1 -1
  67. package/dist/providers/together/index.js +414 -133
  68. package/dist/providers/together/index.js.map +1 -1
  69. package/dist/providers/vercel-ai/index.cjs +398 -132
  70. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  71. package/dist/providers/vercel-ai/index.js +398 -132
  72. package/dist/providers/vercel-ai/index.js.map +1 -1
  73. package/package.json +1 -1
@@ -38,6 +38,35 @@ module.exports = __toCommonJS(bedrock_exports);
38
38
  // src/client.ts
39
39
  var import_node_crypto3 = require("crypto");
40
40
 
41
+ // src/exporters/retry.ts
42
+ var RETRY_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
43
+ var TOO_LARGE_STATUS = 413;
44
+ var RETRY_BACKOFF_BASE_S = 1;
45
+ var RETRY_BACKOFF_CAP_S = 30;
46
+ var DEFAULT_RETRY_HORIZON_S = 300;
47
+ var DEFAULT_SHUTDOWN_TIMEOUT_S = 10;
48
+ var RETRY_WARN_AFTER_ATTEMPTS = 3;
49
+ var jitter = { fraction: () => Math.random() };
50
+ function backoffDelayS(retryNumber, fraction) {
51
+ const exponent = Math.min(Math.max(retryNumber, 0), 62);
52
+ const ceiling = Math.min(RETRY_BACKOFF_CAP_S, RETRY_BACKOFF_BASE_S * 2 ** exponent);
53
+ return Math.min(Math.max(fraction, 0), 1) * ceiling;
54
+ }
55
+ var SECONDS = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
56
+ function parseRetryAfterS(value, nowMs = Date.now()) {
57
+ if (value === null || value === void 0) return null;
58
+ const text = String(value).trim();
59
+ if (text === "") return null;
60
+ if (SECONDS.test(text)) {
61
+ const seconds = Number(text);
62
+ return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
63
+ }
64
+ if (!/[A-Za-z]/.test(text)) return null;
65
+ const when = Date.parse(text);
66
+ if (!Number.isFinite(when)) return null;
67
+ return Math.max(0, (when - nowMs) / 1e3);
68
+ }
69
+
41
70
  // src/globals.ts
42
71
  var import_node_async_hooks = require("async_hooks");
43
72
  var G = globalThis;
@@ -138,11 +167,65 @@ function hasCredentials(url) {
138
167
  }
139
168
  }
140
169
 
170
+ // src/masking.ts
171
+ var CONTENT_IN_JSON_OBJECT = /* @__PURE__ */ new Map([
172
+ [
173
+ "llm.invocation_parameters",
174
+ /* @__PURE__ */ new Set([
175
+ "additionalinstructions",
176
+ // OpenAI assistants run
177
+ "chathistory",
178
+ // Cohere
179
+ "contents",
180
+ // Gemini
181
+ "documents",
182
+ // Cohere RAG
183
+ "functions",
184
+ "input",
185
+ "inputtext",
186
+ // Bedrock Titan
187
+ "instructions",
188
+ "message",
189
+ // Cohere
190
+ "messages",
191
+ "preamble",
192
+ // Cohere
193
+ "prediction",
194
+ // OpenAI predicted output
195
+ "prompt",
196
+ "system",
197
+ // Anthropic
198
+ "systeminstruction",
199
+ // Gemini
200
+ "texts",
201
+ // Cohere embed
202
+ "toolconfig",
203
+ // Gemini
204
+ "tools"
205
+ ])
206
+ ]
207
+ ]);
208
+ var VALUE_RULE_PREFIXES = new Set(
209
+ [...CONTENT_IN_JSON_OBJECT.keys()].flatMap((key) => {
210
+ const segments = key.split(".");
211
+ return segments.slice(1).map((_, i) => segments.slice(0, i + 1).join("."));
212
+ })
213
+ );
214
+
141
215
  // src/exporters/batch.ts
216
+ var SHUTDOWN_BUDGET_MS = DEFAULT_SHUTDOWN_TIMEOUT_S * 1e3;
142
217
  var MAX_TIMEOUT_MS = 2 ** 31 - 1;
143
218
  var MAX_BATCH_BYTES = 8 * 1024 * 1024;
144
219
  var utf8ByteLength = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function" ? (s) => Buffer.byteLength(s, "utf8") : (s) => s.length * 3;
145
220
 
221
+ // src/context/storage.ts
222
+ function storage() {
223
+ return getContextStorage();
224
+ }
225
+ function getContext() {
226
+ return storage().getStore() ?? {};
227
+ }
228
+
146
229
  // src/ids.ts
147
230
  var import_node_crypto = require("crypto");
148
231
 
@@ -273,16 +356,8 @@ var SUPPLEMENTAL_RULES = [
273
356
  { re: new RegExp("json|syntaxerror|unexpected token|decodeerror", "u"), code: "PERCEPTION.PARSING.JSON_INVALID" }
274
357
  ];
275
358
 
276
- // src/context/storage.ts
277
- function storage() {
278
- return getContextStorage();
279
- }
280
- function getContext() {
281
- return storage().getStore() ?? {};
282
- }
283
-
284
359
  // src/version.ts
285
- var SDK_VERSION = "0.9.2";
360
+ var SDK_VERSION = "0.11.0";
286
361
 
287
362
  // src/exporters/quota.ts
288
363
  var QUOTA_REASON = "monthly_quota_exceeded";
@@ -390,12 +465,18 @@ var QuotaPause = class {
390
465
 
391
466
  // src/exporters/http.ts
392
467
  var CAPACITY_REFUSAL_STATUSES = /* @__PURE__ */ new Set([429, 503]);
393
- var RETRY_AFTER_CEILING_MS = 1e4;
394
- var REFUSAL_BACKOFF_BASE_MS = 1e3;
395
- var REFUSAL_NO_HINT = -1;
396
468
  var MISROUTE_WARN_WINDOW_MS = 3e5;
397
469
  var AUTH_REFUSAL_STATUSES = /* @__PURE__ */ new Set([401, 403]);
398
470
  var FAILURE_WARN_WINDOW_MS = 3e5;
471
+ var MAX_TIMER_MS = 2 ** 31 - 1;
472
+ function validHorizonS(value) {
473
+ if (value === void 0) return DEFAULT_RETRY_HORIZON_S;
474
+ if (typeof value === "number" && Number.isFinite(value) && value >= 0) return value;
475
+ warn(
476
+ `Risicare: retryHorizonS=${String(value)} is not a finite number of 0 or more; using the default, ${DEFAULT_RETRY_HORIZON_S} s.`
477
+ );
478
+ return DEFAULT_RETRY_HORIZON_S;
479
+ }
399
480
  var HttpExporter = class {
400
481
  name = "http";
401
482
  _endpoint;
@@ -405,20 +486,28 @@ var HttpExporter = class {
405
486
  _timeoutMs;
406
487
  _maxRetries;
407
488
  _compress;
489
+ _retryHorizonS;
490
+ /** Total HTTP requests that this exporter sent (each retry and each half of a split counts). */
491
+ attempts = 0;
408
492
  // Circuit breaker (CON-201 / B-16). Threshold and cooldown sized for
409
- // a "30-second prod restart" scenario: with default 1s batch flush a
410
- // 5-failure threshold opens the circuit ~5s into an outage and the 60s
411
- // cooldown gives the gateway time to come back before the half-open
412
- // probe fires. Lower numbers (was 3@30s) tripped on transient blips.
493
+ // a "30-second prod restart" scenario. Since W2-1c only answers that a retry
494
+ // cannot change move it (see the block above).
413
495
  _consecutiveFailures = 0;
414
496
  _lastMisrouteWarnAt = -Infinity;
415
497
  _lastFailureWarnAt = -Infinity;
498
+ _lastExhaustedWarnAt = -Infinity;
499
+ /** "log once" (W2-1c): the WARNING for a `too_large` drop is written one time. */
500
+ _tooLargeWarned = false;
416
501
  /**
417
502
  * The kind of failure that the last outage WARNING named ('auth', 'http', 'none',
418
503
  * 'unknown'). `null` after a success. A new kind in the same outage writes one more
419
504
  * WARNING, also inside the window.
420
505
  */
421
506
  _failureKind = null;
507
+ /** `endRetries()` was called, and `shutdown()` has not run since. */
508
+ _noWait = false;
509
+ /** The wake-ups of the backoff waits in progress. `endRetries()` calls each one. */
510
+ _waits = /* @__PURE__ */ new Set();
422
511
  /** The endpoint as a log line may show it: no userinfo, no query (see `safeUrl`). */
423
512
  _safeEndpoint;
424
513
  /** The endpoint holds userinfo. `fetch` refuses such a URL. */
@@ -429,6 +518,8 @@ var HttpExporter = class {
429
518
  _acks = /* @__PURE__ */ new WeakMap();
430
519
  /** The requests that each finished call sent, by its batch. Read once by `takeAttempts(spans)`. */
431
520
  _requests = /* @__PURE__ */ new WeakMap();
521
+ /** The drop reason of each failed call, by its batch. Read once by `takeDropReason(spans)`. */
522
+ _dropReasons = /* @__PURE__ */ new WeakMap();
432
523
  /** The batch processor dropped span(s) from a full queue in the quota pause (S-1). */
433
524
  noteQuotaDrop(count = 1) {
434
525
  this._quota.addDrops(count);
@@ -453,8 +544,16 @@ var HttpExporter = class {
453
544
  this._projectId = options.projectId;
454
545
  this._environment = options.environment;
455
546
  this._timeoutMs = options.timeoutMs ?? 5e3;
456
- this._maxRetries = options.maxRetries ?? 3;
547
+ let maxRetries = options.maxRetries;
548
+ if (maxRetries !== void 0 && !(Number.isInteger(maxRetries) && maxRetries >= 1)) {
549
+ warn(
550
+ `Risicare: maxRetries=${String(maxRetries)} is not a whole number of 1 or more; the exporter uses no count limit (the retry horizon is the limit).`
551
+ );
552
+ maxRetries = void 0;
553
+ }
554
+ this._maxRetries = maxRetries;
457
555
  this._compress = options.compress ?? false;
556
+ this._retryHorizonS = validHorizonS(options.retryHorizonS);
458
557
  this._safeEndpoint = safeUrl(this._endpoint);
459
558
  this._endpointHasCredentials = hasCredentials(this._endpoint);
460
559
  }
@@ -476,16 +575,18 @@ var HttpExporter = class {
476
575
  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
477
576
  return `HttpExporter { endpoint: '${this._safeEndpoint}' }`;
478
577
  }
479
- /** The most requests that one `export()` call sends (`maxRetries`). */
578
+ /**
579
+ * The most attempts for one request body (`maxRetries`). `undefined` when no count is set:
580
+ * the retry horizon is the limit.
581
+ */
480
582
  get attemptsPerExport() {
481
583
  return this._maxRetries;
482
584
  }
483
585
  /**
484
586
  * Returns the number of HTTP requests that the `export()` call for `spans` sent, and clears
485
- * it. This is the number that was sent, not the most that the call may send
486
- * (`attemptsPerExport`): a 401 or 403 stops the loop after one request, and an open circuit
487
- * breaker sends none. Returns `null` when no call is on record for `spans`. The answer is
488
- * kept per batch, as `takeAck` keeps the ack.
587
+ * it. Each retry and each half of a 413 split counts one; a call that the open circuit
588
+ * breaker or the quota pause stops sends none. Returns `null` when no call is on record for
589
+ * `spans`. The answer is kept per batch, as `takeAck` keeps the ack.
489
590
  */
490
591
  takeAttempts(spans) {
491
592
  const n = this._requests.get(spans) ?? null;
@@ -502,6 +603,12 @@ var HttpExporter = class {
502
603
  this._acks.delete(spans);
503
604
  return ack;
504
605
  }
606
+ /** Returns why the `export()` call for `spans` failed (W2-1c), and clears it. See `SpanExporter`. */
607
+ takeDropReason(spans) {
608
+ const reason = this._dropReasons.get(spans) ?? null;
609
+ this._dropReasons.delete(spans);
610
+ return reason;
611
+ }
505
612
  /** Returns the spans of `spans` that could not be serialized and were not sent, and clears them. */
506
613
  takeUnserializable(spans) {
507
614
  const bad = this._unserializable.get(spans) ?? [];
@@ -510,7 +617,7 @@ var HttpExporter = class {
510
617
  }
511
618
  /**
512
619
  * Cancel the `export()` call for `spans` (all calls when `spans` is not given): its
513
- * request, its retries and its backoff sleep. The batch processor calls it when
620
+ * request, its retries and its backoff wait. The batch processor calls it when
514
621
  * `shutdown()` abandons the batch, so that the call does not keep the process alive. The
515
622
  * cancelled call returns FAILURE, changes no counter (the circuit breaker included) and
516
623
  * logs no WARNING.
@@ -520,24 +627,39 @@ var HttpExporter = class {
520
627
  else for (const call of this._calls.values()) call.cancel.abort();
521
628
  }
522
629
  /**
523
- * Send one batch. The limits are the request timeout and `maxRetries`.
630
+ * End the retry waits of this exporter until its next `shutdown()`. The batch processor
631
+ * calls it when `shutdown()` starts. A call that waits for a retry makes one more attempt
632
+ * at once. An attempt that fails after this is not retried: the call fails with the drop
633
+ * reason `shutdown_residue`. So a drain against a dead endpoint costs one attempt for each
634
+ * batch, not the shutdown budget.
635
+ */
636
+ endRetries() {
637
+ this._noWait = true;
638
+ for (const wake of [...this._waits]) wake();
639
+ }
640
+ /**
641
+ * Send one batch, with the W2-1c retry policy (see the block above the class).
642
+ *
643
+ * Resolves SUCCESS when the backend accounted for the batch: `takeAck` has the counts (and
644
+ * the spans that a 413 split dropped, in `dropped`). Resolves FAILURE when no span was
645
+ * accounted for: `takeDropReason` then says why, and the batch processor drops the batch
646
+ * with that reason.
524
647
  *
525
648
  * ⚠ NO CALLER BUDGET. `flush(timeoutMs)` only stops WAITING at its deadline; it never
526
- * cuts a request that is already sent. A short flush budget that cut the request made a
527
- * healthy, slow server look like a failure: the span used a retry, the breaker moved, and
528
- * the server stored the same spans again. Only `abort()` stops the call, and only
649
+ * cuts a request that is already sent. Only `abort()` stops the call, and only
529
650
  * `shutdown()` calls it.
530
651
  */
531
652
  async export(spans) {
532
653
  if (spans.length === 0) return "success" /* SUCCESS */;
533
654
  const call = {
534
655
  cancel: new AbortController(),
535
- refusalAfterMs: null,
656
+ retryAfterS: null,
536
657
  misroute: null,
537
658
  noRetry: false,
538
659
  status: null,
539
660
  error: null,
540
- attempts: 0
661
+ attempts: 0,
662
+ ack: null
541
663
  };
542
664
  this._calls.set(spans, call);
543
665
  try {
@@ -574,83 +696,236 @@ var HttpExporter = class {
574
696
  );
575
697
  }
576
698
  if (parts.length === 0) return "success" /* SUCCESS */;
577
- const payload = `{"spans":[${parts.join(",")}]` + (this._projectId ? `,"projectId":${JSON.stringify(this._projectId)}` : "") + (this._environment ? `,"environment":${JSON.stringify(this._environment)}` : "") + "}";
578
- const now = Date.now();
579
- let isHalfOpen = false;
580
- if (this._consecutiveFailures >= this._circuitBreakerThreshold) {
581
- if (now < this._circuitOpenUntil) {
582
- return "failure" /* FAILURE */;
699
+ if (this._consecutiveFailures >= this._circuitBreakerThreshold && Date.now() < this._circuitOpenUntil) {
700
+ this._dropReasons.set(spans, "transport_refused");
701
+ return "failure" /* FAILURE */;
702
+ }
703
+ const out = { delivered: [], dropped: {}, failed: [], cancelled: false };
704
+ const start = performance.now();
705
+ await this._deliver(parts, start, call, out, true);
706
+ if (cancelled.aborted || out.cancelled) {
707
+ this._acks.delete(spans);
708
+ return "failure" /* FAILURE */;
709
+ }
710
+ return this._finish(spans, out, call.attempts);
711
+ }
712
+ /** The request body for `parts` (the serialized spans of one part of a batch). */
713
+ _payload(parts) {
714
+ return `{"spans":[${parts.join(",")}]` + (this._projectId ? `,"projectId":${JSON.stringify(this._projectId)}` : "") + (this._environment ? `,"environment":${JSON.stringify(this._environment)}` : "") + "}";
715
+ }
716
+ /**
717
+ * Send one part of a batch with the retry policy, and record its outcome in `out`.
718
+ * `maySplit` is true only for the whole batch: a 413 splits it in two one time. A half
719
+ * that gets 413 again is dropped as `too_large`.
720
+ */
721
+ async _deliver(parts, start, call, out, maySplit) {
722
+ const n = parts.length;
723
+ if (!maySplit && this._quota.paused()) {
724
+ out.delivered.push({ n, ack: { accepted: 0, rejected: 0, quotaDropped: n } });
725
+ return;
726
+ }
727
+ const result = await this._sendWithRetries(this._payload(parts), n, start, call);
728
+ if (result.kind === "delivered") {
729
+ out.delivered.push({ n, ack: result.ack });
730
+ } else if (result.kind === "too_large") {
731
+ if (maySplit && n > 1) {
732
+ const mid = Math.ceil(n / 2);
733
+ debug(`Ingest answered HTTP 413 for ${n} span(s): sending two halves of ${mid} and ${n - mid}`);
734
+ await this._deliver(parts.slice(0, mid), start, call, out, false);
735
+ if (!out.cancelled) await this._deliver(parts.slice(mid), start, call, out, false);
736
+ } else {
737
+ out.dropped.too_large = (out.dropped.too_large ?? 0) + n;
583
738
  }
584
- isHalfOpen = true;
739
+ } else if (result.kind === "cancelled") {
740
+ out.cancelled = true;
741
+ } else {
742
+ out.failed.push({ n, reason: result.kind, answer: result.answer });
585
743
  }
586
- const maxAttempts = isHalfOpen ? 1 : this._maxRetries;
587
- for (let attempt = 0; attempt < maxAttempts; attempt++) {
588
- call.refusalAfterMs = null;
744
+ }
745
+ /** Send one request body until it is delivered or the policy stops. */
746
+ async _sendWithRetries(body, spansSent, start, call) {
747
+ const cancelled = call.cancel.signal;
748
+ let retryNumber = 0;
749
+ let attemptsHere = 0;
750
+ for (; ; ) {
751
+ if (cancelled.aborted) return { kind: "cancelled" };
752
+ call.retryAfterS = null;
589
753
  call.misroute = null;
590
754
  call.noRetry = false;
591
755
  call.status = null;
592
756
  call.error = null;
757
+ call.ack = null;
593
758
  call.attempts++;
594
- const result = await this._sendRequest(payload, parts.length, call, spans);
595
- if (cancelled.aborted) {
596
- this._acks.delete(spans);
597
- return "failure" /* FAILURE */;
598
- }
599
- if (result === "success" /* SUCCESS */) {
600
- this._consecutiveFailures = 0;
601
- this._failureKind = null;
602
- return result;
759
+ attemptsHere++;
760
+ this.attempts++;
761
+ const result = await this._sendRequest(body, spansSent, call);
762
+ if (cancelled.aborted) return { kind: "cancelled" };
763
+ if (result === "success" /* SUCCESS */) return { kind: "delivered", ack: call.ack };
764
+ if (call.status === TOO_LARGE_STATUS) return { kind: "too_large" };
765
+ const answer = {
766
+ status: call.status,
767
+ error: call.error,
768
+ misroute: call.misroute,
769
+ zeroAck: call.noRetry,
770
+ sent: spansSent
771
+ };
772
+ if (!this._retryable(call)) return { kind: "transport_refused", answer };
773
+ if (attemptsHere === RETRY_WARN_AFTER_ATTEMPTS) this._warnOutage(answer, true);
774
+ if (this._noWait) return { kind: "shutdown_residue", answer };
775
+ if (this._maxRetries !== void 0 && attemptsHere >= this._maxRetries) {
776
+ return { kind: "retry_exhausted", answer };
603
777
  }
604
- if (call.misroute !== null || call.noRetry) break;
605
- if (call.status !== null && AUTH_REFUSAL_STATUSES.has(call.status)) break;
606
- if (attempt < maxAttempts - 1) {
607
- const refusal = call.refusalAfterMs;
608
- const delay = refusal === null ? 100 * Math.pow(2, attempt) : refusal === REFUSAL_NO_HINT ? REFUSAL_BACKOFF_BASE_MS * Math.pow(2, attempt) : refusal;
609
- await sleep(delay, cancelled);
610
- if (cancelled.aborted) return "failure" /* FAILURE */;
778
+ const remainingS = this._retryHorizonS - (performance.now() - start) / 1e3;
779
+ if (remainingS <= 0) return { kind: "retry_exhausted", answer };
780
+ const hint = call.retryAfterS;
781
+ const waitS = hint !== null && hint > 0 ? hint : backoffDelayS(retryNumber, jitter.fraction());
782
+ const delayS = Math.min(waitS, remainingS);
783
+ retryNumber++;
784
+ debug(
785
+ `Ingest attempt ${attemptsHere} failed (${answer.status ?? answer.error ?? "unknown"}); next attempt in ${delayS.toFixed(2)} s (${Math.round(remainingS)} s of the horizon left)`
786
+ );
787
+ await this._retryWait(delayS * 1e3, cancelled);
788
+ }
789
+ }
790
+ /** True when the answer of the last attempt of `call` can change on a retry. */
791
+ _retryable(call) {
792
+ if (call.misroute !== null || call.noRetry) return false;
793
+ if (call.status !== null) return RETRY_STATUSES.has(call.status);
794
+ if (this._endpointHasCredentials) return false;
795
+ return call.error !== null;
796
+ }
797
+ /**
798
+ * Wait `ms` before the next attempt. `abort()` and `endRetries()` end the wait at once. The
799
+ * timer does not keep the process alive: when nothing else runs, `beforeExit` starts the
800
+ * SDK's `shutdown()`, which ends the wait.
801
+ */
802
+ _retryWait(ms, signal) {
803
+ return new Promise((resolve) => {
804
+ if (signal.aborted || this._noWait || ms <= 0) return resolve();
805
+ const done = () => {
806
+ clearTimeout(timer);
807
+ signal.removeEventListener("abort", done);
808
+ this._waits.delete(done);
809
+ resolve();
810
+ };
811
+ const timer = setTimeout(done, Math.min(ms, MAX_TIMER_MS));
812
+ timer.unref?.();
813
+ signal.addEventListener("abort", done, { once: true });
814
+ this._waits.add(done);
815
+ });
816
+ }
817
+ /** Turn the outcome of the parts of one batch into the result of `export()`. */
818
+ _finish(spans, out, attempts) {
819
+ const reasons = new Set(out.failed.map((f) => f.reason));
820
+ if (out.delivered.length === 0 && Object.keys(out.dropped).length === 0 && reasons.size === 1) {
821
+ const reason = out.failed[0].reason;
822
+ const nFailed = out.failed.reduce((sum, f) => sum + f.n, 0);
823
+ this._dropReasons.set(spans, reason);
824
+ return this._fail(reason, out.failed[out.failed.length - 1].answer, nFailed, attempts);
825
+ }
826
+ let ack;
827
+ if (out.delivered.length === 1 && Object.keys(out.dropped).length === 0 && out.failed.length === 0) {
828
+ ack = out.delivered[0].ack;
829
+ } else {
830
+ let accepted = 0;
831
+ let rejected = 0;
832
+ let quotaDropped = 0;
833
+ for (const part of out.delivered) {
834
+ accepted += part.ack !== null ? part.ack.accepted : part.n;
835
+ rejected += part.ack !== null ? part.ack.rejected : 0;
836
+ quotaDropped += part.ack?.quotaDropped ?? 0;
611
837
  }
838
+ const dropped = { ...out.dropped };
839
+ for (const f of out.failed) dropped[f.reason] = (dropped[f.reason] ?? 0) + f.n;
840
+ ack = { accepted, rejected };
841
+ if (quotaDropped > 0) ack.quotaDropped = quotaDropped;
842
+ if (Object.keys(dropped).length > 0) ack.dropped = dropped;
612
843
  }
613
- if (call.refusalAfterMs !== null) {
614
- warn(
615
- `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.`
616
- );
844
+ if (ack !== null) this._acks.set(spans, ack);
845
+ this._consecutiveFailures = 0;
846
+ this._failureKind = null;
847
+ const tooLarge = out.dropped.too_large ?? 0;
848
+ if (tooLarge > 0) this._warnTooLarge(tooLarge);
849
+ for (const f of out.failed) {
850
+ if (f.reason === "retry_exhausted") this._warnExhausted(f.n, attempts, f.answer);
851
+ }
852
+ return "success" /* SUCCESS */;
853
+ }
854
+ /** End a call in which no span was accounted for. Always returns FAILURE. */
855
+ _fail(reason, answer, nSpans, attempts) {
856
+ if (reason === "shutdown_residue") {
857
+ debug(`Export ended by shutdown after ${attempts} attempt(s)`);
617
858
  return "failure" /* FAILURE */;
618
859
  }
619
- const misroute = call.misroute;
620
- if (misroute !== null && Date.now() - this._lastMisrouteWarnAt > MISROUTE_WARN_WINDOW_MS) {
621
- this._lastMisrouteWarnAt = Date.now();
622
- warn(
623
- `Risicare: spans are NOT reaching ${this._safeEndpoint}. It answered POST /v1/spans with ${misroute}. That is not the Risicare ingest gateway, so the endpoint is probably wrong (for example the dashboard URL instead of the ingest gateway URL). The SDK does not follow redirects, and this batch is counted as NOT delivered. Set endpoint or RISICARE_ENDPOINT to the ingest gateway URL.`
624
- );
860
+ if (reason === "retry_exhausted") {
861
+ if (answer.status === null || !CAPACITY_REFUSAL_STATUSES.has(answer.status)) this._stepBreaker();
862
+ this._warnOutage(answer, true);
863
+ this._warnExhausted(nSpans, attempts, answer);
864
+ return "failure" /* FAILURE */;
625
865
  }
866
+ this._stepBreaker();
867
+ this._warnOutage(answer, false);
868
+ return "failure" /* FAILURE */;
869
+ }
870
+ /** Count one failed call toward the circuit breaker. */
871
+ _stepBreaker() {
626
872
  this._consecutiveFailures++;
627
- if (misroute === null && !call.noRetry) {
628
- const status = call.status;
629
- const kind = status !== null && AUTH_REFUSAL_STATUSES.has(status) ? "auth" : status !== null ? "http" : call.error !== null ? "none" : "unknown";
630
- let write = false;
631
- if (this._consecutiveFailures === 1 || this._failureKind === null) {
632
- if (Date.now() - this._lastFailureWarnAt > FAILURE_WARN_WINDOW_MS) {
633
- this._lastFailureWarnAt = Date.now();
634
- write = true;
635
- }
636
- this._failureKind = kind;
637
- } else if (kind !== this._failureKind) {
638
- this._failureKind = kind;
639
- write = true;
640
- }
641
- if (write) this._warnOutage(kind, status, call.error);
642
- }
643
873
  if (this._consecutiveFailures >= this._circuitBreakerThreshold) {
644
874
  this._circuitOpenUntil = Date.now() + this._circuitBreakerCooldownMs;
645
875
  warn(
646
876
  `HTTP exporter circuit breaker opened after ${this._consecutiveFailures} failures. Cooldown: ${this._circuitBreakerCooldownMs / 1e3}s`
647
877
  );
648
878
  }
649
- return "failure" /* FAILURE */;
650
879
  }
651
- /** The outage WARNING for one kind of failure. */
652
- _warnOutage(kind, status, error) {
880
+ /**
881
+ * The outage WARNING: at the first failure of an outage, and when its kind changes. At most
882
+ * one in the window for the first failure; a misroute has its own WARNING, at most one in
883
+ * the window. `retrying` is true for a retryable answer (written after
884
+ * `RETRY_WARN_AFTER_ATTEMPTS` failed attempts of one batch, or when its retries end before
885
+ * that), false for an answer that a retry cannot change (one attempt). The WARNING names the last HTTP status, or the error
886
+ * code when there was no answer. It never names the key or the response body, and names
887
+ * the API key as a cause only for a 401 or 403. An ack of 0 and 0 has its WARNING from
888
+ * `checkAck`.
889
+ */
890
+ _warnOutage(answer, retrying) {
891
+ if (answer.misroute !== null) {
892
+ if (Date.now() - this._lastMisrouteWarnAt > MISROUTE_WARN_WINDOW_MS) {
893
+ this._lastMisrouteWarnAt = Date.now();
894
+ warn(
895
+ `Risicare: spans are NOT reaching ${this._safeEndpoint}. It answered POST /v1/spans with ${answer.misroute}. That is not the Risicare ingest gateway, so the endpoint is probably wrong (for example the dashboard URL instead of the ingest gateway URL). The SDK does not follow redirects, and this batch is counted as NOT delivered. Set endpoint or RISICARE_ENDPOINT to the ingest gateway URL.`
896
+ );
897
+ }
898
+ return;
899
+ }
900
+ if (answer.zeroAck) return;
901
+ const status = answer.status;
902
+ const kind = status !== null && AUTH_REFUSAL_STATUSES.has(status) ? "auth" : status !== null ? "http" : answer.error !== null ? "none" : "unknown";
903
+ let write = false;
904
+ if (this._failureKind === null || !retrying && this._consecutiveFailures === 1) {
905
+ if (Date.now() - this._lastFailureWarnAt > FAILURE_WARN_WINDOW_MS) {
906
+ this._lastFailureWarnAt = Date.now();
907
+ write = true;
908
+ }
909
+ this._failureKind = kind;
910
+ } else if (kind !== this._failureKind) {
911
+ this._failureKind = kind;
912
+ write = true;
913
+ }
914
+ if (!write) return;
653
915
  const where = `Risicare: spans are NOT reaching ${this._safeEndpoint}`;
916
+ if (retrying) {
917
+ let limit = `${this._retryHorizonS} s from its first attempt (retryHorizonS)`;
918
+ if (this._maxRetries !== void 0) limit = `${this._maxRetries} attempt(s) (maxRetries) or ${limit}`;
919
+ const retryText = `The SDK sends each batch again with a growing wait, for up to ${limit}, and then drops it (reason=retry_exhausted).`;
920
+ if (kind === "http") {
921
+ warn(`${where}: it answered HTTP ${status}. ${retryText} Set debug: true to see each attempt.`);
922
+ } else {
923
+ warn(
924
+ `${where}: no answer (${answer.error}). The endpoint cannot be reached, or it did not answer in time. ${retryText} Set debug: true to see each attempt.`
925
+ );
926
+ }
927
+ return;
928
+ }
654
929
  const tail = "Tracing continues, but the SDK drops the spans that it cannot send.";
655
930
  if (kind === "auth") {
656
931
  warn(
@@ -658,15 +933,11 @@ var HttpExporter = class {
658
933
  );
659
934
  } else if (kind === "http") {
660
935
  warn(
661
- `${where}: it answered HTTP ${status}. The server did not take the batch. Check the endpoint and the server. ${tail} Set debug: true to see each attempt.`
936
+ `${where}: it answered HTTP ${status}. The server did not take the batch, and a retry cannot change that answer. Check the endpoint and the server. ${tail} Set debug: true to see each attempt.`
662
937
  );
663
938
  } else if (kind === "none" && this._endpointHasCredentials) {
664
939
  warn(
665
- `${where}: no answer (${error}). The endpoint URL holds credentials (a user name or a password before the host), and fetch does not send a request to such a URL. Remove the credentials from the endpoint URL. ${tail}`
666
- );
667
- } else if (kind === "none") {
668
- warn(
669
- `${where}: no answer (${error}). The endpoint cannot be reached, or it did not answer in time. Check the endpoint and the network. ${tail} Set debug: true to see each attempt.`
940
+ `${where}: no answer (${answer.error}). The endpoint URL holds credentials (a user name or a password before the host), and fetch does not send a request to such a URL. Remove the credentials from the endpoint URL. ${tail}`
670
941
  );
671
942
  } else {
672
943
  warn(
@@ -674,33 +945,38 @@ var HttpExporter = class {
674
945
  );
675
946
  }
676
947
  }
948
+ /** The WARNING for spans dropped as `retry_exhausted`. At most one in the window. */
949
+ _warnExhausted(nSpans, attempts, answer) {
950
+ if (Date.now() - this._lastExhaustedWarnAt <= FAILURE_WARN_WINDOW_MS) return;
951
+ this._lastExhaustedWarnAt = Date.now();
952
+ const last = answer.status !== null ? `HTTP ${answer.status}` : `no answer (${answer.error})`;
953
+ const capacity = answer.status !== null && CAPACITY_REFUSAL_STATUSES.has(answer.status) ? " (over capacity)" : "";
954
+ const limit = this._maxRetries !== void 0 && attempts >= this._maxRetries ? `the maxRetries limit of ${this._maxRetries} attempt(s)` : `the retry horizon of ${this._retryHorizonS} s (retryHorizonS)`;
955
+ warn(
956
+ `Risicare: ${nSpans} span(s) DISCARDED (reason=retry_exhausted): ${this._safeEndpoint} did not take them in ${attempts} attempt(s), and ${limit} is used up. The last answer: ${last}${capacity}. A gateway outage that is longer than the retry horizon loses spans. To wait longer, raise retryHorizonS.`
957
+ );
958
+ }
959
+ /** The WARNING for spans dropped as `too_large`. One time for each exporter. */
960
+ _warnTooLarge(nSpans) {
961
+ if (this._tooLargeWarned) return;
962
+ this._tooLargeWarned = true;
963
+ warn(
964
+ `Risicare: ${nSpans} span(s) DISCARDED (reason=too_large): ${this._safeEndpoint} answered HTTP 413 (the request is too large) for a batch, and again for a half of it after one split. The SDK does not send these spans again. Make the span attributes smaller. This WARNING is written one time; droppedSpansByReason.too_large has the count.`
965
+ );
966
+ }
677
967
  /** Record a MISROUTE for the retry loop and the breaker. Always returns FAILURE. */
678
968
  _noteMisroute(call, answer) {
679
969
  call.misroute = this._scrub(answer, 300);
680
970
  debug(`Ingest misroute: ${call.misroute}`);
681
971
  return "failure" /* FAILURE */;
682
972
  }
683
- /**
684
- * Record a CAPACITY REFUSAL for the retry loop. Returns true if it was one.
685
- *
686
- * `Retry-After` is honoured only in its delta-seconds form (RFC 9110 §10.2.3 also permits an
687
- * HTTP-date); anything else falls back to our own backoff rather than guessing at a date
688
- * parse.
689
- */
690
- _noteRefusal(call, status, retryAfterRaw) {
691
- if (!CAPACITY_REFUSAL_STATUSES.has(status)) return false;
692
- let delay = REFUSAL_NO_HINT;
693
- if (retryAfterRaw) {
694
- const secs = Number(retryAfterRaw);
695
- if (Number.isFinite(secs) && secs >= 0) {
696
- delay = Math.min(secs * 1e3, RETRY_AFTER_CEILING_MS);
697
- }
698
- }
699
- call.refusalAfterMs = delay;
700
- debug(`Ingest refused for capacity: HTTP ${status} (Retry-After=${this._scrub(retryAfterRaw)})`);
701
- return true;
973
+ /** Record the `Retry-After` wait of a retryable answer for the retry loop. */
974
+ _noteRetryAfter(call, status, retryAfterRaw) {
975
+ if (!RETRY_STATUSES.has(status)) return;
976
+ call.retryAfterS = parseRetryAfterS(retryAfterRaw);
977
+ debug(`Ingest answered HTTP ${status} (Retry-After=${this._scrub(retryAfterRaw)})`);
702
978
  }
703
- async _sendRequest(body, spansSent, call, spans) {
979
+ async _sendRequest(body, spansSent, call) {
704
980
  const cancelled = call.cancel.signal;
705
981
  const timeoutMs = this._timeoutMs;
706
982
  const url = `${this._endpoint}/v1/spans`;
@@ -768,14 +1044,15 @@ var HttpExporter = class {
768
1044
  } else if (ack.result === "success" /* SUCCESS */) {
769
1045
  this._quota.accepted(`the ingest endpoint ${this._safeEndpoint}`);
770
1046
  }
771
- if (ack.result === "success" /* SUCCESS */) this._acks.set(spans, ack.counts);
1047
+ if (ack.result === "success" /* SUCCESS */) call.ack = ack.counts;
772
1048
  if (ack.final) call.noRetry = true;
773
1049
  return ack.result;
774
- } else if (response.status === 408 || response.status === 504) {
1050
+ }
1051
+ this._noteRetryAfter(call, response.status, response.headers?.get?.("Retry-After") ?? null);
1052
+ if (response.status === 408 || response.status === 504) {
775
1053
  debug(`HTTP export timeout: ${response.status}`);
776
1054
  return "timeout" /* TIMEOUT */;
777
1055
  }
778
- this._noteRefusal(call, response.status, response.headers.get("Retry-After"));
779
1056
  debug(`HTTP export failed: ${response.status}`);
780
1057
  return "failure" /* FAILURE */;
781
1058
  } catch (e) {
@@ -789,20 +1066,9 @@ var HttpExporter = class {
789
1066
  }
790
1067
  }
791
1068
  shutdown() {
1069
+ this._noWait = false;
792
1070
  }
793
1071
  };
794
- function sleep(ms, signal) {
795
- return new Promise((resolve) => {
796
- if (signal?.aborted) return resolve();
797
- const done = () => {
798
- clearTimeout(timer);
799
- signal?.removeEventListener("abort", done);
800
- resolve();
801
- };
802
- const timer = setTimeout(done, ms);
803
- signal?.addEventListener("abort", done, { once: true });
804
- });
805
- }
806
1072
  function asCount(v) {
807
1073
  return typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : void 0;
808
1074
  }
@@ -883,7 +1149,7 @@ function className(error) {
883
1149
  }
884
1150
  return typeof error;
885
1151
  }
886
- function responseReadFailed(provider, site, error, span) {
1152
+ function responseReadFailed(provider, site, error, span, part = "response") {
887
1153
  try {
888
1154
  const cls = className(error);
889
1155
  span?.setAttribute("risicare.observer_error", cls);
@@ -891,7 +1157,7 @@ function responseReadFailed(provider, site, error, span) {
891
1157
  const key = `${provider}\0${site}\0${cls}`;
892
1158
  if (logged.has(key) || logged.size >= LOGGED_MAX) return;
893
1159
  logged.add(key);
894
- debug(`could not read the ${provider} response in ${site} (${cls}); the span keeps fewer facts`);
1160
+ debug(`could not read the ${provider} ${part} in ${site} (${cls}); the span keeps fewer facts`);
895
1161
  } catch {
896
1162
  }
897
1163
  }
@@ -1184,7 +1450,21 @@ function calculateCost(model, promptTokens, completionTokens) {
1184
1450
  function tokenCount(value) {
1185
1451
  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
1186
1452
  }
1187
- function recordTokenUsage(span, counts, model) {
1453
+ var CACHE_READ_TOKENS_KEY = "gen_ai.usage.cache_read.input_tokens";
1454
+ var CACHE_WRITE_TOKENS_KEY = "gen_ai.usage.cache_write.input_tokens";
1455
+ var REASONING_TOKENS_KEY = "gen_ai.usage.reasoning.output_tokens";
1456
+ function providerInteger(value) {
1457
+ return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : void 0;
1458
+ }
1459
+ function recordUsageDetails(span, details) {
1460
+ const cacheRead = providerInteger(details.cacheRead);
1461
+ const cacheWrite = providerInteger(details.cacheWrite);
1462
+ const reasoning = providerInteger(details.reasoning);
1463
+ if (cacheRead !== void 0) span.setAttribute(CACHE_READ_TOKENS_KEY, cacheRead);
1464
+ if (cacheWrite !== void 0) span.setAttribute(CACHE_WRITE_TOKENS_KEY, cacheWrite);
1465
+ if (reasoning !== void 0) span.setAttribute(REASONING_TOKENS_KEY, reasoning);
1466
+ }
1467
+ function recordTokenUsage(span, counts, model, details) {
1188
1468
  const promptTokens = tokenCount(counts.prompt);
1189
1469
  const completionTokens = tokenCount(counts.completion);
1190
1470
  const bothKnown = promptTokens !== void 0 && completionTokens !== void 0;
@@ -1195,6 +1475,7 @@ function recordTokenUsage(span, counts, model) {
1195
1475
  if (completionTokens !== void 0) span.setAttribute("gen_ai.usage.completion_tokens", completionTokens);
1196
1476
  if (totalTokens !== void 0) span.setAttribute("gen_ai.usage.total_tokens", totalTokens);
1197
1477
  if (costUsd !== void 0) span.setAttribute("llm.cost.total_usd", costUsd);
1478
+ if (details) recordUsageDetails(span, details);
1198
1479
  }
1199
1480
 
1200
1481
  // src/utils/assert-client.ts