risicare 0.10.0 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +76 -5
- package/README.md +157 -39
- package/dist/frameworks/instructor.cjs +338 -117
- package/dist/frameworks/instructor.cjs.map +1 -1
- package/dist/frameworks/instructor.js +338 -117
- package/dist/frameworks/instructor.js.map +1 -1
- package/dist/frameworks/langchain.cjs +351 -130
- package/dist/frameworks/langchain.cjs.map +1 -1
- package/dist/frameworks/langchain.js +351 -130
- package/dist/frameworks/langchain.js.map +1 -1
- package/dist/frameworks/langgraph.cjs +351 -130
- package/dist/frameworks/langgraph.cjs.map +1 -1
- package/dist/frameworks/langgraph.js +351 -130
- package/dist/frameworks/langgraph.js.map +1 -1
- package/dist/frameworks/llamaindex.cjs +351 -130
- package/dist/frameworks/llamaindex.cjs.map +1 -1
- package/dist/frameworks/llamaindex.js +351 -130
- package/dist/frameworks/llamaindex.js.map +1 -1
- package/dist/index.cjs +808 -226
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +137 -21
- package/dist/index.d.ts +137 -21
- package/dist/index.js +804 -226
- package/dist/index.js.map +1 -1
- package/dist/providers/anthropic/index.cjs +351 -130
- package/dist/providers/anthropic/index.cjs.map +1 -1
- package/dist/providers/anthropic/index.js +351 -130
- package/dist/providers/anthropic/index.js.map +1 -1
- package/dist/providers/bedrock/index.cjs +346 -125
- package/dist/providers/bedrock/index.cjs.map +1 -1
- package/dist/providers/bedrock/index.js +346 -125
- package/dist/providers/bedrock/index.js.map +1 -1
- package/dist/providers/cerebras/index.cjs +351 -130
- package/dist/providers/cerebras/index.cjs.map +1 -1
- package/dist/providers/cerebras/index.js +351 -130
- package/dist/providers/cerebras/index.js.map +1 -1
- package/dist/providers/cohere/index.cjs +351 -130
- package/dist/providers/cohere/index.cjs.map +1 -1
- package/dist/providers/cohere/index.js +351 -130
- package/dist/providers/cohere/index.js.map +1 -1
- package/dist/providers/google/index.cjs +351 -130
- package/dist/providers/google/index.cjs.map +1 -1
- package/dist/providers/google/index.js +351 -130
- package/dist/providers/google/index.js.map +1 -1
- package/dist/providers/groq/index.cjs +351 -130
- package/dist/providers/groq/index.cjs.map +1 -1
- package/dist/providers/groq/index.js +351 -130
- package/dist/providers/groq/index.js.map +1 -1
- package/dist/providers/huggingface/index.cjs +351 -130
- package/dist/providers/huggingface/index.cjs.map +1 -1
- package/dist/providers/huggingface/index.js +351 -130
- package/dist/providers/huggingface/index.js.map +1 -1
- package/dist/providers/mistral/index.cjs +351 -130
- package/dist/providers/mistral/index.cjs.map +1 -1
- package/dist/providers/mistral/index.js +351 -130
- package/dist/providers/mistral/index.js.map +1 -1
- package/dist/providers/ollama/index.cjs +351 -130
- package/dist/providers/ollama/index.cjs.map +1 -1
- package/dist/providers/ollama/index.js +351 -130
- package/dist/providers/ollama/index.js.map +1 -1
- package/dist/providers/openai/index.cjs +351 -130
- package/dist/providers/openai/index.cjs.map +1 -1
- package/dist/providers/openai/index.js +351 -130
- package/dist/providers/openai/index.js.map +1 -1
- package/dist/providers/together/index.cjs +351 -130
- package/dist/providers/together/index.cjs.map +1 -1
- package/dist/providers/together/index.js +351 -130
- package/dist/providers/together/index.js.map +1 -1
- package/dist/providers/vercel-ai/index.cjs +351 -130
- package/dist/providers/vercel-ai/index.cjs.map +1 -1
- package/dist/providers/vercel-ai/index.js +351 -130
- package/dist/providers/vercel-ai/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -329,8 +329,26 @@ interface RisicareConfig {
|
|
|
329
329
|
batchSize?: number;
|
|
330
330
|
/** Batch timeout in ms before flush (default: 1000) */
|
|
331
331
|
batchTimeoutMs?: number;
|
|
332
|
-
/**
|
|
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
|
+
*/
|
|
333
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;
|
|
334
352
|
/** Enable debug logging (default: false) */
|
|
335
353
|
debug?: boolean;
|
|
336
354
|
/** Enable gzip compression for HTTP exports (default: false) */
|
|
@@ -495,10 +513,10 @@ declare function init(config?: Partial<RisicareConfig>): void;
|
|
|
495
513
|
/**
|
|
496
514
|
* Gracefully shut down the SDK. Flushes pending spans before resolving.
|
|
497
515
|
*
|
|
498
|
-
* @param timeoutMs - The shutdown budget in milliseconds
|
|
499
|
-
*
|
|
500
|
-
* string, null)
|
|
501
|
-
* 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.
|
|
502
520
|
*
|
|
503
521
|
* At the deadline, `shutdown()` stops the export in flight. Spans still queued
|
|
504
522
|
* and spans in the stopped export are counted as `shutdown_residue`, with one
|
|
@@ -607,14 +625,18 @@ declare function getMetrics(): {
|
|
|
607
625
|
rejectedSpans: number;
|
|
608
626
|
droppedSpans: number;
|
|
609
627
|
droppedSpansByReason: {
|
|
610
|
-
queue_full: number;
|
|
611
628
|
transport_refused: number;
|
|
629
|
+
retry_exhausted: number;
|
|
612
630
|
shutdown_residue: number;
|
|
631
|
+
too_large: number;
|
|
632
|
+
queue_full: number;
|
|
613
633
|
unacknowledged: number;
|
|
614
634
|
quota_exceeded: number;
|
|
615
635
|
};
|
|
616
636
|
droppedQuota: number;
|
|
617
637
|
failedExports: number;
|
|
638
|
+
attempts: number;
|
|
639
|
+
oldestPendingAgeS: number;
|
|
618
640
|
maskErrors: number;
|
|
619
641
|
queueSize: number;
|
|
620
642
|
queueCapacity: number;
|
|
@@ -622,9 +644,11 @@ declare function getMetrics(): {
|
|
|
622
644
|
} | {
|
|
623
645
|
failedScores: number;
|
|
624
646
|
droppedSpansByReason: {
|
|
625
|
-
queue_full: number;
|
|
626
647
|
transport_refused: number;
|
|
648
|
+
retry_exhausted: number;
|
|
627
649
|
shutdown_residue: number;
|
|
650
|
+
too_large: number;
|
|
651
|
+
queue_full: number;
|
|
628
652
|
unacknowledged: number;
|
|
629
653
|
quota_exceeded: number;
|
|
630
654
|
};
|
|
@@ -634,6 +658,8 @@ declare function getMetrics(): {
|
|
|
634
658
|
droppedSpans: number;
|
|
635
659
|
droppedQuota: number;
|
|
636
660
|
failedExports: number;
|
|
661
|
+
attempts: number;
|
|
662
|
+
oldestPendingAgeS: number;
|
|
637
663
|
maskErrors: number;
|
|
638
664
|
queueSize: number;
|
|
639
665
|
queueCapacity: number;
|
|
@@ -649,9 +675,13 @@ declare function getMetrics(): {
|
|
|
649
675
|
shutdown_residue: number;
|
|
650
676
|
unacknowledged: number;
|
|
651
677
|
quota_exceeded: number;
|
|
678
|
+
retry_exhausted: number;
|
|
679
|
+
too_large: number;
|
|
652
680
|
};
|
|
653
681
|
droppedQuota: number;
|
|
654
682
|
failedExports: number;
|
|
683
|
+
attempts: number;
|
|
684
|
+
oldestPendingAgeS: number;
|
|
655
685
|
queueSize: number;
|
|
656
686
|
queueCapacity: number;
|
|
657
687
|
queueUtilization: number;
|
|
@@ -671,8 +701,37 @@ declare function reportError(error: unknown, options?: {
|
|
|
671
701
|
name?: string;
|
|
672
702
|
attributes?: Record<string, unknown>;
|
|
673
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
|
+
}
|
|
674
723
|
/**
|
|
675
|
-
* 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.
|
|
676
735
|
*
|
|
677
736
|
* Sends the score in the background. The root `flush()` waits for it.
|
|
678
737
|
* This function never throws and does not block. At most 50 score requests
|
|
@@ -687,21 +746,23 @@ declare function reportError(error: unknown, options?: {
|
|
|
687
746
|
* the score name and the status or the error code. Later failures in the next
|
|
688
747
|
* 10 s are counted, and the next WARNING gives their number. Root `flush()`
|
|
689
748
|
* waits for pending scores inside its deadline, and returns `false` when a
|
|
690
|
-
* score failed since the previous `flush()` returned.
|
|
691
|
-
* value that is not a number,
|
|
692
|
-
*
|
|
693
|
-
*
|
|
694
|
-
*
|
|
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).
|
|
695
754
|
*
|
|
696
|
-
* If a `mask` is configured on `init()`, `
|
|
697
|
-
*
|
|
698
|
-
*
|
|
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.
|
|
699
759
|
*
|
|
700
|
-
* @
|
|
701
|
-
*
|
|
702
|
-
*
|
|
703
|
-
* @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' });
|
|
704
763
|
*/
|
|
764
|
+
declare function score(options: ScoreOptions): void;
|
|
765
|
+
/** @deprecated Use `score({ name, value, traceId, spanId, comment })`. */
|
|
705
766
|
declare function score(traceId: string, name: string, value: number, options?: {
|
|
706
767
|
spanId?: string;
|
|
707
768
|
comment?: string;
|
|
@@ -823,6 +884,61 @@ declare function session(options: SessionOptions): <TArgs extends unknown[], TR>
|
|
|
823
884
|
declare function session<TArgs extends unknown[]>(resolver: (...args: TArgs) => SessionOptions): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
|
|
824
885
|
declare function session<TArgs extends unknown[]>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions)): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
|
|
825
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
|
+
|
|
826
942
|
/**
|
|
827
943
|
* Phase decorators — decision phase tracking (Tier 4).
|
|
828
944
|
*
|
|
@@ -1778,4 +1894,4 @@ type Tracer = Tracer$1;
|
|
|
1778
1894
|
|
|
1779
1895
|
type Span = Span$1;
|
|
1780
1896
|
|
|
1781
|
-
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
|
@@ -329,8 +329,26 @@ interface RisicareConfig {
|
|
|
329
329
|
batchSize?: number;
|
|
330
330
|
/** Batch timeout in ms before flush (default: 1000) */
|
|
331
331
|
batchTimeoutMs?: number;
|
|
332
|
-
/**
|
|
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
|
+
*/
|
|
333
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;
|
|
334
352
|
/** Enable debug logging (default: false) */
|
|
335
353
|
debug?: boolean;
|
|
336
354
|
/** Enable gzip compression for HTTP exports (default: false) */
|
|
@@ -495,10 +513,10 @@ declare function init(config?: Partial<RisicareConfig>): void;
|
|
|
495
513
|
/**
|
|
496
514
|
* Gracefully shut down the SDK. Flushes pending spans before resolving.
|
|
497
515
|
*
|
|
498
|
-
* @param timeoutMs - The shutdown budget in milliseconds
|
|
499
|
-
*
|
|
500
|
-
* string, null)
|
|
501
|
-
* 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.
|
|
502
520
|
*
|
|
503
521
|
* At the deadline, `shutdown()` stops the export in flight. Spans still queued
|
|
504
522
|
* and spans in the stopped export are counted as `shutdown_residue`, with one
|
|
@@ -607,14 +625,18 @@ declare function getMetrics(): {
|
|
|
607
625
|
rejectedSpans: number;
|
|
608
626
|
droppedSpans: number;
|
|
609
627
|
droppedSpansByReason: {
|
|
610
|
-
queue_full: number;
|
|
611
628
|
transport_refused: number;
|
|
629
|
+
retry_exhausted: number;
|
|
612
630
|
shutdown_residue: number;
|
|
631
|
+
too_large: number;
|
|
632
|
+
queue_full: number;
|
|
613
633
|
unacknowledged: number;
|
|
614
634
|
quota_exceeded: number;
|
|
615
635
|
};
|
|
616
636
|
droppedQuota: number;
|
|
617
637
|
failedExports: number;
|
|
638
|
+
attempts: number;
|
|
639
|
+
oldestPendingAgeS: number;
|
|
618
640
|
maskErrors: number;
|
|
619
641
|
queueSize: number;
|
|
620
642
|
queueCapacity: number;
|
|
@@ -622,9 +644,11 @@ declare function getMetrics(): {
|
|
|
622
644
|
} | {
|
|
623
645
|
failedScores: number;
|
|
624
646
|
droppedSpansByReason: {
|
|
625
|
-
queue_full: number;
|
|
626
647
|
transport_refused: number;
|
|
648
|
+
retry_exhausted: number;
|
|
627
649
|
shutdown_residue: number;
|
|
650
|
+
too_large: number;
|
|
651
|
+
queue_full: number;
|
|
628
652
|
unacknowledged: number;
|
|
629
653
|
quota_exceeded: number;
|
|
630
654
|
};
|
|
@@ -634,6 +658,8 @@ declare function getMetrics(): {
|
|
|
634
658
|
droppedSpans: number;
|
|
635
659
|
droppedQuota: number;
|
|
636
660
|
failedExports: number;
|
|
661
|
+
attempts: number;
|
|
662
|
+
oldestPendingAgeS: number;
|
|
637
663
|
maskErrors: number;
|
|
638
664
|
queueSize: number;
|
|
639
665
|
queueCapacity: number;
|
|
@@ -649,9 +675,13 @@ declare function getMetrics(): {
|
|
|
649
675
|
shutdown_residue: number;
|
|
650
676
|
unacknowledged: number;
|
|
651
677
|
quota_exceeded: number;
|
|
678
|
+
retry_exhausted: number;
|
|
679
|
+
too_large: number;
|
|
652
680
|
};
|
|
653
681
|
droppedQuota: number;
|
|
654
682
|
failedExports: number;
|
|
683
|
+
attempts: number;
|
|
684
|
+
oldestPendingAgeS: number;
|
|
655
685
|
queueSize: number;
|
|
656
686
|
queueCapacity: number;
|
|
657
687
|
queueUtilization: number;
|
|
@@ -671,8 +701,37 @@ declare function reportError(error: unknown, options?: {
|
|
|
671
701
|
name?: string;
|
|
672
702
|
attributes?: Record<string, unknown>;
|
|
673
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
|
+
}
|
|
674
723
|
/**
|
|
675
|
-
* 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.
|
|
676
735
|
*
|
|
677
736
|
* Sends the score in the background. The root `flush()` waits for it.
|
|
678
737
|
* This function never throws and does not block. At most 50 score requests
|
|
@@ -687,21 +746,23 @@ declare function reportError(error: unknown, options?: {
|
|
|
687
746
|
* the score name and the status or the error code. Later failures in the next
|
|
688
747
|
* 10 s are counted, and the next WARNING gives their number. Root `flush()`
|
|
689
748
|
* waits for pending scores inside its deadline, and returns `false` when a
|
|
690
|
-
* score failed since the previous `flush()` returned.
|
|
691
|
-
* value that is not a number,
|
|
692
|
-
*
|
|
693
|
-
*
|
|
694
|
-
*
|
|
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).
|
|
695
754
|
*
|
|
696
|
-
* If a `mask` is configured on `init()`, `
|
|
697
|
-
*
|
|
698
|
-
*
|
|
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.
|
|
699
759
|
*
|
|
700
|
-
* @
|
|
701
|
-
*
|
|
702
|
-
*
|
|
703
|
-
* @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' });
|
|
704
763
|
*/
|
|
764
|
+
declare function score(options: ScoreOptions): void;
|
|
765
|
+
/** @deprecated Use `score({ name, value, traceId, spanId, comment })`. */
|
|
705
766
|
declare function score(traceId: string, name: string, value: number, options?: {
|
|
706
767
|
spanId?: string;
|
|
707
768
|
comment?: string;
|
|
@@ -823,6 +884,61 @@ declare function session(options: SessionOptions): <TArgs extends unknown[], TR>
|
|
|
823
884
|
declare function session<TArgs extends unknown[]>(resolver: (...args: TArgs) => SessionOptions): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
|
|
824
885
|
declare function session<TArgs extends unknown[]>(optionsOrResolver: SessionOptions | ((...args: TArgs) => SessionOptions)): <TR>(fn: (...args: TArgs) => TR) => (...args: TArgs) => TR;
|
|
825
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
|
+
|
|
826
942
|
/**
|
|
827
943
|
* Phase decorators — decision phase tracking (Tier 4).
|
|
828
944
|
*
|
|
@@ -1778,4 +1894,4 @@ type Tracer = Tracer$1;
|
|
|
1778
1894
|
|
|
1779
1895
|
type Span = Span$1;
|
|
1780
1896
|
|
|
1781
|
-
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 };
|