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

import { assert, describe, it } from "@effect/vitest";
import * as ConfigProvider from "effect/ConfigProvider";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as OtlpResource from "effect/observability/OtlpResource";

import * as OtelEnvironment from "./otelEnvironment.ts";

const load = (env: Record<string, string>) =>
  OtelEnvironment.load.pipe(Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnv({ env }))));

const SPEC_OFF =
  "OTEL_SDK_DISABLED is set, so no telemetry is exported, whatever configured it; set T3CODE_OTEL_SDK_DISABLED=false to export anyway";
const T3_OFF =
  "T3CODE_OTEL_SDK_DISABLED is set, so no telemetry is exported, whatever configured it";
const specIgnored = (value: string) =>
  `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`;

describe("OtelEnvironment", () => {
  it.effect.each([
    { name: "nothing set", env: {}, disabled: false, warnings: [] },
    { name: "spec true", env: { OTEL_SDK_DISABLED: "true" }, disabled: true, warnings: [SPEC_OFF] },
    {
      name: "spec 1",
      env: { OTEL_SDK_DISABLED: "1" },
      disabled: false,
      warnings: [specIgnored("1")],
    },
    { name: "t3 1", env: { T3CODE_OTEL_SDK_DISABLED: "1" }, disabled: true, warnings: [T3_OFF] },
    {
      name: "t3 false overrides spec true",
      env: { T3CODE_OTEL_SDK_DISABLED: "false", OTEL_SDK_DISABLED: "true" },
      disabled: false,
      warnings: [],
    },
    {
      name: "unreadable t3 warns and falls through",
      env: { T3CODE_OTEL_SDK_DISABLED: "maybe", OTEL_SDK_DISABLED: "true" },
      disabled: true,
      warnings: ["T3CODE_OTEL_SDK_DISABLED=maybe is not a yes or a no and was ignored", SPEC_OFF],
    },
  ])("$name", ({ env, disabled, warnings }) =>
    Effect.gen(function* () {
      const resolved = yield* load(env);
      assert.strictEqual(resolved.disabled, disabled);
      assert.deepStrictEqual(resolved.warnings, warnings);
    }),
  );

  it.effect.each([
    {
      name: "a percent-encoded list",
      env: { OTEL_RESOURCE_ATTRIBUTES: "team=core,message=hello%20world" },
      resourceAttributes: { team: "core", message: "hello world" },
      warnings: [],
    },
    {
      name: "a list that does not decode",
      env: { OTEL_RESOURCE_ATTRIBUTES: "team=core,broken=%zz" },
      resourceAttributes: {},
      warnings: [
        "OTEL_RESOURCE_ATTRIBUTES is not a list of percent-encoded key=value pairs and was ignored",
      ],
    },
  ])("resource attributes: $name", ({ env, resourceAttributes, warnings }) =>
    Effect.gen(function* () {
      const resolved = yield* load(env);
      assert.deepStrictEqual(resolved.resourceAttributes, resourceAttributes);
      assert.deepStrictEqual(resolved.warnings, warnings);
    }),
  );

  describe("endpoints", () => {
    const urlOf = (signal: OtelEnvironment.OtelSignal) =>
      OtelEnvironment.OtelSignal.$match(signal, {
        Export: ({ url }) => url,
        Off: () => "Off",
        Unset: () => "Unset",
      });
    it.effect.each([
      {
        name: "generic endpoint appends each signal's path, keeping the query",
        env: { OTEL_EXPORTER_OTLP_ENDPOINT: "https://collector:4318/base?api_key=secret" },
        traces: "https://collector:4318/base/v1/traces?api_key=secret",
        metrics: "https://collector:4318/base/v1/metrics?api_key=secret",
        logs: "https://collector:4318/base/v1/logs?api_key=secret",
        warnings: [],
      },
      {
        name: "a per-signal endpoint is used verbatim",
        env: { OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "https://tempo:4318/custom" },
        traces: "https://tempo:4318/custom",
        metrics: "Unset",
        logs: "Unset",
        warnings: [],
      },
      {
        name: "a per-signal endpoint beats the generic one",
        env: {
          OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "https://tempo:4318/custom",
          OTEL_EXPORTER_OTLP_ENDPOINT: "https://collector:4318/base",
        },
        traces: "https://tempo:4318/custom",
        metrics: "https://collector:4318/base/v1/metrics",
        logs: "https://collector:4318/base/v1/logs",
        warnings: [],
      },
      {
        name: "a blank per-signal endpoint falls through to the generic one",
        env: {
          OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "  ",
          OTEL_EXPORTER_OTLP_ENDPOINT: "https://collector:4318/base",
        },
        traces: "https://collector:4318/base/v1/traces",
        metrics: "https://collector:4318/base/v1/metrics",
        logs: "https://collector:4318/base/v1/logs",
        warnings: [],
      },
      {
        name: "an invalid per-signal endpoint warns and does not fall through",
        env: {
          OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "not-a-url",
          OTEL_EXPORTER_OTLP_ENDPOINT: "https://collector:4318/base",
        },
        traces: "Off",
        metrics: "https://collector:4318/base/v1/metrics",
        logs: "https://collector:4318/base/v1/logs",
        warnings: [
          "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is not an http or https URL, so the signals it configures are not exported",
        ],
      },
      {
        name: "an invalid generic endpoint warns without leaking its query",
        env: { OTEL_EXPORTER_OTLP_ENDPOINT: "not-a-url?api_key=secret" },
        traces: "Off",
        metrics: "Off",
        logs: "Off",
        warnings: [
          "OTEL_EXPORTER_OTLP_ENDPOINT is not an http or https URL, so the signals it configures are not exported",
        ],
      },
      {
        name: "the kill switch wins outright over a valid endpoint",
        env: {
          T3CODE_OTEL_SDK_DISABLED: "true",
          OTEL_EXPORTER_OTLP_ENDPOINT: "https://collector:4318/base",
        },
        traces: "Unset",
        metrics: "Unset",
        logs: "Unset",
        warnings: [T3_OFF],
      },
      {
        name: "an exporter of none turns off only its signal",
        env: {
          OTEL_EXPORTER_OTLP_ENDPOINT: "https://collector:4318",
          OTEL_LOGS_EXPORTER: "none",
        },
        traces: "https://collector:4318/v1/traces",
        metrics: "https://collector:4318/v1/metrics",
        logs: "Off",
        warnings: [],
      },
    ])("$name", ({ env, traces, metrics, logs, warnings }) =>
      Effect.gen(function* () {
        const resolved = yield* load(env);
        assert.strictEqual(urlOf(resolved.traces), traces);
        assert.strictEqual(urlOf(resolved.metrics), metrics);
        assert.strictEqual(urlOf(resolved.logs), logs);
        assert.deepStrictEqual(resolved.warnings, warnings);
      }),
    );

    const ENDPOINT = { OTEL_EXPORTER_OTLP_ENDPOINT: "https://collector:4318" };
    const exportOf = (signal: OtelEnvironment.OtelSignal): unknown =>
      OtelEnvironment.OtelSignal.$match(signal, {
        Export: ({ protocol, headers }) => ({ protocol, headers }),
        Off: () => "Off",
        Unset: () => "Unset",
      });
    it.effect.each([
      {
        name: "a per-signal protocol and headers beat the generic ones",
        env: {
          ...ENDPOINT,
          OTEL_EXPORTER_OTLP_PROTOCOL: "http/json",
          OTEL_EXPORTER_OTLP_HEADERS: "api-key=shared",
          OTEL_EXPORTER_OTLP_TRACES_PROTOCOL: "http/protobuf",
          OTEL_EXPORTER_OTLP_TRACES_HEADERS: "api-key=traces%20only",
        },
        traces: { protocol: "http/protobuf", headers: { "api-key": "traces only" } },
        logs: { protocol: "http/json", headers: { "api-key": "shared" } },
        warnings: [],
      },
      {
        name: "an unsupported protocol turns off the signals it configures",
        env: { ...ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_PROTOCOL: "grpc" },
        traces: { protocol: "http/protobuf", headers: undefined },
        logs: "Off",
        warnings: [
          "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL is not http/protobuf or http/json, so the signals it configures are not exported",
        ],
      },
      {
        name: "undecodable headers turn off every signal once, without leaking them",
        env: { ...ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS: "api-key=%zz" },
        traces: "Off",
        logs: "Off",
        warnings: [
          "OTEL_EXPORTER_OTLP_HEADERS is not a list of key=value pairs with percent-encoded values, so the signals it configures are not exported",
        ],
      },
    ])("$name", ({ env, traces, logs, warnings }) =>
      Effect.gen(function* () {
        const resolved = yield* load(env);
        assert.deepStrictEqual(exportOf(resolved.traces), traces);
        assert.deepStrictEqual(exportOf(resolved.logs), logs);
        assert.deepStrictEqual(resolved.warnings, warnings);
      }),
    );
  });

  it.effect("names the variable each signal's endpoint came from", () =>
    Effect.gen(function* () {
      const otel = yield* load({
        OTEL_EXPORTER_OTLP_ENDPOINT: "https://collector:4318",
        OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "https://tempo:4318/v1/traces",
      });
      const variableOf = (signal: OtelEnvironment.OtelSignal) =>
        OtelEnvironment.OtelSignal.$match(signal, {
          Export: ({ variable }) => variable,
          Off: () => undefined,
          Unset: () => undefined,
        });
      assert.strictEqual(variableOf(otel.traces), "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT");
      assert.strictEqual(variableOf(otel.metrics), "OTEL_EXPORTER_OTLP_ENDPOINT");
      assert.strictEqual(variableOf(otel.logs), "OTEL_EXPORTER_OTLP_ENDPOINT");
    }),
  );

  describe("resolveSignalEndpoint", () => {
    const t3Export = {
      protocol: "http/json",
      headers: { "x-key": "t3" },
      exportIntervalMs: 5_000,
    } as const;
    const withLogs = (logs: OtelEnvironment.OtelSignal, disabled = false) => ({
      ...OtelEnvironment.none,
      disabled,
      logs,
    });
    const otelExport = OtelEnvironment.OtelSignal.Export({
      url: "http://otel:4318/v1/logs",
      variable: "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT",
      protocol: "http/protobuf",
      headers: { "x-key": "otel" },
    });
    it.each([
      {
        name: "T3CODE_OTLP_*_URL wins over a signal the OTEL variables turned off",
        otel: withLogs(OtelEnvironment.OtelSignal.Off()),
        t3Url: "http://t3:4318/v1/logs",
        expected: {
          url: "http://t3:4318/v1/logs",
          export: t3Export,
          source: "environment" as const,
          variable: "T3CODE_OTLP_LOGS_URL",
        },
      },
      {
        name: "an OTEL endpoint brings its headers and protocol over the fallback",
        otel: withLogs(otelExport),
        t3Url: " ",
        expected: {
          url: "http://otel:4318/v1/logs",
          export: {
            protocol: "http/protobuf" as const,
            headers: { "x-key": "otel" },
            exportIntervalMs: 5_000,
          },
          source: "environment" as const,
          variable: "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT",
        },
      },
      {
        name: "a signal the OTEL variables turned off does not fall through",
        otel: withLogs(OtelEnvironment.OtelSignal.Off()),
        t3Url: undefined,
        expected: undefined,
      },
      {
        name: "an unset signal takes the first non-blank fallback",
        otel: withLogs(OtelEnvironment.OtelSignal.Unset()),
        t3Url: undefined,
        expected: {
          url: "http://settings:4318/v1/logs",
          export: t3Export,
          source: "settings" as const,
        },
      },
      {
        name: "a desktop bootstrap URL that differs from the setting wins as the desktop's own",
        otel: withLogs(OtelEnvironment.OtelSignal.Unset()),
        t3Url: undefined,
        bootstrapUrl: "http://desktop:4318/v1/logs",
        expected: {
          url: "http://desktop:4318/v1/logs",
          export: t3Export,
          source: "bootstrap" as const,
        },
      },
      {
        name: "a desktop bootstrap URL that forwards the setting counts as the setting",
        otel: withLogs(OtelEnvironment.OtelSignal.Unset()),
        t3Url: undefined,
        bootstrapUrl: " http://settings:4318/v1/logs ",
        expected: {
          url: "http://settings:4318/v1/logs",
          export: t3Export,
          source: "settings" as const,
        },
      },
    ])("$name", ({ otel, t3Url, bootstrapUrl = "", expected }) => {
      assert.deepStrictEqual(
        OtelEnvironment.resolveSignalEndpoint(
          otel,
          "logs",
          { url: t3Url, export: t3Export },
          { bootstrapUrl, settingsUrl: "http://settings:4318/v1/logs" },
        ),
        expected,
      );
    });
  });

  it.effect("an exporter of none keeps the Settings endpoint from re-enabling its signal", () =>
    Effect.gen(function* () {
      const otel = yield* load({ OTEL_LOGS_EXPORTER: "none" });
      const t3 = {
        url: undefined,
        export: { protocol: "http/json", headers: undefined, exportIntervalMs: 10_000 },
      } as const;
      assert.strictEqual(
        OtelEnvironment.resolveSignalEndpoint(otel, "logs", t3, {
          bootstrapUrl: undefined,
          settingsUrl: "http://settings:4318/v1/logs",
        }),
        undefined,
      );
      assert.strictEqual(
        OtelEnvironment.resolveSignalEndpoint(otel, "traces", t3, {
          bootstrapUrl: undefined,
          settingsUrl: "http://settings:4318/v1/traces",
        })?.url,
        "http://settings:4318/v1/traces",
      );
    }),
  );

  describe("layerResourceAttributes", () => {
    it.effect.each([
      { name: "a list that does not decode", raw: "team=%zz", attributes: [] },
      { name: "encoded separators", raw: "a%2Cb=x%3Dy", attributes: ["a,b"] },
    ])("lets the exporters' own read succeed with $name", ({ raw, attributes }) =>
      Effect.gen(function* () {
        const layerEnv = ConfigProvider.layer(
          ConfigProvider.fromEnv({ env: { OTEL_RESOURCE_ATTRIBUTES: raw } }),
        );
        const otel = yield* OtelEnvironment.load.pipe(Effect.provide(layerEnv));
        const resource = yield* OtlpResource.fromConfig({ serviceName: "t3" }).pipe(
          Effect.provide(
            Layer.provide(
              OtelEnvironment.layerResourceAttributes(otel.resourceAttributes),
              layerEnv,
            ),
          ),
        );
        assert.deepStrictEqual(
          resource.attributes
            .map((attribute) => attribute.key)
            .filter((key) => !key.startsWith("telemetry.sdk.")),
          [...attributes, "service.name"],
        );
      }),
    );
  });
});

describe("isRelayTracingEnabled", () => {
  it("defaults on and respects the T3CODE SDK override of the standard kill switch", () => {
    assert.isTrue(OtelEnvironment.isRelayTracingEnabled({}));
    assert.isFalse(OtelEnvironment.isRelayTracingEnabled({ OTEL_SDK_DISABLED: "true" }));
    assert.isTrue(
      OtelEnvironment.isRelayTracingEnabled({
        OTEL_SDK_DISABLED: "true",
        T3CODE_OTEL_SDK_DISABLED: "false",
      }),
    );
    assert.isFalse(
      OtelEnvironment.isRelayTracingEnabled({
        OTEL_SDK_DISABLED: "false",
        T3CODE_OTEL_SDK_DISABLED: "true",
      }),
    );
  });

  it.effect("product opt-out beats SDK enable without disabling user-configured tracing", () =>
    Effect.gen(function* () {
      const env = {
        T3CODE_TELEMETRY_ENABLED: "false",
        T3CODE_OTEL_SDK_DISABLED: "false",
        OTEL_SDK_DISABLED: "true",
        OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "https://user.example.test/v1/traces",
      };
      assert.isFalse(OtelEnvironment.isRelayTracingEnabled(env));

      const otel = yield* load(env);
      assert.isFalse(otel.disabled);
      assert.deepStrictEqual(
        otel.traces,
        OtelEnvironment.OtelSignal.Export({
          url: env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
          variable: "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
          protocol: "http/protobuf",
          headers: undefined,
        }),
      );
    }),
  );
});