feat(otel-web): emit browser.language and browser.timezone resource attributes

.changeset/rum-browser-context.md

@@ -0,0 +1,12 @@
+---
+'@hyperdx/otel-web': minor
+'@hyperdx/browser': minor
+---
+
+Emit approximate locale/region resource attributes from the browser RUM
+SDK: `browser.language` (OTel semconv, from `navigator.language`) and
+`hyperdx.browser.timezone` (IANA zone from `Intl`). These are honest proxies for
+where a user is — they are NOT IP geolocation (the browser can't
+determine country without a permission prompt; true geo is derived in the
+collector from the client IP). Added before user-provided
+`resourceAttributes` so callers can override them.

packages/otel-web/.mocharc.json

@@ -1,5 +1,5 @@
 {
   "extension": ["ts"],
-  "spec": "test/nodejs.test.ts",
+  "spec": ["test/nodejs.test.ts", "test/browserContext.test.ts"],
   "require": "ts-node/register"
 }

packages/otel-web/src/browserContext.ts

@@ -0,0 +1,55 @@
+import type { Attributes } from '@opentelemetry/api';
+
+/**
+ * Approximate locale/region signals read from the browser environment.
+ * These are HONEST PROXIES for where a user is — they are NOT IP
+ * geolocation (the browser cannot determine country without a permission
+ * prompt). True geo (`geo.country.name`, …) is derived in the OTel
+ * collector from the client IP. See the geoip processor.
+ */
+export interface BrowserContext {
+  /** navigator.language, e.g. "en-US" (OTel semconv `browser.language`). */
+  language?: string;
+  /** IANA time zone, e.g. "America/New_York" (emitted as `hyperdx.browser.timezone`). */
+  timeZone?: string;
+}
+
+/** Read the browser context from the current environment (best-effort). */
+export function resolveBrowserContext(): BrowserContext {
+  const language =
+    typeof navigator !== 'undefined' ? navigator.language : undefined;
+
+  let timeZone: string | undefined;
+  try {
+    timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone || undefined;
+  } catch {
+    // Intl or the resolved time zone is unavailable in this environment.
+    timeZone = undefined;
+  }
+
+  return { language, timeZone };
+}
+
+/**
+ * Map a {@link BrowserContext} to resource attributes. `browser.language`
+ * is an OpenTelemetry semantic-convention attribute; `hyperdx.browser.timezone`
+ * is a vendor-namespaced custom attribute — OTel semconv has no timezone
+ * resource attribute, so it is kept out of the reserved `browser.` namespace
+ * to avoid a future collision. Absent values are omitted so they never
+ * overwrite a user-provided attribute with an empty string.
+ *
+ * The context is injectable so the mapping can be unit-tested without real
+ * browser globals.
+ */
+export function getBrowserContextResourceAttributes(
+  context: BrowserContext = resolveBrowserContext(),
+): Attributes {
+  const attrs: Attributes = {};
+  if (context.language) {
+    attrs['browser.language'] = context.language;
+  }
+  if (context.timeZone) {
+    attrs['hyperdx.browser.timezone'] = context.timeZone;
+  }
+  return attrs;
+}

packages/otel-web/src/index.ts

@@ -71,6 +71,7 @@ import {
 } from './SplunkContextManager';
 import { resourceFromAttributes } from '@opentelemetry/resources';
 import { SDK_INFO } from '@opentelemetry/core';
+import { getBrowserContextResourceAttributes } from './browserContext';
 import {
   ATTR_SERVICE_NAME,
   ATTR_TELEMETRY_SDK_NAME,
@@ -547,6 +548,10 @@ export const Rum: RumOtelWebType = {
     const pluginDefaults = { ignoreUrls, enabled: false };
 
     const resourceAttrs: Attributes = {
+      // Approximate locale/region signals (browser.language, hyperdx.browser.timezone).
+      // Honest proxies, NOT IP geolocation; placed first so user-provided
+      // resourceAttributes can override them.
+      ...getBrowserContextResourceAttributes(),
       // User-provided resource attributes
       ...(resourceAttributes || {}),
       ...SDK_INFO,

packages/otel-web/test/browserContext.test.ts

@@ -0,0 +1,59 @@
+import * as assert from 'assert';
+
+import {
+  getBrowserContextResourceAttributes,
+  resolveBrowserContext,
+} from '../src/browserContext';
+
+describe('browserContext', () => {
+  it('maps language and timeZone to resource attributes', () => {
+    assert.deepStrictEqual(
+      getBrowserContextResourceAttributes({
+        language: 'en-US',
+        timeZone: 'America/New_York',
+      }),
+      {
+        'browser.language': 'en-US',
+        'hyperdx.browser.timezone': 'America/New_York',
+      },
+    );
+  });
+
+  it('omits absent values so it never overwrites with empty attributes', () => {
+    assert.deepStrictEqual(getBrowserContextResourceAttributes({}), {});
+    assert.deepStrictEqual(
+      getBrowserContextResourceAttributes({ timeZone: 'UTC' }),
+      { 'hyperdx.browser.timezone': 'UTC' },
+    );
+  });
+
+  it('treats an empty-string language as absent', () => {
+    assert.deepStrictEqual(
+      getBrowserContextResourceAttributes({ language: '' }),
+      {},
+    );
+  });
+
+  it('resolveBrowserContext reads a non-empty IANA time zone from the environment', () => {
+    const { timeZone } = resolveBrowserContext();
+    assert.strictEqual(typeof timeZone, 'string');
+    assert.ok((timeZone as string).length > 0);
+  });
+
+  it('resolveBrowserContext reads navigator.language when available', () => {
+    const original = Object.getOwnPropertyDescriptor(globalThis, 'navigator');
+    Object.defineProperty(globalThis, 'navigator', {
+      value: { language: 'fr-FR' },
+      configurable: true,
+    });
+    try {
+      assert.strictEqual(resolveBrowserContext().language, 'fr-FR');
+    } finally {
+      if (original) {
+        Object.defineProperty(globalThis, 'navigator', original);
+      } else {
+        delete (globalThis as any).navigator;
+      }
+    }
+  });
+});