@narumitw/pi-otel 0.0.0-stage → 0.54.3
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 +162 -0
- package/LICENSE +21 -0
- package/README.md +368 -2
- package/dist/chunks/chunk-DSQBXICE.ts +150 -0
- package/dist/chunks/chunk-DSQBXICE.ts.map +7 -0
- package/dist/chunks/runtime-X3YFJUNH.ts +404 -0
- package/dist/chunks/runtime-X3YFJUNH.ts.map +7 -0
- package/dist/config.d.ts +36 -0
- package/dist/durable-projection.d.ts +9 -0
- package/dist/durable-recorder.d.ts +57 -0
- package/dist/durable-state.d.ts +43 -0
- package/dist/durable.d.ts +25 -0
- package/dist/durable.js +897 -0
- package/dist/durable.js.map +7 -0
- package/dist/git.d.ts +5 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1732 -0
- package/dist/index.js.map +7 -0
- package/dist/index.ts +1874 -0
- package/dist/index.ts.map +7 -0
- package/dist/library-chunks/chunk-7DN64UHE.js +158 -0
- package/dist/library-chunks/chunk-7DN64UHE.js.map +7 -0
- package/dist/library-chunks/chunk-7JGM5RS3.js +72 -0
- package/dist/library-chunks/chunk-7JGM5RS3.js.map +7 -0
- package/dist/library-chunks/chunk-BBL32ZV5.js +84 -0
- package/dist/library-chunks/chunk-BBL32ZV5.js.map +7 -0
- package/dist/library-chunks/runtime-554E6FVF.js +406 -0
- package/dist/library-chunks/runtime-554E6FVF.js.map +7 -0
- package/dist/otel.d.ts +13 -0
- package/dist/otlp-settings.d.ts +8 -0
- package/dist/pi-session.d.ts +43 -0
- package/dist/public-api.d.ts +2 -0
- package/dist/runtime-api.d.ts +6 -0
- package/dist/runtime-core.d.ts +26 -0
- package/dist/runtime-defaults.d.ts +1 -0
- package/dist/runtime.d.ts +26 -0
- package/dist/sanitizer.d.ts +2 -0
- package/dist/tracing.d.ts +198 -0
- package/docs/durable.md +128 -0
- package/package.json +87 -4
- package/src/config.ts +330 -0
- package/src/durable-projection.ts +112 -0
- package/src/durable-recorder.ts +539 -0
- package/src/durable-state.ts +135 -0
- package/src/durable.ts +364 -0
- package/src/git.ts +64 -0
- package/src/index.ts +12 -0
- package/src/otel.ts +397 -0
- package/src/otlp-settings.ts +72 -0
- package/src/pi-session.ts +570 -0
- package/src/public-api.ts +13 -0
- package/src/runtime-api.ts +16 -0
- package/src/runtime-core.ts +114 -0
- package/src/runtime-defaults.ts +1 -0
- package/src/runtime.ts +509 -0
- package/src/sanitizer.ts +157 -0
- package/src/tracing.ts +940 -0
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
import type { TraceBackend } from "./tracing.js";
|
|
2
|
+
|
|
3
|
+
export interface LangfuseRuntimeConfig {
|
|
4
|
+
publicKey?: string;
|
|
5
|
+
secretKey?: string;
|
|
6
|
+
baseUrl?: string;
|
|
7
|
+
environment?: string;
|
|
8
|
+
release?: string;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
export interface CreateLangfuseRuntimeOptions {
|
|
12
|
+
config?: LangfuseRuntimeConfig;
|
|
13
|
+
env?: NodeJS.ProcessEnv | false;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export interface LangfuseRuntime {
|
|
17
|
+
readonly closed: boolean;
|
|
18
|
+
flush(): Promise<void>;
|
|
19
|
+
shutdown(): Promise<void>;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
type RuntimeSessionDisposer = (statusMessage: string) => void | Promise<void>;
|
|
23
|
+
|
|
24
|
+
export interface LangfuseRuntimeInternal extends LangfuseRuntime {
|
|
25
|
+
readonly backend: TraceBackend;
|
|
26
|
+
registerSession(disposer: RuntimeSessionDisposer): () => void;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
const RUNTIME_INTERNAL_KEY = Symbol.for("@narumitw/pi-langfuse/runtime-internal/v2");
|
|
30
|
+
|
|
31
|
+
class ManagedLangfuseRuntime implements LangfuseRuntimeInternal {
|
|
32
|
+
private state: "open" | "closing" | "closed" = "open";
|
|
33
|
+
private readonly sessionDisposers = new Set<RuntimeSessionDisposer>();
|
|
34
|
+
private flushQueue = Promise.resolve();
|
|
35
|
+
private shutdownPromise: Promise<void> | undefined;
|
|
36
|
+
|
|
37
|
+
constructor(readonly backend: TraceBackend) {}
|
|
38
|
+
|
|
39
|
+
get closed(): boolean {
|
|
40
|
+
return this.state !== "open";
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
registerSession(disposer: RuntimeSessionDisposer): () => void {
|
|
44
|
+
if (this.state !== "open") throw new Error("Langfuse runtime is shutting down or already closed.");
|
|
45
|
+
this.sessionDisposers.add(disposer);
|
|
46
|
+
return () => this.sessionDisposers.delete(disposer);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
flush(): Promise<void> {
|
|
50
|
+
if (this.state !== "open") {
|
|
51
|
+
return Promise.reject(new Error("Langfuse runtime is shutting down or already closed."));
|
|
52
|
+
}
|
|
53
|
+
const operation = this.flushQueue.then(() => this.backend.forceFlush());
|
|
54
|
+
this.flushQueue = operation.then(
|
|
55
|
+
() => undefined,
|
|
56
|
+
() => undefined,
|
|
57
|
+
);
|
|
58
|
+
return operation;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
shutdown(): Promise<void> {
|
|
62
|
+
if (this.shutdownPromise) return this.shutdownPromise;
|
|
63
|
+
this.state = "closing";
|
|
64
|
+
// Publish the promise before invoking controller callbacks, which can reenter shutdown().
|
|
65
|
+
this.shutdownPromise = Promise.resolve().then(() => this.shutdownNow());
|
|
66
|
+
return this.shutdownPromise;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
private async shutdownNow(): Promise<void> {
|
|
70
|
+
const errors: unknown[] = [];
|
|
71
|
+
for (const dispose of [...this.sessionDisposers]) {
|
|
72
|
+
try {
|
|
73
|
+
await dispose("Langfuse runtime shut down before the Pi session was disposed.");
|
|
74
|
+
} catch (error) {
|
|
75
|
+
errors.push(error);
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
this.sessionDisposers.clear();
|
|
79
|
+
|
|
80
|
+
await this.flushQueue;
|
|
81
|
+
try {
|
|
82
|
+
await this.backend.forceFlush();
|
|
83
|
+
} catch (error) {
|
|
84
|
+
errors.push(error);
|
|
85
|
+
}
|
|
86
|
+
try {
|
|
87
|
+
await this.backend.shutdown();
|
|
88
|
+
} catch (error) {
|
|
89
|
+
errors.push(error);
|
|
90
|
+
} finally {
|
|
91
|
+
this.state = "closed";
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
if (errors.length === 1) throw errors[0];
|
|
95
|
+
if (errors.length > 1) throw new AggregateError(errors, "Langfuse runtime shutdown failed.");
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
export function getLangfuseRuntimeInternal(runtime: LangfuseRuntime): LangfuseRuntimeInternal {
|
|
100
|
+
const internal = (runtime as LangfuseRuntime & { [key: symbol]: LangfuseRuntimeInternal | undefined })[
|
|
101
|
+
RUNTIME_INTERNAL_KEY
|
|
102
|
+
];
|
|
103
|
+
if (!internal) throw new Error("The tracing runtime was not created by this package.");
|
|
104
|
+
return internal;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
export function createLangfuseRuntimeFromBackend(backend: TraceBackend): LangfuseRuntime {
|
|
108
|
+
return registerLangfuseRuntime(new ManagedLangfuseRuntime(backend));
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
export function registerLangfuseRuntime(runtime: LangfuseRuntimeInternal): LangfuseRuntimeInternal {
|
|
112
|
+
Object.defineProperty(runtime, RUNTIME_INTERNAL_KEY, { value: runtime });
|
|
113
|
+
return runtime;
|
|
114
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export const DEFAULT_BASE_URL = "https://us.cloud.langfuse.com";
|
package/src/runtime.ts
ADDED
|
@@ -0,0 +1,509 @@
|
|
|
1
|
+
import { Buffer } from "node:buffer";
|
|
2
|
+
import { createHash } from "node:crypto";
|
|
3
|
+
import { context, ROOT_CONTEXT, type Span, SpanKind, SpanStatusCode, type Tracer, trace } from "@opentelemetry/api";
|
|
4
|
+
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
|
|
5
|
+
import {
|
|
6
|
+
CompressionAlgorithm,
|
|
7
|
+
getSharedConfigurationDefaults,
|
|
8
|
+
OTLPExporterBase,
|
|
9
|
+
} from "@opentelemetry/otlp-exporter-base";
|
|
10
|
+
import { createOtlpHttpExportDelegate, httpAgentFactoryFromOptions } from "@opentelemetry/otlp-exporter-base/node-http";
|
|
11
|
+
import { ProtobufTraceSerializer, TraceExporterMetricsHelper } from "@opentelemetry/otlp-transformer";
|
|
12
|
+
import { resourceFromAttributes } from "@opentelemetry/resources";
|
|
13
|
+
import { BatchSpanProcessor, type ReadableSpan, type SpanProcessor, TracerProvider } from "@opentelemetry/sdk-trace";
|
|
14
|
+
import type { LangfuseConfig } from "./config.js";
|
|
15
|
+
import { normalizeOtlpConnection, type OtlpConnection, type OtlpRuntimeConfig, otlpSecrets } from "./otlp-settings.js";
|
|
16
|
+
import {
|
|
17
|
+
type CreateLangfuseRuntimeOptions,
|
|
18
|
+
createLangfuseRuntimeFromBackend,
|
|
19
|
+
getLangfuseRuntimeInternal,
|
|
20
|
+
type LangfuseRuntime,
|
|
21
|
+
type LangfuseRuntimeInternal,
|
|
22
|
+
} from "./runtime-core.js";
|
|
23
|
+
import { DEFAULT_BASE_URL } from "./runtime-defaults.js";
|
|
24
|
+
import type { Observation, ObservationAttributes, ObservationType, TraceBackend } from "./tracing.js";
|
|
25
|
+
|
|
26
|
+
export type {
|
|
27
|
+
CreateLangfuseRuntimeOptions,
|
|
28
|
+
LangfuseRuntime,
|
|
29
|
+
LangfuseRuntimeConfig,
|
|
30
|
+
} from "./runtime-core.js";
|
|
31
|
+
|
|
32
|
+
// Keep the process slots and Langfuse instrumentation scope stable across the package rename.
|
|
33
|
+
const RUNTIME_KEY = Symbol.for("@narumitw/pi-langfuse/runtime/v2");
|
|
34
|
+
const LEGACY_RUNTIME_KEY = Symbol.for("@narumitw/pi-langfuse/runtime/v1");
|
|
35
|
+
const LANGFUSE_SCOPE = "@narumitw/pi-langfuse";
|
|
36
|
+
const OTLP_SCOPE = "@narumitw/pi-otel";
|
|
37
|
+
const MAX_PENDING_METADATA_ATTRIBUTES = 128;
|
|
38
|
+
|
|
39
|
+
interface ResolvedLangfuseConfig {
|
|
40
|
+
publicKey: string;
|
|
41
|
+
secretKey: string;
|
|
42
|
+
baseUrl: string;
|
|
43
|
+
environment?: string;
|
|
44
|
+
release?: string;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
type ResolvedOtlpConfig = OtlpConnection & { backend: "otlp" };
|
|
48
|
+
type ResolvedRuntimeConfig = ResolvedLangfuseConfig | ResolvedOtlpConfig;
|
|
49
|
+
|
|
50
|
+
function isOtlpConfig(config: ResolvedRuntimeConfig): config is ResolvedOtlpConfig {
|
|
51
|
+
return "backend" in config;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
function instrumentationScope(config: ResolvedRuntimeConfig): string {
|
|
55
|
+
return isOtlpConfig(config) ? OTLP_SCOPE : LANGFUSE_SCOPE;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
interface SharedRuntime {
|
|
59
|
+
fingerprint: string;
|
|
60
|
+
runtime: LangfuseRuntimeInternal;
|
|
61
|
+
shutdown: true;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
type GlobalWithRuntime = typeof globalThis & {
|
|
65
|
+
[RUNTIME_KEY]?: Promise<SharedRuntime>;
|
|
66
|
+
[LEGACY_RUNTIME_KEY]?: unknown;
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
interface RuntimeFactories {
|
|
70
|
+
createProcessor(config: ResolvedRuntimeConfig): SpanProcessor;
|
|
71
|
+
createProvider(processor: SpanProcessor, config: ResolvedRuntimeConfig): TracerProvider;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
class ProductionObservation implements Observation {
|
|
75
|
+
readonly traceId: string;
|
|
76
|
+
private readonly metadata = new Map<string, string | number | boolean>();
|
|
77
|
+
private readonly observationScope: string;
|
|
78
|
+
private readonly traceScope: string;
|
|
79
|
+
|
|
80
|
+
constructor(
|
|
81
|
+
readonly span: Span,
|
|
82
|
+
private readonly secrets: readonly string[],
|
|
83
|
+
private readonly otlp: boolean,
|
|
84
|
+
) {
|
|
85
|
+
this.observationScope = otlp ? "pi.observation" : "langfuse.observation";
|
|
86
|
+
this.traceScope = otlp ? "pi.trace" : "langfuse.trace";
|
|
87
|
+
this.traceId = span.spanContext().traceId;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
update(attributes: ObservationAttributes): Observation {
|
|
91
|
+
const {
|
|
92
|
+
input,
|
|
93
|
+
output,
|
|
94
|
+
metadata,
|
|
95
|
+
level,
|
|
96
|
+
statusMessage,
|
|
97
|
+
model,
|
|
98
|
+
modelParameters,
|
|
99
|
+
usageDetails,
|
|
100
|
+
costDetails,
|
|
101
|
+
completionStartTime,
|
|
102
|
+
version,
|
|
103
|
+
sessionId,
|
|
104
|
+
userId,
|
|
105
|
+
} = attributes;
|
|
106
|
+
const scope = this.observationScope;
|
|
107
|
+
this.span.setAttributes({
|
|
108
|
+
[`${scope}.input`]: serializeIO(input, this.secrets),
|
|
109
|
+
[`${scope}.output`]: serializeIO(output, this.secrets),
|
|
110
|
+
[`${scope}.level`]: level,
|
|
111
|
+
[`${scope}.status_message`]: this.mask(statusMessage),
|
|
112
|
+
[`${scope}.model.name`]: this.mask(model),
|
|
113
|
+
[`${scope}.model.parameters`]: serializeIO(modelParameters, this.secrets),
|
|
114
|
+
[`${scope}.usage_details`]: serializeIO(usageDetails, this.secrets),
|
|
115
|
+
[`${scope}.cost_details`]: serializeIO(costDetails, this.secrets),
|
|
116
|
+
[`${scope}.completion_start_time`]: serializeIO(completionStartTime, this.secrets),
|
|
117
|
+
[this.otlp ? "pi.version" : "langfuse.version"]: this.mask(version),
|
|
118
|
+
"session.id": this.mask(sessionId),
|
|
119
|
+
"user.id": this.mask(userId),
|
|
120
|
+
});
|
|
121
|
+
if (this.otlp && level === "ERROR") this.span.setStatus({ code: SpanStatusCode.ERROR });
|
|
122
|
+
this.setMetadata(scope, metadata);
|
|
123
|
+
return this;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
updateTrace(attributes: ObservationAttributes): Observation {
|
|
127
|
+
const { input, output, metadata, name, sessionId, userId, tags, version } = attributes;
|
|
128
|
+
// Trace IO belongs to the receiving span without changing its observation IO.
|
|
129
|
+
const scope = this.traceScope;
|
|
130
|
+
this.span.setAttributes({
|
|
131
|
+
[`${scope}.input`]: serializeIO(input, this.secrets),
|
|
132
|
+
[`${scope}.output`]: serializeIO(output, this.secrets),
|
|
133
|
+
[`${scope}.name`]: this.mask(name),
|
|
134
|
+
[`${scope}.tags`]: tags?.map((tag) => maskSecretString(tag, this.secrets)),
|
|
135
|
+
[this.otlp ? "pi.version" : "langfuse.version"]: this.mask(version),
|
|
136
|
+
"session.id": this.mask(sessionId),
|
|
137
|
+
"user.id": this.mask(userId),
|
|
138
|
+
});
|
|
139
|
+
this.setMetadata(scope, metadata);
|
|
140
|
+
return this;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
end(endTime?: number): Observation {
|
|
144
|
+
// Write metadata last so it can only use slots left by trace and observation fields.
|
|
145
|
+
for (const [key, value] of this.metadata) this.span.setAttribute(key, value);
|
|
146
|
+
this.metadata.clear();
|
|
147
|
+
this.span.end(endTime);
|
|
148
|
+
return this;
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
private mask(value: string | undefined): string | undefined {
|
|
152
|
+
return value === undefined ? undefined : maskSecretString(value, this.secrets);
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
private setMetadata(scope: string, metadata: Record<string, unknown> | undefined): void {
|
|
156
|
+
if (!metadata || !this.span.isRecording()) return;
|
|
157
|
+
for (const [key, value] of Object.entries(metadata)) {
|
|
158
|
+
if (scope === this.observationScope && value == null) continue;
|
|
159
|
+
const attribute = `${scope}.metadata.${maskSecretString(key, this.secrets)}`;
|
|
160
|
+
if (this.metadata.size >= MAX_PENDING_METADATA_ATTRIBUTES && !this.metadata.has(attribute)) continue;
|
|
161
|
+
const serialized =
|
|
162
|
+
this.otlp && (typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value)))
|
|
163
|
+
? value
|
|
164
|
+
: this.otlp && typeof value === "string"
|
|
165
|
+
? this.mask(value)
|
|
166
|
+
: serializeMetadataValue(value, this.secrets);
|
|
167
|
+
if (serialized !== undefined) this.metadata.set(attribute, serialized);
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
class ProductionTraceBackend implements TraceBackend {
|
|
173
|
+
private readonly tracer: Tracer;
|
|
174
|
+
private readonly spans = new WeakSet<Span>();
|
|
175
|
+
private readonly secrets: readonly string[];
|
|
176
|
+
|
|
177
|
+
constructor(
|
|
178
|
+
private readonly provider: TracerProvider,
|
|
179
|
+
private readonly processor: SpanProcessor,
|
|
180
|
+
private readonly config: ResolvedRuntimeConfig,
|
|
181
|
+
) {
|
|
182
|
+
this.tracer = provider.getTracer(instrumentationScope(config));
|
|
183
|
+
this.secrets = isOtlpConfig(config)
|
|
184
|
+
? otlpSecrets(config.headers)
|
|
185
|
+
: [config.publicKey, config.secretKey].sort((a, b) => b.length - a.length);
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
start(
|
|
189
|
+
name: string,
|
|
190
|
+
attributes: ObservationAttributes,
|
|
191
|
+
options: { asType: ObservationType; parent?: Observation; startTime?: Date },
|
|
192
|
+
): Observation {
|
|
193
|
+
const parent = options.parent instanceof ProductionObservation ? options.parent.span : undefined;
|
|
194
|
+
const parentContext = parent ? trace.setSpan(ROOT_CONTEXT, parent) : context.active();
|
|
195
|
+
const parentSpan = trace.getSpan(parentContext);
|
|
196
|
+
// Preserve the trace ID of an explicit parent even if it ended before this span started.
|
|
197
|
+
const isAppRoot = !parentSpan || !this.spans.has(parentSpan) || !parentSpan.isRecording();
|
|
198
|
+
const config = this.config;
|
|
199
|
+
const otlp = isOtlpConfig(config);
|
|
200
|
+
const span = this.tracer.startSpan(
|
|
201
|
+
maskSecretString(name, this.secrets),
|
|
202
|
+
{
|
|
203
|
+
startTime: options.startTime,
|
|
204
|
+
...(otlp && options.asType === "generation" ? { kind: SpanKind.CLIENT } : {}),
|
|
205
|
+
attributes: otlp
|
|
206
|
+
? { "pi.observation.type": options.asType }
|
|
207
|
+
: {
|
|
208
|
+
"langfuse.observation.type": options.asType,
|
|
209
|
+
"langfuse.internal.is_app_root": isAppRoot ? true : undefined,
|
|
210
|
+
"langfuse.environment": config.environment && maskSecretString(config.environment, this.secrets),
|
|
211
|
+
"langfuse.release": config.release && maskSecretString(config.release, this.secrets),
|
|
212
|
+
},
|
|
213
|
+
},
|
|
214
|
+
parentContext,
|
|
215
|
+
);
|
|
216
|
+
this.spans.add(span);
|
|
217
|
+
return new ProductionObservation(span, this.secrets, otlp).update(attributes);
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
forceFlush(): Promise<void> {
|
|
221
|
+
return this.processor.forceFlush();
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
shutdown(): Promise<void> {
|
|
225
|
+
return this.provider.shutdown();
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
export async function createLangfuseRuntime(options: CreateLangfuseRuntimeOptions = {}): Promise<LangfuseRuntime> {
|
|
230
|
+
return createSharedRuntime(resolveLangfuseRuntimeConfig(options), defaultFactories);
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
export async function createOtelRuntime(config: OtlpRuntimeConfig): Promise<LangfuseRuntime> {
|
|
234
|
+
return createSharedRuntime({ backend: "otlp", ...normalizeOtlpConnection({ ...config }) }, defaultFactories);
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
export async function createProductionBackend(
|
|
238
|
+
config: LangfuseConfig,
|
|
239
|
+
factoryOverrides: Partial<RuntimeFactories> = {},
|
|
240
|
+
): Promise<TraceBackend> {
|
|
241
|
+
const runtime = await createSharedRuntime(resolveLangfuseRuntimeConfig({ config, env: false }), {
|
|
242
|
+
...defaultFactories,
|
|
243
|
+
...factoryOverrides,
|
|
244
|
+
});
|
|
245
|
+
return getLangfuseRuntimeInternal(runtime).backend;
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
async function createSharedRuntime(
|
|
249
|
+
config: ResolvedRuntimeConfig,
|
|
250
|
+
factories: RuntimeFactories,
|
|
251
|
+
): Promise<LangfuseRuntime> {
|
|
252
|
+
const globalRuntime = globalThis as GlobalWithRuntime;
|
|
253
|
+
const fingerprint = configFingerprint(config);
|
|
254
|
+
const existing = globalRuntime[RUNTIME_KEY];
|
|
255
|
+
const legacyRuntime = globalRuntime[LEGACY_RUNTIME_KEY];
|
|
256
|
+
if (legacyRuntime !== undefined && legacyRuntime !== existing) {
|
|
257
|
+
throw new Error("An older Langfuse runtime is already loaded; restart the process before enabling this version.");
|
|
258
|
+
}
|
|
259
|
+
if (existing) {
|
|
260
|
+
if (legacyRuntime === undefined) globalRuntime[LEGACY_RUNTIME_KEY] = existing;
|
|
261
|
+
const shared = await existing;
|
|
262
|
+
if (shared.runtime.closed) {
|
|
263
|
+
throw new Error("Tracing was already shut down; restart the process to enable it again.");
|
|
264
|
+
}
|
|
265
|
+
if (shared.fingerprint !== fingerprint) {
|
|
266
|
+
throw new Error("Tracing configuration changed; restart the process to apply the new connection settings.");
|
|
267
|
+
}
|
|
268
|
+
return shared.runtime;
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
const initializing = initializeRuntime(config, fingerprint, factories);
|
|
272
|
+
globalRuntime[RUNTIME_KEY] = initializing;
|
|
273
|
+
globalRuntime[LEGACY_RUNTIME_KEY] = initializing;
|
|
274
|
+
try {
|
|
275
|
+
return (await initializing).runtime;
|
|
276
|
+
} catch (error) {
|
|
277
|
+
if (globalRuntime[RUNTIME_KEY] === initializing) delete globalRuntime[RUNTIME_KEY];
|
|
278
|
+
if (globalRuntime[LEGACY_RUNTIME_KEY] === initializing) delete globalRuntime[LEGACY_RUNTIME_KEY];
|
|
279
|
+
throw error;
|
|
280
|
+
}
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
async function initializeRuntime(
|
|
284
|
+
config: ResolvedRuntimeConfig,
|
|
285
|
+
fingerprint: string,
|
|
286
|
+
factories: RuntimeFactories,
|
|
287
|
+
): Promise<SharedRuntime> {
|
|
288
|
+
const processor = factories.createProcessor(config);
|
|
289
|
+
let provider: TracerProvider;
|
|
290
|
+
try {
|
|
291
|
+
provider = factories.createProvider(processor, config);
|
|
292
|
+
} catch (error) {
|
|
293
|
+
await processor.shutdown().catch(() => undefined);
|
|
294
|
+
throw error;
|
|
295
|
+
}
|
|
296
|
+
const runtime = getLangfuseRuntimeInternal(
|
|
297
|
+
createLangfuseRuntimeFromBackend(new ProductionTraceBackend(provider, processor, config)),
|
|
298
|
+
);
|
|
299
|
+
return { fingerprint, runtime, shutdown: true };
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
class PiBatchSpanProcessor extends BatchSpanProcessor {
|
|
303
|
+
constructor(config: ResolvedRuntimeConfig) {
|
|
304
|
+
super({
|
|
305
|
+
exporter: isOtlpConfig(config) ? createOtlpExporter(config) : createLangfuseExporter(config),
|
|
306
|
+
// Keep batches smaller than the SDK default because each span can carry large captured inputs and outputs.
|
|
307
|
+
maxExportBatchSize: 128,
|
|
308
|
+
scheduledDelayMillis: 5_000,
|
|
309
|
+
});
|
|
310
|
+
this.scope = instrumentationScope(config);
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
private readonly scope: string;
|
|
314
|
+
|
|
315
|
+
override onEnd(span: ReadableSpan): void {
|
|
316
|
+
if (span.instrumentationScope.name === this.scope) super.onEnd(span);
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
const defaultFactories: RuntimeFactories = {
|
|
321
|
+
createProcessor: (config) => new PiBatchSpanProcessor(config),
|
|
322
|
+
// The provider is private: do not register it with OpenTelemetry or replace the host's provider.
|
|
323
|
+
createProvider: (processor, config) =>
|
|
324
|
+
new TracerProvider({
|
|
325
|
+
spanProcessors: [processor],
|
|
326
|
+
...(isOtlpConfig(config)
|
|
327
|
+
? {
|
|
328
|
+
resource: resourceFromAttributes({
|
|
329
|
+
"service.name": maskSecretString(config.serviceName, otlpSecrets(config.headers)),
|
|
330
|
+
}),
|
|
331
|
+
}
|
|
332
|
+
: {}),
|
|
333
|
+
}),
|
|
334
|
+
};
|
|
335
|
+
|
|
336
|
+
function createLangfuseExporter(config: ResolvedLangfuseConfig): OTLPTraceExporter {
|
|
337
|
+
return new OTLPTraceExporter({
|
|
338
|
+
url: `${config.baseUrl}/api/public/otel/v1/traces`,
|
|
339
|
+
headers: {
|
|
340
|
+
Authorization: `Basic ${Buffer.from(`${config.publicKey}:${config.secretKey}`).toString("base64")}`,
|
|
341
|
+
"x-langfuse-ingestion-version": "4",
|
|
342
|
+
},
|
|
343
|
+
timeoutMillis: 5_000,
|
|
344
|
+
compression: resolveCompression(),
|
|
345
|
+
});
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
function createOtlpExporter(config: ResolvedOtlpConfig): OTLPExporterBase<ReadableSpan[]> {
|
|
349
|
+
// The legacy exporter constructor merges ambient OTLP headers, which can send credentials to the wrong endpoint.
|
|
350
|
+
return new OTLPExporterBase(
|
|
351
|
+
createOtlpHttpExportDelegate(
|
|
352
|
+
{
|
|
353
|
+
...getSharedConfigurationDefaults(),
|
|
354
|
+
url: config.endpoint,
|
|
355
|
+
headers: async () => ({ ...config.headers, "content-type": "application/x-protobuf" }),
|
|
356
|
+
timeoutMillis: 5_000,
|
|
357
|
+
agentFactory: httpAgentFactoryFromOptions({ keepAlive: true }),
|
|
358
|
+
},
|
|
359
|
+
ProtobufTraceSerializer,
|
|
360
|
+
"otlp_http_span_exporter",
|
|
361
|
+
TraceExporterMetricsHelper,
|
|
362
|
+
undefined,
|
|
363
|
+
),
|
|
364
|
+
);
|
|
365
|
+
}
|
|
366
|
+
|
|
367
|
+
function resolveCompression(): CompressionAlgorithm {
|
|
368
|
+
for (const key of [
|
|
369
|
+
"LANGFUSE_OTEL_COMPRESSION",
|
|
370
|
+
"OTEL_EXPORTER_OTLP_TRACES_COMPRESSION",
|
|
371
|
+
"OTEL_EXPORTER_OTLP_COMPRESSION",
|
|
372
|
+
]) {
|
|
373
|
+
const value = process.env[key]?.trim().toLowerCase();
|
|
374
|
+
if (value === CompressionAlgorithm.NONE || value === CompressionAlgorithm.GZIP) return value;
|
|
375
|
+
}
|
|
376
|
+
return CompressionAlgorithm.GZIP;
|
|
377
|
+
}
|
|
378
|
+
|
|
379
|
+
export function resolveLangfuseRuntimeConfig(options: CreateLangfuseRuntimeOptions): ResolvedLangfuseConfig {
|
|
380
|
+
const env = options.env === false ? undefined : (options.env ?? process.env);
|
|
381
|
+
const publicKey = requiredSetting("publicKey", options.config?.publicKey, env?.LANGFUSE_PUBLIC_KEY);
|
|
382
|
+
const secretKey = requiredSetting("secretKey", options.config?.secretKey, env?.LANGFUSE_SECRET_KEY);
|
|
383
|
+
const explicitBaseUrl = options.config?.baseUrl;
|
|
384
|
+
if (explicitBaseUrl !== undefined && !normalizeString(explicitBaseUrl)) {
|
|
385
|
+
throw new Error("Langfuse baseUrl must be a non-empty string.");
|
|
386
|
+
}
|
|
387
|
+
const rawBaseUrl = selectedSetting(explicitBaseUrl, env?.LANGFUSE_BASE_URL) ?? DEFAULT_BASE_URL;
|
|
388
|
+
const baseUrl = normalizeBaseUrl(rawBaseUrl);
|
|
389
|
+
if (!baseUrl) {
|
|
390
|
+
throw new Error("Langfuse baseUrl must use HTTP or HTTPS without credentials, a query, or a fragment.");
|
|
391
|
+
}
|
|
392
|
+
const environment = optionalSetting("environment", options.config?.environment, env?.LANGFUSE_TRACING_ENVIRONMENT);
|
|
393
|
+
if (environment && (environment.length > 40 || !/^(?!langfuse)[a-z0-9_-]+$/u.test(environment))) {
|
|
394
|
+
throw new Error(
|
|
395
|
+
"Langfuse environment must be at most 40 lowercase letters, numbers, hyphens, or underscores and must not start with langfuse.",
|
|
396
|
+
);
|
|
397
|
+
}
|
|
398
|
+
const release = optionalSetting("release", options.config?.release, env?.LANGFUSE_RELEASE);
|
|
399
|
+
return { publicKey, secretKey, baseUrl, ...(environment ? { environment } : {}), ...(release ? { release } : {}) };
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
function requiredSetting(name: string, explicit: string | undefined, environment: string | undefined): string {
|
|
403
|
+
const value = selectedSetting(explicit, environment);
|
|
404
|
+
if (!value) throw new Error(`Langfuse ${name} is required.`);
|
|
405
|
+
return value;
|
|
406
|
+
}
|
|
407
|
+
|
|
408
|
+
function optionalSetting(
|
|
409
|
+
name: string,
|
|
410
|
+
explicit: string | undefined,
|
|
411
|
+
environment: string | undefined,
|
|
412
|
+
): string | undefined {
|
|
413
|
+
const selected = explicit !== undefined ? explicit : environment;
|
|
414
|
+
if (selected === undefined) return undefined;
|
|
415
|
+
const value = normalizeString(selected);
|
|
416
|
+
if (!value) throw new Error(`Langfuse ${name} must be a non-empty string.`);
|
|
417
|
+
return value;
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
function selectedSetting(explicit: string | undefined, environment: string | undefined): string | undefined {
|
|
421
|
+
if (explicit !== undefined) return normalizeString(explicit);
|
|
422
|
+
return normalizeString(environment);
|
|
423
|
+
}
|
|
424
|
+
|
|
425
|
+
function normalizeBaseUrl(value: string): string | undefined {
|
|
426
|
+
try {
|
|
427
|
+
const url = new URL(value);
|
|
428
|
+
if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
|
|
429
|
+
if (url.username || url.password || url.search || url.hash) return undefined;
|
|
430
|
+
return url.toString().replace(/\/+$/, "");
|
|
431
|
+
} catch {
|
|
432
|
+
return undefined;
|
|
433
|
+
}
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
function normalizeString(value: unknown): string | undefined {
|
|
437
|
+
return typeof value === "string" && value.trim() ? value.trim() : undefined;
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
function serializeIO(value: unknown, secrets: readonly string[]): string | undefined {
|
|
441
|
+
if (typeof value === "string") return maskSecretString(value, secrets);
|
|
442
|
+
if (value == null) return undefined;
|
|
443
|
+
try {
|
|
444
|
+
const serialized = JSON.stringify(value);
|
|
445
|
+
if (serialized === undefined) return undefined;
|
|
446
|
+
// Mask decoded keys and values so escaped credentials are redacted without breaking JSON.
|
|
447
|
+
return JSON.stringify(maskSecrets(JSON.parse(serialized), secrets));
|
|
448
|
+
} catch {
|
|
449
|
+
return "<failed to serialize>";
|
|
450
|
+
}
|
|
451
|
+
}
|
|
452
|
+
|
|
453
|
+
function serializeMetadataValue(value: unknown, secrets: readonly string[]): string | undefined {
|
|
454
|
+
try {
|
|
455
|
+
return JSON.stringify(maskSecrets(value, secrets), (_, entry: unknown) => {
|
|
456
|
+
if (typeof entry === "number" && !Number.isFinite(entry)) return String(entry);
|
|
457
|
+
if (typeof entry !== "bigint") return entry;
|
|
458
|
+
return entry >= BigInt(Number.MIN_SAFE_INTEGER) && entry <= BigInt(Number.MAX_SAFE_INTEGER)
|
|
459
|
+
? Number(entry)
|
|
460
|
+
: entry.toString();
|
|
461
|
+
});
|
|
462
|
+
} catch {
|
|
463
|
+
return JSON.stringify("<failed to serialize>");
|
|
464
|
+
}
|
|
465
|
+
}
|
|
466
|
+
|
|
467
|
+
function maskSecretString(value: string, secrets: readonly string[]): string {
|
|
468
|
+
let masked = value.replace(/\b(?:sk|pk)-lf-[A-Za-z0-9_-]+\b/gu, "[LANGFUSE_KEY_REDACTED]");
|
|
469
|
+
// Replace longer configured keys first if one key is a prefix of the other.
|
|
470
|
+
for (const secret of secrets) {
|
|
471
|
+
if (secret) masked = masked.replaceAll(secret, "[LANGFUSE_KEY_REDACTED]");
|
|
472
|
+
}
|
|
473
|
+
return masked;
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
function configFingerprint(config: ResolvedRuntimeConfig): string {
|
|
477
|
+
return createHash("sha256")
|
|
478
|
+
.update(
|
|
479
|
+
isOtlpConfig(config)
|
|
480
|
+
? JSON.stringify([config.backend, config.endpoint, config.headers, config.serviceName])
|
|
481
|
+
: `${config.publicKey}\0${config.secretKey}\0${config.baseUrl}\0${config.environment ?? ""}\0${config.release ?? ""}`,
|
|
482
|
+
)
|
|
483
|
+
.digest("hex");
|
|
484
|
+
}
|
|
485
|
+
|
|
486
|
+
export function maskSecrets(data: unknown, secrets: readonly string[]): unknown {
|
|
487
|
+
return maskSecretValue(data, secrets, new WeakSet<object>());
|
|
488
|
+
}
|
|
489
|
+
|
|
490
|
+
function maskSecretValue(data: unknown, secrets: readonly string[], active: WeakSet<object>): unknown {
|
|
491
|
+
if (typeof data === "string") return maskSecretString(data, secrets);
|
|
492
|
+
if (!data || typeof data !== "object") return data;
|
|
493
|
+
if (active.has(data)) return "[circular]";
|
|
494
|
+
|
|
495
|
+
active.add(data);
|
|
496
|
+
try {
|
|
497
|
+
if (Array.isArray(data)) {
|
|
498
|
+
return data.map((item) => maskSecretValue(item, secrets, active));
|
|
499
|
+
}
|
|
500
|
+
return Object.fromEntries(
|
|
501
|
+
Object.entries(data).map(([key, value]) => [
|
|
502
|
+
maskSecretString(key, secrets),
|
|
503
|
+
maskSecretValue(value, secrets, active),
|
|
504
|
+
]),
|
|
505
|
+
);
|
|
506
|
+
} finally {
|
|
507
|
+
active.delete(data);
|
|
508
|
+
}
|
|
509
|
+
}
|