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,
}),
);
}),
);
});