fix(observability): resource attributes follow OTel semantic conventions (#68)

Author: yordis

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

@@ -412,7 +412,8 @@ describe("DesktopObservability", () => {
       const [request] = requests;
       assert.strictEqual(request?.url, "https://collector.example.com/v1/logs");
       assert.include(request?.body ?? "", "desktop log export");
-      assert.include(request?.body ?? "", "service.runtime");
+      assert.include(request?.body ?? "", "deployment.environment.name");
+      assert.include(request?.body ?? "", "process.runtime.name");
       assert.strictEqual(request?.headers["x-scope"], "desktop");
 
       // The log record is the export now, so the same message must not also
@@ -497,7 +498,7 @@ describe("DesktopObservability", () => {
       assert.lengthOf(requests, 1);
       const body = requests[0]?.body ?? "";
       assert.include(body, '"stringValue":"t3code-desktop"');
-      assert.include(body, "deployment.environment.name");
+      assert.include(body, '"key":"deployment.environment.name","value":{"stringValue":"staging"}');
       assert.include(body, '"key":"service.namespace","value":{"stringValue":"t3code"}');
       assert.notInclude(body, "renamed");
     }).pipe(
@@ -511,7 +512,7 @@ describe("DesktopObservability", () => {
               env: {
                 OTEL_SERVICE_NAME: "renamed",
                 OTEL_RESOURCE_ATTRIBUTES:
-                  "service.name=renamed,service.namespace=renamed,deployment.environment.name=development",
+                  "service.name=renamed,service.namespace=renamed,deployment.environment.name=staging",
               },
             }),
           ),

apps/desktop/src/app/DesktopObservability.ts

@@ -2,6 +2,7 @@ import { PRIMARY_LOCAL_ENVIRONMENT_ID } from "@t3tools/contracts";
 import {
   makeLocalFileTracer,
   makeTraceSink,
+  nodeProcessResourceAttributes,
   otlpSerializationLayer,
   type SignalExport,
 } from "@t3tools/shared/observability";
@@ -627,10 +628,13 @@ const telemetryLayer = Layer.unwrap(
     const endpoints = yield* resolveOtlpEndpoints;
     const resource = {
       serviceName: "t3code-desktop",
+      serviceVersion: environment.appVersion,
       attributes: {
         "service.namespace": "t3code",
-        "service.runtime": "desktop",
-        "service.mode": environment.isDevelopment ? "development" : "packaged",
+        ...nodeProcessResourceAttributes({
+          operatorAttributes: endpoints.resourceAttributes,
+          isDevelopment: environment.isDevelopment,
+        }),
       },
     };
 

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

@@ -27,6 +27,7 @@ it.effect("exports spans through the scoped mobile OTLP layer", () => {
     },
     {
       appVariant: "test",
+      serviceInstanceId: "test-instance",
       serviceVersion: "1.2.3",
     },
   ).pipe(Layer.provide(remoteHttpClientLayer(fetchFn)));
@@ -47,7 +48,15 @@ it.effect("exports spans through the scoped mobile OTLP layer", () => {
         expect(String(url)).toBe("https://api.axiom.test/v1/traces");
         expect(new Headers(init?.headers).get("authorization")).toBe("Bearer public-ingest-token");
         expect(new Headers(init?.headers).get("x-axiom-dataset")).toBe("mobile-traces");
-        expect(new TextDecoder().decode(init?.body as Uint8Array)).toContain("mobile.test.span");
+        const body = new TextDecoder().decode(init?.body as Uint8Array);
+        expect(body).toContain("mobile.test.span");
+        expect(body).toContain('"key":"t3code.client.surface","value":{"stringValue":"mobile"}');
+        expect(body).toContain(
+          '"key":"deployment.environment.name","value":{"stringValue":"test"}',
+        );
+        expect(body).toContain(
+          '"key":"service.instance.id","value":{"stringValue":"test-instance"}',
+        );
       }),
     ),
   );
@@ -63,6 +72,7 @@ it.effect("does not let OTLP serialization failures alter application effects",
     },
     {
       appVariant: "test",
+      serviceInstanceId: "test-instance",
       serviceVersion: "1.2.3",
     },
   ).pipe(Layer.provide(remoteHttpClientLayer(fetchFn)));

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

@@ -11,6 +11,7 @@ export interface TracingConfig {
 
 export interface TracingResource {
   readonly serviceVersion?: string;
+  readonly serviceInstanceId: string;
   readonly appVariant: string;
 }
 
@@ -27,13 +28,20 @@ export function makeTracingLayer(config: TracingConfig | null, resource: Tracing
   return makeRelayClientTracingLayer(config, {
     serviceName: "t3code-mobile",
     serviceVersion: resource.serviceVersion,
-    runtime: "react-native",
-    client: `mobile-${resource.appVariant}`,
+    serviceInstanceId: resource.serviceInstanceId,
+    client: "mobile",
+    attributes: {
+      "process.runtime.name": "react-native",
+      ...(resource.appVariant !== "unknown" && {
+        "deployment.environment.name": resource.appVariant,
+      }),
+    },
   });
 }
 
 export const tracingLayer = makeTracingLayer(resolveTracingConfig(), {
   serviceVersion: Constants.expoConfig?.version,
+  serviceInstanceId: Constants.sessionId,
   appVariant:
     typeof Constants.expoConfig?.extra?.appVariant === "string"
       ? Constants.expoConfig.extra.appVariant

apps/server/src/cloud/relayTracing.ts

@@ -1,3 +1,7 @@
+import {
+  nodeProcessRuntimeAttributes,
+  processServiceInstanceId,
+} from "@t3tools/shared/observability";
 import { makeRelayClientTracingLayer } from "@t3tools/shared/relayTracing";
 
 import { resolveRelayClientTracingConfig } from "./publicConfig.ts";
@@ -8,14 +12,16 @@ export const headlessRelayClientTracingLayer = makeRelayClientTracingLayer(
   relayClientTracingConfig,
   {
     serviceName: "t3code-server",
-    runtime: "node",
+    serviceInstanceId: processServiceInstanceId(),
+    attributes: nodeProcessRuntimeAttributes(),
     client: "headless-cli",
   },
 );
 
 export const serverRelayBrokerTracingLayer = makeRelayClientTracingLayer(relayClientTracingConfig, {
   serviceName: "t3code-server",
-  runtime: "node",
+  serviceInstanceId: processServiceInstanceId(),
+  attributes: nodeProcessRuntimeAttributes(),
   client: "environment-server",
   component: "relay-broker",
 });

apps/server/src/config.ts

@@ -16,8 +16,13 @@ import * as Path from "effect/Path";
 import type * as Redacted from "effect/Redacted";
 import * as Schema from "effect/Schema";
 
+import packageJson from "../package.json" with { type: "json" };
 import { sweepStalePendingAttachments } from "./attachmentStore.ts";
-import { DEFAULT_SIGNAL_EXPORT, type SignalExport } from "@t3tools/shared/observability";
+import {
+  DEFAULT_SIGNAL_EXPORT,
+  nodeProcessResourceAttributes,
+  type SignalExport,
+} from "@t3tools/shared/observability";
 import * as OtelEnvironment from "@t3tools/shared/otelEnvironment";
 
 export const DEFAULT_PORT = 3773;
@@ -118,10 +123,14 @@ export const make = (config: ServerConfig["Service"]) => ServerConfig.of(config)
  */
 export const otlpResource = (config: ServerConfig["Service"]) => ({
   serviceName: "t3code-server",
+  serviceVersion: packageJson.version,
   attributes: {
     "service.namespace": "t3code",
-    "service.runtime": "t3-server",
-    "service.mode": config.mode,
+    "t3code.server.managed_by": config.mode === "desktop" ? "desktop" : "standalone",
+    ...nodeProcessResourceAttributes({
+      operatorAttributes: config.otelEnvironment.resourceAttributes,
+      isDevelopment: config.devUrl !== undefined,
+    }),
   },
 });
 

apps/server/src/serverLogger.test.ts

@@ -147,7 +147,9 @@ describe("ServerLoggerLive", () => {
       assert.strictEqual(request?.url, "https://collector.example.com/v1/logs");
       assert.include(request?.body ?? "", "server logger under test");
       assert.include(request?.body ?? "", "t3code-server");
-      assert.include(request?.body ?? "", "service.runtime");
+      assert.include(request?.body ?? "", "t3code.server.managed_by");
+      assert.include(request?.body ?? "", "process.runtime.name");
+      assert.include(request?.body ?? "", "service.instance.id");
     }),
   );
 

apps/web/src/lib/runtime.ts

@@ -12,6 +12,7 @@ import { browserCryptoLayer } from "../cloud/dpop";
 import { managedRelayClientLayer } from "../cloud/managedRelayLayer";
 import { resolveCloudPublicConfig, resolveRelayTracingConfig } from "../cloud/publicConfig";
 import * as ClientTracer from "../observability/clientTracer";
+import { serviceInstanceId } from "../observability/serviceInstance";
 
 function configuredRelayUrl(): string {
   return resolveCloudPublicConfig().relayUrl ?? "http://relay.invalid";
@@ -21,7 +22,8 @@ const httpClientLayer = remoteHttpClientLayer((input, init) => globalThis.fetch(
 const relayTracingLayer = makeRelayClientTracingLayer(resolveRelayTracingConfig(), {
   serviceName: "t3code-web",
   serviceVersion: import.meta.env.APP_VERSION,
-  runtime: "browser",
+  serviceInstanceId,
+  attributes: { "process.runtime.name": "browser" },
   client: typeof window !== "undefined" && window.desktopBridge ? "desktop" : "web",
 }).pipe(Layer.provide(httpClientLayer));
 

apps/web/src/observability/clientTracing.ts

@@ -9,20 +9,51 @@ import { settleAsyncResult, squashAtomCommandFailure } from "@t3tools/client-run
 import { safeErrorLogAttributes } from "@t3tools/client-runtime/errors";
 import { resolvePrimaryEnvironmentHttpUrl } from "../environments/primary";
 import * as ClientTracer from "./clientTracer";
+import { serviceInstanceId } from "./serviceInstance";
 import { primaryEnvironmentHttpLayer } from "../environments/primary/httpLayer";
 import { isElectron } from "../env";
 import { APP_VERSION } from "~/branding";
 
 const DEFAULT_EXPORT_INTERVAL_MS = 1_000;
+interface NavigatorUserAgentData {
+  readonly platform: string;
+  readonly mobile: boolean;
+  readonly brands: ReadonlyArray<{ readonly brand: string; readonly version: string }>;
+}
+
+/**
+ * The same `browser.*` and `user_agent.original` attributes the OpenTelemetry
+ * browser resource detector reports, plus the `process.runtime.*` values the
+ * semantic conventions give a web browser. `userAgentData` exists only in
+ * Chromium, which includes the desktop app.
+ */
+const browserResourceAttributes = (): Record<string, unknown> => {
+  if (typeof navigator === "undefined") return {};
+  const userAgentData = (navigator as Navigator & { userAgentData?: NavigatorUserAgentData })
+    .userAgentData;
+  return {
+    "user_agent.original": navigator.userAgent,
+    "process.runtime.name": "browser",
+    "process.runtime.version": navigator.userAgent,
+    "browser.language": navigator.language,
+    ...(userAgentData && {
+      "browser.platform": userAgentData.platform,
+      "browser.mobile": userAgentData.mobile,
+      "browser.brands": userAgentData.brands.map(({ brand, version }) => `${brand} ${version}`),
+    }),
+  };
+};
+
 const CLIENT_TRACING_RESOURCE = {
   serviceName: "t3code-web",
+  serviceVersion: APP_VERSION,
   attributes: {
     "service.namespace": "t3code",
-    "service.runtime": "t3-web",
-    "service.mode": isElectron ? "electron" : "browser",
-    "service.version": APP_VERSION,
+    "service.instance.id": serviceInstanceId,
+    "t3code.client.surface": isElectron ? "desktop" : "web",
+    ...browserResourceAttributes(),
   },
-} as const;
+};
 
 const delegateRuntimeLayer = Layer.mergeAll(
   primaryEnvironmentHttpLayer,

apps/web/src/observability/serviceInstance.ts

@@ -0,0 +1,4 @@
+import { randomUUID } from "../lib/utils";
+
+/** `service.instance.id` for this page load, shared by every resource the UI exports. */
+export const serviceInstanceId = randomUUID();