risicare 0.8.0 → 0.9.1

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 (72) hide show
  1. package/README.md +98 -21
  2. package/dist/frameworks/instructor.cjs +144 -2
  3. package/dist/frameworks/instructor.cjs.map +1 -1
  4. package/dist/frameworks/instructor.js +144 -2
  5. package/dist/frameworks/instructor.js.map +1 -1
  6. package/dist/frameworks/langchain.cjs +144 -2
  7. package/dist/frameworks/langchain.cjs.map +1 -1
  8. package/dist/frameworks/langchain.js +144 -2
  9. package/dist/frameworks/langchain.js.map +1 -1
  10. package/dist/frameworks/langgraph.cjs +144 -2
  11. package/dist/frameworks/langgraph.cjs.map +1 -1
  12. package/dist/frameworks/langgraph.js +144 -2
  13. package/dist/frameworks/langgraph.js.map +1 -1
  14. package/dist/frameworks/llamaindex.cjs +144 -2
  15. package/dist/frameworks/llamaindex.cjs.map +1 -1
  16. package/dist/frameworks/llamaindex.js +144 -2
  17. package/dist/frameworks/llamaindex.js.map +1 -1
  18. package/dist/index.cjs +329 -67
  19. package/dist/index.cjs.map +1 -1
  20. package/dist/index.d.cts +29 -9
  21. package/dist/index.d.ts +29 -9
  22. package/dist/index.js +329 -67
  23. package/dist/index.js.map +1 -1
  24. package/dist/providers/anthropic/index.cjs +144 -2
  25. package/dist/providers/anthropic/index.cjs.map +1 -1
  26. package/dist/providers/anthropic/index.js +144 -2
  27. package/dist/providers/anthropic/index.js.map +1 -1
  28. package/dist/providers/bedrock/index.cjs +144 -2
  29. package/dist/providers/bedrock/index.cjs.map +1 -1
  30. package/dist/providers/bedrock/index.js +144 -2
  31. package/dist/providers/bedrock/index.js.map +1 -1
  32. package/dist/providers/cerebras/index.cjs +144 -2
  33. package/dist/providers/cerebras/index.cjs.map +1 -1
  34. package/dist/providers/cerebras/index.js +144 -2
  35. package/dist/providers/cerebras/index.js.map +1 -1
  36. package/dist/providers/cohere/index.cjs +144 -2
  37. package/dist/providers/cohere/index.cjs.map +1 -1
  38. package/dist/providers/cohere/index.js +144 -2
  39. package/dist/providers/cohere/index.js.map +1 -1
  40. package/dist/providers/google/index.cjs +144 -2
  41. package/dist/providers/google/index.cjs.map +1 -1
  42. package/dist/providers/google/index.js +144 -2
  43. package/dist/providers/google/index.js.map +1 -1
  44. package/dist/providers/groq/index.cjs +144 -2
  45. package/dist/providers/groq/index.cjs.map +1 -1
  46. package/dist/providers/groq/index.js +144 -2
  47. package/dist/providers/groq/index.js.map +1 -1
  48. package/dist/providers/huggingface/index.cjs +144 -2
  49. package/dist/providers/huggingface/index.cjs.map +1 -1
  50. package/dist/providers/huggingface/index.js +144 -2
  51. package/dist/providers/huggingface/index.js.map +1 -1
  52. package/dist/providers/mistral/index.cjs +144 -2
  53. package/dist/providers/mistral/index.cjs.map +1 -1
  54. package/dist/providers/mistral/index.js +144 -2
  55. package/dist/providers/mistral/index.js.map +1 -1
  56. package/dist/providers/ollama/index.cjs +144 -2
  57. package/dist/providers/ollama/index.cjs.map +1 -1
  58. package/dist/providers/ollama/index.js +144 -2
  59. package/dist/providers/ollama/index.js.map +1 -1
  60. package/dist/providers/openai/index.cjs +144 -2
  61. package/dist/providers/openai/index.cjs.map +1 -1
  62. package/dist/providers/openai/index.js +144 -2
  63. package/dist/providers/openai/index.js.map +1 -1
  64. package/dist/providers/together/index.cjs +144 -2
  65. package/dist/providers/together/index.cjs.map +1 -1
  66. package/dist/providers/together/index.js +144 -2
  67. package/dist/providers/together/index.js.map +1 -1
  68. package/dist/providers/vercel-ai/index.cjs +144 -2
  69. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  70. package/dist/providers/vercel-ai/index.js +144 -2
  71. package/dist/providers/vercel-ai/index.js.map +1 -1
  72. package/package.json +1 -1
package/README.md CHANGED
@@ -84,8 +84,9 @@ reads to `https://my-host`.
84
84
  | unset, empty, or whitespace only | the default applies |
85
85
  | any other value | tracing off, with one WARNING that names the value |
86
86
 
87
- The `enabled` option has priority over the variable. With no API key and no
88
- explicit setting, tracing is off (see "A note on running without an API key").
87
+ The `enabled` option has priority over the variable. With no API key, tracing
88
+ is off, whatever `enabled` or `RISICARE_TRACING` says (see "A note on running
89
+ without an API key").
89
90
 
90
91
  ## Imports
91
92
 
@@ -304,14 +305,57 @@ await shutdown(5000) // Deliver what it can in the time, th
304
305
  ## Delivery: flush, shutdown and metrics
305
306
 
306
307
  - `await flush(timeoutMs?)` waits for the queued spans and the pending scores
307
- (default 5000 ms). It returns `true` only when nothing is queued, no batch is
308
- in flight, and no span was dropped or rejected and no score failed since the
309
- previous `flush()` returned (or since `init()`, for the first call). A loss
310
- makes the next `flush()` return `false` one time, also when it occurred while
311
- no flush ran. It returns `false` at its deadline. `flush()` only waits. It
312
- does not stop a request that is already sent. With more than one exporter,
308
+ (default 5000 ms). It returns `true` only when the gateway acknowledged every
309
+ span and every score that the SDK accepted since the previous `flush()`
310
+ returned (or since `init()`), and nothing is queued or in flight. When the SDK
311
+ has no evidence of delivery, `flush()` is not `true`.
312
+ - A loss of any kind makes exactly one `flush()` return `false`: the next one
313
+ that ends. A loss is a drop for any reason (`shutdown_residue` included), a
314
+ rejection, a failed score, and a score that `score()` refuses at the call. It
315
+ also raises a counter with a named reason: `droppedSpansByReason`,
316
+ `rejectedSpans` or `failedScores`. A `flush()` that returns `false` at its
317
+ deadline, while none of these counters went up since the previous `flush()`,
318
+ means that spans are still in flight: they are not lost. `flush()` only waits.
319
+ It does not stop a request that is already sent. With more than one exporter,
313
320
  a batch counts as delivered when the first exporter that succeeds takes it:
314
321
  `flush()` can then return `true` while another exporter refused the batch.
322
+ - `flush()` returns `false` when the SDK is not active: before `init()`, with
323
+ tracing off at `init()` (`enabled: false`, `RISICARE_TRACING=false`), and with
324
+ no API key. `isEnabled()` is `false` in the same cases, and after `shutdown()`
325
+ or the SDK's own drain at SIGTERM or SIGINT.
326
+ - A `flush()` that comes while a `shutdown()` runs (your own call, or the SDK's
327
+ drain at SIGTERM or SIGINT) waits for that shutdown, inside its own deadline,
328
+ and then reports the real outcome of what the SDK accepted, with the same
329
+ loss rule. So does a `flush()` after `shutdown()`. It never answers from the
330
+ state of an empty queue.
331
+ - A span that ends while a `shutdown()` runs (your own call, or the SDK's drain
332
+ at SIGTERM or SIGINT) joins that drain, and is exported before the drain ends.
333
+ A span that ends after the drain has stopped taking spans (nothing was left
334
+ to export, a round failed, or its time ended) is counted at once as
335
+ `shutdown_residue`, with one WARNING for the first one, and one `flush()`
336
+ returns `false`. It is never dropped without a count.
337
+ - At SIGTERM and SIGINT the SDK drains what it holds. In both orders of
338
+ registration `flush()` reports the real outcome, and your listener runs once
339
+ and decides the exit. When your application has its own listener for the
340
+ signal when the signal arrives, the SDK does not raise the signal again and
341
+ does not end the process. When it has none at that moment, and had none when
342
+ it called `init()`, the SDK raises the signal again after its drain, so that
343
+ the default action ends the process. A listener that you add during the
344
+ drain runs on that second signal.
345
+ - The order of registration does change one thing: which spans your listener
346
+ makes are delivered. Node calls the listeners in the order of registration. A
347
+ listener that you register BEFORE `init()` runs before the SDK's: the spans
348
+ that it ends before it first waits are in the queue when the SDK drains, and
349
+ are delivered. A listener that you register AFTER `init()` runs after the
350
+ SDK's drain started. A span that it ends can miss the drain, when the drain
351
+ has stopped taking spans (nothing was left to export, a round failed, or its
352
+ time ended). That span is counted as `shutdown_residue`, and one `flush()`
353
+ returns `false`. A span that ends after the drain ended is counted in the same
354
+ way, in both orders. If your listener must make spans that are delivered,
355
+ register it before `init()`, or end the spans before the signal.
356
+ - A new `init()` (after `shutdown()`) starts a new count: "since `init()`" in the
357
+ rules above. A loss that was not reported is not carried over. Report the old
358
+ client's loss with `flush()` or `getMetrics()` before you call `init()` again.
315
359
  - `await shutdown(timeoutMs?)` is the call that ends a process in a fixed time
316
360
  (default 5000 ms). At the deadline it stops the export in flight. It counts
317
361
  the spans that it did not deliver as `shutdown_residue`, with one WARNING.
@@ -321,11 +365,18 @@ await shutdown(5000) // Deliver what it can in the time, th
321
365
  `transport_refused`, `shutdown_residue`, `unacknowledged`), `failedExports`,
322
366
  `failedScores`, the queue numbers and `sdkState`. `unacknowledged` counts
323
367
  spans that were sent, or that could not be serialized, and that the
324
- backend's answer did not account for.
368
+ backend's answer did not account for. `failedExports` counts the export
369
+ calls that failed as a whole. A later round can still deliver those spans, so
370
+ it is not a loss counter: the loss counters are `droppedSpansByReason`,
371
+ `rejectedSpans` and `failedScores`.
325
372
  - `score()` stops its request after 2000 ms and does not follow a redirect. A
326
373
  status of 300 or more, an error or a timeout adds 1 to `failedScores`. The
327
374
  first failure writes one WARNING at once. Failures in the next 10 seconds
328
- are counted, and the next WARNING gives their number.
375
+ are counted, and the next WARNING gives their number. A score that `score()`
376
+ refuses at the call (a value that is not a number or is outside 0 to 1, an
377
+ empty trace id or name) writes one WARNING, is not sent, and also adds 1 to
378
+ `failedScores`. When the SDK is not active (before `init()`, after `shutdown()`
379
+ or the SDK's own drain, tracing off, no key), nothing is counted.
329
380
  At most 50 score requests run at one time. Up to 1,000 scores wait for a free
330
381
  slot, with no timer: the 2000 ms bound starts when the request starts. A score
331
382
  that comes when 1,000 already wait fails at once and is counted. When the bound
@@ -436,6 +487,24 @@ const result = await withSession(
436
487
  `session()` does not run the callback. It returns a wrapped function, which you
437
488
  call later, for example once for each request.
438
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
+
439
508
  ## Known limitation — span loss during a backend outage
440
509
 
441
510
  The SDK does **not** keep spans through a long outage of the Risicare backend.
@@ -472,17 +541,25 @@ example in its path) is logged as you gave it.
472
541
 
473
542
  ## A note on running without an API key
474
543
 
475
- If you give no API key, or an empty one, tracing is off. This applies when
476
- you do not set tracing explicitly. The SDK then writes one WARNING to stderr.
477
- The SDK sends no span.
478
-
479
- If tracing is enabled explicitly (`enabled: true` or `RISICARE_TRACING=true`)
480
- but no API key is configured, the SDK emits a one-time
481
- `console.warn` and **drops** the spans. It deliberately does **not** print span
482
- payloads to your console: the SDK performs no redaction of its own, so printing
483
- would put prompts, completions and anything else in your attributes onto your
484
- stderr. If you want console output for local development, pass `debug: true`
485
- explicitly.
544
+ With no API key (an empty one, or one of only whitespace, counts as none) the SDK
545
+ sends nothing to Risicare, whatever `RISICARE_TRACING`, `enabled` or `enable()`
546
+ says. Tracing is off:
547
+ `isEnabled()` is `false`, `flush()` returns `false`, and the metrics show
548
+ nothing exported. The SDK says so once, at `init()`, in one WARNING on stderr:
549
+ there is no API key, nothing is sent, `flush()` returns `false`, and how to set
550
+ the key. There is no WARNING when you turned tracing off on purpose
551
+ (`enabled: false`, `RISICARE_TRACING=false`).
552
+
553
+ The SDK also prints no span without a key, with `debug: true` too. It performs no
554
+ redaction of its own, so printing would put prompts, completions and anything
555
+ else in your attributes onto your stderr. (The Python SDK prints spans with
556
+ `debug=True` and no key. They are display only: never counted, never sent.)
557
+
558
+ The SDK trims the key. An `apiKey` option that is empty, or only whitespace, counts
559
+ as "not given": the SDK then uses `RISICARE_API_KEY`.
560
+
561
+ Not active means not true: `flush()` also returns `false` before `init()` and
562
+ with tracing off at `init()`.
486
563
 
487
564
  ## Requirements
488
565
 
@@ -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.8.0";
270
+ var SDK_VERSION = "0.9.1";
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,21 @@ 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 batch processor dropped span(s) from a full queue in the quota pause (S-1). */
416
+ noteQuotaDrop(count = 1) {
417
+ this._quota.addDrops(count);
418
+ }
419
+ /** True while the exporter is paused for the monthly event quota (S-1). */
420
+ quotaPaused() {
421
+ return this._quota.paused();
422
+ }
307
423
  /** The spans of each finished call that could not be serialized, by its batch. */
308
424
  _unserializable = /* @__PURE__ */ new WeakMap();
425
+ /**
426
+ * S-1: the paused state after a monthly-quota discard (see `quota.ts`). A discard is not a
427
+ * failure: it does not touch the circuit breaker.
428
+ */
429
+ _quota = new QuotaPause();
309
430
  _circuitOpenUntil = 0;
310
431
  _circuitBreakerThreshold = 5;
311
432
  _circuitBreakerCooldownMs = 6e4;
@@ -397,6 +518,13 @@ var HttpExporter = class {
397
518
  }
398
519
  async _export(spans, call) {
399
520
  const cancelled = call.cancel.signal;
521
+ if (this._quota.paused()) {
522
+ debug(
523
+ `Export skipped: monthly quota pause, ${Math.round(this._quota.remainingS())} s left; ${spans.length} span(s) dropped`
524
+ );
525
+ this._acks.set(spans, { accepted: 0, rejected: 0, quotaDropped: spans.length });
526
+ return "success" /* SUCCESS */;
527
+ }
400
528
  const parts = [];
401
529
  const bad = [];
402
530
  let errorClass = "";
@@ -605,6 +733,11 @@ var HttpExporter = class {
605
733
  `HTTP ${response.status} and a body that is not a Risicare ack (content-type: ${response.headers?.get?.("Content-Type") || "none"})`
606
734
  );
607
735
  }
736
+ if (ack.quota !== void 0) {
737
+ this._quota.enter(ack.quota, `The ingest endpoint ${this._safeEndpoint}`, spansSent);
738
+ } else if (ack.result === "success" /* SUCCESS */) {
739
+ this._quota.accepted(`the ingest endpoint ${this._safeEndpoint}`);
740
+ }
608
741
  if (ack.result === "success" /* SUCCESS */) this._acks.set(spans, ack.counts);
609
742
  if (ack.final) call.noRetry = true;
610
743
  return ack.result;
@@ -671,7 +804,16 @@ async function checkAck(response, spansSent, scrub) {
671
804
  try {
672
805
  payload = await response.json();
673
806
  } catch {
674
- return null;
807
+ payload = void 0;
808
+ }
809
+ const discard = parseJsonDiscard(payload, response.headers);
810
+ if (discard !== null) {
811
+ return {
812
+ result: "success" /* SUCCESS */,
813
+ counts: { accepted: 0, rejected: 0, quotaDropped: spansSent },
814
+ final: false,
815
+ quota: discard
816
+ };
675
817
  }
676
818
  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
677
819
  return null;