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/README.md CHANGED
@@ -487,6 +487,24 @@ const result = await withSession(
487
487
  `session()` does not run the callback. It returns a wrapped function, which you
488
488
  call later, for example once for each request.
489
489
 
490
+ ## What happens at the Free quota
491
+
492
+ Each plan has a monthly event quota. When your organisation has used it, the Risicare
493
+ backend discards new spans until the quota resets (the first day of the next UTC month),
494
+ or until you upgrade or buy an event pack. Nothing throws in your application, and
495
+ tracing continues.
496
+
497
+ The SDK treats this as a state, not an error (0.9.1 and later). It writes one WARNING
498
+ that names the reset time, and it stops sending. It sends one batch again every 5 minutes (the
499
+ `retryAfterSeconds` that the backend returns; it does not wait for the reset time). Spans that
500
+ end in the meantime wait in the SDK queue, which has a fixed size: when it is full, the oldest
501
+ spans are dropped and the most recent are kept. `flush()` returns false at once in this time, and
502
+ does not wait for its timeout. When the backend accepts a batch again, the SDK writes one INFO and sends the queued spans, so an upgrade takes effect
503
+ within minutes and nothing new is lost unless the queue overflows. While the quota stays used
504
+ up, it writes at most one WARNING an hour. A batch that the backend discards, and a span that
505
+ the full queue drops in the pause, are counted in `getMetrics().droppedQuota` (the same number as
506
+ `droppedSpansByReason.quota_exceeded`). They are also in the flat dropped total, and not in `rejectedSpans`. They are not stored.
507
+
490
508
  ## Known limitation — span loss during a backend outage
491
509
 
492
510
  The SDK does **not** keep spans through a long outage of the Risicare backend.
@@ -59,6 +59,10 @@ function warn(msg) {
59
59
  process.stderr.write(`[risicare] WARNING: ${msg}
60
60
  `);
61
61
  }
62
+ function info(msg) {
63
+ process.stderr.write(`[risicare] INFO: ${msg}
64
+ `);
65
+ }
62
66
 
63
67
  // src/utils/text.ts
64
68
  function cutCodePoints(text, max) {
@@ -263,7 +267,111 @@ var SUPPLEMENTAL_RULES = [
263
267
  ];
264
268
 
265
269
  // src/version.ts
266
- var SDK_VERSION = "0.9.0";
270
+ var SDK_VERSION = "0.9.2";
271
+
272
+ // src/exporters/quota.ts
273
+ var QUOTA_REASON = "monthly_quota_exceeded";
274
+ var QUOTA_HEADER = "X-Risicare-Quota";
275
+ var QUOTA_HEADER_VALUE = "exceeded";
276
+ var DEFAULT_RETRY_AFTER_S = 300;
277
+ var MIN_RETRY_AFTER_S = 1;
278
+ var MAX_RETRY_AFTER_S = 3600;
279
+ var QUOTA_WARN_WINDOW_MS = 36e5;
280
+ var MAX_RESETS_AT_CHARS = 40;
281
+ function asPositiveCount(v) {
282
+ if (typeof v === "number") return Number.isFinite(v) && v > 0;
283
+ if (typeof v === "string" && /^[0-9]+$/.test(v)) return Number(v) > 0;
284
+ return false;
285
+ }
286
+ function boundedRetryAfter(value) {
287
+ let n;
288
+ if (typeof value === "number") n = value;
289
+ else if (typeof value === "string" && value.trim() !== "") n = Number(value);
290
+ else return DEFAULT_RETRY_AFTER_S;
291
+ if (!Number.isFinite(n)) return DEFAULT_RETRY_AFTER_S;
292
+ return Math.min(Math.max(n, MIN_RETRY_AFTER_S), MAX_RETRY_AFTER_S);
293
+ }
294
+ function boundedResetsAt(value) {
295
+ if (typeof value !== "string" || value.length === 0) return null;
296
+ const cut = value.slice(0, MAX_RESETS_AT_CHARS);
297
+ return /^[ -~]*$/.test(cut) ? cut : null;
298
+ }
299
+ function headerSaysExceeded(headers) {
300
+ try {
301
+ const value = headers?.get?.(QUOTA_HEADER);
302
+ return typeof value === "string" && value.trim().toLowerCase() === QUOTA_HEADER_VALUE;
303
+ } catch {
304
+ return false;
305
+ }
306
+ }
307
+ function parseJsonDiscard(payload, headers) {
308
+ const body = payload !== null && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
309
+ const stored = (asPositiveCount(body.accepted) || asPositiveCount(body.spansAccepted)) === true;
310
+ if (body.reason === QUOTA_REASON || headerSaysExceeded(headers) && !stored) {
311
+ return {
312
+ retryAfterS: boundedRetryAfter(body.retryAfterSeconds),
313
+ resetsAt: boundedResetsAt(body.resetsAt)
314
+ };
315
+ }
316
+ return null;
317
+ }
318
+ var EPISODE_END_ACCEPTS = 3;
319
+ var QuotaPause = class {
320
+ constructor(now = () => performance.now()) {
321
+ this.now = now;
322
+ }
323
+ _until = -Infinity;
324
+ _inEpisode = false;
325
+ _accepts = 0;
326
+ _lastWarn = -Infinity;
327
+ _lastInfo = -Infinity;
328
+ /**
329
+ * Spans dropped since the last WARNING: the full queue's (`addDrops`) and the batches that a
330
+ * probe lost while the WARNING was held back. The WARNING carries the number.
331
+ */
332
+ _drops = 0;
333
+ addDrops(count) {
334
+ this._drops += count;
335
+ }
336
+ paused() {
337
+ return this.now() < this._until;
338
+ }
339
+ remainingS() {
340
+ return Math.max(0, (this._until - this.now()) / 1e3);
341
+ }
342
+ enter(discard, where, dropped) {
343
+ const t = this.now();
344
+ this._until = t + discard.retryAfterS * 1e3;
345
+ this._inEpisode = true;
346
+ this._accepts = 0;
347
+ if (t - this._lastWarn >= QUOTA_WARN_WINDOW_MS) {
348
+ this._lastWarn = t;
349
+ const since = this._drops;
350
+ this._drops = 0;
351
+ warn(
352
+ `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}.` : "")
353
+ );
354
+ } else {
355
+ this._drops += dropped;
356
+ debug(`Quota discard again: ${dropped} span(s); paused for ${Math.round(discard.retryAfterS)} s`);
357
+ }
358
+ }
359
+ accepted(where) {
360
+ if (!this._inEpisode) return;
361
+ this._accepts++;
362
+ if (this._accepts < EPISODE_END_ACCEPTS) return;
363
+ this._inEpisode = false;
364
+ this._accepts = 0;
365
+ this._until = -Infinity;
366
+ const t = this.now();
367
+ if (t - this._lastInfo >= QUOTA_WARN_WINDOW_MS) {
368
+ this._lastInfo = t;
369
+ info(`Risicare: ${where} accepts spans again; the export pause for the quota has ended.`);
370
+ } else {
371
+ debug("Quota pause ended (INFO already written this hour)");
372
+ }
373
+ }
374
+ };
267
375
 
268
376
  // src/exporters/http.ts
269
377
  var CAPACITY_REFUSAL_STATUSES = /* @__PURE__ */ new Set([429, 503]);
@@ -304,8 +412,23 @@ var HttpExporter = class {
304
412
  _calls = /* @__PURE__ */ new Map();
305
413
  /** The ack of each finished call, by its batch. Read once by `takeAck(spans)`. */
306
414
  _acks = /* @__PURE__ */ new WeakMap();
415
+ /** The requests that each finished call sent, by its batch. Read once by `takeAttempts(spans)`. */
416
+ _requests = /* @__PURE__ */ new WeakMap();
417
+ /** The batch processor dropped span(s) from a full queue in the quota pause (S-1). */
418
+ noteQuotaDrop(count = 1) {
419
+ this._quota.addDrops(count);
420
+ }
421
+ /** True while the exporter is paused for the monthly event quota (S-1). */
422
+ quotaPaused() {
423
+ return this._quota.paused();
424
+ }
307
425
  /** The spans of each finished call that could not be serialized, by its batch. */
308
426
  _unserializable = /* @__PURE__ */ new WeakMap();
427
+ /**
428
+ * S-1: the paused state after a monthly-quota discard (see `quota.ts`). A discard is not a
429
+ * failure: it does not touch the circuit breaker.
430
+ */
431
+ _quota = new QuotaPause();
309
432
  _circuitOpenUntil = 0;
310
433
  _circuitBreakerThreshold = 5;
311
434
  _circuitBreakerCooldownMs = 6e4;
@@ -342,6 +465,18 @@ var HttpExporter = class {
342
465
  get attemptsPerExport() {
343
466
  return this._maxRetries;
344
467
  }
468
+ /**
469
+ * Returns the number of HTTP requests that the `export()` call for `spans` sent, and clears
470
+ * it. This is the number that was sent, not the most that the call may send
471
+ * (`attemptsPerExport`): a 401 or 403 stops the loop after one request, and an open circuit
472
+ * breaker sends none. Returns `null` when no call is on record for `spans`. The answer is
473
+ * kept per batch, as `takeAck` keeps the ack.
474
+ */
475
+ takeAttempts(spans) {
476
+ const n = this._requests.get(spans) ?? null;
477
+ this._requests.delete(spans);
478
+ return n;
479
+ }
345
480
  /**
346
481
  * Returns the counts of the ack that the `export()` call for `spans` received, and clears
347
482
  * them. The answer is kept per batch, not on the instance: two processors that share this
@@ -386,17 +521,26 @@ var HttpExporter = class {
386
521
  misroute: null,
387
522
  noRetry: false,
388
523
  status: null,
389
- error: null
524
+ error: null,
525
+ attempts: 0
390
526
  };
391
527
  this._calls.set(spans, call);
392
528
  try {
393
529
  return await this._export(spans, call);
394
530
  } finally {
395
531
  this._calls.delete(spans);
532
+ this._requests.set(spans, this._endpointHasCredentials ? 0 : call.attempts);
396
533
  }
397
534
  }
398
535
  async _export(spans, call) {
399
536
  const cancelled = call.cancel.signal;
537
+ if (this._quota.paused()) {
538
+ debug(
539
+ `Export skipped: monthly quota pause, ${Math.round(this._quota.remainingS())} s left; ${spans.length} span(s) dropped`
540
+ );
541
+ this._acks.set(spans, { accepted: 0, rejected: 0, quotaDropped: spans.length });
542
+ return "success" /* SUCCESS */;
543
+ }
400
544
  const parts = [];
401
545
  const bad = [];
402
546
  let errorClass = "";
@@ -425,14 +569,13 @@ var HttpExporter = class {
425
569
  isHalfOpen = true;
426
570
  }
427
571
  const maxAttempts = isHalfOpen ? 1 : this._maxRetries;
428
- let attempts = 0;
429
572
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
430
573
  call.refusalAfterMs = null;
431
574
  call.misroute = null;
432
575
  call.noRetry = false;
433
576
  call.status = null;
434
577
  call.error = null;
435
- attempts++;
578
+ call.attempts++;
436
579
  const result = await this._sendRequest(payload, parts.length, call, spans);
437
580
  if (cancelled.aborted) {
438
581
  this._acks.delete(spans);
@@ -454,7 +597,7 @@ var HttpExporter = class {
454
597
  }
455
598
  if (call.refusalAfterMs !== null) {
456
599
  warn(
457
- `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.`
600
+ `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.`
458
601
  );
459
602
  return "failure" /* FAILURE */;
460
603
  }
@@ -605,6 +748,11 @@ var HttpExporter = class {
605
748
  `HTTP ${response.status} and a body that is not a Risicare ack (content-type: ${response.headers?.get?.("Content-Type") || "none"})`
606
749
  );
607
750
  }
751
+ if (ack.quota !== void 0) {
752
+ this._quota.enter(ack.quota, `The ingest endpoint ${this._safeEndpoint}`, spansSent);
753
+ } else if (ack.result === "success" /* SUCCESS */) {
754
+ this._quota.accepted(`the ingest endpoint ${this._safeEndpoint}`);
755
+ }
608
756
  if (ack.result === "success" /* SUCCESS */) this._acks.set(spans, ack.counts);
609
757
  if (ack.final) call.noRetry = true;
610
758
  return ack.result;
@@ -671,7 +819,16 @@ async function checkAck(response, spansSent, scrub) {
671
819
  try {
672
820
  payload = await response.json();
673
821
  } catch {
674
- return null;
822
+ payload = void 0;
823
+ }
824
+ const discard = parseJsonDiscard(payload, response.headers);
825
+ if (discard !== null) {
826
+ return {
827
+ result: "success" /* SUCCESS */,
828
+ counts: { accepted: 0, rejected: 0, quotaDropped: spansSent },
829
+ final: false,
830
+ quota: discard
831
+ };
675
832
  }
676
833
  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
677
834
  return null;