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

main
ts 217 lines 7.23 KB
Raw
1 /**
2 * Connects Effect logging to the OpenTelemetry Logs SDK.
3 *
4 * This module turns Effect log events into OpenTelemetry log records. It maps
5 * Effect log levels to OpenTelemetry severity numbers, provides the
6 * `OtelLoggerProvider` service, creates an Effect `Logger` with `make`, and
7 * offers layers for installing that logger or creating a scoped SDK
8 * `LoggerProvider` from one or more `LogRecordProcessor`s.
9 *
10 * @stability unstable
11 * @since 4.0.0
12 */
13 import * as OtelApi from "@opentelemetry/api"
14 import { SeverityNumber } from "@opentelemetry/api-logs"
15 import * as Otel from "@opentelemetry/sdk-logs"
16 import type { NonEmptyReadonlyArray } from "effect/Array"
17 import * as Arr from "effect/Array"
18 import * as Cause from "effect/Cause"
19 import * as Clock from "effect/Clock"
20 import * as Context from "effect/Context"
21 import type * as Duration from "effect/Duration"
22 import * as Effect from "effect/Effect"
23 import * as Layer from "effect/Layer"
24 import * as Logger from "effect/Logger"
25 import type * as LogLevel from "effect/LogLevel"
26 import * as Predicate from "effect/Predicate"
27 import * as Rec from "effect/Record"
28 import * as References from "effect/References"
29 import * as Tracer from "effect/Tracer"
30 import * as Version from "effect/Version"
31 import { nanosToHrTime, unknownToAttributeValue } from "./internal/attributes.ts"
32 import { populateContext } from "./OtelTracer.ts"
33 import { Resource } from "./Resource.ts"
34
35 /**
36 * Context service containing the OpenTelemetry `LoggerProvider` used to emit Effect log records.
37 *
38 * @stability unstable
39 * @category services
40 * @since 4.0.0
41 */
42 export class OtelLoggerProvider extends Context.Service<
43 OtelLoggerProvider,
44 Otel.LoggerProvider
45 >()("@effect/opentelemetry/Logger/OtelLoggerProvider") {}
46
47 /**
48 * Maps an Effect `LogLevel` to the corresponding OpenTelemetry `SeverityNumber`.
49 *
50 * **Details**
51 *
52 * OpenTelemetry log severity numbers are in the range `1` through `24`. This
53 * function maps from Effect's log levels instead of using
54 * `LogLevel.getOrdinal`, whose internal sort ordinals, such as the `Info`
55 * ordinal `20000`, fall outside the OpenTelemetry logs data model and can be
56 * treated as `UNSPECIFIED` by validating backends.
57 *
58 * @stability unstable
59 * @category converting
60 * @since 4.0.0
61 */
62 export const logLevelToSeverityNumber = (level: LogLevel.LogLevel): SeverityNumber => {
63 switch (level) {
64 case "Trace":
65 return SeverityNumber.TRACE
66 case "Debug":
67 return SeverityNumber.DEBUG
68 case "Info":
69 return SeverityNumber.INFO
70 case "Warn":
71 return SeverityNumber.WARN
72 case "Error":
73 return SeverityNumber.ERROR
74 case "Fatal":
75 return SeverityNumber.FATAL
76 default:
77 return SeverityNumber.UNSPECIFIED
78 }
79 }
80
81 /**
82 * Creates an Effect logger that emits log records through the configured OpenTelemetry logger provider.
83 *
84 * @stability unstable
85 * @category constructors
86 * @since 4.0.0
87 */
88 export const make: Effect.Effect<
89 Logger.Logger<unknown, void>,
90 never,
91 OtelLoggerProvider
92 > = Effect.gen(function*() {
93 const loggerProvider = yield* OtelLoggerProvider
94 const clock = yield* Clock.Clock
95 const otelLogger = loggerProvider.getLogger("effect", Version.getCurrentVersion())
96
97 return Logger.make((options) => {
98 const attributes: Record<string, any> = {}
99
100 for (const [key, value] of Object.entries(options.fiber.getRef(References.CurrentLogAnnotations))) {
101 Rec.assignProperty(attributes, key, unknownToAttributeValue(value))
102 }
103
104 attributes["effect.fiberId"] = options.fiber.id
105
106 const span = Context.getOrUndefined(options.fiber.context, Tracer.ParentSpan)
107 const activeContext = OtelApi.context.active()
108 const logContext = Predicate.isNotUndefined(span)
109 ? populateContext(activeContext, span, span.annotations)
110 : activeContext
111
112 if (Predicate.isNotUndefined(span)) {
113 attributes.spanId = span.spanId
114 attributes.traceId = span.traceId
115 }
116
117 const now = options.date.getTime()
118 // Outermost spans win duplicate labels.
119 for (const [label, startTime] of options.fiber.getRef(References.CurrentLogSpans)) {
120 attributes[`effect.log_span.${label}`] = now - startTime
121 }
122
123 const errors = Cause.prettyErrors(options.cause, { includeCauseInStack: true })
124 if (errors.length > 0) {
125 attributes["exception.type"] = errors[0].name
126 attributes["exception.message"] = errors[0].message
127 attributes["exception.stacktrace"] = errors.map((error) => error.stack).join("\n")
128 }
129
130 const message = Arr.ensure(options.message).map(unknownToAttributeValue)
131 otelLogger.emit({
132 body: message.length === 1 ? message[0] : message,
133 severityText: options.logLevel,
134 severityNumber: logLevelToSeverityNumber(options.logLevel),
135 timestamp: options.date,
136 observedTimestamp: nanosToHrTime(clock.currentTimeNanosUnsafe()),
137 attributes,
138 context: logContext
139 })
140 })
141 })
142
143 /**
144 * Creates a layer that installs the OpenTelemetry-backed Effect logger, merging with existing loggers by default.
145 *
146 * **When to use**
147 *
148 * Use to install the OpenTelemetry-backed Effect logger in an application that
149 * has an `OtelLoggerProvider`, so standard Effect logging emits OpenTelemetry
150 * log records.
151 *
152 * **Details**
153 *
154 * The layer installs the logger created by `make`. `mergeWithExisting` defaults
155 * to `true`; set it to `false` to replace the current logger set.
156 *
157 * @see {@link make} for constructing the logger directly
158 * @see {@link layerLoggerProvider} for creating the required logger provider
159 *
160 * @stability unstable
161 * @category layers
162 * @since 4.0.0
163 */
164 export const layer = (options: {
165 /**
166 * Whether to merge the OpenTelemetry logger with existing loggers.
167 *
168 * **Details**
169 *
170 * If set to `true`, the OpenTelemetry logger will be merged with existing
171 * loggers in the application.
172 *
173 * If set to `false`, the OpenTelemetry logger will replace all existing
174 * loggers in the application.
175 *
176 * Defaults to `true`.
177 */
178 readonly mergeWithExisting?: boolean | undefined
179 }): Layer.Layer<never, never, OtelLoggerProvider> =>
180 Logger.layer([make], {
181 mergeWithExisting: options.mergeWithExisting ?? true
182 })
183
184 /**
185 * Creates a scoped OpenTelemetry logger provider from one or more log record processors, using the current `Resource` and flushing and shutting down the provider when the layer is released.
186 *
187 * @stability unstable
188 * @category layers
189 * @since 4.0.0
190 */
191 export const layerLoggerProvider = (
192 processor: Otel.LogRecordProcessor | NonEmptyReadonlyArray<Otel.LogRecordProcessor>,
193 config?: Omit<Otel.LoggerProviderConfig, "resource"> & {
194 readonly shutdownTimeout?: Duration.Input | undefined
195 }
196 ): Layer.Layer<OtelLoggerProvider, never, Resource> =>
197 Layer.effect(
198 OtelLoggerProvider,
199 Effect.gen(function*() {
200 const resource = yield* Resource
201 return yield* Effect.acquireRelease(
202 Effect.sync(() =>
203 new Otel.LoggerProvider({
204 ...(config ?? undefined),
205 processors: Arr.ensure(processor),
206 resource
207 })
208 ),
209 (provider) =>
210 Effect.promise(() => provider.forceFlush().finally(() => provider.shutdown())).pipe(
211 Effect.ignore,
212 Effect.interruptible,
213 Effect.timeoutOption(config?.shutdownTimeout ?? 3000)
214 )
215 )
216 })
217 )