sailfork / t3code-github / packages/ shared/ src/ otelEnvironment.ts

import * as Config from "effect/Config";
import * as ConfigProvider from "effect/ConfigProvider";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Schema from "effect/Schema";
import * as SchemaTransformation from "effect/SchemaTransformation";

import type { OtlpEndpointSource } from "@t3tools/contracts";

import { OtlpHeadersFromString, OtlpProtocol, type SignalExport } from "./observability.ts";

type OtlpSignalName = "TRACES" | "METRICS" | "LOGS";

export type OtelSignal = Data.TaggedEnum<{
  Unset: {};
  Off: {};
  Export: {
    readonly url: string;
    readonly variable: string;
    readonly protocol: OtlpProtocol;
    readonly headers: Readonly<Record<string, string>> | undefined;
  };
}>;
export const OtelSignal = Data.taggedEnum<OtelSignal>();

export interface OtelEnvironment {
  readonly disabled: boolean;
  readonly warnings: ReadonlyArray<string>;
  readonly resourceAttributes: Readonly<Record<string, string>>;
  readonly traces: OtelSignal;
  readonly metrics: OtelSignal;
  readonly logs: OtelSignal;
}

const blankAsUnset = (value: string | undefined): string | undefined => {
  const trimmed = value?.trim();
  return trimmed === undefined || trimmed === "" ? undefined : trimmed;
};

interface Flag {
  readonly value: boolean | undefined;
  readonly warning?: string;
}

const TrimmedLowercase = Schema.String.pipe(
  Schema.decodeTo(
    Schema.String,
    SchemaTransformation.trim().pipe(
      SchemaTransformation.composeTransformation(SchemaTransformation.toLowerCase()),
    ),
  ),
);

const flag = (
  name: string,
  truthy: ReadonlyArray<string>,
  falsy: ReadonlyArray<string>,
  invalid: (value: string) => string,
) =>
  Config.schema(
    TrimmedLowercase.pipe(Schema.decodeTo(Schema.Literals([...truthy, ...falsy]))),
    name,
  ).pipe(
    Config.map((value): Flag => ({ value: truthy.includes(value) })),
    Config.orElse(() =>
      Config.String(name).pipe(
        Config.map((raw): Flag => {
          const value = raw.trim();
          return value === ""
            ? { value: undefined }
            : { value: undefined, warning: invalid(value) };
        }),
      ),
    ),
    Config.withDefault<Flag>({ value: undefined }),
  );

// `Config.Boolean`'s literals, which effect does not export on their own.
const T3CODE_TRUE = ["true", "yes", "on", "1", "y"];
const T3CODE_FALSE = ["false", "no", "off", "0", "n"];

const RESOURCE_ATTRIBUTES = "OTEL_RESOURCE_ATTRIBUTES";

interface ResourceAttributes {
  readonly value: Readonly<Record<string, string>>;
  readonly warning?: string;
}

const resourceAttributes = Config.Record(
  Schema.StringFromUriComponent,
  Schema.StringFromUriComponent,
  RESOURCE_ATTRIBUTES,
).pipe(
  Config.map((value): ResourceAttributes => ({ value })),
  Config.orElse(() =>
    Config.String(RESOURCE_ATTRIBUTES).pipe(
      // The value is left out because attributes can carry credentials.
      Config.map((): ResourceAttributes => ({
        value: {},
        warning: `${RESOURCE_ATTRIBUTES} is not a list of percent-encoded key=value pairs and was ignored`,
      })),
    ),
  ),
  Config.withDefault<ResourceAttributes>({ value: {} }),
);

interface Setting<A> {
  readonly value: A | undefined;
  readonly warning?: string;
}

const readOrWarn = <A>(
  name: string,
  parse: (raw: string) => Option.Option<A>,
  warning: string,
): Config.Config<Setting<A>> =>
  Config.String(name).pipe(
    Config.option,
    Config.map((option): Setting<A> => {
      const raw = blankAsUnset(Option.getOrUndefined(option));
      if (raw === undefined) {
        return { value: undefined };
      }
      return Option.match(parse(raw), {
        onNone: () => ({ value: undefined, warning }),
        onSome: (value) => ({ value }),
      });
    }),
  );

const parseHttpUrl = (raw: string) =>
  Option.liftThrowable((value: string) => new URL(value))(raw).pipe(
    Option.filter((url) => url.protocol === "http:" || url.protocol === "https:"),
  );

const NOT_EXPORTED = "so the signals it configures are not exported";

const endpoint = (name: string) =>
  readOrWarn(name, parseHttpUrl, `${name} is not an http or https URL, ${NOT_EXPORTED}`);
const decodeOtlpProtocol = Schema.decodeUnknownOption(OtlpProtocol);

// The specification reads enum values case-insensitively.
const protocol = (name: string) =>
  readOrWarn(
    name,
    (raw) => decodeOtlpProtocol(raw.toLowerCase()),
    `${name} is not http/protobuf or http/json, ${NOT_EXPORTED}`,
  );

const headers = (name: string) =>
  readOrWarn(
    name,
    Schema.decodeUnknownOption(OtlpHeadersFromString),
    `${name} is not a list of key=value pairs with percent-encoded values, ${NOT_EXPORTED}`,
  );

type Exporter = "otlp" | "none";

const EXPORTERS: ReadonlySet<string> = new Set<Exporter>(["otlp", "none"]);

const isExporter = (entry: string): entry is Exporter => EXPORTERS.has(entry);

const exporter = (name: string): Config.Config<Setting<Exporter>> =>
  Config.String(name).pipe(
    Config.option,
    Config.map((option): Setting<Exporter> => {
      const entries = (Option.getOrUndefined(option) ?? "")
        .split(",")
        .map((entry) => entry.trim().toLowerCase())
        .filter((entry) => entry !== "");
      const ignored = [...new Set(entries.filter((entry) => !isExporter(entry)))];
      const known = new Set(entries.filter(isExporter));
      const value = known.has("otlp") ? "otlp" : known.has("none") ? "none" : undefined;
      return ignored.length === 0
        ? { value }
        : {
            value,
            warning: `${name} names ${ignored.join(", ")}, which T3 Code does not export to, so ${ignored.length === 1 ? "it was" : "they were"} ignored`,
          };
    }),
  );

interface Settings {
  readonly endpoint: Setting<URL>;
  readonly protocol: Setting<OtlpProtocol>;
  readonly headers: Setting<Readonly<Record<string, string>>>;
}

const settings = (prefix: string): Config.Config<Settings> =>
  Config.all({
    endpoint: endpoint(`${prefix}ENDPOINT`),
    protocol: protocol(`${prefix}PROTOCOL`),
    headers: headers(`${prefix}HEADERS`),
  });

/** The signal's own variable claims the signal once set, valid or not. */
const isClaimed = (setting: Setting<unknown>) =>
  setting.value !== undefined || setting.warning !== undefined;

const claimed = <A>(own: Setting<A>, generic: Setting<A>) => (isClaimed(own) ? own : generic);

/** Appends the signal's path, keeping the query an intake may take its API key in. */
const withSignalPath = (signal: OtlpSignalName, base: URL) => {
  const url = new URL(base);
  const slash = url.pathname.endsWith("/") ? "" : "/";
  url.pathname += `${slash}v1/${signal.toLowerCase()}`;
  return url;
};

interface ResolvedSignal {
  readonly signal: OtelSignal;
  readonly used: ReadonlyArray<Setting<unknown>>;
}

const signal = (
  name: OtlpSignalName,
  exporter: Setting<Exporter>,
  own: Settings,
  generic: Settings,
): ResolvedSignal => {
  if (exporter.value === "none") {
    return { signal: OtelSignal.Off(), used: [exporter] };
  }
  const resolved = endpointSignal(name, own, generic);
  return { signal: resolved.signal, used: [exporter, ...resolved.used] };
};

const endpointSignal = (name: OtlpSignalName, own: Settings, generic: Settings): ResolvedSignal => {
  const ownEndpoint = isClaimed(own.endpoint);
  const endpoint = ownEndpoint ? own.endpoint : generic.endpoint;
  if (endpoint.value === undefined) {
    const signal = endpoint.warning === undefined ? OtelSignal.Unset() : OtelSignal.Off();
    return { signal, used: [endpoint] };
  }
  const protocol = claimed(own.protocol, generic.protocol);
  const headers = claimed(own.headers, generic.headers);
  const used = [endpoint, protocol, headers];
  if (protocol.warning !== undefined || headers.warning !== undefined) {
    return { signal: OtelSignal.Off(), used };
  }
  const url = ownEndpoint ? endpoint.value : withSignalPath(name, endpoint.value);
  return {
    signal: OtelSignal.Export({
      url: url.toString(),
      variable: ownEndpoint ? `OTEL_EXPORTER_OTLP_${name}_ENDPOINT` : "OTEL_EXPORTER_OTLP_ENDPOINT",
      protocol: protocol.value ?? "http/protobuf",
      headers: headers.value,
    }),
    used,
  };
};

const sdkFlags = {
  t3: flag(
    "T3CODE_OTEL_SDK_DISABLED",
    T3CODE_TRUE,
    T3CODE_FALSE,
    (value) => `T3CODE_OTEL_SDK_DISABLED=${value} is not a yes or a no and was ignored`,
  ),
  // OTEL booleans are true only for case-insensitive true; warn on unrecognized values.
  spec: flag(
    "OTEL_SDK_DISABLED",
    ["true"],
    ["false"],
    (value) =>
      `OTEL_SDK_DISABLED=${value} was read as false; the OpenTelemetry specification recognizes only the string true, so use OTEL_SDK_DISABLED=true or T3CODE_OTEL_SDK_DISABLED to say it any other way`,
  ),
};

export const load: Effect.Effect<OtelEnvironment> = Config.all({
  ...sdkFlags,
  resource: resourceAttributes,
  generic: settings("OTEL_EXPORTER_OTLP_"),
  traces: settings("OTEL_EXPORTER_OTLP_TRACES_"),
  metrics: settings("OTEL_EXPORTER_OTLP_METRICS_"),
  logs: settings("OTEL_EXPORTER_OTLP_LOGS_"),
  exporters: Config.all({
    traces: exporter("OTEL_TRACES_EXPORTER"),
    metrics: exporter("OTEL_METRICS_EXPORTER"),
    logs: exporter("OTEL_LOGS_EXPORTER"),
  }),
}).pipe(
  Effect.map(({ t3, spec, resource, generic, exporters, ...own }) => {
    const disabled = t3.value ?? spec.value ?? false;
    const signals = disabled
      ? undefined
      : {
          traces: signal("TRACES", exporters.traces, own.traces, generic),
          metrics: signal("METRICS", exporters.metrics, own.metrics, generic),
          logs: signal("LOGS", exporters.logs, own.logs, generic),
        };
    const used = new Set(
      signals === undefined ? [] : Object.values(signals).flatMap((resolved) => resolved.used),
    );
    const warnings = [
      t3.warning,
      spec.warning,
      resource.warning,
      ...Array.from(used, (setting) => setting.warning),
    ].filter((warning) => warning !== undefined);
    if (disabled) {
      warnings.push(
        t3.value
          ? "T3CODE_OTEL_SDK_DISABLED is set, so no telemetry is exported, whatever configured it"
          : "OTEL_SDK_DISABLED is set, so no telemetry is exported, whatever configured it; set T3CODE_OTEL_SDK_DISABLED=false to export anyway",
      );
    }
    return {
      disabled,
      warnings,
      resourceAttributes: resource.value,
      traces: signals?.traces.signal ?? OtelSignal.Unset(),
      metrics: signals?.metrics.signal ?? OtelSignal.Unset(),
      logs: signals?.logs.signal ?? OtelSignal.Unset(),
    };
  }),
  Effect.orDie,
);

export const isRelayTracingEnabled = (env: Readonly<Record<string, string | undefined>>) =>
  Config.all({
    ...sdkFlags,
    telemetry: flag("T3CODE_TELEMETRY_ENABLED", T3CODE_TRUE, T3CODE_FALSE, String),
  }).pipe(
    Effect.map(
      ({ telemetry, t3, spec }) => telemetry.value !== false && !(t3.value ?? spec.value ?? false),
    ),
    Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnvRecord(env))),
    Effect.orDie,
    Effect.runSync,
  );

export type SignalName = "traces" | "metrics" | "logs";

export interface SignalEndpoint {
  readonly url: string;
  readonly export: SignalExport;
  readonly source: OtlpEndpointSource;
  /** The environment variable that set the endpoint, when `source` is `environment`. */
  readonly variable?: string;
}

export const resolveSignalEndpoint = (
  otel: OtelEnvironment,
  signal: SignalName,
  t3: { readonly url: string | undefined; readonly export: SignalExport },
  fallback: { readonly bootstrapUrl: string | undefined; readonly settingsUrl: string | undefined },
): SignalEndpoint | undefined => {
  if (otel.disabled) {
    return undefined;
  }
  const t3Url = blankAsUnset(t3.url);
  if (t3Url !== undefined) {
    return {
      url: t3Url,
      export: t3.export,
      source: "environment",
      variable: `T3CODE_OTLP_${signal.toUpperCase()}_URL`,
    };
  }
  return OtelSignal.$match(otel[signal], {
    Export: ({ url, variable, protocol, headers }): SignalEndpoint => ({
      url,
      export: { protocol, headers, exportIntervalMs: t3.export.exportIntervalMs },
      source: "environment",
      variable,
    }),
    Off: () => undefined,
    Unset: (): SignalEndpoint | undefined => {
      const settingsUrl = blankAsUnset(fallback.settingsUrl);
      // The desktop forwards the saved setting as its bootstrap URL, so only a differing one is
      // the desktop's own.
      const url = blankAsUnset(fallback.bootstrapUrl) ?? settingsUrl;
      if (url === undefined) return undefined;
      return { url, export: t3.export, source: url === settingsUrl ? "settings" : "bootstrap" };
    },
  });
};

/** Give OTLP exporters the accepted resource attributes so their own decoding cannot fail. */
export const layerResourceAttributes = (attributes: Readonly<Record<string, string>>) =>
  ConfigProvider.layerAdd(
    ConfigProvider.fromEnv({
      env: {
        [RESOURCE_ATTRIBUTES]: Object.entries(attributes)
          .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
          .join(","),
      },
      preserveEmptyStrings: true,
    }),
    { asPrimary: true },
  );

export const none: OtelEnvironment = {
  disabled: false,
  warnings: [],
  resourceAttributes: {},
  traces: OtelSignal.Unset(),
  metrics: OtelSignal.Unset(),
  logs: OtelSignal.Unset(),
};