Skip to content

Commit 2294cb9

Browse files
committed
fix(observability): resource attributes follow OTel semantic conventions
Dashboards and backends key off semantic convention names such as process.runtime.* and deployment.environment.name, so the custom service.runtime attribute left T3 Code services unrecognized. Signed-off-by: Yordis Prieto <[email protected]>
1 parent 807319c commit 2294cb9

12 files changed

Lines changed: 191 additions & 19 deletions

File tree

‎apps/desktop/src/app/DesktopObservability.test.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -312,4 +312,36 @@ describe("DesktopObservability", () => {
312312
),
313313
);
314314
});
315+
316+
it.effect("exports the process resource under the semantic convention keys", () => {
317+
const requests: Array<ExportedRequest> = [];
318+
return Effect.gen(function* () {
319+
const fileSystem = yield* FileSystem.FileSystem;
320+
const baseDir = yield* fileSystem.makeTempDirectoryScoped({
321+
prefix: "t3-desktop-observability-test-",
322+
});
323+
const layerEnvironment = layerEnvironmentFor(baseDir);
324+
yield* writeObservabilitySettings(layerEnvironment, {
325+
otlpLogsUrl: "https://settings.example.com/v1/logs",
326+
});
327+
328+
yield* Effect.scoped(
329+
Effect.logInfo("desktop resource under test").pipe(
330+
Effect.provide(DesktopObservability.layer.pipe(Layer.provideMerge(layerEnvironment))),
331+
),
332+
);
333+
334+
const body = requests.map((request) => request.body).join("\n");
335+
assert.include(
336+
body,
337+
'"key":"deployment.environment.name","value":{"stringValue":"development"}',
338+
);
339+
assert.include(body, '"key":"process.runtime.name","value":{"stringValue":"nodejs"}');
340+
assert.notInclude(body, "service.runtime");
341+
assert.notInclude(body, "service.mode");
342+
}).pipe(
343+
Effect.scoped,
344+
Effect.provide(Layer.mergeAll(NodeServices.layer, layerCollector(requests), layerEmptyEnv)),
345+
);
346+
});
315347
});

‎apps/desktop/src/app/DesktopObservability.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import { PRIMARY_LOCAL_ENVIRONMENT_ID } from "@t3tools/contracts";
22
import {
33
makeLocalFileTracer,
44
makeTraceSink,
5+
nodeProcessResourceAttributes,
56
type SignalExport,
67
} from "@t3tools/shared/observability";
78
import * as HostProcess from "@t3tools/shared/HostProcess";
@@ -600,9 +601,11 @@ const layerTelemetry = Layer.unwrap(
600601
serviceVersion: environment.appVersion,
601602
attributes: {
602603
"service.namespace": "t3code",
603-
"service.runtime": "desktop",
604-
"service.mode": environment.isDevelopment ? "development" : "packaged",
605604
"host.name": endpoints.resourceAttributes["host.name"] || (yield* HostProcess.Hostname),
605+
...nodeProcessResourceAttributes({
606+
operatorAttributes: endpoints.resourceAttributes,
607+
isDevelopment: environment.isDevelopment,
608+
}),
606609
},
607610
};
608611

‎apps/mobile/src/features/observability/tracing.test.ts‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,3 +59,37 @@ it.effect("does not let OTLP serialization failures alter application effects",
5959
),
6060
);
6161
});
62+
63+
it.effect("exports the mobile client under the semantic convention resource keys", () => {
64+
const fetchFn = vi.fn<typeof fetch>(async () => new Response(null, { status: 202 }));
65+
const layerTracing = Tracing.layerFromConfig(
66+
{
67+
tracesUrl: "https://api.axiom.test/v1/traces",
68+
tracesDataset: "mobile-traces",
69+
tracesToken: "public-ingest-token",
70+
},
71+
{
72+
appVariant: "test",
73+
serviceVersion: "1.2.3",
74+
},
75+
).pipe(Layer.provide(layerRemoteHttpClient(fetchFn)));
76+
const layerTracedApplication = Layer.effectDiscard(
77+
Effect.void.pipe(Effect.withSpan("mobile.test.span"), withRelayClientTracing),
78+
).pipe(Layer.provide(layerTracing));
79+
80+
return Layer.build(layerTracedApplication).pipe(
81+
Effect.scoped,
82+
Effect.andThen(
83+
Effect.sync(() => {
84+
const body = new TextDecoder().decode(fetchFn.mock.calls[0]?.[1]?.body as Uint8Array);
85+
expect(body).toContain(
86+
'"key":"process.runtime.name","value":{"stringValue":"react-native"}',
87+
);
88+
expect(body).toContain(
89+
'"key":"deployment.environment.name","value":{"stringValue":"test"}',
90+
);
91+
expect(body).not.toContain("service.runtime");
92+
}),
93+
),
94+
);
95+
});

‎apps/mobile/src/features/observability/tracing.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,13 @@ export function layerFromConfig(config: TracingConfig | null, resource: TracingR
2727
return RelayTracing.layer(config, {
2828
serviceName: "t3code-mobile",
2929
serviceVersion: resource.serviceVersion,
30-
runtime: "react-native",
31-
client: `mobile-${resource.appVariant}`,
30+
client: "mobile",
31+
attributes: {
32+
"process.runtime.name": "react-native",
33+
...(resource.appVariant !== "unknown" && {
34+
"deployment.environment.name": resource.appVariant,
35+
}),
36+
},
3237
});
3338
}
3439

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { nodeProcessRuntimeAttributes } from "@t3tools/shared/observability";
12
import * as RelayTracing from "@t3tools/shared/relayTracing";
23

34
import { resolveRelayClientTracingConfig } from "./publicConfig.ts";
@@ -6,13 +7,13 @@ const relayClientTracingConfig = resolveRelayClientTracingConfig();
67

78
export const layerHeadlessRelayClient = RelayTracing.layer(relayClientTracingConfig, {
89
serviceName: "t3code-server",
9-
runtime: "node",
10+
attributes: nodeProcessRuntimeAttributes(),
1011
client: "headless-cli",
1112
});
1213

1314
export const layerServerRelayBroker = RelayTracing.layer(relayClientTracingConfig, {
1415
serviceName: "t3code-server",
15-
runtime: "node",
16+
attributes: nodeProcessRuntimeAttributes(),
1617
client: "environment-server",
1718
component: "relay-broker",
1819
});

‎apps/server/src/config.ts‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,11 @@ import * as Schema from "effect/Schema";
1010

1111
import type { OtlpEndpointSource } from "@t3tools/contracts";
1212
import { sweepStalePendingAttachments } from "./attachmentStore.ts";
13-
import { DEFAULT_SIGNAL_EXPORT, type SignalExport } from "@t3tools/shared/observability";
13+
import {
14+
DEFAULT_SIGNAL_EXPORT,
15+
nodeProcessResourceAttributes,
16+
type SignalExport,
17+
} from "@t3tools/shared/observability";
1418
import * as OtelEnvironment from "@t3tools/shared/otelEnvironment";
1519
import packageJson from "../package.json" with { type: "json" };
1620

@@ -103,16 +107,19 @@ export class ServerConfig extends Context.Service<
103107
export const make = (config: ServerConfig["Service"]) => ServerConfig.of(config);
104108

105109
export const otlpResource = (
106-
config: Pick<ServerConfig["Service"], "mode" | "otelEnvironment">,
110+
config: Pick<ServerConfig["Service"], "mode" | "devUrl" | "otelEnvironment">,
107111
hostName: string,
108112
) => ({
109113
serviceName: "t3code-server",
110114
serviceVersion: packageJson.version,
111115
attributes: {
112116
"service.namespace": "t3code",
113-
"service.runtime": "t3-server",
114117
"service.mode": config.mode,
115118
"host.name": config.otelEnvironment.resourceAttributes["host.name"] || hostName,
119+
...nodeProcessResourceAttributes({
120+
operatorAttributes: config.otelEnvironment.resourceAttributes,
121+
isDevelopment: config.devUrl !== undefined,
122+
}),
116123
},
117124
});
118125

‎apps/web/src/lib/runtime.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ const layerHttpClient = layerRemoteHttpClient((input, init) => globalThis.fetch(
2121
const layerRelayTracing = RelayTracing.layer(resolveRelayTracingConfig(), {
2222
serviceName: "t3code-web",
2323
serviceVersion: import.meta.env.APP_VERSION,
24-
runtime: "browser",
24+
attributes: { "process.runtime.name": "browser" },
2525
client: typeof window !== "undefined" && window.desktopBridge ? "desktop" : "web",
2626
}).pipe(Layer.provide(layerHttpClient));
2727

‎apps/web/src/observability/clientTracing.ts‎

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,44 @@ import { isElectron } from "../env";
1414
import { APP_VERSION } from "~/branding";
1515

1616
const DEFAULT_EXPORT_INTERVAL_MS = 1_000;
17+
interface NavigatorUserAgentData {
18+
readonly platform: string;
19+
readonly mobile: boolean;
20+
readonly brands: ReadonlyArray<{ readonly brand: string; readonly version: string }>;
21+
}
22+
23+
/**
24+
* The same `browser.*` and `user_agent.original` attributes the OpenTelemetry
25+
* browser resource detector reports, plus the `process.runtime.*` values the
26+
* semantic conventions give a web browser. `userAgentData` exists only in
27+
* Chromium, which includes the desktop app.
28+
*/
29+
const browserResourceAttributes = (): Record<string, unknown> => {
30+
if (typeof navigator === "undefined") return {};
31+
const userAgentData = (navigator as Navigator & { userAgentData?: NavigatorUserAgentData })
32+
.userAgentData;
33+
return {
34+
"user_agent.original": navigator.userAgent,
35+
"process.runtime.name": "browser",
36+
"process.runtime.version": navigator.userAgent,
37+
"browser.language": navigator.language,
38+
...(userAgentData && {
39+
"browser.platform": userAgentData.platform,
40+
"browser.mobile": userAgentData.mobile,
41+
"browser.brands": userAgentData.brands.map(({ brand, version }) => `${brand} ${version}`),
42+
}),
43+
};
44+
};
45+
1746
const CLIENT_TRACING_RESOURCE = {
1847
serviceName: "t3code-web",
48+
serviceVersion: APP_VERSION,
1949
attributes: {
2050
"service.namespace": "t3code",
21-
"service.runtime": "t3-web",
2251
"service.mode": isElectron ? "electron" : "browser",
23-
"service.version": APP_VERSION,
52+
...browserResourceAttributes(),
2453
},
25-
} as const;
54+
};
2655

2756
const layerDelegateRuntime = Layer.mergeAll(
2857
PrimaryEnvironmentHttpLayer.layer,

‎docs/operations/observability.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -622,10 +622,14 @@ an `http` or `https` URL, a protocol other than `http/protobuf` or `http/json` s
622622
headers that are not `key=value` pairs with percent-encoded values turn that signal's export off
623623
with a startup warning, rather than sending it to the Settings endpoint.
624624

625-
Service names are fixed: `t3code-server` for the backend and `t3code-desktop` for the desktop main
626-
process, both in `service.namespace` `t3code`. `OTEL_SERVICE_NAME` and a `service.name` or
627-
`service.namespace` in `OTEL_RESOURCE_ATTRIBUTES` are ignored. Tell installations apart with other
628-
resource attributes, such as `OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=development`.
625+
Service names are fixed: `t3code-server` for the backend, `t3code-desktop` for the desktop main
626+
process, and `t3code-web` for the UI, all in `service.namespace` `t3code`. `OTEL_SERVICE_NAME` and a
627+
`service.name` or `service.namespace` in `OTEL_RESOURCE_ATTRIBUTES` are ignored. Tell installations
628+
apart with other resource attributes, such as
629+
`OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=staging`. The server and the desktop main
630+
process report `deployment.environment.name` as `development` or `production` on their own, and a
631+
value in `OTEL_RESOURCE_ATTRIBUTES` replaces it. Runtimes are described with `process.runtime.*`, and
632+
the UI adds `browser.*` and `user_agent.original`.
629633

630634
If the OTLP URLs are unset, local tracing still works, metrics stay in-process only, and logs stay
631635
on stdout only.

‎packages/shared/src/observability.test.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,36 @@ import {
2424
type TraceRecord,
2525
OtlpHeadersFromString,
2626
truncateTraceAttributes,
27+
nodeProcessResourceAttributes,
2728
} from "./observability.ts";
2829

30+
describe("nodeProcessResourceAttributes", () => {
31+
it("defaults the environment tier from the build and names the Node runtime", () => {
32+
const development = nodeProcessResourceAttributes({
33+
operatorAttributes: {},
34+
isDevelopment: true,
35+
});
36+
const production = nodeProcessResourceAttributes({
37+
operatorAttributes: {},
38+
isDevelopment: false,
39+
});
40+
41+
expect(development["deployment.environment.name"]).toBe("development");
42+
expect(production["deployment.environment.name"]).toBe("production");
43+
expect(development["process.runtime.name"]).toBe("nodejs");
44+
expect(development["process.runtime.version"]).toBe(process.versions.node);
45+
});
46+
47+
it("keeps a tier the operator set in OTEL_RESOURCE_ATTRIBUTES", () => {
48+
const attributes = nodeProcessResourceAttributes({
49+
operatorAttributes: { "deployment.environment.name": "staging" },
50+
isDevelopment: true,
51+
});
52+
53+
expect(attributes["deployment.environment.name"]).toBe("staging");
54+
});
55+
});
56+
2957
describe("errorTag", () => {
3058
it("reports structural tags without retaining arbitrary values", () => {
3159
assert.equal(errorTag({ _tag: "AcpRequestError" }), "AcpRequestError");

0 commit comments

Comments
 (0)