Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
13.5 KB
Raw Blame
export type ObservabilityBackend = "none" | "otel" | "sentry"
export type ObservabilityEnv = Record<string, string | undefined>

export type OTelProtocol = "http/protobuf"
export type OTelSignal = "traces" | "metrics" | "logs"
export type OTelSignalExporter = "otlp" | "none"
export type OTelEndpointSource = "default" | "base" | "signal"
export type OTelSampler =
  | "always_on"
  | "always_off"
  | "traceidratio"
  | "parentbased_always_on"
  | "parentbased_always_off"
  | "parentbased_traceidratio"

export type OTelSamplerConfig = {
  name: OTelSampler
  ratio: number
  argument?: string
}

export type OTelSignalConfig = {
  exporter: OTelSignalExporter
  protocol: OTelProtocol
  endpoint?: string
  endpointSource: OTelEndpointSource
}

export type OTelObservabilityConfig = {
  protocol: OTelProtocol
  baseEndpoint?: string
  sampler: OTelSamplerConfig
  signals: {
    traces: OTelSignalConfig
    metrics: OTelSignalConfig
    logs: OTelSignalConfig
  }
}

export type SentryBuildVariableValues = {
  SENTRY_ORG?: string
  SENTRY_PROJECT?: string
  SENTRY_URL?: string
  SENTRY_RELEASE?: string
  SENTRY_ENVIRONMENT?: string
  SENTRY_DIST?: string
}

export type SentryBuildVariables = {
  values: SentryBuildVariableValues
  redactedKeys: string[]
}

export type SentryObservabilityConfig = {
  dsn: string
  tracesSampleRate: number
}

type BaseObservabilityConfig = {
  serviceName: string
  sentryBuild: SentryBuildVariables
}

export type NoneObservabilityConfig = BaseObservabilityConfig & {
  backend: "none"
}

export type OTelBackendObservabilityConfig = BaseObservabilityConfig & {
  backend: "otel"
  otel: OTelObservabilityConfig
}

export type SentryBackendObservabilityConfig = BaseObservabilityConfig & {
  backend: "sentry"
  sentry: SentryObservabilityConfig
}

export type ObservabilityConfig =
  | NoneObservabilityConfig
  | OTelBackendObservabilityConfig
  | SentryBackendObservabilityConfig

export type JsonPrimitive = string | number | boolean | null
export type JsonValue = JsonPrimitive | JsonValue[] | JsonObject
export type JsonObject = {
  readonly [key: string]: JsonValue | undefined
}

export type JsonStdoutLogger = {
  log: (level: StructuredLogLevel, message: string, fields?: JsonObject) => void
  debug: (message: string, fields?: JsonObject) => void
  info: (message: string, fields?: JsonObject) => void
  warn: (message: string, fields?: JsonObject) => void
  error: (message: string, fields?: JsonObject) => void
  child: (fields: JsonObject) => JsonStdoutLogger
}

export type StructuredLogLevel = "debug" | "info" | "warn" | "error"

export type JsonStdoutLoggerOptions = {
  serviceName: string
  fields?: JsonObject
  now?: () => Date
  write?: (line: string) => void
}

export class ObservabilityConfigError extends Error {
  readonly envKey?: string

  constructor(message: string, envKey?: string) {
    super(envKey ? `${envKey}: ${message}` : message)
    this.name = "ObservabilityConfigError"
    this.envKey = envKey
  }
}

const OTEL_DEFAULT_PROTOCOL: OTelProtocol = "http/protobuf"

function envValue(env: ObservabilityEnv, key: string): string | undefined {
  const value = env[key]
  if (value === undefined) {
    return undefined
  }

  const trimmed = value.trim()
  return trimmed ? trimmed : undefined
}

function parseBackend(env: ObservabilityEnv): ObservabilityBackend {
  const backend = envValue(env, "DEN_OBSERVABILITY_BACKEND")
  if (backend === undefined) {
    return "none"
  }

  switch (backend) {
    case "none":
    case "otel":
    case "sentry":
      return backend
    default:
      throw new ObservabilityConfigError(
        "must be one of none, otel, sentry",
        "DEN_OBSERVABILITY_BACKEND",
      )
  }
}

function requireServiceName(serviceName: string): string {
  const trimmed = serviceName.trim()
  if (!trimmed) {
    throw new ObservabilityConfigError("service name is required")
  }
  return trimmed
}

function validateHttpUrl(value: string, envKey: string): string {
  let parsed: URL
  try {
    parsed = new URL(value)
  } catch {
    throw new ObservabilityConfigError("must be an absolute http(s) URL", envKey)
  }

  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
    throw new ObservabilityConfigError("must use http or https", envKey)
  }
  if (!parsed.hostname) {
    throw new ObservabilityConfigError("must include a hostname", envKey)
  }

  return value
}

function validateSentryDsn(value: string): string {
  validateHttpUrl(value, "SENTRY_DSN")

  const parsed = new URL(value)
  if (!parsed.username) {
    throw new ObservabilityConfigError("must include a public key", "SENTRY_DSN")
  }

  const projectId = parsed.pathname.split("/").filter(Boolean).at(-1)
  if (!projectId) {
    throw new ObservabilityConfigError("must include a project id", "SENTRY_DSN")
  }

  return value
}

function parseUnitInterval(raw: string, envKey: string): number {
  const value = Number(raw)
  if (!Number.isFinite(value) || value < 0 || value > 1) {
    throw new ObservabilityConfigError("must be a number from 0 through 1", envKey)
  }
  return value
}

function parseOtelProtocol(env: ObservabilityEnv, envKey: string, fallback: OTelProtocol): OTelProtocol {
  const protocol = envValue(env, envKey)
  if (protocol === undefined) {
    return fallback
  }

  if (protocol === "http/protobuf") {
    return protocol
  }

  throw new ObservabilityConfigError("must be http/protobuf", envKey)
}

function parseOtelExporter(env: ObservabilityEnv, envKey: string): OTelSignalExporter {
  const exporter = envValue(env, envKey)
  if (exporter === undefined) {
    return "otlp"
  }

  switch (exporter) {
    case "otlp":
    case "none":
      return exporter
    default:
      throw new ObservabilityConfigError("must be otlp or none", envKey)
  }
}

function parseOtelSamplerName(env: ObservabilityEnv): OTelSampler {
  const sampler = envValue(env, "OTEL_TRACES_SAMPLER")
  if (sampler === undefined) {
    return "parentbased_always_on"
  }

  switch (sampler) {
    case "always_on":
    case "always_off":
    case "traceidratio":
    case "parentbased_always_on":
    case "parentbased_always_off":
    case "parentbased_traceidratio":
      return sampler
    default:
      throw new ObservabilityConfigError(
        "must be a standard OpenTelemetry sampler",
        "OTEL_TRACES_SAMPLER",
      )
  }
}

function isRatioSampler(sampler: OTelSampler): boolean {
  return sampler === "traceidratio" || sampler === "parentbased_traceidratio"
}

function parseOtelSampler(env: ObservabilityEnv): OTelSamplerConfig {
  const name = parseOtelSamplerName(env)
  const rawArgument = envValue(env, "OTEL_TRACES_SAMPLER_ARG")

  if (isRatioSampler(name)) {
    const ratio = rawArgument === undefined ? 1 : parseUnitInterval(rawArgument, "OTEL_TRACES_SAMPLER_ARG")
    return { name, ratio, argument: String(ratio) }
  }

  if (rawArgument !== undefined) {
    throw new ObservabilityConfigError(
      "is only supported for traceidratio samplers",
      "OTEL_TRACES_SAMPLER_ARG",
    )
  }

  if (name === "always_off" || name === "parentbased_always_off") {
    return { name, ratio: 0 }
  }

  return { name, ratio: 1 }
}

function otelSignalPath(signal: OTelSignal): string {
  switch (signal) {
    case "traces":
      return "/v1/traces"
    case "metrics":
      return "/v1/metrics"
    case "logs":
      return "/v1/logs"
  }
}

function appendOtelSignalPath(baseEndpoint: string, signal: OTelSignal): string {
  const parsed = new URL(baseEndpoint)
  const basePath = parsed.pathname.replace(/\/+$/u, "")
  parsed.pathname = `${basePath}${otelSignalPath(signal)}`
  return parsed.toString()
}

function otelSignalEnv(signal: OTelSignal): {
  endpoint: string
  exporter: string
  protocol: string
} {
  switch (signal) {
    case "traces":
      return {
        endpoint: "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
        exporter: "OTEL_TRACES_EXPORTER",
        protocol: "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL",
      }
    case "metrics":
      return {
        endpoint: "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT",
        exporter: "OTEL_METRICS_EXPORTER",
        protocol: "OTEL_EXPORTER_OTLP_METRICS_PROTOCOL",
      }
    case "logs":
      return {
        endpoint: "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT",
        exporter: "OTEL_LOGS_EXPORTER",
        protocol: "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL",
      }
  }
}

function parseOtelSignal(
  env: ObservabilityEnv,
  signal: OTelSignal,
  protocol: OTelProtocol,
  baseEndpoint: string | undefined,
): OTelSignalConfig {
  const keys = otelSignalEnv(signal)
  const endpointOverride = envValue(env, keys.endpoint)

  let endpoint: string | undefined
  let endpointSource: OTelEndpointSource = "default"
  if (endpointOverride !== undefined) {
    endpoint = validateHttpUrl(endpointOverride, keys.endpoint)
    endpointSource = "signal"
  } else if (baseEndpoint !== undefined) {
    endpoint = appendOtelSignalPath(baseEndpoint, signal)
    endpointSource = "base"
  }

  return {
    exporter: parseOtelExporter(env, keys.exporter),
    protocol: parseOtelProtocol(env, keys.protocol, protocol),
    endpoint,
    endpointSource,
  }
}

function validateOtelSignalEndpoint(signal: OTelSignal, config: OTelSignalConfig): void {
  if (config.exporter === "none" || config.endpoint !== undefined) {
    return
  }

  throw new ObservabilityConfigError(
    "is required when the signal exporter is otlp",
    otelSignalEnv(signal).endpoint,
  )
}

function parseOtelConfig(env: ObservabilityEnv): OTelObservabilityConfig {
  const protocol = parseOtelProtocol(env, "OTEL_EXPORTER_OTLP_PROTOCOL", OTEL_DEFAULT_PROTOCOL)
  const rawBaseEndpoint = envValue(env, "OTEL_EXPORTER_OTLP_ENDPOINT")
  const baseEndpoint = rawBaseEndpoint === undefined
    ? undefined
    : validateHttpUrl(rawBaseEndpoint, "OTEL_EXPORTER_OTLP_ENDPOINT")
  const sampler = parseOtelSampler(env)

  const signals = {
    traces: parseOtelSignal(env, "traces", protocol, baseEndpoint),
    metrics: parseOtelSignal(env, "metrics", protocol, baseEndpoint),
    logs: parseOtelSignal(env, "logs", protocol, baseEndpoint),
  }

  validateOtelSignalEndpoint("traces", signals.traces)
  validateOtelSignalEndpoint("metrics", signals.metrics)
  validateOtelSignalEndpoint("logs", signals.logs)

  return {
    protocol,
    baseEndpoint,
    sampler,
    signals,
  }
}

function parseSentryConfig(env: ObservabilityEnv): SentryObservabilityConfig {
  const dsn = envValue(env, "SENTRY_DSN")
  if (dsn === undefined) {
    throw new ObservabilityConfigError(
      "is required when DEN_OBSERVABILITY_BACKEND=sentry",
      "SENTRY_DSN",
    )
  }

  const sampleRate = envValue(env, "SENTRY_TRACES_SAMPLE_RATE")

  return {
    dsn: validateSentryDsn(dsn),
    tracesSampleRate: sampleRate === undefined
      ? 0.01
      : parseUnitInterval(sampleRate, "SENTRY_TRACES_SAMPLE_RATE"),
  }
}

function parseSentryBuildVariables(
  env: ObservabilityEnv,
  options: { validateUrls: boolean },
): SentryBuildVariables {
  const values: SentryBuildVariableValues = {}
  const org = envValue(env, "SENTRY_ORG")
  const project = envValue(env, "SENTRY_PROJECT")
  const url = envValue(env, "SENTRY_URL")
  const release = envValue(env, "SENTRY_RELEASE")
  const environment = envValue(env, "SENTRY_ENVIRONMENT")
  const dist = envValue(env, "SENTRY_DIST")
  const authToken = envValue(env, "SENTRY_AUTH_TOKEN")

  if (org !== undefined) {
    values.SENTRY_ORG = org
  }
  if (project !== undefined) {
    values.SENTRY_PROJECT = project
  }
  if (url !== undefined) {
    values.SENTRY_URL = options.validateUrls ? validateHttpUrl(url, "SENTRY_URL") : url
  }
  if (release !== undefined) {
    values.SENTRY_RELEASE = release
  }
  if (environment !== undefined) {
    values.SENTRY_ENVIRONMENT = environment
  }
  if (dist !== undefined) {
    values.SENTRY_DIST = dist
  }

  return {
    values,
    redactedKeys: authToken === undefined ? [] : ["SENTRY_AUTH_TOKEN"],
  }
}

export function parseObservabilityEnv(
  env: ObservabilityEnv,
  options: { serviceName: string },
): ObservabilityConfig {
  const serviceName = requireServiceName(options.serviceName)
  const backend = parseBackend(env)
  const sentryBuild = parseSentryBuildVariables(env, { validateUrls: backend === "sentry" })

  switch (backend) {
    case "none":
      return { backend, serviceName, sentryBuild }
    case "otel":
      return { backend, serviceName, sentryBuild, otel: parseOtelConfig(env) }
    case "sentry":
      return { backend, serviceName, sentryBuild, sentry: parseSentryConfig(env) }
  }
}

function defaultWrite(line: string): void {
  console.log(line)
}

function mergeJsonFields(first: JsonObject | undefined, second: JsonObject | undefined): JsonObject {
  return {
    ...(first ?? {}),
    ...(second ?? {}),
  }
}

export function createJsonStdoutLogger(options: JsonStdoutLoggerOptions): JsonStdoutLogger {
  const serviceName = requireServiceName(options.serviceName)
  const write = options.write ?? defaultWrite
  const now = options.now ?? (() => new Date())
  const baseFields = options.fields

  const log = (level: StructuredLogLevel, message: string, fields?: JsonObject) => {
    const entry: JsonObject = {
      ...mergeJsonFields(baseFields, fields),
      timestamp: now().toISOString(),
      level,
      service: serviceName,
      message,
    }

    write(JSON.stringify(entry))
  }

  return {
    log,
    debug: (message, fields) => log("debug", message, fields),
    info: (message, fields) => log("info", message, fields),
    warn: (message, fields) => log("warn", message, fields),
    error: (message, fields) => log("error", message, fields),
    child: (fields) => createJsonStdoutLogger({
      serviceName,
      fields: mergeJsonFields(baseFields, fields),
      now,
      write,
    }),
  }
}