import * as Effect from "effect/Effect"; import * as FetchHttpClient from "effect/http/FetchHttpClient"; import * as HttpClient from "effect/http/HttpClient"; import * as HttpClientRequest from "effect/http/HttpClientRequest"; import { HttpServerRequest } from "effect/http/HttpServerRequest"; import * as HttpServerResponse from "effect/http/HttpServerResponse"; import * as Option from "effect/Option"; import { configuredDestinations, type ResolvedSignal } from "./TelemetryRuntime.ts"; /** An OpenTelemetry signal the relay forwards. */ export type Signal = "traces" | "logs" | "metrics"; /** Where the relay forwards one batch: an OTLP/HTTP endpoint and the headers to send it. */ export interface Destination { readonly url: string; readonly headers?: Readonly>; } /** Options for {@link relay}. */ export interface RelayOptions { /** * The signals the relay accepts. A post for any other gets a 404. * @default ["traces", "logs", "metrics"] */ readonly signals?: ReadonlyArray; /** * The largest body accepted, in bytes. Larger posts get a 413. * @default 1048576 */ readonly maxBytes?: number; /** * Decide whether to accept a post, e.g. only from signed-in users. A post * it refuses gets a 403. The relay is a public endpoint, so gate it when * you can. * @default every post is accepted */ readonly authorize?: Effect.Effect; /** * Choose where a batch goes. It receives the destinations this runtime * exports its own telemetry to, and returns the ones to forward to: all * of them, some, or others entirely. * @default the runtime's own destinations for that signal */ readonly route?: ( signal: Signal, configured: ReadonlyArray, ) => Effect.Effect, never, R | HttpServerRequest>; } const SIGNALS: ReadonlyArray = ["traces", "logs", "metrics"]; const json = (status: number, body: unknown) => HttpServerResponse.jsonUnsafe(body, { status }); /** * Collect OpenTelemetry from browsers and other clients through your own * Worker or Function, and forward it to where your backend's telemetry * goes, with the backend's own credentials. Clients post OTLP/HTTP to a * path ending in `/v1/traces`, `/v1/logs` or `/v1/metrics`; each body is * forwarded unchanged, JSON or protobuf. * * No ingest token ever reaches the client, the client posts to its own * origin, and `route` decides where each batch goes. * * ### Collecting browser traces * **Example:** Relay the app's spans through the backend Worker * ```typescript * import * as Telemetry from "alchemy/Telemetry"; * * const telemetry = Telemetry.relay({ signals: ["traces"] }); * * // in the Worker's fetch handler * if (path.startsWith("/api/telemetry/")) return yield* telemetry; * ``` * * **Example:** The browser exports to it * ```typescript * import * as OtlpTracer from "effect/observability/OtlpTracer"; * * OtlpTracer.layer({ * url: `${location.origin}/api/telemetry/v1/traces`, * resource: { serviceName: "bank-web" }, * }); * ``` * * ### Routing batches * **Example:** Send browser traces to their own dataset * ```typescript * Telemetry.relay({ * route: (signal, configured) => * Effect.succeed( * signal === "traces" * ? configured.map((d) => ({ ...d, headers: { ...d.headers, "x-axiom-dataset": "browser" } })) * : configured, * ), * }); * ``` * * @primitive */ export const relay = ( options: RelayOptions = {}, ): Effect.Effect => Effect.gen(function* () { const request = yield* HttpServerRequest; if (request.method !== "POST") return json(405, { error: "OTLP is posted" }); const signal = SIGNALS.find((s) => new URL(request.url, "http://relay").pathname.endsWith(`/v1/${s}`), ); if (!signal || !(options.signals ?? SIGNALS).includes(signal)) { return json(404, { error: "Unknown signal" }); } const maxBytes = options.maxBytes ?? 1_048_576; const declared = Number(request.headers["content-length"] ?? "0"); if (declared > maxBytes) return json(413, { error: "Too large" }); if (options.authorize && !(yield* options.authorize)) return json(403, { error: "Forbidden" }); const body = yield* request.arrayBuffer.pipe(Effect.option); if (Option.isNone(body)) return json(400, { error: "Unreadable body" }); if (body.value.byteLength > maxBytes) return json(413, { error: "Too large" }); const configured = (yield* configuredDestinations).flatMap( (destination): ReadonlyArray => { const target = destination[signal]; return target ? [target] : []; }, ); const targets = options.route ? yield* options.route(signal, configured) : configured; // Nowhere to send it is not the client's problem: accept and drop. if (targets.length === 0) return json(200, {}); const client = Option.getOrElse( yield* Effect.serviceOption(HttpClient.HttpClient), () => undefined, ); const contentType = request.headers["content-type"] ?? "application/json"; const forward = (target: Destination) => Effect.gen(function* () { const http = client ?? (yield* HttpClient.HttpClient.pipe(Effect.provide(FetchHttpClient.layer))); const response = yield* http.execute( HttpClientRequest.post(target.url).pipe( HttpClientRequest.bodyUint8Array(new Uint8Array(body.value), contentType), HttpClientRequest.setHeaders(target.headers ?? {}), ), ); return response.status >= 200 && response.status < 300; }).pipe(Effect.orElseSucceed(() => false)); const delivered = yield* Effect.forEach(targets, forward, { concurrency: "unbounded" }); return delivered.some(Boolean) ? json(200, {}) : json(502, { error: "No destination accepted the batch" }); });