risicare 0.10.0 → 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 +76 -5
  2. package/README.md +157 -39
  3. package/dist/frameworks/instructor.cjs +338 -117
  4. package/dist/frameworks/instructor.cjs.map +1 -1
  5. package/dist/frameworks/instructor.js +338 -117
  6. package/dist/frameworks/instructor.js.map +1 -1
  7. package/dist/frameworks/langchain.cjs +351 -130
  8. package/dist/frameworks/langchain.cjs.map +1 -1
  9. package/dist/frameworks/langchain.js +351 -130
  10. package/dist/frameworks/langchain.js.map +1 -1
  11. package/dist/frameworks/langgraph.cjs +351 -130
  12. package/dist/frameworks/langgraph.cjs.map +1 -1
  13. package/dist/frameworks/langgraph.js +351 -130
  14. package/dist/frameworks/langgraph.js.map +1 -1
  15. package/dist/frameworks/llamaindex.cjs +351 -130
  16. package/dist/frameworks/llamaindex.cjs.map +1 -1
  17. package/dist/frameworks/llamaindex.js +351 -130
  18. package/dist/frameworks/llamaindex.js.map +1 -1
  19. package/dist/index.cjs +808 -226
  20. package/dist/index.cjs.map +1 -1
  21. package/dist/index.d.cts +137 -21
  22. package/dist/index.d.ts +137 -21
  23. package/dist/index.js +804 -226
  24. package/dist/index.js.map +1 -1
  25. package/dist/providers/anthropic/index.cjs +351 -130
  26. package/dist/providers/anthropic/index.cjs.map +1 -1
  27. package/dist/providers/anthropic/index.js +351 -130
  28. package/dist/providers/anthropic/index.js.map +1 -1
  29. package/dist/providers/bedrock/index.cjs +346 -125
  30. package/dist/providers/bedrock/index.cjs.map +1 -1
  31. package/dist/providers/bedrock/index.js +346 -125
  32. package/dist/providers/bedrock/index.js.map +1 -1
  33. package/dist/providers/cerebras/index.cjs +351 -130
  34. package/dist/providers/cerebras/index.cjs.map +1 -1
  35. package/dist/providers/cerebras/index.js +351 -130
  36. package/dist/providers/cerebras/index.js.map +1 -1
  37. package/dist/providers/cohere/index.cjs +351 -130
  38. package/dist/providers/cohere/index.cjs.map +1 -1
  39. package/dist/providers/cohere/index.js +351 -130
  40. package/dist/providers/cohere/index.js.map +1 -1
  41. package/dist/providers/google/index.cjs +351 -130
  42. package/dist/providers/google/index.cjs.map +1 -1
  43. package/dist/providers/google/index.js +351 -130
  44. package/dist/providers/google/index.js.map +1 -1
  45. package/dist/providers/groq/index.cjs +351 -130
  46. package/dist/providers/groq/index.cjs.map +1 -1
  47. package/dist/providers/groq/index.js +351 -130
  48. package/dist/providers/groq/index.js.map +1 -1
  49. package/dist/providers/huggingface/index.cjs +351 -130
  50. package/dist/providers/huggingface/index.cjs.map +1 -1
  51. package/dist/providers/huggingface/index.js +351 -130
  52. package/dist/providers/huggingface/index.js.map +1 -1
  53. package/dist/providers/mistral/index.cjs +351 -130
  54. package/dist/providers/mistral/index.cjs.map +1 -1
  55. package/dist/providers/mistral/index.js +351 -130
  56. package/dist/providers/mistral/index.js.map +1 -1
  57. package/dist/providers/ollama/index.cjs +351 -130
  58. package/dist/providers/ollama/index.cjs.map +1 -1
  59. package/dist/providers/ollama/index.js +351 -130
  60. package/dist/providers/ollama/index.js.map +1 -1
  61. package/dist/providers/openai/index.cjs +351 -130
  62. package/dist/providers/openai/index.cjs.map +1 -1
  63. package/dist/providers/openai/index.js +351 -130
  64. package/dist/providers/openai/index.js.map +1 -1
  65. package/dist/providers/together/index.cjs +351 -130
  66. package/dist/providers/together/index.cjs.map +1 -1
  67. package/dist/providers/together/index.js +351 -130
  68. package/dist/providers/together/index.js.map +1 -1
  69. package/dist/providers/vercel-ai/index.cjs +351 -130
  70. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  71. package/dist/providers/vercel-ai/index.js +351 -130
  72. package/dist/providers/vercel-ai/index.js.map +1 -1
  73. package/package.json +1 -1
@@ -1,6 +1,35 @@
1
1
  // src/client.ts
2
2
  import { createHash as createHash2 } from "crypto";
3
3
 
4
+ // src/exporters/retry.ts
5
+ var RETRY_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
6
+ var TOO_LARGE_STATUS = 413;
7
+ var RETRY_BACKOFF_BASE_S = 1;
8
+ var RETRY_BACKOFF_CAP_S = 30;
9
+ var DEFAULT_RETRY_HORIZON_S = 300;
10
+ var DEFAULT_SHUTDOWN_TIMEOUT_S = 10;
11
+ var RETRY_WARN_AFTER_ATTEMPTS = 3;
12
+ var jitter = { fraction: () => Math.random() };
13
+ function backoffDelayS(retryNumber, fraction) {
14
+ const exponent = Math.min(Math.max(retryNumber, 0), 62);
15
+ const ceiling = Math.min(RETRY_BACKOFF_CAP_S, RETRY_BACKOFF_BASE_S * 2 ** exponent);
16
+ return Math.min(Math.max(fraction, 0), 1) * ceiling;
17
+ }
18
+ var SECONDS = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
19
+ function parseRetryAfterS(value, nowMs = Date.now()) {
20
+ if (value === null || value === void 0) return null;
21
+ const text = String(value).trim();
22
+ if (text === "") return null;
23
+ if (SECONDS.test(text)) {
24
+ const seconds = Number(text);
25
+ return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
26
+ }
27
+ if (!/[A-Za-z]/.test(text)) return null;
28
+ const when = Date.parse(text);
29
+ if (!Number.isFinite(when)) return null;
30
+ return Math.max(0, (when - nowMs) / 1e3);
31
+ }
32
+
4
33
  // src/globals.ts
5
34
  import { AsyncLocalStorage } from "async_hooks";
6
35
  var G = globalThis;
@@ -147,10 +176,24 @@ var VALUE_RULE_PREFIXES = new Set(
147
176
  );
148
177
 
149
178
  // src/exporters/batch.ts
179
+ var SHUTDOWN_BUDGET_MS = DEFAULT_SHUTDOWN_TIMEOUT_S * 1e3;
150
180
  var MAX_TIMEOUT_MS = 2 ** 31 - 1;
151
181
  var MAX_BATCH_BYTES = 8 * 1024 * 1024;
152
182
  var utf8ByteLength = typeof Buffer !== "undefined" && typeof Buffer.byteLength === "function" ? (s) => Buffer.byteLength(s, "utf8") : (s) => s.length * 3;
153
183
 
184
+ // src/context/storage.ts
185
+ function storage() {
186
+ return getContextStorage();
187
+ }
188
+ function getContext() {
189
+ return storage().getStore() ?? {};
190
+ }
191
+ function runWithContext(overrides, fn) {
192
+ const parent = getContext();
193
+ const merged = { ...parent, ...overrides };
194
+ return storage().run(merged, fn);
195
+ }
196
+
154
197
  // src/ids.ts
155
198
  import { randomBytes } from "crypto";
156
199
 
@@ -281,21 +324,8 @@ var SUPPLEMENTAL_RULES = [
281
324
  { re: new RegExp("json|syntaxerror|unexpected token|decodeerror", "u"), code: "PERCEPTION.PARSING.JSON_INVALID" }
282
325
  ];
283
326
 
284
- // src/context/storage.ts
285
- function storage() {
286
- return getContextStorage();
287
- }
288
- function getContext() {
289
- return storage().getStore() ?? {};
290
- }
291
- function runWithContext(overrides, fn) {
292
- const parent = getContext();
293
- const merged = { ...parent, ...overrides };
294
- return storage().run(merged, fn);
295
- }
296
-
297
327
  // src/version.ts
298
- var SDK_VERSION = "0.10.0";
328
+ var SDK_VERSION = "0.11.0";
299
329
 
300
330
  // src/exporters/quota.ts
301
331
  var QUOTA_REASON = "monthly_quota_exceeded";
@@ -403,12 +433,18 @@ var QuotaPause = class {
403
433
 
404
434
  // src/exporters/http.ts
405
435
  var CAPACITY_REFUSAL_STATUSES = /* @__PURE__ */ new Set([429, 503]);
406
- var RETRY_AFTER_CEILING_MS = 1e4;
407
- var REFUSAL_BACKOFF_BASE_MS = 1e3;
408
- var REFUSAL_NO_HINT = -1;
409
436
  var MISROUTE_WARN_WINDOW_MS = 3e5;
410
437
  var AUTH_REFUSAL_STATUSES = /* @__PURE__ */ new Set([401, 403]);
411
438
  var FAILURE_WARN_WINDOW_MS = 3e5;
439
+ var MAX_TIMER_MS = 2 ** 31 - 1;
440
+ function validHorizonS(value) {
441
+ if (value === void 0) return DEFAULT_RETRY_HORIZON_S;
442
+ if (typeof value === "number" && Number.isFinite(value) && value >= 0) return value;
443
+ warn(
444
+ `Risicare: retryHorizonS=${String(value)} is not a finite number of 0 or more; using the default, ${DEFAULT_RETRY_HORIZON_S} s.`
445
+ );
446
+ return DEFAULT_RETRY_HORIZON_S;
447
+ }
412
448
  var HttpExporter = class {
413
449
  name = "http";
414
450
  _endpoint;
@@ -418,20 +454,28 @@ var HttpExporter = class {
418
454
  _timeoutMs;
419
455
  _maxRetries;
420
456
  _compress;
457
+ _retryHorizonS;
458
+ /** Total HTTP requests that this exporter sent (each retry and each half of a split counts). */
459
+ attempts = 0;
421
460
  // Circuit breaker (CON-201 / B-16). Threshold and cooldown sized for
422
- // a "30-second prod restart" scenario: with default 1s batch flush a
423
- // 5-failure threshold opens the circuit ~5s into an outage and the 60s
424
- // cooldown gives the gateway time to come back before the half-open
425
- // probe fires. Lower numbers (was 3@30s) tripped on transient blips.
461
+ // a "30-second prod restart" scenario. Since W2-1c only answers that a retry
462
+ // cannot change move it (see the block above).
426
463
  _consecutiveFailures = 0;
427
464
  _lastMisrouteWarnAt = -Infinity;
428
465
  _lastFailureWarnAt = -Infinity;
466
+ _lastExhaustedWarnAt = -Infinity;
467
+ /** "log once" (W2-1c): the WARNING for a `too_large` drop is written one time. */
468
+ _tooLargeWarned = false;
429
469
  /**
430
470
  * The kind of failure that the last outage WARNING named ('auth', 'http', 'none',
431
471
  * 'unknown'). `null` after a success. A new kind in the same outage writes one more
432
472
  * WARNING, also inside the window.
433
473
  */
434
474
  _failureKind = null;
475
+ /** `endRetries()` was called, and `shutdown()` has not run since. */
476
+ _noWait = false;
477
+ /** The wake-ups of the backoff waits in progress. `endRetries()` calls each one. */
478
+ _waits = /* @__PURE__ */ new Set();
435
479
  /** The endpoint as a log line may show it: no userinfo, no query (see `safeUrl`). */
436
480
  _safeEndpoint;
437
481
  /** The endpoint holds userinfo. `fetch` refuses such a URL. */
@@ -442,6 +486,8 @@ var HttpExporter = class {
442
486
  _acks = /* @__PURE__ */ new WeakMap();
443
487
  /** The requests that each finished call sent, by its batch. Read once by `takeAttempts(spans)`. */
444
488
  _requests = /* @__PURE__ */ new WeakMap();
489
+ /** The drop reason of each failed call, by its batch. Read once by `takeDropReason(spans)`. */
490
+ _dropReasons = /* @__PURE__ */ new WeakMap();
445
491
  /** The batch processor dropped span(s) from a full queue in the quota pause (S-1). */
446
492
  noteQuotaDrop(count = 1) {
447
493
  this._quota.addDrops(count);
@@ -466,8 +512,16 @@ var HttpExporter = class {
466
512
  this._projectId = options.projectId;
467
513
  this._environment = options.environment;
468
514
  this._timeoutMs = options.timeoutMs ?? 5e3;
469
- this._maxRetries = options.maxRetries ?? 3;
515
+ let maxRetries = options.maxRetries;
516
+ if (maxRetries !== void 0 && !(Number.isInteger(maxRetries) && maxRetries >= 1)) {
517
+ warn(
518
+ `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).`
519
+ );
520
+ maxRetries = void 0;
521
+ }
522
+ this._maxRetries = maxRetries;
470
523
  this._compress = options.compress ?? false;
524
+ this._retryHorizonS = validHorizonS(options.retryHorizonS);
471
525
  this._safeEndpoint = safeUrl(this._endpoint);
472
526
  this._endpointHasCredentials = hasCredentials(this._endpoint);
473
527
  }
@@ -489,16 +543,18 @@ var HttpExporter = class {
489
543
  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
490
544
  return `HttpExporter { endpoint: '${this._safeEndpoint}' }`;
491
545
  }
492
- /** The most requests that one `export()` call sends (`maxRetries`). */
546
+ /**
547
+ * The most attempts for one request body (`maxRetries`). `undefined` when no count is set:
548
+ * the retry horizon is the limit.
549
+ */
493
550
  get attemptsPerExport() {
494
551
  return this._maxRetries;
495
552
  }
496
553
  /**
497
554
  * Returns the number of HTTP requests that the `export()` call for `spans` sent, and clears
498
- * it. This is the number that was sent, not the most that the call may send
499
- * (`attemptsPerExport`): a 401 or 403 stops the loop after one request, and an open circuit
500
- * breaker sends none. Returns `null` when no call is on record for `spans`. The answer is
501
- * kept per batch, as `takeAck` keeps the ack.
555
+ * it. Each retry and each half of a 413 split counts one; a call that the open circuit
556
+ * breaker or the quota pause stops sends none. Returns `null` when no call is on record for
557
+ * `spans`. The answer is kept per batch, as `takeAck` keeps the ack.
502
558
  */
503
559
  takeAttempts(spans) {
504
560
  const n = this._requests.get(spans) ?? null;
@@ -515,6 +571,12 @@ var HttpExporter = class {
515
571
  this._acks.delete(spans);
516
572
  return ack;
517
573
  }
574
+ /** Returns why the `export()` call for `spans` failed (W2-1c), and clears it. See `SpanExporter`. */
575
+ takeDropReason(spans) {
576
+ const reason = this._dropReasons.get(spans) ?? null;
577
+ this._dropReasons.delete(spans);
578
+ return reason;
579
+ }
518
580
  /** Returns the spans of `spans` that could not be serialized and were not sent, and clears them. */
519
581
  takeUnserializable(spans) {
520
582
  const bad = this._unserializable.get(spans) ?? [];
@@ -523,7 +585,7 @@ var HttpExporter = class {
523
585
  }
524
586
  /**
525
587
  * Cancel the `export()` call for `spans` (all calls when `spans` is not given): its
526
- * request, its retries and its backoff sleep. The batch processor calls it when
588
+ * request, its retries and its backoff wait. The batch processor calls it when
527
589
  * `shutdown()` abandons the batch, so that the call does not keep the process alive. The
528
590
  * cancelled call returns FAILURE, changes no counter (the circuit breaker included) and
529
591
  * logs no WARNING.
@@ -533,24 +595,39 @@ var HttpExporter = class {
533
595
  else for (const call of this._calls.values()) call.cancel.abort();
534
596
  }
535
597
  /**
536
- * Send one batch. The limits are the request timeout and `maxRetries`.
598
+ * End the retry waits of this exporter until its next `shutdown()`. The batch processor
599
+ * calls it when `shutdown()` starts. A call that waits for a retry makes one more attempt
600
+ * at once. An attempt that fails after this is not retried: the call fails with the drop
601
+ * reason `shutdown_residue`. So a drain against a dead endpoint costs one attempt for each
602
+ * batch, not the shutdown budget.
603
+ */
604
+ endRetries() {
605
+ this._noWait = true;
606
+ for (const wake of [...this._waits]) wake();
607
+ }
608
+ /**
609
+ * Send one batch, with the W2-1c retry policy (see the block above the class).
610
+ *
611
+ * Resolves SUCCESS when the backend accounted for the batch: `takeAck` has the counts (and
612
+ * the spans that a 413 split dropped, in `dropped`). Resolves FAILURE when no span was
613
+ * accounted for: `takeDropReason` then says why, and the batch processor drops the batch
614
+ * with that reason.
537
615
  *
538
616
  * ⚠ NO CALLER BUDGET. `flush(timeoutMs)` only stops WAITING at its deadline; it never
539
- * cuts a request that is already sent. A short flush budget that cut the request made a
540
- * healthy, slow server look like a failure: the span used a retry, the breaker moved, and
541
- * the server stored the same spans again. Only `abort()` stops the call, and only
617
+ * cuts a request that is already sent. Only `abort()` stops the call, and only
542
618
  * `shutdown()` calls it.
543
619
  */
544
620
  async export(spans) {
545
621
  if (spans.length === 0) return "success" /* SUCCESS */;
546
622
  const call = {
547
623
  cancel: new AbortController(),
548
- refusalAfterMs: null,
624
+ retryAfterS: null,
549
625
  misroute: null,
550
626
  noRetry: false,
551
627
  status: null,
552
628
  error: null,
553
- attempts: 0
629
+ attempts: 0,
630
+ ack: null
554
631
  };
555
632
  this._calls.set(spans, call);
556
633
  try {
@@ -587,83 +664,236 @@ var HttpExporter = class {
587
664
  );
588
665
  }
589
666
  if (parts.length === 0) return "success" /* SUCCESS */;
590
- const payload = `{"spans":[${parts.join(",")}]` + (this._projectId ? `,"projectId":${JSON.stringify(this._projectId)}` : "") + (this._environment ? `,"environment":${JSON.stringify(this._environment)}` : "") + "}";
591
- const now = Date.now();
592
- let isHalfOpen = false;
593
- if (this._consecutiveFailures >= this._circuitBreakerThreshold) {
594
- if (now < this._circuitOpenUntil) {
595
- return "failure" /* FAILURE */;
667
+ if (this._consecutiveFailures >= this._circuitBreakerThreshold && Date.now() < this._circuitOpenUntil) {
668
+ this._dropReasons.set(spans, "transport_refused");
669
+ return "failure" /* FAILURE */;
670
+ }
671
+ const out = { delivered: [], dropped: {}, failed: [], cancelled: false };
672
+ const start = performance.now();
673
+ await this._deliver(parts, start, call, out, true);
674
+ if (cancelled.aborted || out.cancelled) {
675
+ this._acks.delete(spans);
676
+ return "failure" /* FAILURE */;
677
+ }
678
+ return this._finish(spans, out, call.attempts);
679
+ }
680
+ /** The request body for `parts` (the serialized spans of one part of a batch). */
681
+ _payload(parts) {
682
+ return `{"spans":[${parts.join(",")}]` + (this._projectId ? `,"projectId":${JSON.stringify(this._projectId)}` : "") + (this._environment ? `,"environment":${JSON.stringify(this._environment)}` : "") + "}";
683
+ }
684
+ /**
685
+ * Send one part of a batch with the retry policy, and record its outcome in `out`.
686
+ * `maySplit` is true only for the whole batch: a 413 splits it in two one time. A half
687
+ * that gets 413 again is dropped as `too_large`.
688
+ */
689
+ async _deliver(parts, start, call, out, maySplit) {
690
+ const n = parts.length;
691
+ if (!maySplit && this._quota.paused()) {
692
+ out.delivered.push({ n, ack: { accepted: 0, rejected: 0, quotaDropped: n } });
693
+ return;
694
+ }
695
+ const result = await this._sendWithRetries(this._payload(parts), n, start, call);
696
+ if (result.kind === "delivered") {
697
+ out.delivered.push({ n, ack: result.ack });
698
+ } else if (result.kind === "too_large") {
699
+ if (maySplit && n > 1) {
700
+ const mid = Math.ceil(n / 2);
701
+ debug(`Ingest answered HTTP 413 for ${n} span(s): sending two halves of ${mid} and ${n - mid}`);
702
+ await this._deliver(parts.slice(0, mid), start, call, out, false);
703
+ if (!out.cancelled) await this._deliver(parts.slice(mid), start, call, out, false);
704
+ } else {
705
+ out.dropped.too_large = (out.dropped.too_large ?? 0) + n;
596
706
  }
597
- isHalfOpen = true;
707
+ } else if (result.kind === "cancelled") {
708
+ out.cancelled = true;
709
+ } else {
710
+ out.failed.push({ n, reason: result.kind, answer: result.answer });
598
711
  }
599
- const maxAttempts = isHalfOpen ? 1 : this._maxRetries;
600
- for (let attempt = 0; attempt < maxAttempts; attempt++) {
601
- call.refusalAfterMs = null;
712
+ }
713
+ /** Send one request body until it is delivered or the policy stops. */
714
+ async _sendWithRetries(body, spansSent, start, call) {
715
+ const cancelled = call.cancel.signal;
716
+ let retryNumber = 0;
717
+ let attemptsHere = 0;
718
+ for (; ; ) {
719
+ if (cancelled.aborted) return { kind: "cancelled" };
720
+ call.retryAfterS = null;
602
721
  call.misroute = null;
603
722
  call.noRetry = false;
604
723
  call.status = null;
605
724
  call.error = null;
725
+ call.ack = null;
606
726
  call.attempts++;
607
- const result = await this._sendRequest(payload, parts.length, call, spans);
608
- if (cancelled.aborted) {
609
- this._acks.delete(spans);
610
- return "failure" /* FAILURE */;
727
+ attemptsHere++;
728
+ this.attempts++;
729
+ const result = await this._sendRequest(body, spansSent, call);
730
+ if (cancelled.aborted) return { kind: "cancelled" };
731
+ if (result === "success" /* SUCCESS */) return { kind: "delivered", ack: call.ack };
732
+ if (call.status === TOO_LARGE_STATUS) return { kind: "too_large" };
733
+ const answer = {
734
+ status: call.status,
735
+ error: call.error,
736
+ misroute: call.misroute,
737
+ zeroAck: call.noRetry,
738
+ sent: spansSent
739
+ };
740
+ if (!this._retryable(call)) return { kind: "transport_refused", answer };
741
+ if (attemptsHere === RETRY_WARN_AFTER_ATTEMPTS) this._warnOutage(answer, true);
742
+ if (this._noWait) return { kind: "shutdown_residue", answer };
743
+ if (this._maxRetries !== void 0 && attemptsHere >= this._maxRetries) {
744
+ return { kind: "retry_exhausted", answer };
611
745
  }
612
- if (result === "success" /* SUCCESS */) {
613
- this._consecutiveFailures = 0;
614
- this._failureKind = null;
615
- return result;
616
- }
617
- if (call.misroute !== null || call.noRetry) break;
618
- if (call.status !== null && AUTH_REFUSAL_STATUSES.has(call.status)) break;
619
- if (attempt < maxAttempts - 1) {
620
- const refusal = call.refusalAfterMs;
621
- const delay = refusal === null ? 100 * Math.pow(2, attempt) : refusal === REFUSAL_NO_HINT ? REFUSAL_BACKOFF_BASE_MS * Math.pow(2, attempt) : refusal;
622
- await sleep(delay, cancelled);
623
- if (cancelled.aborted) return "failure" /* FAILURE */;
746
+ const remainingS = this._retryHorizonS - (performance.now() - start) / 1e3;
747
+ if (remainingS <= 0) return { kind: "retry_exhausted", answer };
748
+ const hint = call.retryAfterS;
749
+ const waitS = hint !== null && hint > 0 ? hint : backoffDelayS(retryNumber, jitter.fraction());
750
+ const delayS = Math.min(waitS, remainingS);
751
+ retryNumber++;
752
+ debug(
753
+ `Ingest attempt ${attemptsHere} failed (${answer.status ?? answer.error ?? "unknown"}); next attempt in ${delayS.toFixed(2)} s (${Math.round(remainingS)} s of the horizon left)`
754
+ );
755
+ await this._retryWait(delayS * 1e3, cancelled);
756
+ }
757
+ }
758
+ /** True when the answer of the last attempt of `call` can change on a retry. */
759
+ _retryable(call) {
760
+ if (call.misroute !== null || call.noRetry) return false;
761
+ if (call.status !== null) return RETRY_STATUSES.has(call.status);
762
+ if (this._endpointHasCredentials) return false;
763
+ return call.error !== null;
764
+ }
765
+ /**
766
+ * Wait `ms` before the next attempt. `abort()` and `endRetries()` end the wait at once. The
767
+ * timer does not keep the process alive: when nothing else runs, `beforeExit` starts the
768
+ * SDK's `shutdown()`, which ends the wait.
769
+ */
770
+ _retryWait(ms, signal) {
771
+ return new Promise((resolve) => {
772
+ if (signal.aborted || this._noWait || ms <= 0) return resolve();
773
+ const done = () => {
774
+ clearTimeout(timer);
775
+ signal.removeEventListener("abort", done);
776
+ this._waits.delete(done);
777
+ resolve();
778
+ };
779
+ const timer = setTimeout(done, Math.min(ms, MAX_TIMER_MS));
780
+ timer.unref?.();
781
+ signal.addEventListener("abort", done, { once: true });
782
+ this._waits.add(done);
783
+ });
784
+ }
785
+ /** Turn the outcome of the parts of one batch into the result of `export()`. */
786
+ _finish(spans, out, attempts) {
787
+ const reasons = new Set(out.failed.map((f) => f.reason));
788
+ if (out.delivered.length === 0 && Object.keys(out.dropped).length === 0 && reasons.size === 1) {
789
+ const reason = out.failed[0].reason;
790
+ const nFailed = out.failed.reduce((sum, f) => sum + f.n, 0);
791
+ this._dropReasons.set(spans, reason);
792
+ return this._fail(reason, out.failed[out.failed.length - 1].answer, nFailed, attempts);
793
+ }
794
+ let ack;
795
+ if (out.delivered.length === 1 && Object.keys(out.dropped).length === 0 && out.failed.length === 0) {
796
+ ack = out.delivered[0].ack;
797
+ } else {
798
+ let accepted = 0;
799
+ let rejected = 0;
800
+ let quotaDropped = 0;
801
+ for (const part of out.delivered) {
802
+ accepted += part.ack !== null ? part.ack.accepted : part.n;
803
+ rejected += part.ack !== null ? part.ack.rejected : 0;
804
+ quotaDropped += part.ack?.quotaDropped ?? 0;
624
805
  }
806
+ const dropped = { ...out.dropped };
807
+ for (const f of out.failed) dropped[f.reason] = (dropped[f.reason] ?? 0) + f.n;
808
+ ack = { accepted, rejected };
809
+ if (quotaDropped > 0) ack.quotaDropped = quotaDropped;
810
+ if (Object.keys(dropped).length > 0) ack.dropped = dropped;
625
811
  }
626
- if (call.refusalAfterMs !== null) {
627
- warn(
628
- `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.`
629
- );
812
+ if (ack !== null) this._acks.set(spans, ack);
813
+ this._consecutiveFailures = 0;
814
+ this._failureKind = null;
815
+ const tooLarge = out.dropped.too_large ?? 0;
816
+ if (tooLarge > 0) this._warnTooLarge(tooLarge);
817
+ for (const f of out.failed) {
818
+ if (f.reason === "retry_exhausted") this._warnExhausted(f.n, attempts, f.answer);
819
+ }
820
+ return "success" /* SUCCESS */;
821
+ }
822
+ /** End a call in which no span was accounted for. Always returns FAILURE. */
823
+ _fail(reason, answer, nSpans, attempts) {
824
+ if (reason === "shutdown_residue") {
825
+ debug(`Export ended by shutdown after ${attempts} attempt(s)`);
630
826
  return "failure" /* FAILURE */;
631
827
  }
632
- const misroute = call.misroute;
633
- if (misroute !== null && Date.now() - this._lastMisrouteWarnAt > MISROUTE_WARN_WINDOW_MS) {
634
- this._lastMisrouteWarnAt = Date.now();
635
- warn(
636
- `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.`
637
- );
828
+ if (reason === "retry_exhausted") {
829
+ if (answer.status === null || !CAPACITY_REFUSAL_STATUSES.has(answer.status)) this._stepBreaker();
830
+ this._warnOutage(answer, true);
831
+ this._warnExhausted(nSpans, attempts, answer);
832
+ return "failure" /* FAILURE */;
638
833
  }
834
+ this._stepBreaker();
835
+ this._warnOutage(answer, false);
836
+ return "failure" /* FAILURE */;
837
+ }
838
+ /** Count one failed call toward the circuit breaker. */
839
+ _stepBreaker() {
639
840
  this._consecutiveFailures++;
640
- if (misroute === null && !call.noRetry) {
641
- const status = call.status;
642
- const kind = status !== null && AUTH_REFUSAL_STATUSES.has(status) ? "auth" : status !== null ? "http" : call.error !== null ? "none" : "unknown";
643
- let write = false;
644
- if (this._consecutiveFailures === 1 || this._failureKind === null) {
645
- if (Date.now() - this._lastFailureWarnAt > FAILURE_WARN_WINDOW_MS) {
646
- this._lastFailureWarnAt = Date.now();
647
- write = true;
648
- }
649
- this._failureKind = kind;
650
- } else if (kind !== this._failureKind) {
651
- this._failureKind = kind;
652
- write = true;
653
- }
654
- if (write) this._warnOutage(kind, status, call.error);
655
- }
656
841
  if (this._consecutiveFailures >= this._circuitBreakerThreshold) {
657
842
  this._circuitOpenUntil = Date.now() + this._circuitBreakerCooldownMs;
658
843
  warn(
659
844
  `HTTP exporter circuit breaker opened after ${this._consecutiveFailures} failures. Cooldown: ${this._circuitBreakerCooldownMs / 1e3}s`
660
845
  );
661
846
  }
662
- return "failure" /* FAILURE */;
663
847
  }
664
- /** The outage WARNING for one kind of failure. */
665
- _warnOutage(kind, status, error) {
848
+ /**
849
+ * The outage WARNING: at the first failure of an outage, and when its kind changes. At most
850
+ * one in the window for the first failure; a misroute has its own WARNING, at most one in
851
+ * the window. `retrying` is true for a retryable answer (written after
852
+ * `RETRY_WARN_AFTER_ATTEMPTS` failed attempts of one batch, or when its retries end before
853
+ * that), false for an answer that a retry cannot change (one attempt). The WARNING names the last HTTP status, or the error
854
+ * code when there was no answer. It never names the key or the response body, and names
855
+ * the API key as a cause only for a 401 or 403. An ack of 0 and 0 has its WARNING from
856
+ * `checkAck`.
857
+ */
858
+ _warnOutage(answer, retrying) {
859
+ if (answer.misroute !== null) {
860
+ if (Date.now() - this._lastMisrouteWarnAt > MISROUTE_WARN_WINDOW_MS) {
861
+ this._lastMisrouteWarnAt = Date.now();
862
+ warn(
863
+ `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.`
864
+ );
865
+ }
866
+ return;
867
+ }
868
+ if (answer.zeroAck) return;
869
+ const status = answer.status;
870
+ const kind = status !== null && AUTH_REFUSAL_STATUSES.has(status) ? "auth" : status !== null ? "http" : answer.error !== null ? "none" : "unknown";
871
+ let write = false;
872
+ if (this._failureKind === null || !retrying && this._consecutiveFailures === 1) {
873
+ if (Date.now() - this._lastFailureWarnAt > FAILURE_WARN_WINDOW_MS) {
874
+ this._lastFailureWarnAt = Date.now();
875
+ write = true;
876
+ }
877
+ this._failureKind = kind;
878
+ } else if (kind !== this._failureKind) {
879
+ this._failureKind = kind;
880
+ write = true;
881
+ }
882
+ if (!write) return;
666
883
  const where = `Risicare: spans are NOT reaching ${this._safeEndpoint}`;
884
+ if (retrying) {
885
+ let limit = `${this._retryHorizonS} s from its first attempt (retryHorizonS)`;
886
+ if (this._maxRetries !== void 0) limit = `${this._maxRetries} attempt(s) (maxRetries) or ${limit}`;
887
+ const retryText = `The SDK sends each batch again with a growing wait, for up to ${limit}, and then drops it (reason=retry_exhausted).`;
888
+ if (kind === "http") {
889
+ warn(`${where}: it answered HTTP ${status}. ${retryText} Set debug: true to see each attempt.`);
890
+ } else {
891
+ warn(
892
+ `${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.`
893
+ );
894
+ }
895
+ return;
896
+ }
667
897
  const tail = "Tracing continues, but the SDK drops the spans that it cannot send.";
668
898
  if (kind === "auth") {
669
899
  warn(
@@ -671,15 +901,11 @@ var HttpExporter = class {
671
901
  );
672
902
  } else if (kind === "http") {
673
903
  warn(
674
- `${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.`
904
+ `${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.`
675
905
  );
676
906
  } else if (kind === "none" && this._endpointHasCredentials) {
677
907
  warn(
678
- `${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}`
679
- );
680
- } else if (kind === "none") {
681
- warn(
682
- `${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.`
908
+ `${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}`
683
909
  );
684
910
  } else {
685
911
  warn(
@@ -687,33 +913,38 @@ var HttpExporter = class {
687
913
  );
688
914
  }
689
915
  }
916
+ /** The WARNING for spans dropped as `retry_exhausted`. At most one in the window. */
917
+ _warnExhausted(nSpans, attempts, answer) {
918
+ if (Date.now() - this._lastExhaustedWarnAt <= FAILURE_WARN_WINDOW_MS) return;
919
+ this._lastExhaustedWarnAt = Date.now();
920
+ const last = answer.status !== null ? `HTTP ${answer.status}` : `no answer (${answer.error})`;
921
+ const capacity = answer.status !== null && CAPACITY_REFUSAL_STATUSES.has(answer.status) ? " (over capacity)" : "";
922
+ 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)`;
923
+ warn(
924
+ `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.`
925
+ );
926
+ }
927
+ /** The WARNING for spans dropped as `too_large`. One time for each exporter. */
928
+ _warnTooLarge(nSpans) {
929
+ if (this._tooLargeWarned) return;
930
+ this._tooLargeWarned = true;
931
+ warn(
932
+ `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.`
933
+ );
934
+ }
690
935
  /** Record a MISROUTE for the retry loop and the breaker. Always returns FAILURE. */
691
936
  _noteMisroute(call, answer) {
692
937
  call.misroute = this._scrub(answer, 300);
693
938
  debug(`Ingest misroute: ${call.misroute}`);
694
939
  return "failure" /* FAILURE */;
695
940
  }
696
- /**
697
- * Record a CAPACITY REFUSAL for the retry loop. Returns true if it was one.
698
- *
699
- * `Retry-After` is honoured only in its delta-seconds form (RFC 9110 §10.2.3 also permits an
700
- * HTTP-date); anything else falls back to our own backoff rather than guessing at a date
701
- * parse.
702
- */
703
- _noteRefusal(call, status, retryAfterRaw) {
704
- if (!CAPACITY_REFUSAL_STATUSES.has(status)) return false;
705
- let delay = REFUSAL_NO_HINT;
706
- if (retryAfterRaw) {
707
- const secs = Number(retryAfterRaw);
708
- if (Number.isFinite(secs) && secs >= 0) {
709
- delay = Math.min(secs * 1e3, RETRY_AFTER_CEILING_MS);
710
- }
711
- }
712
- call.refusalAfterMs = delay;
713
- debug(`Ingest refused for capacity: HTTP ${status} (Retry-After=${this._scrub(retryAfterRaw)})`);
714
- return true;
941
+ /** Record the `Retry-After` wait of a retryable answer for the retry loop. */
942
+ _noteRetryAfter(call, status, retryAfterRaw) {
943
+ if (!RETRY_STATUSES.has(status)) return;
944
+ call.retryAfterS = parseRetryAfterS(retryAfterRaw);
945
+ debug(`Ingest answered HTTP ${status} (Retry-After=${this._scrub(retryAfterRaw)})`);
715
946
  }
716
- async _sendRequest(body, spansSent, call, spans) {
947
+ async _sendRequest(body, spansSent, call) {
717
948
  const cancelled = call.cancel.signal;
718
949
  const timeoutMs = this._timeoutMs;
719
950
  const url = `${this._endpoint}/v1/spans`;
@@ -781,14 +1012,15 @@ var HttpExporter = class {
781
1012
  } else if (ack.result === "success" /* SUCCESS */) {
782
1013
  this._quota.accepted(`the ingest endpoint ${this._safeEndpoint}`);
783
1014
  }
784
- if (ack.result === "success" /* SUCCESS */) this._acks.set(spans, ack.counts);
1015
+ if (ack.result === "success" /* SUCCESS */) call.ack = ack.counts;
785
1016
  if (ack.final) call.noRetry = true;
786
1017
  return ack.result;
787
- } else if (response.status === 408 || response.status === 504) {
1018
+ }
1019
+ this._noteRetryAfter(call, response.status, response.headers?.get?.("Retry-After") ?? null);
1020
+ if (response.status === 408 || response.status === 504) {
788
1021
  debug(`HTTP export timeout: ${response.status}`);
789
1022
  return "timeout" /* TIMEOUT */;
790
1023
  }
791
- this._noteRefusal(call, response.status, response.headers.get("Retry-After"));
792
1024
  debug(`HTTP export failed: ${response.status}`);
793
1025
  return "failure" /* FAILURE */;
794
1026
  } catch (e) {
@@ -802,20 +1034,9 @@ var HttpExporter = class {
802
1034
  }
803
1035
  }
804
1036
  shutdown() {
1037
+ this._noWait = false;
805
1038
  }
806
1039
  };
807
- function sleep(ms, signal) {
808
- return new Promise((resolve) => {
809
- if (signal?.aborted) return resolve();
810
- const done = () => {
811
- clearTimeout(timer);
812
- signal?.removeEventListener("abort", done);
813
- resolve();
814
- };
815
- const timer = setTimeout(done, ms);
816
- signal?.addEventListener("abort", done, { once: true });
817
- });
818
- }
819
1040
  function asCount(v) {
820
1041
  return typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : void 0;
821
1042
  }