@devries-cameron20 / t3code Mirror · read-only / commits / e78297d891
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 22, 19:30 UTC

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