risicare 0.8.0 → 0.9.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 (72) hide show
  1. package/README.md +80 -21
  2. package/dist/frameworks/instructor.cjs +1 -1
  3. package/dist/frameworks/instructor.cjs.map +1 -1
  4. package/dist/frameworks/instructor.js +1 -1
  5. package/dist/frameworks/instructor.js.map +1 -1
  6. package/dist/frameworks/langchain.cjs +1 -1
  7. package/dist/frameworks/langchain.cjs.map +1 -1
  8. package/dist/frameworks/langchain.js +1 -1
  9. package/dist/frameworks/langchain.js.map +1 -1
  10. package/dist/frameworks/langgraph.cjs +1 -1
  11. package/dist/frameworks/langgraph.cjs.map +1 -1
  12. package/dist/frameworks/langgraph.js +1 -1
  13. package/dist/frameworks/langgraph.js.map +1 -1
  14. package/dist/frameworks/llamaindex.cjs +1 -1
  15. package/dist/frameworks/llamaindex.cjs.map +1 -1
  16. package/dist/frameworks/llamaindex.js +1 -1
  17. package/dist/frameworks/llamaindex.js.map +1 -1
  18. package/dist/index.cjs +131 -61
  19. package/dist/index.cjs.map +1 -1
  20. package/dist/index.d.cts +22 -8
  21. package/dist/index.d.ts +22 -8
  22. package/dist/index.js +131 -61
  23. package/dist/index.js.map +1 -1
  24. package/dist/providers/anthropic/index.cjs +1 -1
  25. package/dist/providers/anthropic/index.cjs.map +1 -1
  26. package/dist/providers/anthropic/index.js +1 -1
  27. package/dist/providers/anthropic/index.js.map +1 -1
  28. package/dist/providers/bedrock/index.cjs +1 -1
  29. package/dist/providers/bedrock/index.cjs.map +1 -1
  30. package/dist/providers/bedrock/index.js +1 -1
  31. package/dist/providers/bedrock/index.js.map +1 -1
  32. package/dist/providers/cerebras/index.cjs +1 -1
  33. package/dist/providers/cerebras/index.cjs.map +1 -1
  34. package/dist/providers/cerebras/index.js +1 -1
  35. package/dist/providers/cerebras/index.js.map +1 -1
  36. package/dist/providers/cohere/index.cjs +1 -1
  37. package/dist/providers/cohere/index.cjs.map +1 -1
  38. package/dist/providers/cohere/index.js +1 -1
  39. package/dist/providers/cohere/index.js.map +1 -1
  40. package/dist/providers/google/index.cjs +1 -1
  41. package/dist/providers/google/index.cjs.map +1 -1
  42. package/dist/providers/google/index.js +1 -1
  43. package/dist/providers/google/index.js.map +1 -1
  44. package/dist/providers/groq/index.cjs +1 -1
  45. package/dist/providers/groq/index.cjs.map +1 -1
  46. package/dist/providers/groq/index.js +1 -1
  47. package/dist/providers/groq/index.js.map +1 -1
  48. package/dist/providers/huggingface/index.cjs +1 -1
  49. package/dist/providers/huggingface/index.cjs.map +1 -1
  50. package/dist/providers/huggingface/index.js +1 -1
  51. package/dist/providers/huggingface/index.js.map +1 -1
  52. package/dist/providers/mistral/index.cjs +1 -1
  53. package/dist/providers/mistral/index.cjs.map +1 -1
  54. package/dist/providers/mistral/index.js +1 -1
  55. package/dist/providers/mistral/index.js.map +1 -1
  56. package/dist/providers/ollama/index.cjs +1 -1
  57. package/dist/providers/ollama/index.cjs.map +1 -1
  58. package/dist/providers/ollama/index.js +1 -1
  59. package/dist/providers/ollama/index.js.map +1 -1
  60. package/dist/providers/openai/index.cjs +1 -1
  61. package/dist/providers/openai/index.cjs.map +1 -1
  62. package/dist/providers/openai/index.js +1 -1
  63. package/dist/providers/openai/index.js.map +1 -1
  64. package/dist/providers/together/index.cjs +1 -1
  65. package/dist/providers/together/index.cjs.map +1 -1
  66. package/dist/providers/together/index.js +1 -1
  67. package/dist/providers/together/index.js.map +1 -1
  68. package/dist/providers/vercel-ai/index.cjs +1 -1
  69. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  70. package/dist/providers/vercel-ai/index.js +1 -1
  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
@@ -472,17 +523,25 @@ example in its path) is logged as you gave it.
472
523
 
473
524
  ## A note on running without an API key
474
525
 
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.
526
+ With no API key (an empty one, or one of only whitespace, counts as none) the SDK
527
+ sends nothing to Risicare, whatever `RISICARE_TRACING`, `enabled` or `enable()`
528
+ says. Tracing is off:
529
+ `isEnabled()` is `false`, `flush()` returns `false`, and the metrics show
530
+ nothing exported. The SDK says so once, at `init()`, in one WARNING on stderr:
531
+ there is no API key, nothing is sent, `flush()` returns `false`, and how to set
532
+ the key. There is no WARNING when you turned tracing off on purpose
533
+ (`enabled: false`, `RISICARE_TRACING=false`).
534
+
535
+ The SDK also prints no span without a key, with `debug: true` too. It performs no
536
+ redaction of its own, so printing would put prompts, completions and anything
537
+ else in your attributes onto your stderr. (The Python SDK prints spans with
538
+ `debug=True` and no key. They are display only: never counted, never sent.)
539
+
540
+ The SDK trims the key. An `apiKey` option that is empty, or only whitespace, counts
541
+ as "not given": the SDK then uses `RISICARE_API_KEY`.
542
+
543
+ Not active means not true: `flush()` also returns `false` before `init()` and
544
+ with tracing off at `init()`.
486
545
 
487
546
  ## Requirements
488
547
 
@@ -263,7 +263,7 @@ var SUPPLEMENTAL_RULES = [
263
263
  ];
264
264
 
265
265
  // src/version.ts
266
- var SDK_VERSION = "0.8.0";
266
+ var SDK_VERSION = "0.9.0";
267
267
 
268
268
  // src/exporters/http.ts
269
269
  var CAPACITY_REFUSAL_STATUSES = /* @__PURE__ */ new Set([429, 503]);