feat(node): emit os.name and os.version on spans

Reads the host OS from node:os in a node-only module so the edge bundle keeps
resolving no builtins, and normalizes os.name to the names posthog-ios and
posthog-android already send.

Author: turnipdabeets

.changeset/node-os-resource-attributes.md

@@ -0,0 +1,5 @@
+---
+'posthog-node': minor
+---
+
+Spans sent by `posthog-node` now carry `os.name` and `os.version` resource attributes, so traces can be filtered by the host operating system. `os.name` uses the same values `posthog-ios` and `posthog-android` send (`macOS`, `Windows`, `Linux`), and `os.version` is the kernel release. Both keys are overridable via `traces.resourceAttributes`, and neither is emitted on edge runtimes, which expose no OS.

packages/node/src/__tests__/host-os.spec.ts

@@ -0,0 +1,55 @@
+import { platform, release } from 'node:os'
+import { hostOsResourceAttributes } from '../host-os.node'
+
+jest.mock('node:os', () => ({ platform: jest.fn(), release: jest.fn() }))
+
+const mockPlatform = platform as jest.Mock
+const mockRelease = release as jest.Mock
+
+describe('hostOsResourceAttributes', () => {
+  it('reports the host OS', () => {
+    mockPlatform.mockReturnValue('linux')
+    mockRelease.mockReturnValue('6.1.0-27-amd64')
+
+    expect(hostOsResourceAttributes()).toEqual({ 'os.name': 'Linux', 'os.version': '6.1.0-27-amd64' })
+  })
+
+  it.each([
+    ['darwin', 'macOS'],
+    ['win32', 'Windows'],
+    ['linux', 'Linux'],
+    ['freebsd', 'FreeBSD'],
+  ])('reports %s under the name the other PostHog SDKs use, %s', (identifier, expected) => {
+    // posthog-ios and posthog-android already send these names; `platform()`
+    // returns os.type identifiers, which would be a second spelling.
+    mockPlatform.mockReturnValue(identifier)
+    mockRelease.mockReturnValue('1.0.0')
+
+    expect(hostOsResourceAttributes()['os.name']).toBe(expected)
+  })
+
+  it('passes an unmapped platform through rather than dropping it', () => {
+    mockPlatform.mockReturnValue('haiku')
+    mockRelease.mockReturnValue('1.0.0')
+
+    expect(hostOsResourceAttributes()['os.name']).toBe('haiku')
+  })
+
+  it('omits a key node:os cannot supply rather than emitting it empty', () => {
+    mockPlatform.mockReturnValue('linux')
+    mockRelease.mockReturnValue('')
+
+    expect(hostOsResourceAttributes()).toEqual({ 'os.name': 'Linux' })
+  })
+
+  it('returns no attributes when node:os throws', () => {
+    mockPlatform.mockImplementation(() => {
+      throw new Error('unsupported')
+    })
+    mockRelease.mockImplementation(() => {
+      throw new Error('unsupported')
+    })
+
+    expect(hostOsResourceAttributes()).toEqual({})
+  })
+})

packages/node/src/__tests__/traces-defaults.spec.ts

@@ -71,4 +71,25 @@ describe('resolveTracesConfig', () => {
   it('floors an explicit maxQueueSize at the export batch size', () => {
     expect(resolveTracesConfig({ maxExportBatchSize: 512, maxQueueSize: 10 }).maxQueueSize).toBe(512)
   })
+
+  it('attaches the host resource attributes the entrypoint supplies', () => {
+    expect(
+      resolveTracesConfig(undefined, { 'os.name': 'linux', 'os.version': '6.1.0-27-amd64' }).resourceAttributes
+    ).toEqual({ 'os.name': 'linux', 'os.version': '6.1.0-27-amd64' })
+  })
+
+  it('lets user resource attributes override the host ones', () => {
+    expect(
+      resolveTracesConfig(
+        { resourceAttributes: { 'os.name': 'my-os', 'os.version': '1.2.3' } },
+        { 'os.name': 'linux', 'os.version': '6.1.0-27-amd64' }
+      ).resourceAttributes
+    ).toEqual({ 'os.name': 'my-os', 'os.version': '1.2.3' })
+  })
+
+  it('resolves when the entrypoint supplies no host attributes', () => {
+    expect(resolveTracesConfig({ resourceAttributes: { 'host.name': 'worker-01' } }).resourceAttributes).toEqual({
+      'host.name': 'worker-01',
+    })
+  })
 })

packages/node/src/__tests__/traces.spec.ts

@@ -1,3 +1,4 @@
+import { hostOsResourceAttributes } from '../host-os.node'
 import { PostHog } from '@/entrypoints/index.node'
 import type { OtlpSpan, OtlpTracesPayload } from '@posthog/types'
 import { waitForPromises } from './utils'
@@ -114,6 +115,30 @@ describe('PostHog traces', () => {
         value: { stringValue: 'posthog-node' },
       })
     })
+
+    it('sends the host OS as resource attributes', async () => {
+      posthog.startSpan('checkout').end()
+      await flushTraces()
+
+      // Compared against the resolver rather than `platform()` directly: the point
+      // is that the node entrypoint's override reaches the wire, not what this
+      // machine runs.
+      const { 'os.name': osName, 'os.version': osVersion } = hostOsResourceAttributes()
+      const attributes = sentPayloads()[0].resourceSpans[0].resource.attributes
+      expect(attributes).toContainEqual({ key: 'os.name', value: { stringValue: osName } })
+      expect(attributes).toContainEqual({ key: 'os.version', value: { stringValue: osVersion } })
+    })
+
+    it('lets configured resourceAttributes override the host OS', async () => {
+      posthog = createClient({ traces: { serviceName: 'checkout-api', resourceAttributes: { 'os.name': 'my-os' } } })
+      posthog.startSpan('checkout').end()
+      await flushTraces()
+
+      expect(sentPayloads()[0].resourceSpans[0].resource.attributes).toContainEqual({
+        key: 'os.name',
+        value: { stringValue: 'my-os' },
+      })
+    })
   })
 
   describe('span shape', () => {

packages/node/src/client.ts

@@ -628,6 +628,15 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     return new SyncSpanContextManager()
   }
 
+  /**
+   * Runtime-detected OTLP resource attributes for every span. Overridden by the
+   * Node entrypoint with the host OS; the edge build contributes none, keeping
+   * `node:os` out of an edge bundle, which cannot resolve it.
+   */
+  protected hostResourceAttributes(): Record<string, string> {
+    return {}
+  }
+
   /**
    * The traces pipeline, built on first use. Returns `undefined` when the
    * `traces` client option is absent — tracing is off until configured.
@@ -639,7 +648,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     if (!this._traces) {
       this._traces = new PostHogTraces(
         this,
-        resolveTracesConfig(this.options.traces),
+        resolveTracesConfig(this.options.traces, this.hostResourceAttributes()),
         this._logger,
         () => this._tracingContext(),
         this.initializeSpanContextManager()

packages/node/src/entrypoints/index.node.ts

@@ -11,6 +11,7 @@ import type { SpanContextManager } from '@posthog/core'
 import { PostHogContext } from '../extensions/context/context'
 import { AsyncLocalStorageSpanContextManager } from '../extensions/context/span-context.node'
 import { gzipCompress } from '../gzip.node'
+import { hostOsResourceAttributes } from '../host-os.node'
 
 export class PostHog extends PostHogBackendClient {
   getLibraryId(): string {
@@ -29,6 +30,10 @@ export class PostHog extends PostHogBackendClient {
     return new AsyncLocalStorageSpanContextManager()
   }
 
+  protected override hostResourceAttributes(): Record<string, string> {
+    return hostOsResourceAttributes()
+  }
+
   protected override createErrorPropertiesBuilder(): CoreErrorTracking.ErrorPropertiesBuilder {
     return new CoreErrorTracking.ErrorPropertiesBuilder(
       [

packages/node/src/host-os.node.ts

@@ -0,0 +1,46 @@
+import { platform, release } from 'node:os'
+
+/**
+ * OTLP `os.name` values for the `node:os` platform identifiers.
+ *
+ * OpenTelemetry defines `os.name` as the human-readable OS name; the identifiers
+ * `platform()` returns (`darwin`, `win32`) belong to `os.type`, a different
+ * attribute. These are the names `posthog-ios` and `posthog-android` already
+ * send, so one `os.name` filter spans every PostHog SDK.
+ */
+const OS_NAMES: Record<string, string> = {
+  darwin: 'macOS',
+  win32: 'Windows',
+  linux: 'Linux',
+  android: 'Android',
+  freebsd: 'FreeBSD',
+  openbsd: 'OpenBSD',
+  sunos: 'SunOS',
+  aix: 'AIX',
+}
+
+/**
+ * OTLP `os.name` / `os.version` for the machine running the SDK, so spans can
+ * be filtered by platform (e.g. "only the Linux workers") in PostHog.
+ *
+ * Node-only, like the other `.node` modules: importing `node:os` from a shared
+ * module would put it in the edge bundle. A failed read omits the key rather
+ * than throwing out of client construction.
+ *
+ * `os.version` is the kernel release (`25.6.0` on macOS 26, `6.1.0-27-amd64` on
+ * Debian 12), not the marketing version — Node exposes no product-version API,
+ * and `os.version()` returns a full banner string rather than a version.
+ */
+export function hostOsResourceAttributes(): Record<string, string> {
+  let osName: string | undefined
+  let osVersion: string | undefined
+  try {
+    // An unmapped platform passes through: a raw identifier beats no OS at all.
+    osName = OS_NAMES[platform()] ?? platform()
+    osVersion = release()
+  } catch {}
+  return {
+    ...(osName ? { 'os.name': osName } : {}),
+    ...(osVersion ? { 'os.version': osVersion } : {}),
+  }
+}

packages/node/src/traces-defaults.ts

@@ -22,10 +22,14 @@ function positiveInteger(value: number | undefined, fallback: number): number {
 /**
  * Resolves the public `traces` config into the shape core `PostHogTraces` consumes.
  * OTLP resource attributes take precedence over the named fields, matching the
- * logs config — a user who sets `service.name` directly means it.
+ * logs config. `hostResourceAttributes` are runtime-detected by the entrypoint and
+ * merge first, so a user-supplied value of the same key wins.
  */
-export function resolveTracesConfig(config: TracesConfig | undefined): ResolvedTracesConfig {
-  const resourceAttributes = config?.resourceAttributes
+export function resolveTracesConfig(
+  config: TracesConfig | undefined,
+  hostResourceAttributes?: Record<string, string>
+): ResolvedTracesConfig {
+  const resourceAttributes = { ...hostResourceAttributes, ...config?.resourceAttributes }
   const maxExportBatchSize = positiveInteger(config?.maxExportBatchSize, DEFAULT_MAX_EXPORT_BATCH_SIZE)
   return {
     serviceName: stringAttribute(resourceAttributes?.['service.name']) ?? config?.serviceName,