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

main
ts 142 lines 4.01 KB
Raw
1 /**
2 * The `OpenAiTelemetry` module defines OpenAI-compatible 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 a list of
72 * 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 telemetry
87 * attributes with optional OpenAI-compatible 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 OpenAI-compatible model span with standard GenAI telemetry
114 * attributes and OpenAI-specific request or response metadata.
115 *
116 * **Details**
117 *
118 * Standard GenAI attributes are applied first. OpenAI metadata is written under
119 * `openai.request.*` and `openai.response.*`.
120 *
121 * **Gotchas**
122 *
123 * Mutates the supplied `Span` in place.
124 *
125 * @stability unstable
126 * @category tracing
127 * @since 4.0.0
128 */
129 export const addGenAIAnnotations: {
130 (options: OpenAiTelemetryAttributeOptions): (span: Span) => void
131 (span: Span, options: OpenAiTelemetryAttributeOptions): void
132 } = dual(2, (span: Span, options: OpenAiTelemetryAttributeOptions) => {
133 Telemetry.addGenAIAnnotations(span, options)
134 if (options.openai != null) {
135 if (options.openai.request != null) {
136 addOpenAiRequestAttributes(span, options.openai.request)
137 }
138 if (options.openai.response != null) {
139 addOpenAiResponseAttributes(span, options.openai.response)
140 }
141 }
142 })