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

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

Add approximate locale/region signals to the browser RUM resource:
- browser.language  (OTel semconv) from navigator.language, e.g. "en-US"
- browser.timezone  (IANA zone) from Intl, e.g. "America/New_York"

These are honest proxies for a user's region, NOT IP geolocation — the
browser cannot determine country without a permission prompt; true geo
(geo.country.name, …) is derived in the collector from the client IP.

The resolver is split out (browserContext.ts) with the context injectable
so the attribute mapping is unit-tested without real browser globals, and
omits absent values so it never overwrites a user attribute with an empty
string. Wired into resourceAttrs before the user-provided
resourceAttributes so callers can override.

* test(otel-web): cover navigator.language and empty-string language branches

Adds two unit tests flagged in review of the RUM browser-context change:

- getBrowserContextResourceAttributes({ language: '' }) -> {} confirms an
  empty-string language is treated as absent.
- resolveBrowserContext() reads navigator.language: mock navigator with a
  fixed 'fr-FR' locale so the truthful branch is exercised deterministically,
  independent of the host's locale (Node 22 defines navigator.language).

* refactor(otel-web): namespace the custom timezone attr as hyperdx.browser.timezone

Per review: the OTel browser resource semconv has no timezone attribute, so
the custom one was squatting in the reserved `browser.` namespace. Move it to
the vendor namespace `hyperdx.browser.timezone` to avoid a future collision.
`browser.language` is unchanged (it is the spec attribute). Updates the emit
site, docstring, changeset, and the two existing test assertions.

* fix(deno): import dnt from JSR to avoid deno.land brotli fetch errors

The unpinned https://deno.land/x/dnt import pulls ts_morph from
deno.land/x, which intermittently fails with 'error: brotli error'
on Deno 1.x in CI. The JSR-published dnt resolves its dependencies
from jsr.io instead, eliminating the failing fetch.

---------

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
Co-authored-by: Warren Lee <5959690+wrn14897@users.noreply.github.com>

Author: 3 people

.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/deno/build-npm.ts

@@ -1,4 +1,4 @@
-import { build, emptyDir } from 'https://deno.land/x/dnt/mod.ts';
+import { build, emptyDir } from 'jsr:@deno/dnt@0.41.3';
 
 async function getJson(filePath: string) {
   return JSON.parse(await Deno.readTextFile(filePath));

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