Skip to content

Commit 841ee8f

Browse files
refactor(observability): read the kill switch through Config.schema
Both switch variables now go through one small reader built on Config.schema, with trimming and lowercasing in the schema. Behavior is unchanged: OTEL_SDK_DISABLED still follows the specification (only `true` disables, anything else warns), and T3CODE_OTEL_SDK_DISABLED still takes precedence with Config.Boolean's values. Tests collapse into one table that checks exact warnings, and the docs section is shortened to what an operator needs. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent ab2824a commit 841ee8f

5 files changed

Lines changed: 148 additions & 351 deletions

File tree

‎apps/desktop/src/backend/DesktopBackendConfiguration.test.ts‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -963,9 +963,6 @@ describe("DesktopBackendConfiguration", () => {
963963
const configuration = yield* DesktopBackendConfiguration.DesktopBackendConfiguration;
964964
const config = yield* configuration.resolveWsl({ port: 5050, distro: null });
965965

966-
// Nothing crosses wsl.exe that WSLENV does not declare, and the
967-
// endpoints reach the backend through the bootstrap regardless, so
968-
// the switch has to travel or the server keeps exporting.
969966
assert.equal(config.env.OTEL_SDK_DISABLED, "true");
970967
assert.include((config.env.WSLENV ?? "").split(":"), "OTEL_SDK_DISABLED");
971968
}).pipe(

‎apps/desktop/src/backend/DesktopBackendConfiguration.ts‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -96,11 +96,7 @@ const DESKTOP_BACKEND_ENV_NAMES = [
9696
const WSL_FORWARDED_ENV_NAMES = [
9797
"OPENAI_API_KEY",
9898
"ANTHROPIC_API_KEY",
99-
// The kill switch has to reach the distro under its own name. A WSL backend
100-
// reads its endpoints from the bootstrap envelope, so without these two the
101-
// switch would silence this process while the server it launched kept
102-
// exporting to a persisted endpoint, which is the one outcome nobody would
103-
// look for.
99+
// Otherwise the WSL server keeps exporting to endpoints from the bootstrap.
104100
"T3CODE_OTEL_SDK_DISABLED",
105101
"OTEL_SDK_DISABLED",
106102
"T3CODE_OTLP_HEADERS",

‎docs/operations/observability.md‎

Lines changed: 9 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -557,35 +557,15 @@ on stdout only.
557557

558558
### The Kill Switch
559559

560-
`T3CODE_OTEL_SDK_DISABLED` and `OTEL_SDK_DISABLED` turn every OTLP export off, in both the server
561-
and the desktop main process, regardless of what any endpoint variable or Settings entry says.
562-
`T3CODE_OTEL_SDK_DISABLED` is read first; `OTEL_SDK_DISABLED` is read only when it is unset, so a
563-
machine that already exports `OTEL_SDK_DISABLED` for everything else can still opt T3 Code back in
564-
with `T3CODE_OTEL_SDK_DISABLED=false` without touching the ambient variable everything else depends
565-
on.
566-
567-
The two names accept different values, and the narrower one is not a choice we made.
568-
`OTEL_SDK_DISABLED` is a name the OpenTelemetry specification defines, and the specification says a
569-
boolean variable it defines "MUST be set to true only by the case-insensitive string `true`" and
570-
that "an implementation MUST NOT extend this definition and define additional values that are
571-
interpreted as true". So `OTEL_SDK_DISABLED=1` and `OTEL_SDK_DISABLED=yes` leave export running:
572-
reading them as affirmative would make T3 Code disagree with every other OpenTelemetry SDK reading
573-
the same variable on the same machine, which is the whole point of the variable having a standard
574-
name.
575-
576-
A value that looks affirmative and is read as false is the failure that rule produces, so the
577-
specification asks for a warning on anything it does not recognize, and one is reported at startup.
578-
It is reported even when `T3CODE_OTEL_SDK_DISABLED` already answered, since the value is wrong
579-
either way. Only `false`, blank and unset are quiet, because those are the ways of saying no that
580-
the specification recognizes.
581-
582-
`T3CODE_OTEL_SDK_DISABLED` is a name of ours, which the specification does not constrain, so it is
583-
read the way every other `T3CODE_*` boolean is read: `true`, `yes`, `on`, `1`, `y` and their
584-
negations, case-insensitively. A value that matches none of them is a warning rather than a refusal
585-
to start, and that name is treated as unset so `OTEL_SDK_DISABLED` decides instead.
586-
587-
An endpoint stored in Settings never overrides the switch: when it is set, the server and desktop
588-
app report every OTLP endpoint as unset no matter what was persisted.
560+
`T3CODE_OTEL_SDK_DISABLED` and `OTEL_SDK_DISABLED` turn off every OTLP export in both the server and
561+
the desktop main process, overriding any endpoint from the environment or Settings. Local trace
562+
files and stdout logs are unaffected.
563+
564+
`T3CODE_OTEL_SDK_DISABLED` wins when set, so `T3CODE_OTEL_SDK_DISABLED=false` re-enables export on a
565+
machine that sets `OTEL_SDK_DISABLED` for everything else. It accepts the usual boolean spellings
566+
(`true`/`false`, `yes`/`no`, `on`/`off`, `1`/`0`, `y`/`n`). `OTEL_SDK_DISABLED` follows the
567+
OpenTelemetry specification and only `true` disables export, so `OTEL_SDK_DISABLED=1` does not.
568+
Values are case-insensitive and trimmed. An unrecognized value is ignored with a startup warning.
589569

590570
### What Is Instrumented Today
591571

Lines changed: 70 additions & 138 deletions
Original file line numberDiff line numberDiff line change
@@ -1,150 +1,82 @@
11
import { assert, describe, it } from "@effect/vitest";
22
import * as ConfigProvider from "effect/ConfigProvider";
33
import * as Effect from "effect/Effect";
4-
import * as Layer from "effect/Layer";
54

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

8-
const withEnv = (env: Record<string, string>) =>
9-
Effect.provide(Layer.mergeAll(ConfigProvider.layer(ConfigProvider.fromEnv({ env }))));
7+
const load = (env: Record<string, string>) =>
8+
OtelEnvironment.load.pipe(Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnv({ env }))));
109

11-
describe("OtelEnvironment", () => {
12-
it.effect("stays enabled when nothing is configured", () =>
13-
Effect.gen(function* () {
14-
const resolved = yield* OtelEnvironment.load.pipe(withEnv({}));
15-
assert.strictEqual(resolved.disabled, false);
16-
assert.deepStrictEqual(resolved.warnings, []);
17-
}),
18-
);
19-
20-
it.effect("OTEL_SDK_DISABLED disables only on the exact string true", () =>
21-
Effect.gen(function* () {
22-
const trueValue = yield* OtelEnvironment.load.pipe(withEnv({ OTEL_SDK_DISABLED: "true" }));
23-
assert.isTrue(trueValue.disabled);
24-
25-
const upper = yield* OtelEnvironment.load.pipe(withEnv({ OTEL_SDK_DISABLED: "True" }));
26-
assert.isTrue(upper.disabled);
27-
28-
const numeric = yield* OtelEnvironment.load.pipe(withEnv({ OTEL_SDK_DISABLED: "1" }));
29-
assert.isFalse(numeric.disabled);
30-
31-
const yes = yield* OtelEnvironment.load.pipe(withEnv({ OTEL_SDK_DISABLED: "yes" }));
32-
assert.isFalse(yes.disabled);
33-
}),
34-
);
35-
36-
it.effect("warns about a value the specification reads as the opposite of its meaning", () =>
37-
Effect.gen(function* () {
38-
const affirmative = yield* OtelEnvironment.load.pipe(withEnv({ OTEL_SDK_DISABLED: "yes" }));
39-
assert.isFalse(affirmative.disabled);
40-
assert.include(affirmative.warnings.join("\n"), "OTEL_SDK_DISABLED=yes was read as false");
41-
42-
const spelled = yield* OtelEnvironment.load.pipe(withEnv({ OTEL_SDK_DISABLED: "false" }));
43-
assert.isFalse(spelled.disabled);
44-
assert.deepStrictEqual(spelled.warnings, []);
45-
}),
46-
);
47-
48-
it.effect("keeps complaining about a bad standard value when T3 Code's name answered", () =>
49-
Effect.gen(function* () {
50-
const resolved = yield* OtelEnvironment.load.pipe(
51-
withEnv({ T3CODE_OTEL_SDK_DISABLED: "false", OTEL_SDK_DISABLED: "yes" }),
52-
);
53-
assert.isFalse(resolved.disabled);
54-
assert.include(resolved.warnings.join("\n"), "OTEL_SDK_DISABLED=yes was read as false");
55-
}),
56-
);
57-
58-
it.effect("T3CODE_OTEL_SDK_DISABLED accepts the values every T3CODE_* boolean accepts", () =>
59-
Effect.gen(function* () {
60-
const numeric = yield* OtelEnvironment.load.pipe(withEnv({ T3CODE_OTEL_SDK_DISABLED: "1" }));
61-
assert.isTrue(numeric.disabled);
62-
63-
const yes = yield* OtelEnvironment.load.pipe(withEnv({ T3CODE_OTEL_SDK_DISABLED: "yes" }));
64-
assert.isTrue(yes.disabled);
65-
66-
const off = yield* OtelEnvironment.load.pipe(withEnv({ T3CODE_OTEL_SDK_DISABLED: "off" }));
67-
assert.isFalse(off.disabled);
10+
const SPEC_OFF =
11+
"OTEL_SDK_DISABLED is set, so no telemetry is exported, whatever configured it; set T3CODE_OTEL_SDK_DISABLED=false to export anyway";
12+
const T3_OFF =
13+
"T3CODE_OTEL_SDK_DISABLED is set, so no telemetry is exported, whatever configured it";
14+
const specIgnored = (value: string) =>
15+
`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`;
6816

69-
// Config.Boolean's literals, because the specification constrains the
70-
// names it defines and not ours, and T3 Code's own variables should not
71-
// disagree with each other about what a yes looks like.
72-
const shortYes = yield* OtelEnvironment.load.pipe(withEnv({ T3CODE_OTEL_SDK_DISABLED: "y" }));
73-
assert.isTrue(shortYes.disabled);
74-
75-
const shortNo = yield* OtelEnvironment.load.pipe(withEnv({ T3CODE_OTEL_SDK_DISABLED: "n" }));
76-
assert.isFalse(shortNo.disabled);
77-
78-
// The standard name is case-insensitive by specification, so ours cannot
79-
// be the stricter of the two.
80-
const shouted = yield* OtelEnvironment.load.pipe(
81-
withEnv({ T3CODE_OTEL_SDK_DISABLED: "TRUE" }),
82-
);
83-
assert.isTrue(shouted.disabled);
84-
}),
85-
);
86-
87-
it.effect("an unreadable T3CODE_OTEL_SDK_DISABLED warns and falls through", () =>
88-
Effect.gen(function* () {
89-
const resolved = yield* OtelEnvironment.load.pipe(
90-
withEnv({ T3CODE_OTEL_SDK_DISABLED: "maybe", OTEL_SDK_DISABLED: "true" }),
91-
);
92-
assert.isTrue(resolved.disabled);
93-
assert.include(resolved.warnings.join("\n"), "T3CODE_OTEL_SDK_DISABLED=maybe");
94-
}),
95-
);
96-
97-
it.effect("T3CODE_OTEL_SDK_DISABLED=false overrides an ambient OTEL_SDK_DISABLED=true", () =>
98-
Effect.gen(function* () {
99-
const resolved = yield* OtelEnvironment.load.pipe(
100-
withEnv({ T3CODE_OTEL_SDK_DISABLED: "false", OTEL_SDK_DISABLED: "true" }),
101-
);
102-
assert.isFalse(resolved.disabled);
103-
assert.deepStrictEqual(resolved.warnings, []);
104-
}),
105-
);
106-
107-
it.effect("a set but blank value means unset", () =>
108-
Effect.gen(function* () {
109-
const resolved = yield* OtelEnvironment.load.pipe(
110-
withEnv({ T3CODE_OTEL_SDK_DISABLED: " ", OTEL_SDK_DISABLED: "true" }),
111-
);
112-
assert.isTrue(resolved.disabled);
113-
assert.deepStrictEqual(resolved.warnings, [
114-
"OTEL_SDK_DISABLED is set, so no telemetry is exported, whatever configured it; set T3CODE_OTEL_SDK_DISABLED=false to export anyway",
115-
]);
116-
}),
117-
);
118-
119-
it.effect("padding around a value is not part of the value", () =>
120-
Effect.gen(function* () {
121-
// The specification is silent on whitespace, and other SDKs read a
122-
// boolean as trim then compare, so a variable a shell or .env file padded
123-
// still says what the operator wrote. Reading " " as unset and " true "
124-
// as a bad value would also be two different answers to the same
125-
// question.
126-
const padded = yield* OtelEnvironment.load.pipe(withEnv({ OTEL_SDK_DISABLED: " true " }));
127-
assert.isTrue(padded.disabled);
128-
129-
const paddedBad = yield* OtelEnvironment.load.pipe(withEnv({ OTEL_SDK_DISABLED: " yes " }));
130-
assert.isFalse(paddedBad.disabled);
131-
assert.deepStrictEqual(paddedBad.warnings, [
132-
"OTEL_SDK_DISABLED=yes 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",
133-
]);
134-
}),
135-
);
136-
137-
it.effect("names the switch that turned telemetry off", () =>
17+
describe("OtelEnvironment", () => {
18+
it.effect.each([
19+
{ name: "nothing set", env: {}, disabled: false, warnings: [] },
20+
// OTEL_SDK_DISABLED follows the specification: only `true`, case-insensitively.
21+
{ name: "spec true", env: { OTEL_SDK_DISABLED: "true" }, disabled: true, warnings: [SPEC_OFF] },
22+
{ name: "spec True", env: { OTEL_SDK_DISABLED: "True" }, disabled: true, warnings: [SPEC_OFF] },
23+
{
24+
name: "spec padded",
25+
env: { OTEL_SDK_DISABLED: " true " },
26+
disabled: true,
27+
warnings: [SPEC_OFF],
28+
},
29+
{ name: "spec false", env: { OTEL_SDK_DISABLED: "false" }, disabled: false, warnings: [] },
30+
{
31+
name: "spec 1",
32+
env: { OTEL_SDK_DISABLED: "1" },
33+
disabled: false,
34+
warnings: [specIgnored("1")],
35+
},
36+
{
37+
name: "spec padded yes",
38+
env: { OTEL_SDK_DISABLED: " yes " },
39+
disabled: false,
40+
warnings: [specIgnored("yes")],
41+
},
42+
// T3CODE_OTEL_SDK_DISABLED takes Config.Boolean's values, case-insensitively.
43+
{ name: "t3 1", env: { T3CODE_OTEL_SDK_DISABLED: "1" }, disabled: true, warnings: [T3_OFF] },
44+
{
45+
name: "t3 TRUE",
46+
env: { T3CODE_OTEL_SDK_DISABLED: "TRUE" },
47+
disabled: true,
48+
warnings: [T3_OFF],
49+
},
50+
{ name: "t3 n", env: { T3CODE_OTEL_SDK_DISABLED: "n" }, disabled: false, warnings: [] },
51+
{
52+
name: "t3 false overrides spec true",
53+
env: { T3CODE_OTEL_SDK_DISABLED: "false", OTEL_SDK_DISABLED: "true" },
54+
disabled: false,
55+
warnings: [],
56+
},
57+
{
58+
name: "blank t3 falls through",
59+
env: { T3CODE_OTEL_SDK_DISABLED: " ", OTEL_SDK_DISABLED: "true" },
60+
disabled: true,
61+
warnings: [SPEC_OFF],
62+
},
63+
{
64+
name: "unreadable t3 warns and falls through",
65+
env: { T3CODE_OTEL_SDK_DISABLED: "maybe", OTEL_SDK_DISABLED: "true" },
66+
disabled: true,
67+
warnings: ["T3CODE_OTEL_SDK_DISABLED=maybe is not a yes or a no and was ignored", SPEC_OFF],
68+
},
69+
{
70+
name: "bad spec value still warns when t3 answered",
71+
env: { T3CODE_OTEL_SDK_DISABLED: "false", OTEL_SDK_DISABLED: "yes" },
72+
disabled: false,
73+
warnings: [specIgnored("yes")],
74+
},
75+
])("$name", ({ env, disabled, warnings }) =>
13876
Effect.gen(function* () {
139-
const viaT3 = yield* OtelEnvironment.load.pipe(withEnv({ T3CODE_OTEL_SDK_DISABLED: "true" }));
140-
assert.deepStrictEqual(viaT3.warnings, [
141-
"T3CODE_OTEL_SDK_DISABLED is set, so no telemetry is exported, whatever configured it",
142-
]);
143-
144-
const viaSpec = yield* OtelEnvironment.load.pipe(withEnv({ OTEL_SDK_DISABLED: "true" }));
145-
assert.deepStrictEqual(viaSpec.warnings, [
146-
"OTEL_SDK_DISABLED is set, so no telemetry is exported, whatever configured it; set T3CODE_OTEL_SDK_DISABLED=false to export anyway",
147-
]);
77+
const resolved = yield* load(env);
78+
assert.strictEqual(resolved.disabled, disabled);
79+
assert.deepStrictEqual(resolved.warnings, warnings);
14880
}),
14981
);
15082
});

0 commit comments

Comments
 (0)