@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
ts 140 lines 4.02 KB
Raw
1 /**
2 * The `OpenAiTelemetry` module defines OpenAI-specific telemetry attributes
3 * and a helper for adding them to a tracing span. It keeps the standard GenAI
4 * telemetry attributes and adds service tier and system fingerprint under
5 * `openai.*`.
6 *
7 * @stability unstable
8 * @since 4.0.0
9 */
10 import * as Telemetry from "effect/ai/Telemetry"
11 import { dual } from "effect/Function"
12 import * as String from "effect/String"
13 import type { Span } from "effect/Tracer"
14 import type { Simplify } from "effect/Types"
15
16 /**
17 * The attributes used to describe telemetry in the context of Generative
18 * Artificial Intelligence (GenAI) Models requests and responses.
19 *
20 * **Details**
21 *
22 * These attributes follow the OpenTelemetry generative AI semantic
23 * conventions:
24 * https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/
25 *
26 * @stability unstable
27 * @category models
28 * @since 4.0.0
29 */
30 export type OpenAiTelemetryAttributes = Simplify<
31 & Telemetry.GenAITelemetryAttributes
32 & Telemetry.AttributesWithPrefix<RequestAttributes, "openai.request">
33 & Telemetry.AttributesWithPrefix<ResponseAttributes, "openai.response">
34 >
35
36 /**
37 * OpenAI request metadata, written under `openai.request.*`.
38 *
39 * @stability unstable
40 * @category models
41 * @since 4.0.0
42 */
43 export interface RequestAttributes {
44 /**
45 * The service tier requested. May be a specific tier, `default`, or `auto`.
46 */
47 readonly serviceTier?: (string & {}) | WellKnownServiceTier | null | undefined
48 }
49
50 /**
51 * Telemetry attributes which are part of the GenAI specification and are
52 * namespaced by `openai.response`.
53 *
54 * @stability unstable
55 * @category models
56 * @since 4.0.0
57 */
58 export interface ResponseAttributes {
59 /**
60 * The service tier used for the response.
61 */
62 readonly serviceTier?: string | null | undefined
63 /**
64 * A fingerprint to track any eventual change in the Generative AI
65 * environment.
66 */
67 readonly systemFingerprint?: string | null | undefined
68 }
69
70 /**
71 * The `openai.request.service_tier` attribute has the following
72 * list of well-known values.
73 *
74 * **Details**
75 *
76 * If one of them applies, then the respective value **MUST** be used;
77 * otherwise, a custom value **MAY** be used.
78 *
79 * @stability unstable
80 * @category models
81 * @since 4.0.0
82 */
83 export type WellKnownServiceTier = "auto" | "default"
84
85 /**
86 * Options accepted by `addGenAIAnnotations`, combining standard GenAI
87 * telemetry attributes with optional OpenAI request and response attributes.
88 *
89 * @stability unstable
90 * @category options
91 * @since 4.0.0
92 */
93 export type OpenAiTelemetryAttributeOptions = Telemetry.GenAITelemetryAttributeOptions & {
94 openai?: {
95 request?: RequestAttributes | undefined
96 response?: ResponseAttributes | undefined
97 } | undefined
98 }
99
100 const addOpenAiRequestAttributes = Telemetry.addSpanAttributes("openai.request", String.camelToSnake)<
101 RequestAttributes
102 >
103 const addOpenAiResponseAttributes = Telemetry.addSpanAttributes("openai.response", String.camelToSnake)<
104 ResponseAttributes
105 >
106
107 /**
108 * Applies the specified OpenAI GenAI telemetry attributes to the provided
109 * `Span`.
110 *
111 * **When to use**
112 *
113 * Use to annotate an existing OpenTelemetry span with standard GenAI attributes
114 * plus OpenAI-specific request and response metadata.
115 *
116 * **Gotchas**
117 *
118 * Mutates the supplied `Span` in place.
119 *
120 * @see {@link OpenAiTelemetryAttributeOptions} for the accepted telemetry attributes
121 * @see {@link Telemetry.addGenAIAnnotations} for the provider-neutral annotation helper
122 *
123 * @stability unstable
124 * @category tracing
125 * @since 4.0.0
126 */
127 export const addGenAIAnnotations: {
128 (options: OpenAiTelemetryAttributeOptions): (span: Span) => void
129 (span: Span, options: OpenAiTelemetryAttributeOptions): void
130 } = dual(2, (span: Span, options: OpenAiTelemetryAttributeOptions) => {
131 Telemetry.addGenAIAnnotations(span, options)
132 if (options.openai != null) {
133 if (options.openai.request != null) {
134 addOpenAiRequestAttributes(span, options.openai.request)
135 }
136 if (options.openai.response != null) {
137 addOpenAiResponseAttributes(span, options.openai.response)
138 }
139 }
140 })