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.
- package/CHANGELOG.md +254 -0
- package/README.md +194 -58
- package/dist/frameworks/instructor.cjs +383 -117
- package/dist/frameworks/instructor.cjs.map +1 -1
- package/dist/frameworks/instructor.js +383 -117
- package/dist/frameworks/instructor.js.map +1 -1
- package/dist/frameworks/langchain.cjs +396 -130
- package/dist/frameworks/langchain.cjs.map +1 -1
- package/dist/frameworks/langchain.js +396 -130
- package/dist/frameworks/langchain.js.map +1 -1
- package/dist/frameworks/langgraph.cjs +396 -130
- package/dist/frameworks/langgraph.cjs.map +1 -1
- package/dist/frameworks/langgraph.js +396 -130
- package/dist/frameworks/langgraph.js.map +1 -1
- package/dist/frameworks/llamaindex.cjs +396 -130
- package/dist/frameworks/llamaindex.cjs.map +1 -1
- package/dist/frameworks/llamaindex.js +396 -130
- package/dist/frameworks/llamaindex.js.map +1 -1
- package/dist/index.cjs +1136 -240
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +151 -26
- package/dist/index.d.ts +151 -26
- package/dist/index.js +1132 -240
- package/dist/index.js.map +1 -1
- package/dist/providers/anthropic/index.cjs +467 -137
- package/dist/providers/anthropic/index.cjs.map +1 -1
- package/dist/providers/anthropic/index.js +467 -137
- package/dist/providers/anthropic/index.js.map +1 -1
- package/dist/providers/bedrock/index.cjs +409 -128
- package/dist/providers/bedrock/index.cjs.map +1 -1
- package/dist/providers/bedrock/index.js +409 -128
- package/dist/providers/bedrock/index.js.map +1 -1
- package/dist/providers/cerebras/index.cjs +414 -133
- package/dist/providers/cerebras/index.cjs.map +1 -1
- package/dist/providers/cerebras/index.js +414 -133
- package/dist/providers/cerebras/index.js.map +1 -1
- package/dist/providers/cohere/index.cjs +414 -133
- package/dist/providers/cohere/index.cjs.map +1 -1
- package/dist/providers/cohere/index.js +414 -133
- package/dist/providers/cohere/index.js.map +1 -1
- package/dist/providers/google/index.cjs +414 -133
- package/dist/providers/google/index.cjs.map +1 -1
- package/dist/providers/google/index.js +414 -133
- package/dist/providers/google/index.js.map +1 -1
- package/dist/providers/groq/index.cjs +414 -133
- package/dist/providers/groq/index.cjs.map +1 -1
- package/dist/providers/groq/index.js +414 -133
- package/dist/providers/groq/index.js.map +1 -1
- package/dist/providers/huggingface/index.cjs +414 -133
- package/dist/providers/huggingface/index.cjs.map +1 -1
- package/dist/providers/huggingface/index.js +414 -133
- package/dist/providers/huggingface/index.js.map +1 -1
- package/dist/providers/mistral/index.cjs +414 -133
- package/dist/providers/mistral/index.cjs.map +1 -1
- package/dist/providers/mistral/index.js +414 -133
- package/dist/providers/mistral/index.js.map +1 -1
- package/dist/providers/ollama/index.cjs +414 -133
- package/dist/providers/ollama/index.cjs.map +1 -1
- package/dist/providers/ollama/index.js +414 -133
- package/dist/providers/ollama/index.js.map +1 -1
- package/dist/providers/openai/index.cjs +452 -135
- package/dist/providers/openai/index.cjs.map +1 -1
- package/dist/providers/openai/index.js +452 -135
- package/dist/providers/openai/index.js.map +1 -1
- package/dist/providers/together/index.cjs +414 -133
- package/dist/providers/together/index.cjs.map +1 -1
- package/dist/providers/together/index.js +414 -133
- package/dist/providers/together/index.js.map +1 -1
- package/dist/providers/vercel-ai/index.cjs +398 -132
- package/dist/providers/vercel-ai/index.cjs.map +1 -1
- package/dist/providers/vercel-ai/index.js +398 -132
- package/dist/providers/vercel-ai/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -310,10 +310,17 @@ interface RisicareConfig {
|
|
|
310
310
|
/**
|
|
311
311
|
* Whether prompt/completion content may leave the process.
|
|
312
312
|
*
|
|
313
|
-
* **Default `
|
|
314
|
-
*
|
|
315
|
-
*
|
|
316
|
-
*
|
|
313
|
+
* **Default `true`** (capture is on). Set `false`, or set
|
|
314
|
+
* `RISICARE_TRACE_CONTENT=false`, to stop capture. Capture was on through
|
|
315
|
+
* 0.5.0, off by default from 0.5.2 to 0.9.2, and is on by default again after
|
|
316
|
+
* 0.9.2. When false, every content-keyed attribute is replaced with
|
|
317
|
+
* `<risicare:content-omitted>` on the export path — including content you
|
|
318
|
+
* set by hand, which 0.5.0 and earlier did NOT gate. The project setting in
|
|
319
|
+
* the Risicare dashboard can also turn content off for a project; the
|
|
320
|
+
* gateway then drops it. With `traceContent: false`, the SDK still sends the
|
|
321
|
+
* status message, the exception message, the stack trace (which repeats the
|
|
322
|
+
* message), `error.message` and `exception.message`. Only the project switch
|
|
323
|
+
* masks them, at the gateway.
|
|
317
324
|
*/
|
|
318
325
|
traceContent?: boolean;
|
|
319
326
|
/** Sample rate 0.0–1.0 (default: 1.0 = trace all) */
|
|
@@ -322,8 +329,26 @@ interface RisicareConfig {
|
|
|
322
329
|
batchSize?: number;
|
|
323
330
|
/** Batch timeout in ms before flush (default: 1000) */
|
|
324
331
|
batchTimeoutMs?: number;
|
|
325
|
-
/**
|
|
332
|
+
/**
|
|
333
|
+
* Maximum queue size (default: 10000). When the queue is full, the OLDEST queued span is
|
|
334
|
+
* dropped (`queue_full`) and the new one is kept.
|
|
335
|
+
*/
|
|
326
336
|
maxQueueSize?: number;
|
|
337
|
+
/**
|
|
338
|
+
* How long the HTTP exporter retries one batch, in seconds from its first attempt (default
|
|
339
|
+
* 300). 408, 429, 500, 502, 503, 504, a connection error and a timeout are retried with
|
|
340
|
+
* full-jitter backoff (base 1 s, cap 30 s; `Retry-After` replaces the wait). A batch that the
|
|
341
|
+
* gateway does not take within the horizon is dropped with the reason `retry_exhausted`: a
|
|
342
|
+
* gateway outage that is longer than the horizon loses spans. 0 sends each batch once. No
|
|
343
|
+
* environment-variable form, as in Python. See `exporters/retry.ts`.
|
|
344
|
+
*/
|
|
345
|
+
retryHorizonS?: number;
|
|
346
|
+
/**
|
|
347
|
+
* The budget of `shutdown()` in seconds (default 10), and of the SDK's own teardown at
|
|
348
|
+
* `beforeExit`, SIGTERM and SIGINT. Spans that it cannot send in that time are counted as
|
|
349
|
+
* `shutdown_residue`. No environment-variable form, as in Python.
|
|
350
|
+
*/
|
|
351
|
+
shutdownTimeoutS?: number;
|
|
327
352
|
/** Enable debug logging (default: false) */
|
|
328
353
|
debug?: boolean;
|
|
329
354
|
/** Enable gzip compression for HTTP exports (default: false) */
|
|
@@ -400,7 +425,9 @@ interface TracerConfig {
|
|
|
400
425
|
/** Whether tracing is enabled */
|
|
401
426
|
enabled?: boolean;
|
|
402
427
|
/**
|
|
403
|
-
* Whether prompt/completion content may leave the process
|
|
428
|
+
* Whether prompt/completion content may leave the process. A Tracer built
|
|
429
|
+
* without this value uses `false` (fail-closed); that is NOT the user default,
|
|
430
|
+
* which is `true` in `resolveConfig`.
|
|
404
431
|
*
|
|
405
432
|
* ⚠ The Tracer only CARRIES this for the provider patches to read via
|
|
406
433
|
* `getTraceContent()`. It is NOT the enforcement point — the gate runs in the
|
|
@@ -486,10 +513,10 @@ declare function init(config?: Partial<RisicareConfig>): void;
|
|
|
486
513
|
/**
|
|
487
514
|
* Gracefully shut down the SDK. Flushes pending spans before resolving.
|
|
488
515
|
*
|
|
489
|
-
* @param timeoutMs - The shutdown budget in milliseconds
|
|
490
|
-
*
|
|
491
|
-
* string, null)
|
|
492
|
-
* 2**31 - 1.
|
|
516
|
+
* @param timeoutMs - The shutdown budget in milliseconds. It is a hard wall-clock
|
|
517
|
+
* bound. Not given, or a value that is not a finite number (NaN, Infinity, a
|
|
518
|
+
* string, null): the `shutdownTimeoutS` of `init()` (default 10 s). A negative
|
|
519
|
+
* value gives 0. The largest value is 2**31 - 1.
|
|
493
520
|
*
|
|
494
521
|
* At the deadline, `shutdown()` stops the export in flight. Spans still queued
|
|
495
522
|
* and spans in the stopped export are counted as `shutdown_residue`, with one
|
|
@@ -598,14 +625,18 @@ declare function getMetrics(): {
|
|
|
598
625
|
rejectedSpans: number;
|
|
599
626
|
droppedSpans: number;
|
|
600
627
|
droppedSpansByReason: {
|
|
601
|
-
queue_full: number;
|
|
602
628
|
transport_refused: number;
|
|
629
|
+
retry_exhausted: number;
|
|
603
630
|
shutdown_residue: number;
|
|
631
|
+
too_large: number;
|
|
632
|
+
queue_full: number;
|
|
604
633
|
unacknowledged: number;
|
|
605
634
|
quota_exceeded: number;
|
|
606
635
|
};
|
|
607
636
|
droppedQuota: number;
|
|
608
637
|
failedExports: number;
|
|
638
|
+
attempts: number;
|
|
639
|
+
oldestPendingAgeS: number;
|
|
609
640
|
maskErrors: number;
|
|
610
641
|
queueSize: number;
|
|
611
642
|
queueCapacity: number;
|
|
@@ -613,9 +644,11 @@ declare function getMetrics(): {
|
|
|
613
644
|
} | {
|
|
614
645
|
failedScores: number;
|
|
615
646
|
droppedSpansByReason: {
|
|
616
|
-
queue_full: number;
|
|
617
647
|
transport_refused: number;
|
|
648
|
+
retry_exhausted: number;
|
|
618
649
|
shutdown_residue: number;
|
|
650
|
+
too_large: number;
|
|
651
|
+
queue_full: number;
|
|
619
652
|
unacknowledged: number;
|
|
620
653
|
quota_exceeded: number;
|
|
621
654
|
};
|
|
@@ -625,6 +658,8 @@ declare function getMetrics(): {
|
|
|
625
658
|
droppedSpans: number;
|
|
626
659
|
droppedQuota: number;
|
|
627
660
|
failedExports: number;
|
|
661
|
+
attempts: number;
|
|
662
|
+
oldestPendingAgeS: number;
|
|
628
663
|
maskErrors: number;
|
|
629
664
|
queueSize: number;
|
|
630
665
|
queueCapacity: number;
|
|
@@ -640,9 +675,13 @@ declare function getMetrics(): {
|
|
|
640
675
|
shutdown_residue: number;
|
|
641
676
|
unacknowledged: number;
|
|
642
677
|
quota_exceeded: number;
|
|
678
|
+
retry_exhausted: number;
|
|
679
|
+
too_large: number;
|
|
643
680
|
};
|
|
644
681
|
droppedQuota: number;
|
|
645
682
|
failedExports: number;
|
|
683
|
+
attempts: number;
|
|
684
|
+
oldestPendingAgeS: number;
|
|
646
685
|
queueSize: number;
|
|
647
686
|
queueCapacity: number;
|
|
648
687
|
queueUtilization: number;
|
|
@@ -662,8 +701,37 @@ declare function reportError(error: unknown, options?: {
|
|
|
662
701
|
name?: string;
|
|
663
702
|
attributes?: Record<string, unknown>;
|
|
664
703
|
}): void;
|
|
704
|
+
/** What a score's judgment is (score v2, W2-5). See "Scores, feedback and outcomes" in the README. */
|
|
705
|
+
type ScoreKind = 'annotation' | 'eval' | 'feedback' | 'outcome';
|
|
706
|
+
/** The arguments of `score()` (score v2). One of `traceId` and `sessionId` is required. */
|
|
707
|
+
interface ScoreOptions {
|
|
708
|
+
/** Score name, 1 to 128 characters (for example "accuracy", "resolved"). */
|
|
709
|
+
name: string;
|
|
710
|
+
/** A finite number (any range), a string of 1 to 256 characters, or a boolean. */
|
|
711
|
+
value: number | string | boolean;
|
|
712
|
+
/** The trace to score (32 lowercase hex characters). */
|
|
713
|
+
traceId?: string;
|
|
714
|
+
/** A span within the trace (16 lowercase hex characters). Needs `traceId`. */
|
|
715
|
+
spanId?: string;
|
|
716
|
+
/** The session to score (1 to 255 characters), with or instead of a trace. */
|
|
717
|
+
sessionId?: string;
|
|
718
|
+
/** A human-readable explanation, at most 4,096 characters. */
|
|
719
|
+
comment?: string;
|
|
720
|
+
/** What the judgment is. Default `annotation`. */
|
|
721
|
+
kind?: ScoreKind;
|
|
722
|
+
}
|
|
665
723
|
/**
|
|
666
|
-
* Record a
|
|
724
|
+
* Record a score on a trace, a span or a session (score v2, W2-5).
|
|
725
|
+
*
|
|
726
|
+
* `value` is typed, and its type decides how the Risicare server stores it: a finite number (any
|
|
727
|
+
* range) is numeric, a string of 1 to 256 characters is categorical, `true` or `false` is boolean.
|
|
728
|
+
* `kind` says what the judgment is: `annotation` (a person's judgment, the default), `eval` (an
|
|
729
|
+
* evaluator, a model or a rule), `feedback` (the end user's reaction) or `outcome` (a result that
|
|
730
|
+
* your own system knows, such as resolved, refunded or goal met; no model infers it). One of
|
|
731
|
+
* `traceId` and `sessionId` is required; `spanId` needs `traceId`.
|
|
732
|
+
*
|
|
733
|
+
* The positional form of 0.10.0 and earlier, `score(traceId, name, value, { spanId, comment })`,
|
|
734
|
+
* still sends the score, and the first such call writes one WARNING. Use the object form.
|
|
667
735
|
*
|
|
668
736
|
* Sends the score in the background. The root `flush()` waits for it.
|
|
669
737
|
* This function never throws and does not block. At most 50 score requests
|
|
@@ -678,21 +746,23 @@ declare function reportError(error: unknown, options?: {
|
|
|
678
746
|
* the score name and the status or the error code. Later failures in the next
|
|
679
747
|
* 10 s are counted, and the next WARNING gives their number. Root `flush()`
|
|
680
748
|
* waits for pending scores inside its deadline, and returns `false` when a
|
|
681
|
-
* score failed since the previous `flush()` returned.
|
|
682
|
-
* value that is not a number,
|
|
683
|
-
*
|
|
684
|
-
*
|
|
685
|
-
*
|
|
749
|
+
* score failed since the previous `flush()` returned. A score that the SDK refuses at the call
|
|
750
|
+
* (a value that is not a finite number, a string of 1 to 256 characters or a boolean; an empty or
|
|
751
|
+
* too long name; no trace and no session; a span with no trace; an unknown kind) writes one
|
|
752
|
+
* WARNING, and the SDK does not send it. It counts as a failed score, so the next `flush()` is
|
|
753
|
+
* false (not when the SDK is not active: then nothing is counted).
|
|
686
754
|
*
|
|
687
|
-
* If a `mask` is configured on `init()`, `
|
|
688
|
-
*
|
|
689
|
-
*
|
|
755
|
+
* If a `mask` is configured on `init()`, `comment` is passed to it under the key `score.comment`
|
|
756
|
+
* before the request is built. `traceId`, `spanId`, `sessionId`, `name` and `value` are NOT
|
|
757
|
+
* masked: they are identifiers and the judgment itself, which the platform joins, groups and
|
|
758
|
+
* filters on.
|
|
690
759
|
*
|
|
691
|
-
* @
|
|
692
|
-
*
|
|
693
|
-
*
|
|
694
|
-
* @param options - Optional span_id and comment
|
|
760
|
+
* @example
|
|
761
|
+
* score({ name: 'factual_accuracy', value: 0.92, traceId });
|
|
762
|
+
* score({ name: 'resolved', value: true, sessionId: 'conv-7', kind: 'outcome' });
|
|
695
763
|
*/
|
|
764
|
+
declare function score(options: ScoreOptions): void;
|
|
765
|
+
/** @deprecated Use `score({ name, value, traceId, spanId, comment })`. */
|
|
696
766
|
declare function score(traceId: string, name: string, value: number, options?: {
|
|
697
767
|
spanId?: string;
|
|
698
768
|
comment?: string;
|
|
@@ -814,6 +884,61 @@ declare function session(options: SessionOptions): <TArgs extends unknown[], TR>
|
|
|
814
884
|
declare function session<TArgs extends unknown[]>(resolver: (...args: TArgs) => SessionOptions): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
|
|
815
885
|
declare function session<TArgs extends unknown[]>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions)): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
|
|
816
886
|
|
|
887
|
+
/**
|
|
888
|
+
* Identity helpers (W2-2): put the user, the session, the release and tags on the current trace.
|
|
889
|
+
*
|
|
890
|
+
* The Python twin is `risicare/identity.py`. Each helper writes one span attribute that the
|
|
891
|
+
* Risicare spans worker reads into a dashboard column (contract spec W2-2, section 6; ANSWER 91):
|
|
892
|
+
*
|
|
893
|
+
* | Helper | Span attribute | Column |
|
|
894
|
+
* |------------------------|----------------------|---------|
|
|
895
|
+
* | `setUser(id)` | `user.id` | User |
|
|
896
|
+
* | `setSession(id)` | `session.id` | Session |
|
|
897
|
+
* | `setRelease(version)` | `risicare.release` | Release |
|
|
898
|
+
* | `addTags([...])` | `tag.tags` | Tags |
|
|
899
|
+
*
|
|
900
|
+
* Scope. The current span gets the attribute at once. Each other span of the same trace that
|
|
901
|
+
* ends after the call gets it when it ends, unless that span has the attribute already (tags are
|
|
902
|
+
* merged, in order, with no repeats). That includes the spans that are open now (for example the
|
|
903
|
+
* root span) and the spans that start later, in any async context of this process. A span of
|
|
904
|
+
* another trace never gets it, so a value cannot pass from one request to the next.
|
|
905
|
+
*
|
|
906
|
+
* Outside a span there is no trace: the helper sets nothing and returns `false`, and the first
|
|
907
|
+
* such call of each helper writes one WARNING. For a value that must apply before the first span,
|
|
908
|
+
* use `withSession({ sessionId, userId }, fn)` or `init({ serviceVersion })`.
|
|
909
|
+
*
|
|
910
|
+
* The values of at most `MAX_TRACES` traces are kept (the oldest is forgotten first), so memory
|
|
911
|
+
* stays bounded in a long-running process. The registry lives on `globalThis`, so that every
|
|
912
|
+
* entry point bundle uses the same one (see `globals.ts`).
|
|
913
|
+
*/
|
|
914
|
+
|
|
915
|
+
/**
|
|
916
|
+
* Set the user of the current trace: the span attribute `user.id` (dashboard column User).
|
|
917
|
+
* Returns `true` when it was set. The worker reads `session.user_id` (from `withSession`) and
|
|
918
|
+
* `user_id` before `user.id`, so a session user wins.
|
|
919
|
+
*/
|
|
920
|
+
declare function setUser(userId: string | number): boolean;
|
|
921
|
+
/**
|
|
922
|
+
* Set the session of the current trace: the span attribute `session.id` (column Session).
|
|
923
|
+
* Returns `true` when it was set. The worker reads the typed session of a span (from
|
|
924
|
+
* `withSession`) before `session.id`, so a session context wins.
|
|
925
|
+
*/
|
|
926
|
+
declare function setSession(sessionId: string | number): boolean;
|
|
927
|
+
/**
|
|
928
|
+
* Set the release of the current trace: the span attribute `risicare.release` (column Release).
|
|
929
|
+
* Returns `true` when it was set. `risicare.release` is the first source of the Release column;
|
|
930
|
+
* the next one is `service.version`, which `init({ serviceVersion })` (or
|
|
931
|
+
* `RISICARE_SERVICE_VERSION`) puts on every span with no other code.
|
|
932
|
+
*/
|
|
933
|
+
declare function setRelease(version: string | number): boolean;
|
|
934
|
+
/**
|
|
935
|
+
* Add tags to the current trace: the span attribute `tag.tags`, an array (column Tags). A later
|
|
936
|
+
* call adds to the tags of the earlier ones, in order, with no repeats. Returns `true` when at
|
|
937
|
+
* least one tag was added. An item that is not a non-empty string is left out, with one WARNING.
|
|
938
|
+
* The worker keeps at most 50 tags for each span and cuts each one at 200 characters.
|
|
939
|
+
*/
|
|
940
|
+
declare function addTags(tags: readonly string[]): boolean;
|
|
941
|
+
|
|
817
942
|
/**
|
|
818
943
|
* Phase decorators — decision phase tracking (Tier 4).
|
|
819
944
|
*
|
|
@@ -1769,4 +1894,4 @@ type Tracer = Tracer$1;
|
|
|
1769
1894
|
|
|
1770
1895
|
type Span = Span$1;
|
|
1771
1896
|
|
|
1772
|
-
export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, GuardRejectedError, type HeaderLookup, MASK_ERROR_MARKER, type MaskFn, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, type Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, type Tracer, type VerifyWebhookOptions, type WebhookPayload, WebhookVerificationError, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getFixRuntime, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, initFixRuntime, injectTraceContext, isEnabled, isProviderInstrumentationSuppressed, registerSpan, reportError, score, session, shutdown, shutdownFixRuntime, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, verifyWebhookSignature, withAgent, withPhase, withSession };
|
|
1897
|
+
export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, GuardRejectedError, type HeaderLookup, MASK_ERROR_MARKER, type MaskFn, MessageType, type RisicareConfig, type ScoreKind, type ScoreOptions, SemanticPhase, type SessionContext, type SessionOptions, type Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, type Tracer, type VerifyWebhookOptions, type WebhookPayload, WebhookVerificationError, addTags, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getFixRuntime, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, initFixRuntime, injectTraceContext, isEnabled, isProviderInstrumentationSuppressed, registerSpan, reportError, score, session, setRelease, setSession, setUser, shutdown, shutdownFixRuntime, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, verifyWebhookSignature, withAgent, withPhase, withSession };
|
package/dist/index.d.ts
CHANGED
|
@@ -310,10 +310,17 @@ interface RisicareConfig {
|
|
|
310
310
|
/**
|
|
311
311
|
* Whether prompt/completion content may leave the process.
|
|
312
312
|
*
|
|
313
|
-
* **Default `
|
|
314
|
-
*
|
|
315
|
-
*
|
|
316
|
-
*
|
|
313
|
+
* **Default `true`** (capture is on). Set `false`, or set
|
|
314
|
+
* `RISICARE_TRACE_CONTENT=false`, to stop capture. Capture was on through
|
|
315
|
+
* 0.5.0, off by default from 0.5.2 to 0.9.2, and is on by default again after
|
|
316
|
+
* 0.9.2. When false, every content-keyed attribute is replaced with
|
|
317
|
+
* `<risicare:content-omitted>` on the export path — including content you
|
|
318
|
+
* set by hand, which 0.5.0 and earlier did NOT gate. The project setting in
|
|
319
|
+
* the Risicare dashboard can also turn content off for a project; the
|
|
320
|
+
* gateway then drops it. With `traceContent: false`, the SDK still sends the
|
|
321
|
+
* status message, the exception message, the stack trace (which repeats the
|
|
322
|
+
* message), `error.message` and `exception.message`. Only the project switch
|
|
323
|
+
* masks them, at the gateway.
|
|
317
324
|
*/
|
|
318
325
|
traceContent?: boolean;
|
|
319
326
|
/** Sample rate 0.0–1.0 (default: 1.0 = trace all) */
|
|
@@ -322,8 +329,26 @@ interface RisicareConfig {
|
|
|
322
329
|
batchSize?: number;
|
|
323
330
|
/** Batch timeout in ms before flush (default: 1000) */
|
|
324
331
|
batchTimeoutMs?: number;
|
|
325
|
-
/**
|
|
332
|
+
/**
|
|
333
|
+
* Maximum queue size (default: 10000). When the queue is full, the OLDEST queued span is
|
|
334
|
+
* dropped (`queue_full`) and the new one is kept.
|
|
335
|
+
*/
|
|
326
336
|
maxQueueSize?: number;
|
|
337
|
+
/**
|
|
338
|
+
* How long the HTTP exporter retries one batch, in seconds from its first attempt (default
|
|
339
|
+
* 300). 408, 429, 500, 502, 503, 504, a connection error and a timeout are retried with
|
|
340
|
+
* full-jitter backoff (base 1 s, cap 30 s; `Retry-After` replaces the wait). A batch that the
|
|
341
|
+
* gateway does not take within the horizon is dropped with the reason `retry_exhausted`: a
|
|
342
|
+
* gateway outage that is longer than the horizon loses spans. 0 sends each batch once. No
|
|
343
|
+
* environment-variable form, as in Python. See `exporters/retry.ts`.
|
|
344
|
+
*/
|
|
345
|
+
retryHorizonS?: number;
|
|
346
|
+
/**
|
|
347
|
+
* The budget of `shutdown()` in seconds (default 10), and of the SDK's own teardown at
|
|
348
|
+
* `beforeExit`, SIGTERM and SIGINT. Spans that it cannot send in that time are counted as
|
|
349
|
+
* `shutdown_residue`. No environment-variable form, as in Python.
|
|
350
|
+
*/
|
|
351
|
+
shutdownTimeoutS?: number;
|
|
327
352
|
/** Enable debug logging (default: false) */
|
|
328
353
|
debug?: boolean;
|
|
329
354
|
/** Enable gzip compression for HTTP exports (default: false) */
|
|
@@ -400,7 +425,9 @@ interface TracerConfig {
|
|
|
400
425
|
/** Whether tracing is enabled */
|
|
401
426
|
enabled?: boolean;
|
|
402
427
|
/**
|
|
403
|
-
* Whether prompt/completion content may leave the process
|
|
428
|
+
* Whether prompt/completion content may leave the process. A Tracer built
|
|
429
|
+
* without this value uses `false` (fail-closed); that is NOT the user default,
|
|
430
|
+
* which is `true` in `resolveConfig`.
|
|
404
431
|
*
|
|
405
432
|
* ⚠ The Tracer only CARRIES this for the provider patches to read via
|
|
406
433
|
* `getTraceContent()`. It is NOT the enforcement point — the gate runs in the
|
|
@@ -486,10 +513,10 @@ declare function init(config?: Partial<RisicareConfig>): void;
|
|
|
486
513
|
/**
|
|
487
514
|
* Gracefully shut down the SDK. Flushes pending spans before resolving.
|
|
488
515
|
*
|
|
489
|
-
* @param timeoutMs - The shutdown budget in milliseconds
|
|
490
|
-
*
|
|
491
|
-
* string, null)
|
|
492
|
-
* 2**31 - 1.
|
|
516
|
+
* @param timeoutMs - The shutdown budget in milliseconds. It is a hard wall-clock
|
|
517
|
+
* bound. Not given, or a value that is not a finite number (NaN, Infinity, a
|
|
518
|
+
* string, null): the `shutdownTimeoutS` of `init()` (default 10 s). A negative
|
|
519
|
+
* value gives 0. The largest value is 2**31 - 1.
|
|
493
520
|
*
|
|
494
521
|
* At the deadline, `shutdown()` stops the export in flight. Spans still queued
|
|
495
522
|
* and spans in the stopped export are counted as `shutdown_residue`, with one
|
|
@@ -598,14 +625,18 @@ declare function getMetrics(): {
|
|
|
598
625
|
rejectedSpans: number;
|
|
599
626
|
droppedSpans: number;
|
|
600
627
|
droppedSpansByReason: {
|
|
601
|
-
queue_full: number;
|
|
602
628
|
transport_refused: number;
|
|
629
|
+
retry_exhausted: number;
|
|
603
630
|
shutdown_residue: number;
|
|
631
|
+
too_large: number;
|
|
632
|
+
queue_full: number;
|
|
604
633
|
unacknowledged: number;
|
|
605
634
|
quota_exceeded: number;
|
|
606
635
|
};
|
|
607
636
|
droppedQuota: number;
|
|
608
637
|
failedExports: number;
|
|
638
|
+
attempts: number;
|
|
639
|
+
oldestPendingAgeS: number;
|
|
609
640
|
maskErrors: number;
|
|
610
641
|
queueSize: number;
|
|
611
642
|
queueCapacity: number;
|
|
@@ -613,9 +644,11 @@ declare function getMetrics(): {
|
|
|
613
644
|
} | {
|
|
614
645
|
failedScores: number;
|
|
615
646
|
droppedSpansByReason: {
|
|
616
|
-
queue_full: number;
|
|
617
647
|
transport_refused: number;
|
|
648
|
+
retry_exhausted: number;
|
|
618
649
|
shutdown_residue: number;
|
|
650
|
+
too_large: number;
|
|
651
|
+
queue_full: number;
|
|
619
652
|
unacknowledged: number;
|
|
620
653
|
quota_exceeded: number;
|
|
621
654
|
};
|
|
@@ -625,6 +658,8 @@ declare function getMetrics(): {
|
|
|
625
658
|
droppedSpans: number;
|
|
626
659
|
droppedQuota: number;
|
|
627
660
|
failedExports: number;
|
|
661
|
+
attempts: number;
|
|
662
|
+
oldestPendingAgeS: number;
|
|
628
663
|
maskErrors: number;
|
|
629
664
|
queueSize: number;
|
|
630
665
|
queueCapacity: number;
|
|
@@ -640,9 +675,13 @@ declare function getMetrics(): {
|
|
|
640
675
|
shutdown_residue: number;
|
|
641
676
|
unacknowledged: number;
|
|
642
677
|
quota_exceeded: number;
|
|
678
|
+
retry_exhausted: number;
|
|
679
|
+
too_large: number;
|
|
643
680
|
};
|
|
644
681
|
droppedQuota: number;
|
|
645
682
|
failedExports: number;
|
|
683
|
+
attempts: number;
|
|
684
|
+
oldestPendingAgeS: number;
|
|
646
685
|
queueSize: number;
|
|
647
686
|
queueCapacity: number;
|
|
648
687
|
queueUtilization: number;
|
|
@@ -662,8 +701,37 @@ declare function reportError(error: unknown, options?: {
|
|
|
662
701
|
name?: string;
|
|
663
702
|
attributes?: Record<string, unknown>;
|
|
664
703
|
}): void;
|
|
704
|
+
/** What a score's judgment is (score v2, W2-5). See "Scores, feedback and outcomes" in the README. */
|
|
705
|
+
type ScoreKind = 'annotation' | 'eval' | 'feedback' | 'outcome';
|
|
706
|
+
/** The arguments of `score()` (score v2). One of `traceId` and `sessionId` is required. */
|
|
707
|
+
interface ScoreOptions {
|
|
708
|
+
/** Score name, 1 to 128 characters (for example "accuracy", "resolved"). */
|
|
709
|
+
name: string;
|
|
710
|
+
/** A finite number (any range), a string of 1 to 256 characters, or a boolean. */
|
|
711
|
+
value: number | string | boolean;
|
|
712
|
+
/** The trace to score (32 lowercase hex characters). */
|
|
713
|
+
traceId?: string;
|
|
714
|
+
/** A span within the trace (16 lowercase hex characters). Needs `traceId`. */
|
|
715
|
+
spanId?: string;
|
|
716
|
+
/** The session to score (1 to 255 characters), with or instead of a trace. */
|
|
717
|
+
sessionId?: string;
|
|
718
|
+
/** A human-readable explanation, at most 4,096 characters. */
|
|
719
|
+
comment?: string;
|
|
720
|
+
/** What the judgment is. Default `annotation`. */
|
|
721
|
+
kind?: ScoreKind;
|
|
722
|
+
}
|
|
665
723
|
/**
|
|
666
|
-
* Record a
|
|
724
|
+
* Record a score on a trace, a span or a session (score v2, W2-5).
|
|
725
|
+
*
|
|
726
|
+
* `value` is typed, and its type decides how the Risicare server stores it: a finite number (any
|
|
727
|
+
* range) is numeric, a string of 1 to 256 characters is categorical, `true` or `false` is boolean.
|
|
728
|
+
* `kind` says what the judgment is: `annotation` (a person's judgment, the default), `eval` (an
|
|
729
|
+
* evaluator, a model or a rule), `feedback` (the end user's reaction) or `outcome` (a result that
|
|
730
|
+
* your own system knows, such as resolved, refunded or goal met; no model infers it). One of
|
|
731
|
+
* `traceId` and `sessionId` is required; `spanId` needs `traceId`.
|
|
732
|
+
*
|
|
733
|
+
* The positional form of 0.10.0 and earlier, `score(traceId, name, value, { spanId, comment })`,
|
|
734
|
+
* still sends the score, and the first such call writes one WARNING. Use the object form.
|
|
667
735
|
*
|
|
668
736
|
* Sends the score in the background. The root `flush()` waits for it.
|
|
669
737
|
* This function never throws and does not block. At most 50 score requests
|
|
@@ -678,21 +746,23 @@ declare function reportError(error: unknown, options?: {
|
|
|
678
746
|
* the score name and the status or the error code. Later failures in the next
|
|
679
747
|
* 10 s are counted, and the next WARNING gives their number. Root `flush()`
|
|
680
748
|
* waits for pending scores inside its deadline, and returns `false` when a
|
|
681
|
-
* score failed since the previous `flush()` returned.
|
|
682
|
-
* value that is not a number,
|
|
683
|
-
*
|
|
684
|
-
*
|
|
685
|
-
*
|
|
749
|
+
* score failed since the previous `flush()` returned. A score that the SDK refuses at the call
|
|
750
|
+
* (a value that is not a finite number, a string of 1 to 256 characters or a boolean; an empty or
|
|
751
|
+
* too long name; no trace and no session; a span with no trace; an unknown kind) writes one
|
|
752
|
+
* WARNING, and the SDK does not send it. It counts as a failed score, so the next `flush()` is
|
|
753
|
+
* false (not when the SDK is not active: then nothing is counted).
|
|
686
754
|
*
|
|
687
|
-
* If a `mask` is configured on `init()`, `
|
|
688
|
-
*
|
|
689
|
-
*
|
|
755
|
+
* If a `mask` is configured on `init()`, `comment` is passed to it under the key `score.comment`
|
|
756
|
+
* before the request is built. `traceId`, `spanId`, `sessionId`, `name` and `value` are NOT
|
|
757
|
+
* masked: they are identifiers and the judgment itself, which the platform joins, groups and
|
|
758
|
+
* filters on.
|
|
690
759
|
*
|
|
691
|
-
* @
|
|
692
|
-
*
|
|
693
|
-
*
|
|
694
|
-
* @param options - Optional span_id and comment
|
|
760
|
+
* @example
|
|
761
|
+
* score({ name: 'factual_accuracy', value: 0.92, traceId });
|
|
762
|
+
* score({ name: 'resolved', value: true, sessionId: 'conv-7', kind: 'outcome' });
|
|
695
763
|
*/
|
|
764
|
+
declare function score(options: ScoreOptions): void;
|
|
765
|
+
/** @deprecated Use `score({ name, value, traceId, spanId, comment })`. */
|
|
696
766
|
declare function score(traceId: string, name: string, value: number, options?: {
|
|
697
767
|
spanId?: string;
|
|
698
768
|
comment?: string;
|
|
@@ -814,6 +884,61 @@ declare function session(options: SessionOptions): <TArgs extends unknown[], TR>
|
|
|
814
884
|
declare function session<TArgs extends unknown[]>(resolver: (...args: TArgs) => SessionOptions): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
|
|
815
885
|
declare function session<TArgs extends unknown[]>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions)): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
|
|
816
886
|
|
|
887
|
+
/**
|
|
888
|
+
* Identity helpers (W2-2): put the user, the session, the release and tags on the current trace.
|
|
889
|
+
*
|
|
890
|
+
* The Python twin is `risicare/identity.py`. Each helper writes one span attribute that the
|
|
891
|
+
* Risicare spans worker reads into a dashboard column (contract spec W2-2, section 6; ANSWER 91):
|
|
892
|
+
*
|
|
893
|
+
* | Helper | Span attribute | Column |
|
|
894
|
+
* |------------------------|----------------------|---------|
|
|
895
|
+
* | `setUser(id)` | `user.id` | User |
|
|
896
|
+
* | `setSession(id)` | `session.id` | Session |
|
|
897
|
+
* | `setRelease(version)` | `risicare.release` | Release |
|
|
898
|
+
* | `addTags([...])` | `tag.tags` | Tags |
|
|
899
|
+
*
|
|
900
|
+
* Scope. The current span gets the attribute at once. Each other span of the same trace that
|
|
901
|
+
* ends after the call gets it when it ends, unless that span has the attribute already (tags are
|
|
902
|
+
* merged, in order, with no repeats). That includes the spans that are open now (for example the
|
|
903
|
+
* root span) and the spans that start later, in any async context of this process. A span of
|
|
904
|
+
* another trace never gets it, so a value cannot pass from one request to the next.
|
|
905
|
+
*
|
|
906
|
+
* Outside a span there is no trace: the helper sets nothing and returns `false`, and the first
|
|
907
|
+
* such call of each helper writes one WARNING. For a value that must apply before the first span,
|
|
908
|
+
* use `withSession({ sessionId, userId }, fn)` or `init({ serviceVersion })`.
|
|
909
|
+
*
|
|
910
|
+
* The values of at most `MAX_TRACES` traces are kept (the oldest is forgotten first), so memory
|
|
911
|
+
* stays bounded in a long-running process. The registry lives on `globalThis`, so that every
|
|
912
|
+
* entry point bundle uses the same one (see `globals.ts`).
|
|
913
|
+
*/
|
|
914
|
+
|
|
915
|
+
/**
|
|
916
|
+
* Set the user of the current trace: the span attribute `user.id` (dashboard column User).
|
|
917
|
+
* Returns `true` when it was set. The worker reads `session.user_id` (from `withSession`) and
|
|
918
|
+
* `user_id` before `user.id`, so a session user wins.
|
|
919
|
+
*/
|
|
920
|
+
declare function setUser(userId: string | number): boolean;
|
|
921
|
+
/**
|
|
922
|
+
* Set the session of the current trace: the span attribute `session.id` (column Session).
|
|
923
|
+
* Returns `true` when it was set. The worker reads the typed session of a span (from
|
|
924
|
+
* `withSession`) before `session.id`, so a session context wins.
|
|
925
|
+
*/
|
|
926
|
+
declare function setSession(sessionId: string | number): boolean;
|
|
927
|
+
/**
|
|
928
|
+
* Set the release of the current trace: the span attribute `risicare.release` (column Release).
|
|
929
|
+
* Returns `true` when it was set. `risicare.release` is the first source of the Release column;
|
|
930
|
+
* the next one is `service.version`, which `init({ serviceVersion })` (or
|
|
931
|
+
* `RISICARE_SERVICE_VERSION`) puts on every span with no other code.
|
|
932
|
+
*/
|
|
933
|
+
declare function setRelease(version: string | number): boolean;
|
|
934
|
+
/**
|
|
935
|
+
* Add tags to the current trace: the span attribute `tag.tags`, an array (column Tags). A later
|
|
936
|
+
* call adds to the tags of the earlier ones, in order, with no repeats. Returns `true` when at
|
|
937
|
+
* least one tag was added. An item that is not a non-empty string is left out, with one WARNING.
|
|
938
|
+
* The worker keeps at most 50 tags for each span and cuts each one at 200 characters.
|
|
939
|
+
*/
|
|
940
|
+
declare function addTags(tags: readonly string[]): boolean;
|
|
941
|
+
|
|
817
942
|
/**
|
|
818
943
|
* Phase decorators — decision phase tracking (Tier 4).
|
|
819
944
|
*
|
|
@@ -1769,4 +1894,4 @@ type Tracer = Tracer$1;
|
|
|
1769
1894
|
|
|
1770
1895
|
type Span = Span$1;
|
|
1771
1896
|
|
|
1772
|
-
export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, GuardRejectedError, type HeaderLookup, MASK_ERROR_MARKER, type MaskFn, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, type Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, type Tracer, type VerifyWebhookOptions, type WebhookPayload, WebhookVerificationError, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getFixRuntime, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, initFixRuntime, injectTraceContext, isEnabled, isProviderInstrumentationSuppressed, registerSpan, reportError, score, session, shutdown, shutdownFixRuntime, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, verifyWebhookSignature, withAgent, withPhase, withSession };
|
|
1897
|
+
export { type ActiveFix, type AgentContext, type AgentOptions, AgentRole, DEFAULT_TIMESTAMP_TOLERANCE_S, type FixRuntimeConfig, GuardRejectedError, type HeaderLookup, MASK_ERROR_MARKER, type MaskFn, MessageType, type RisicareConfig, type ScoreKind, type ScoreOptions, SemanticPhase, type SessionContext, type SessionOptions, type Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, type TracedStreamOptions, type Tracer, type VerifyWebhookOptions, type WebhookPayload, WebhookVerificationError, addTags, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getFixRuntime, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, initFixRuntime, injectTraceContext, isEnabled, isProviderInstrumentationSuppressed, registerSpan, reportError, score, session, setRelease, setSession, setUser, shutdown, shutdownFixRuntime, suppressProviderInstrumentation, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, tracedStream, unregisterSpan, verifyWebhookSignature, withAgent, withPhase, withSession };
|