The best way to control Claude Code, Codex and more from any computer or phone
feat(web): telemetry export settings show where the running endpoint came from (#23713)
Co-authored-by: Julius Marminge <julius0216@outlook.com> Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>
Yordis Prieto committed
Oct 22, 2026 at 19:51 UTC
e78297d89133eb69a375750974c88aa744dae7c7
13 files changed
+408
-46
apps/desktop/src/app/DesktopObservability.ts
+3
-3
@@ -366,19 +366,19 @@ const resolveOtlpEndpoints = Effect.gen(function* () {
366
otel,
367
"traces",
368
{ url: Option.getOrUndefined(environment.otlpTracesUrl), export: signalExport },
369
- persisted.otlpTracesUrl,
369
+ { bootstrapUrl: undefined, settingsUrl: persisted.otlpTracesUrl },
370
),
371
metrics: OtelEnvironment.resolveSignalEndpoint(
372
otel,
373
"metrics",
374
{ url: Option.getOrUndefined(environment.otlpMetricsUrl), export: signalExport },
375
- persisted.otlpMetricsUrl,
375
+ { bootstrapUrl: undefined, settingsUrl: persisted.otlpMetricsUrl },
376
),
377
logs: OtelEnvironment.resolveSignalEndpoint(
378
otel,
379
"logs",
380
{ url: Option.getOrUndefined(environment.otlpLogsUrl), export: signalExport },
381
- persisted.otlpLogsUrl,
381
+ { bootstrapUrl: undefined, settingsUrl: persisted.otlpLogsUrl },
382
),
383
warnings: otel.warnings,
384
resourceAttributes: otel.resourceAttributes,
apps/server/src/cli/config.test.ts
+91
@@ -29,6 +29,21 @@ import { resolveServerConfig } from "./config.ts";
29
const deriveExplicitServerPaths = (baseDir: string, devUrl: URL | undefined) =>
30
deriveServerPaths(baseDir, devUrl, { baseDirIsExplicit: true });
31
32
+const minimalDesktopFlags = (baseDir: string) => ({
33
+ mode: Option.some("desktop" as const),
34
+ port: Option.some(4888),
35
+ host: Option.none<string>(),
36
+ baseDir: Option.some(baseDir),
37
+ cwd: Option.none<string>(),
38
+ devUrl: Option.none<URL>(),
39
+ noBrowser: Option.none<boolean>(),
40
+ bootstrapFd: Option.none<number>(),
41
+ autoBootstrapProjectFromCwd: Option.none<boolean>(),
42
+ logWebSocketEvents: Option.none<boolean>(),
43
+ tailscaleServeEnabled: Option.none<boolean>(),
44
+ tailscaleServePort: Option.none<number>(),
45
+});
46
+
47
const encodeDesktopBootstrap = Schema.encodeEffect(Schema.fromJsonString(DesktopBackendBootstrap));
48
const encodeUnknownJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown));
49
@@ -429,6 +444,77 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
444
}),
445
);
446
447
+ it.effect("reports the desktop bootstrap as the source of endpoints it supplied", () =>
448
+ Effect.gen(function* () {
449
+ const fs = yield* FileSystem.FileSystem;
450
+ const baseDir = yield* fs.makeTempDirectoryScoped({
451
+ prefix: "t3-cli-config-otlp-bootstrap-",
452
+ });
453
+ const fd = yield* openBootstrapFd(
454
+ makeDesktopBootstrap({
455
+ otlpTracesUrl: "http://localhost:4318/v1/traces",
456
+ otlpMetricsUrl: "http://localhost:4318/v1/metrics",
457
+ otlpLogsUrl: "http://localhost:4318/v1/logs",
458
+ }),
459
+ );
460
+
461
+ const resolved = yield* resolveServerConfig(
462
+ { ...minimalDesktopFlags(baseDir), bootstrapFd: Option.some(fd) },
463
+ Option.none(),
464
+ ).pipe(
465
+ Effect.provide(
466
+ Layer.mergeAll(
467
+ ConfigProvider.layer(ConfigProvider.fromEnv({ env: {} })),
468
+ NetService.layer,
469
+ ),
470
+ ),
471
+ );
472
+
473
+ expect(resolved).toMatchObject({
474
+ otlpTracesUrl: "http://localhost:4318/v1/traces",
475
+ otlpTracesSource: "bootstrap",
476
+ otlpMetricsSource: "bootstrap",
477
+ otlpLogsSource: "bootstrap",
478
+ });
479
+ }),
480
+ );
481
+
482
+ it.effect("reports saved settings as the source of endpoints read from settings.json", () =>
483
+ Effect.gen(function* () {
484
+ const fs = yield* FileSystem.FileSystem;
485
+ const path = yield* Path.Path;
486
+ const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-cli-config-otlp-settings-" });
487
+ const derivedPaths = yield* deriveExplicitServerPaths(baseDir, undefined);
488
+ yield* fs.makeDirectory(path.dirname(derivedPaths.settingsPath), { recursive: true });
489
+ yield* fs.writeFileString(
490
+ derivedPaths.settingsPath,
491
+ `${JSON.stringify({
492
+ observability: {
493
+ otlpTracesUrl: "http://localhost:4318/v1/traces",
494
+ otlpMetricsUrl: "http://localhost:4318/v1/metrics",
495
+ otlpLogsUrl: "http://localhost:4318/v1/logs",
496
+ },
497
+ })}\n`,
498
+ );
499
+
500
+ const resolved = yield* resolveServerConfig(minimalDesktopFlags(baseDir), Option.none()).pipe(
501
+ Effect.provide(
502
+ Layer.mergeAll(
503
+ ConfigProvider.layer(ConfigProvider.fromEnv({ env: {} })),
504
+ NetService.layer,
505
+ ),
506
+ ),
507
+ );
508
+
509
+ expect(resolved).toMatchObject({
510
+ otlpTracesUrl: "http://localhost:4318/v1/traces",
511
+ otlpTracesSource: "settings",
512
+ otlpMetricsSource: "settings",
513
+ otlpLogsSource: "settings",
514
+ });
515
+ }),
516
+ );
517
+
518
it.effect("zeroes an endpoint stored in Settings when the SDK is disabled", () =>
519
Effect.gen(function* () {
520
const fs = yield* FileSystem.FileSystem;
@@ -712,6 +798,11 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
798
});
799
expect(resolved.otlpLogsUrl).toBe("http://settings:4318/v1/logs");
800
expect(resolved.otlpLogsExport.headers).toEqual({ "x-key": "secret" });
801
+ expect(resolved).toMatchObject({
802
+ otlpTracesVariable: "T3CODE_OTLP_TRACES_URL",
803
+ otlpMetricsVariable: "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT",
804
+ });
805
+ expect(resolved.otlpLogsVariable).toBeUndefined();
806
}),
807
);
808
apps/server/src/cli/config.ts
+18
-6
@@ -424,22 +424,28 @@ export const resolveServerConfig = Effect.fn("config.resolveServerConfig")(funct
424
otel,
425
"traces",
426
{ url: env.otlpTracesUrl, export: signalExport },
427
- bootstrap?.otlpTracesUrl,
428
- persistedObservabilitySettings.otlpTracesUrl,
427
+ {
428
+ bootstrapUrl: bootstrap?.otlpTracesUrl,
429
+ settingsUrl: persistedObservabilitySettings.otlpTracesUrl,
430
+ },
431
);
432
const metrics = OtelEnvironment.resolveSignalEndpoint(
433
otel,
434
"metrics",
435
{ url: env.otlpMetricsUrl, export: signalExport },
434
- bootstrap?.otlpMetricsUrl,
435
- persistedObservabilitySettings.otlpMetricsUrl,
436
+ {
437
+ bootstrapUrl: bootstrap?.otlpMetricsUrl,
438
+ settingsUrl: persistedObservabilitySettings.otlpMetricsUrl,
439
+ },
440
);
441
const logs = OtelEnvironment.resolveSignalEndpoint(
442
otel,
443
"logs",
444
{ url: env.otlpLogsUrl, export: signalExport },
441
- bootstrap?.otlpLogsUrl,
442
- persistedObservabilitySettings.otlpLogsUrl,
445
+ {
446
+ bootstrapUrl: bootstrap?.otlpLogsUrl,
447
+ settingsUrl: persistedObservabilitySettings.otlpLogsUrl,
448
+ },
449
);
450
451
const config: ServerConfig.ServerConfig["Service"] = {
@@ -455,6 +461,12 @@ export const resolveServerConfig = Effect.fn("config.resolveServerConfig")(funct
461
otlpTracesExport: traces?.export ?? signalExport,
462
otlpMetricsExport: metrics?.export ?? signalExport,
463
otlpLogsExport: logs?.export ?? signalExport,
464
+ ...(traces !== undefined ? { otlpTracesSource: traces.source } : {}),
465
+ ...(traces?.variable !== undefined ? { otlpTracesVariable: traces.variable } : {}),
466
+ ...(metrics !== undefined ? { otlpMetricsSource: metrics.source } : {}),
467
+ ...(metrics?.variable !== undefined ? { otlpMetricsVariable: metrics.variable } : {}),
468
+ ...(logs !== undefined ? { otlpLogsSource: logs.source } : {}),
469
+ ...(logs?.variable !== undefined ? { otlpLogsVariable: logs.variable } : {}),
470
otelEnvironment: otel,
471
mode,
472
port,
apps/server/src/config.ts
+7
@@ -8,6 +8,7 @@ import * as Path from "effect/Path";
8
import type * as Redacted from "effect/Redacted";
9
import * as Schema from "effect/Schema";
10
11
+import type { OtlpEndpointSource } from "@t3tools/contracts";
12
import { sweepStalePendingAttachments } from "./attachmentStore.ts";
13
import { DEFAULT_SIGNAL_EXPORT, type SignalExport } from "@t3tools/shared/observability";
14
import * as OtelEnvironment from "@t3tools/shared/otelEnvironment";
@@ -61,6 +62,12 @@ export class ServerConfig extends Context.Service<
62
readonly otlpTracesExport: SignalExport;
63
readonly otlpMetricsExport: SignalExport;
64
readonly otlpLogsExport: SignalExport;
65
+ readonly otlpTracesSource?: OtlpEndpointSource;
66
+ readonly otlpTracesVariable?: string;
67
+ readonly otlpMetricsSource?: OtlpEndpointSource;
68
+ readonly otlpMetricsVariable?: string;
69
+ readonly otlpLogsSource?: OtlpEndpointSource;
70
+ readonly otlpLogsVariable?: string;
71
readonly otelEnvironment: OtelEnvironment.OtelEnvironment;
72
readonly mode: RuntimeMode;
73
readonly port: number;
apps/server/src/observability/OtlpEndpointCheck.test.ts
+1
@@ -189,6 +189,7 @@ describe("OtlpEndpointCheck", () => {
189
...OtelEnvironment.none,
190
traces: OtelEnvironment.OtelSignal.Export({
191
url: otelUrl,
192
+ variable: "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
193
protocol: otelExport.protocol,
194
headers: otelExport.headers,
195
}),
apps/server/src/ws.ts
+19
-3
@@ -1743,13 +1743,29 @@ export const layerWsRpc = (
1743
observability: {
1744
logsDirectoryPath: config.logsDir,
1745
localTracingEnabled: true,
1746
- ...(config.otlpTracesUrl !== undefined ? { otlpTracesUrl: config.otlpTracesUrl } : {}),
1746
+ ...(config.otlpTracesUrl !== undefined
1747
+ ? {
1748
+ otlpTracesUrl: config.otlpTracesUrl,
1749
+ otlpTracesSource: config.otlpTracesSource,
1750
+ otlpTracesVariable: config.otlpTracesVariable,
1751
+ }
1752
+ : {}),
1753
otlpTracesEnabled: config.otlpTracesUrl !== undefined,
1754
...(config.otlpMetricsUrl !== undefined
1749
- ? { otlpMetricsUrl: config.otlpMetricsUrl }
1755
+ ? {
1756
+ otlpMetricsUrl: config.otlpMetricsUrl,
1757
+ otlpMetricsSource: config.otlpMetricsSource,
1758
+ otlpMetricsVariable: config.otlpMetricsVariable,
1759
+ }
1760
: {}),
1761
otlpMetricsEnabled: config.otlpMetricsUrl !== undefined,
1752
- ...(config.otlpLogsUrl !== undefined ? { otlpLogsUrl: config.otlpLogsUrl } : {}),
1762
+ ...(config.otlpLogsUrl !== undefined
1763
+ ? {
1764
+ otlpLogsUrl: config.otlpLogsUrl,
1765
+ otlpLogsSource: config.otlpLogsSource,
1766
+ otlpLogsVariable: config.otlpLogsVariable,
1767
+ }
1768
+ : {}),
1769
otlpLogsEnabled: config.otlpLogsUrl !== undefined,
1770
},
1771
settings,
apps/web/src/components/settings/TelemetryExportSettings.browser.test.tsx
+64
-5
@@ -1,11 +1,22 @@
1
import { render } from "../../../test/render";
2
-import { DEFAULT_SERVER_SETTINGS } from "@t3tools/contracts";
2
+import { DEFAULT_SERVER_SETTINGS, type ServerObservability } from "@t3tools/contracts";
3
import { describe, expect, it, vi } from "vite-plus/test";
4
import { userEvent } from "vite-plus/test/browser";
5
6
-const { state, updateSettings } = vi.hoisted(() => ({
7
- state: { observability: {} as typeof DEFAULT_SERVER_SETTINGS.observability },
6
+const { state, updateSettings, checkOtlpEndpoint, checkOtlpEndpointCommand } = vi.hoisted(() => ({
7
+ state: {
8
+ observability: {} as typeof DEFAULT_SERVER_SETTINGS.observability,
9
+ serverConfig: { environment: { capabilities: {} } } as {
10
+ environment: { capabilities: { otlpEndpointCheck?: boolean } };
11
+ observability?: ServerObservability;
12
+ },
13
+ },
14
updateSettings: vi.fn(async () => ({ _tag: "Success" as const, value: undefined })),
15
+ checkOtlpEndpoint: vi.fn(async (_request: unknown) => ({
16
+ _tag: "Success" as const,
17
+ value: { _tag: "Accepted" as const, latencyMs: 12 },
18
+ })),
19
+ checkOtlpEndpointCommand: { permissionAtom: () => null },
20
}));
21
22
vi.mock(import("@effect/atom-react"), async (original) => ({
@@ -15,7 +26,11 @@ vi.mock(import("@effect/atom-react"), async (original) => ({
26
vi.mock(import("../../state/use-atom-command"), async (original) => ({
27
...(await original()),
28
useAtomCommand: ((command: unknown) =>
18
- command === "updateSettings" ? updateSettings : vi.fn()) as never,
29
+ command === "updateSettings"
30
+ ? updateSettings
31
+ : command === checkOtlpEndpointCommand
32
+ ? checkOtlpEndpoint
33
+ : vi.fn()) as never,
34
}));
35
vi.mock(import("../../state/server"), async (original) => {
36
const actual = await original();
@@ -24,6 +39,7 @@ vi.mock(import("../../state/server"), async (original) => {
39
serverEnvironment: {
40
...actual.serverEnvironment,
41
updateSettings: "updateSettings",
42
+ checkOtlpEndpoint: checkOtlpEndpointCommand,
43
} as unknown as typeof actual.serverEnvironment,
44
};
45
});
@@ -34,7 +50,7 @@ vi.mock(import("./SettingsScopeContext"), async (original) => ({
50
environment: {
51
environmentId: "env",
52
label: "MAC1",
37
- serverConfig: { environment: { capabilities: {} } },
53
+ serverConfig: state.serverConfig,
54
},
55
})) as never,
56
}));
@@ -47,6 +63,8 @@ import { TelemetryExportSettings } from "./TelemetryExportSettings";
63
64
function setup() {
65
updateSettings.mockClear();
66
+ checkOtlpEndpoint.mockClear();
67
+ state.serverConfig = { environment: { capabilities: {} } };
68
}
69
70
describe("TelemetryExportSettings", () => {
@@ -80,4 +98,45 @@ describe("TelemetryExportSettings", () => {
98
});
99
expect(container.textContent).toContain("Saved. Restart the server to apply.");
100
});
101
+
102
+ it("reports and tests the endpoint the environment set over an empty setting", async () => {
103
+ setup();
104
+ state.observability = { ...DEFAULT_SERVER_SETTINGS.observability, otlpTracesUrl: "" };
105
+ state.serverConfig = {
106
+ environment: { capabilities: { otlpEndpointCheck: true } },
107
+ observability: {
108
+ logsDirectoryPath: "/tmp/logs",
109
+ localTracingEnabled: true,
110
+ otlpTracesUrl: "http://collector/v1/traces",
111
+ otlpTracesSource: "environment",
112
+ otlpTracesVariable: "OTEL_EXPORTER_OTLP_ENDPOINT",
113
+ otlpTracesEnabled: true,
114
+ otlpMetricsEnabled: false,
115
+ otlpLogsEnabled: false,
116
+ },
117
+ };
118
+ await using screen = await render(<TelemetryExportSettings />);
119
+
120
+ await expect
121
+ .element(screen.getByText("Set by environment · Connected · 12 ms"))
122
+ .toBeInTheDocument();
123
+ await expect
124
+ .element(
125
+ screen.getByText("Running: http://collector/v1/traces from OTEL_EXPORTER_OTLP_ENDPOINT"),
126
+ )
127
+ .toBeInTheDocument();
128
+ expect(checkOtlpEndpoint).toHaveBeenCalledExactlyOnceWith({
129
+ environmentId: "env",
130
+ input: { signal: "traces", url: "http://collector/v1/traces" },
131
+ });
132
+ expect(screen.container.querySelector<HTMLInputElement>("#otlpTracesUrl")!.value).toBe("");
133
+
134
+ await userEvent.click(screen.getByRole("button", { name: "Test" }).first());
135
+
136
+ expect(checkOtlpEndpoint).toHaveBeenCalledTimes(2);
137
+ expect(checkOtlpEndpoint).toHaveBeenLastCalledWith({
138
+ environmentId: "env",
139
+ input: { signal: "traces", url: "http://collector/v1/traces" },
140
+ });
141
+ });
142
});
apps/web/src/components/settings/TelemetryExportSettings.tsx
+62
-15
@@ -1,5 +1,5 @@
1
import { useAtomValue } from "@effect/atom-react";
2
-import type { OtlpEndpointCheckResult, OtlpSignal } from "@t3tools/contracts";
2
+import type { OtlpEndpointCheckResult, OtlpSignal, ServerObservability } from "@t3tools/contracts";
3
import { useEffect, useEffectEvent, useState } from "react";
4
5
import { serverEnvironment } from "../../state/server";
@@ -14,12 +14,43 @@ import { SettingsSection } from "./settingsLayout";
14
import { SettingsScopeNotice } from "./SettingsScopeNotice";
15
16
const SIGNALS = [
17
- { key: "otlpTracesUrl", label: "Traces", signal: "traces" },
18
- { key: "otlpMetricsUrl", label: "Metrics", signal: "metrics" },
19
- { key: "otlpLogsUrl", label: "Logs", signal: "logs" },
17
+ {
18
+ key: "otlpTracesUrl",
19
+ sourceKey: "otlpTracesSource",
20
+ variableKey: "otlpTracesVariable",
21
+ label: "Traces",
22
+ signal: "traces",
23
+ },
24
+ {
25
+ key: "otlpMetricsUrl",
26
+ sourceKey: "otlpMetricsSource",
27
+ variableKey: "otlpMetricsVariable",
28
+ label: "Metrics",
29
+ signal: "metrics",
30
+ },
31
+ {
32
+ key: "otlpLogsUrl",
33
+ sourceKey: "otlpLogsSource",
34
+ variableKey: "otlpLogsVariable",
35
+ label: "Logs",
36
+ signal: "logs",
37
+ },
38
] as const;
39
22
-type SignalKey = (typeof SIGNALS)[number]["key"];
40
+type SignalDescriptor = (typeof SIGNALS)[number];
41
+type SignalKey = SignalDescriptor["key"];
42
+
43
+const OVERRIDE_LABELS = { environment: "Set by environment", bootstrap: "Set by desktop" } as const;
44
+
45
+function runningOverride(
46
+ running: ServerObservability | undefined,
47
+ { key, sourceKey, variableKey }: SignalDescriptor,
48
+) {
49
+ const url = running?.[key];
50
+ const source = running?.[sourceKey];
51
+ if (url === undefined || (source !== "environment" && source !== "bootstrap")) return undefined;
52
+ return { url, label: OVERRIDE_LABELS[source], variable: running?.[variableKey] };
53
+}
54
55
type EndpointCheck = { readonly url: string; readonly result: OtlpEndpointCheckResult | null };
56
@@ -66,12 +97,13 @@ function TelemetryExportForm() {
97
);
98
const canCheck =
99
canEdit && environment?.serverConfig?.environment.capabilities.otlpEndpointCheck === true;
100
+ const running = environment?.serverConfig?.observability;
101
const [checks, setChecks] = useState<Partial<Record<SignalKey, EndpointCheck>>>(() =>
102
Object.fromEntries(
71
- SIGNALS.filter(({ key }) => isHttpUrl(saved[key])).map(({ key }) => [
72
- key,
73
- { url: saved[key], result: null },
74
- ]),
103
+ SIGNALS.flatMap((descriptor) => {
104
+ const url = runningOverride(running, descriptor)?.url ?? saved[descriptor.key];
105
+ return isHttpUrl(url) ? [[descriptor.key, { url, result: null }]] : [];
106
+ }),
107
),
108
);
109
const updateSettings = useAtomCommand(serverEnvironment.updateSettings, { reportFailure: true });
@@ -79,7 +111,6 @@ function TelemetryExportForm() {
111
const values = { ...saved, ...draft };
112
const changedSignals = SIGNALS.filter(({ key }) => values[key].trim() !== saved[key]);
113
const changed = changedSignals.length > 0;
82
- const running = environment?.serverConfig?.observability;
114
115
const sendCheck = async (key: SignalKey, signal: OtlpSignal, url: string) => {
116
if (!environmentId) return;
@@ -146,9 +177,17 @@ function TelemetryExportForm() {
177
{environment?.label ?? "the selected environment"}.
178
</p>
179
)}
149
- {SIGNALS.map(({ key, label, signal }) => {
150
- const url = values[key].trim();
151
- const status = canCheck ? endpointStatus(url, checks[key]) : null;
180
+ {SIGNALS.map((descriptor) => {
181
+ const { key, label, signal } = descriptor;
182
+ const override = runningOverride(running, descriptor);
183
+ const url = override?.url ?? values[key].trim();
184
+ const check = canCheck ? endpointStatus(url, checks[key]) : null;
185
+ const status = override
186
+ ? {
187
+ label: check ? `${override.label} · ${check.label}` : override.label,
188
+ dot: check?.dot ?? "bg-muted-foreground/40",
189
+ }
190
+ : check;
191
return (
192
<div key={key} className="grid gap-1.5">
193
<div className="flex items-center justify-between gap-3">
@@ -192,9 +231,15 @@ function TelemetryExportForm() {
231
</Button>
232
)}
233
</div>
195
- {saved[key] !== (running?.[key] ?? "") && (
234
+ {(saved[key] !== (running?.[key] ?? "") || override?.variable) && (
235
<p className="break-all text-xs text-muted-foreground">
236
Running: {running?.[key] || "Disabled"}
237
+ {override?.variable && (
238
+ <>
239
+ {" "}
240
+ from <code className="font-mono">{override.variable}</code>
241
+ </>
242
+ )}
243
</p>
244
)}
245
</div>
@@ -214,7 +259,9 @@ function TelemetryExportForm() {
259
setDraft({});
260
setMessage(null);
261
if (!canCheck) return;
217
- for (const { key, signal } of SIGNALS) {
262
+ for (const descriptor of SIGNALS) {
263
+ const { key, signal } = descriptor;
264
+ if (runningOverride(running, descriptor)) continue;
265
if (checks[key]?.url !== saved[key]) checkEndpoint(key, signal, saved[key]);
266
}
267
}}
docs/user/telemetry.md
+2
-1
@@ -33,7 +33,8 @@ the signal's currently running endpoint and do not follow redirects. To check a
33
that requires authentication, save it and restart the server first.
34
35
`T3CODE_OTLP_*_URL` and standard `OTEL_EXPORTER_OTLP_*` environment variables override the saved
36
-settings. For endpoints saved here or set with `T3CODE_OTLP_*_URL`, set `T3CODE_OTLP_HEADERS` for
36
+settings. An overridden signal shows **Set by environment** and names the variable that set it, and its
37
+**Test** checks the running endpoint instead of the field. For endpoints saved here or set with `T3CODE_OTLP_*_URL`, set `T3CODE_OTLP_HEADERS` for
38
receivers that need authentication and `T3CODE_OTLP_PROTOCOL=http/protobuf` for receivers that do
39
not accept JSON. An endpoint set with `OTEL_EXPORTER_OTLP_*` takes its headers and protocol from
40
`OTEL_EXPORTER_OTLP_HEADERS` and `OTEL_EXPORTER_OTLP_PROTOCOL` instead.
packages/contracts/src/server.test.ts
+38
@@ -5,6 +5,7 @@ import { ExecutionEnvironmentDescriptor } from "./environment.ts";
5
import {
6
OtlpEndpointCheckInput,
7
resolveEnvironmentMachineKind,
8
+ ServerObservability,
9
ServerProvider,
10
ServerProviders,
11
} from "./server.ts";
@@ -71,6 +72,43 @@ describe("server config forward compatibility", () => {
72
});
73
});
74
75
+describe("ServerObservability", () => {
76
+ const decodeServerObservability = Schema.decodeUnknownSync(ServerObservability);
77
+
78
+ it("reads where each running endpoint came from", () => {
79
+ const parsed = decodeServerObservability({
80
+ logsDirectoryPath: "/tmp/t3/logs",
81
+ localTracingEnabled: true,
82
+ otlpTracesUrl: "https://collector.example.com/v1/traces",
83
+ otlpTracesSource: "environment",
84
+ otlpTracesVariable: "OTEL_EXPORTER_OTLP_ENDPOINT",
85
+ otlpTracesEnabled: true,
86
+ otlpMetricsUrl: "https://collector.example.com/v1/metrics",
87
+ otlpMetricsSource: "settings",
88
+ otlpMetricsEnabled: true,
89
+ otlpLogsEnabled: false,
90
+ });
91
+
92
+ expect(parsed.otlpTracesSource).toBe("environment");
93
+ expect(parsed.otlpTracesVariable).toBe("OTEL_EXPORTER_OTLP_ENDPOINT");
94
+ expect(parsed.otlpMetricsSource).toBe("settings");
95
+ expect(parsed.otlpLogsSource).toBeUndefined();
96
+ });
97
+
98
+ it("rejects an unknown endpoint source", () => {
99
+ expect(() =>
100
+ decodeServerObservability({
101
+ logsDirectoryPath: "/tmp/t3/logs",
102
+ localTracingEnabled: true,
103
+ otlpTracesUrl: "https://collector.example.com/v1/traces",
104
+ otlpTracesSource: "cli",
105
+ otlpTracesEnabled: true,
106
+ otlpMetricsEnabled: false,
107
+ }),
108
+ ).toThrow();
109
+ });
110
+});
111
+
112
describe("resolveEnvironmentMachineKind", () => {
113
const decodeDescriptor = Schema.decodeUnknownSync(ExecutionEnvironmentDescriptor);
114
const decodeSettings = Schema.decodeUnknownSync(ServerSettings);
packages/contracts/src/server.ts
+9
@@ -295,14 +295,23 @@ export const isProviderAvailable = (snapshot: ServerProvider): boolean =>
295
export const isProviderTextGenerationCapable = (snapshot: ServerProvider): boolean =>
296
snapshot.supportsTextGeneration !== false;
297
298
+export const OtlpEndpointSource = Schema.Literals(["environment", "bootstrap", "settings"]);
299
+export type OtlpEndpointSource = typeof OtlpEndpointSource.Type;
300
+
301
export const ServerObservability = Schema.Struct({
302
logsDirectoryPath: TrimmedNonEmptyString,
303
localTracingEnabled: Schema.Boolean,
304
otlpTracesUrl: Schema.optional(TrimmedNonEmptyString),
305
+ otlpTracesSource: Schema.optional(OtlpEndpointSource),
306
+ otlpTracesVariable: Schema.optional(TrimmedNonEmptyString),
307
otlpTracesEnabled: Schema.Boolean,
308
otlpMetricsUrl: Schema.optional(TrimmedNonEmptyString),
309
+ otlpMetricsSource: Schema.optional(OtlpEndpointSource),
310
+ otlpMetricsVariable: Schema.optional(TrimmedNonEmptyString),
311
otlpMetricsEnabled: Schema.Boolean,
312
otlpLogsUrl: Schema.optional(TrimmedNonEmptyString),
313
+ otlpLogsSource: Schema.optional(OtlpEndpointSource),
314
+ otlpLogsVariable: Schema.optional(TrimmedNonEmptyString),
315
otlpLogsEnabled: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
316
});
317
export type ServerObservability = typeof ServerObservability.Type;
packages/shared/src/otelEnvironment.test.ts
+70
-7
@@ -220,6 +220,24 @@ describe("OtelEnvironment", () => {
220
);
221
});
222
223
+ it.effect("names the variable each signal's endpoint came from", () =>
224
+ Effect.gen(function* () {
225
+ const otel = yield* load({
226
+ OTEL_EXPORTER_OTLP_ENDPOINT: "https://collector:4318",
227
+ OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "https://tempo:4318/v1/traces",
228
+ });
229
+ const variableOf = (signal: OtelEnvironment.OtelSignal) =>
230
+ OtelEnvironment.OtelSignal.$match(signal, {
231
+ Export: ({ variable }) => variable,
232
+ Off: () => undefined,
233
+ Unset: () => undefined,
234
+ });
235
+ assert.strictEqual(variableOf(otel.traces), "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT");
236
+ assert.strictEqual(variableOf(otel.metrics), "OTEL_EXPORTER_OTLP_ENDPOINT");
237
+ assert.strictEqual(variableOf(otel.logs), "OTEL_EXPORTER_OTLP_ENDPOINT");
238
+ }),
239
+ );
240
+
241
describe("resolveSignalEndpoint", () => {
242
const t3Export = {
243
protocol: "http/json",
@@ -233,6 +251,7 @@ describe("OtelEnvironment", () => {
251
});
252
const otelExport = OtelEnvironment.OtelSignal.Export({
253
url: "http://otel:4318/v1/logs",
254
+ variable: "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT",
255
protocol: "http/protobuf",
256
headers: { "x-key": "otel" },
257
});
@@ -241,7 +260,12 @@ describe("OtelEnvironment", () => {
260
name: "T3CODE_OTLP_*_URL wins over a signal the OTEL variables turned off",
261
otel: withLogs(OtelEnvironment.OtelSignal.Off()),
262
t3Url: "http://t3:4318/v1/logs",
244
- expected: { url: "http://t3:4318/v1/logs", export: t3Export },
263
+ expected: {
264
+ url: "http://t3:4318/v1/logs",
265
+ export: t3Export,
266
+ source: "environment" as const,
267
+ variable: "T3CODE_OTLP_LOGS_URL",
268
+ },
269
},
270
{
271
name: "an OTEL endpoint brings its headers and protocol over the fallback",
@@ -254,6 +278,8 @@ describe("OtelEnvironment", () => {
278
headers: { "x-key": "otel" },
279
exportIntervalMs: 5_000,
280
},
281
+ source: "environment" as const,
282
+ variable: "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT",
283
},
284
},
285
{
@@ -262,14 +288,45 @@ describe("OtelEnvironment", () => {
288
t3Url: undefined,
289
expected: undefined,
290
},
265
- ])("$name", ({ otel, t3Url, expected }) => {
291
+ {
292
+ name: "an unset signal takes the first non-blank fallback",
293
+ otel: withLogs(OtelEnvironment.OtelSignal.Unset()),
294
+ t3Url: undefined,
295
+ expected: {
296
+ url: "http://settings:4318/v1/logs",
297
+ export: t3Export,
298
+ source: "settings" as const,
299
+ },
300
+ },
301
+ {
302
+ name: "a desktop bootstrap URL that differs from the setting wins as the desktop's own",
303
+ otel: withLogs(OtelEnvironment.OtelSignal.Unset()),
304
+ t3Url: undefined,
305
+ bootstrapUrl: "http://desktop:4318/v1/logs",
306
+ expected: {
307
+ url: "http://desktop:4318/v1/logs",
308
+ export: t3Export,
309
+ source: "bootstrap" as const,
310
+ },
311
+ },
312
+ {
313
+ name: "a desktop bootstrap URL that forwards the setting counts as the setting",
314
+ otel: withLogs(OtelEnvironment.OtelSignal.Unset()),
315
+ t3Url: undefined,
316
+ bootstrapUrl: " http://settings:4318/v1/logs ",
317
+ expected: {
318
+ url: "http://settings:4318/v1/logs",
319
+ export: t3Export,
320
+ source: "settings" as const,
321
+ },
322
+ },
323
+ ])("$name", ({ otel, t3Url, bootstrapUrl = "", expected }) => {
324
assert.deepStrictEqual(
325
OtelEnvironment.resolveSignalEndpoint(
326
otel,
327
"logs",
328
{ url: t3Url, export: t3Export },
271
- "",
272
- "http://settings:4318/v1/logs",
329
+ { bootstrapUrl, settingsUrl: "http://settings:4318/v1/logs" },
330
),
331
expected,
332
);
@@ -284,12 +341,17 @@ describe("OtelEnvironment", () => {
341
export: { protocol: "http/json", headers: undefined, exportIntervalMs: 10_000 },
342
} as const;
343
assert.strictEqual(
287
- OtelEnvironment.resolveSignalEndpoint(otel, "logs", t3, "http://settings:4318/v1/logs"),
344
+ OtelEnvironment.resolveSignalEndpoint(otel, "logs", t3, {
345
+ bootstrapUrl: undefined,
346
+ settingsUrl: "http://settings:4318/v1/logs",
347
+ }),
348
undefined,
349
);
350
assert.strictEqual(
291
- OtelEnvironment.resolveSignalEndpoint(otel, "traces", t3, "http://settings:4318/v1/traces")
292
- ?.url,
351
+ OtelEnvironment.resolveSignalEndpoint(otel, "traces", t3, {
352
+ bootstrapUrl: undefined,
353
+ settingsUrl: "http://settings:4318/v1/traces",
354
+ })?.url,
355
"http://settings:4318/v1/traces",
356
);
357
}),
@@ -358,6 +420,7 @@ describe("isRelayTracingEnabled", () => {
420
otel.traces,
421
OtelEnvironment.OtelSignal.Export({
422
url: env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
423
+ variable: "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
424
protocol: "http/protobuf",
425
headers: undefined,
426
}),
packages/shared/src/otelEnvironment.ts
+24
-6
@@ -6,6 +6,8 @@ import * as Option from "effect/Option";
6
import * as Schema from "effect/Schema";
7
import * as SchemaTransformation from "effect/SchemaTransformation";
8
9
+import type { OtlpEndpointSource } from "@t3tools/contracts";
10
+
11
import { OtlpHeadersFromString, OtlpProtocol, type SignalExport } from "./observability.ts";
12
13
type OtlpSignalName = "TRACES" | "METRICS" | "LOGS";
@@ -15,6 +17,7 @@ export type OtelSignal = Data.TaggedEnum<{
17
Off: {};
18
Export: {
19
readonly url: string;
20
+ readonly variable: string;
21
readonly protocol: OtlpProtocol;
22
readonly headers: Readonly<Record<string, string>> | undefined;
23
};
@@ -239,6 +242,7 @@ const endpointSignal = (name: OtlpSignalName, own: Settings, generic: Settings):
242
return {
243
signal: OtelSignal.Export({
244
url: url.toString(),
245
+ variable: ownEndpoint ? `OTEL_EXPORTER_OTLP_${name}_ENDPOINT` : "OTEL_EXPORTER_OTLP_ENDPOINT",
246
protocol: protocol.value ?? "http/protobuf",
247
headers: headers.value,
248
}),
@@ -333,30 +337,44 @@ export type SignalName = "traces" | "metrics" | "logs";
337
export interface SignalEndpoint {
338
readonly url: string;
339
readonly export: SignalExport;
340
+ readonly source: OtlpEndpointSource;
341
+ /** The environment variable that set the endpoint, when `source` is `environment`. */
342
+ readonly variable?: string;
343
}
344
345
export const resolveSignalEndpoint = (
346
otel: OtelEnvironment,
347
signal: SignalName,
348
t3: { readonly url: string | undefined; readonly export: SignalExport },
342
- ...fallbackUrls: ReadonlyArray<string | undefined>
349
+ fallback: { readonly bootstrapUrl: string | undefined; readonly settingsUrl: string | undefined },
350
): SignalEndpoint | undefined => {
351
if (otel.disabled) {
352
return undefined;
353
}
354
const t3Url = blankAsUnset(t3.url);
355
if (t3Url !== undefined) {
349
- return { url: t3Url, export: t3.export };
356
+ return {
357
+ url: t3Url,
358
+ export: t3.export,
359
+ source: "environment",
360
+ variable: `T3CODE_OTLP_${signal.toUpperCase()}_URL`,
361
+ };
362
}
363
return OtelSignal.$match(otel[signal], {
352
- Export: ({ url, protocol, headers }): SignalEndpoint => ({
364
+ Export: ({ url, variable, protocol, headers }): SignalEndpoint => ({
365
url,
366
export: { protocol, headers, exportIntervalMs: t3.export.exportIntervalMs },
367
+ source: "environment",
368
+ variable,
369
}),
370
Off: () => undefined,
357
- Unset: () => {
358
- const url = fallbackUrls.map(blankAsUnset).find((candidate) => candidate !== undefined);
359
- return url === undefined ? undefined : { url, export: t3.export };
371
+ Unset: (): SignalEndpoint | undefined => {
372
+ const settingsUrl = blankAsUnset(fallback.settingsUrl);
373
+ // The desktop forwards the saved setting as its bootstrap URL, so only a differing one is
374
+ // the desktop's own.
375
+ const url = blankAsUnset(fallback.bootstrapUrl) ?? settingsUrl;
376
+ if (url === undefined) return undefined;
377
+ return { url, export: t3.export, source: url === settingsUrl ? "settings" : "bootstrap" };
378
},
379
});
380
};