@posthog/core 1.26.0 → 1.27.1

package/src/logs/logs-utils.ts

@@ -0,0 +1,198 @@
+import type {
+  CaptureLogOptions,
+  LogAttributeValue,
+  LogSdkContext,
+  LogSeverityLevel,
+  OtlpAnyValue,
+  OtlpKeyValue,
+  OtlpLogRecord,
+  OtlpLogsPayload,
+  OtlpSeverityEntry,
+  OtlpSeverityText,
+} from '@posthog/types'
+import { isArray, isBoolean, isNull, isUndefined } from '../utils'
+
+// ============================================================================
+// Severity mapping
+// ============================================================================
+
+const OTLP_SEVERITY_MAP: Record<LogSeverityLevel, OtlpSeverityEntry> = {
+  trace: { text: 'TRACE', number: 1 },
+  debug: { text: 'DEBUG', number: 5 },
+  info: { text: 'INFO', number: 9 },
+  warn: { text: 'WARN', number: 13 },
+  error: { text: 'ERROR', number: 17 },
+  fatal: { text: 'FATAL', number: 21 },
+}
+
+const DEFAULT_OTLP_SEVERITY = OTLP_SEVERITY_MAP.info
+
+export function getOtlpSeverityText(level: LogSeverityLevel): OtlpSeverityText {
+  return (OTLP_SEVERITY_MAP[level] || DEFAULT_OTLP_SEVERITY).text
+}
+
+export function getOtlpSeverityNumber(level: LogSeverityLevel): number {
+  return (OTLP_SEVERITY_MAP[level] || DEFAULT_OTLP_SEVERITY).number
+}
+
+// ============================================================================
+// OTLP AnyValue conversion
+// ============================================================================
+
+export function toOtlpAnyValue(value: LogAttributeValue): OtlpAnyValue {
+  if (isBoolean(value)) {
+    return { boolValue: value }
+  }
+  // NOTE: typeof check (not core's isNumber) so NaN is included. core's
+  // isNumber explicitly excludes NaN via the `x === x` guard, which would
+  // route NaN through the JSON.stringify branch below — JSON has no
+  // representation for non-finite floats and JSON.stringify turns them into
+  // `null`, losing the value server-side. proto3 JSON mapping (which OTLP/HTTP
+  // rides) requires the literal strings; we encode them as stringValue to keep
+  // the human-readable signal regardless of which downstream parser sees them.
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      return { stringValue: String(value) }
+    }
+    if (Number.isInteger(value)) {
+      return { intValue: value }
+    }
+    return { doubleValue: value }
+  }
+  if (typeof value === 'string') {
+    return { stringValue: value }
+  }
+  if (isArray(value)) {
+    return { arrayValue: { values: value.map((v) => toOtlpAnyValue(v as LogAttributeValue)) } }
+  }
+  // Objects fall back to JSON. OTLP supports kvlistValue but the encoder
+  // stays flat for simplicity.
+  try {
+    return { stringValue: JSON.stringify(value) }
+  } catch {
+    return { stringValue: String(value) }
+  }
+}
+
+export function toOtlpKeyValueList(attrs: Record<string, LogAttributeValue>): OtlpKeyValue[] {
+  const result: OtlpKeyValue[] = []
+  for (const key in attrs) {
+    const value = attrs[key]
+    if (isNull(value) || isUndefined(value)) {
+      continue
+    }
+    result.push({ key, value: toOtlpAnyValue(value) })
+  }
+  return result
+}
+
+// ============================================================================
+// OTLP LogRecord construction
+// ============================================================================
+
+/**
+ * Returns the current wall-clock time as a unix-nanos string.
+ *
+ * OTLP requires nanoseconds as a string (uint64 doesn't fit in JS Number).
+ * `Date.now() * 1_000_000` would exceed Number.MAX_SAFE_INTEGER, so we
+ * concatenate instead of multiplying.
+ */
+function timestampToUnixNano(): string {
+  return String(Date.now()) + '000000'
+}
+
+/**
+ * Builds a single OTLP log record.
+ *
+ * Auto-attribute population is shape-driven: any field present on `sdkContext`
+ * is emitted as the corresponding attribute. Each SDK populates only the
+ * fields that apply to it (browser fills `currentUrl`; mobile fills
+ * `screenName` / `appState`), so a missing field never adds a stray attribute.
+ *
+ * User-provided `options.attributes` always wins on conflicts.
+ */
+export function buildOtlpLogRecord(options: CaptureLogOptions, sdkContext: LogSdkContext): OtlpLogRecord {
+  const level: LogSeverityLevel = options.level || 'info'
+  const { text: severityText, number: severityNumber } = OTLP_SEVERITY_MAP[level] || DEFAULT_OTLP_SEVERITY
+  const now = timestampToUnixNano()
+
+  const autoAttributes: Record<string, LogAttributeValue> = {}
+
+  if (sdkContext.distinctId) {
+    autoAttributes.posthogDistinctId = sdkContext.distinctId
+  }
+  if (sdkContext.sessionId) {
+    autoAttributes.sessionId = sdkContext.sessionId
+  }
+  if (sdkContext.currentUrl) {
+    autoAttributes['url.full'] = sdkContext.currentUrl
+  }
+  if (sdkContext.screenName) {
+    autoAttributes['screen.name'] = sdkContext.screenName
+  }
+  if (sdkContext.appState) {
+    autoAttributes['app.state'] = sdkContext.appState
+  }
+  if (sdkContext.activeFeatureFlags && sdkContext.activeFeatureFlags.length > 0) {
+    autoAttributes.feature_flags = sdkContext.activeFeatureFlags
+  }
+
+  const mergedAttributes = {
+    ...autoAttributes,
+    ...(options.attributes || {}),
+  }
+
+  const record: OtlpLogRecord = {
+    timeUnixNano: now,
+    observedTimeUnixNano: now,
+    severityNumber,
+    severityText,
+    body: { stringValue: options.body },
+    attributes: toOtlpKeyValueList(mergedAttributes),
+  }
+
+  if (options.trace_id) {
+    record.traceId = options.trace_id
+  }
+  if (options.span_id) {
+    record.spanId = options.span_id
+  }
+  if (!isUndefined(options.trace_flags)) {
+    record.flags = options.trace_flags
+  }
+
+  return record
+}
+
+// ============================================================================
+// OTLP envelope construction
+// ============================================================================
+
+/**
+ * Wraps a list of records in the OTLP `resourceLogs` envelope.
+ *
+ * `scopeName` is the SDK package name (`posthog-js`, `posthog-react-native`,
+ * etc.). `scopeVersion` is the SDK semver. The server combines them into a
+ * single `instrumentation_scope` field (`{name}@{version}`) used for
+ * SDK-version-level attribution in queries and dashboards.
+ */
+export function buildOtlpLogsPayload(
+  logRecords: OtlpLogRecord[],
+  resourceAttributes: Record<string, LogAttributeValue>,
+  scopeName: string,
+  scopeVersion: string
+): OtlpLogsPayload {
+  return {
+    resourceLogs: [
+      {
+        resource: { attributes: toOtlpKeyValueList(resourceAttributes) },
+        scopeLogs: [
+          {
+            scope: { name: scopeName, version: scopeVersion },
+            logRecords,
+          },
+        ],
+      },
+    ],
+  }
+}

package/src/tracing-headers.ts

@@ -0,0 +1,105 @@
+import { isFunction } from './utils/type-utils'
+
+const DISTINCT_ID_HEADER = 'X-POSTHOG-DISTINCT-ID'
+const SESSION_ID_HEADER = 'X-POSTHOG-SESSION-ID'
+const PATCH_MARKER = '__posthog_tracing_headers_patched__'
+
+const parseHostname = (url: string): string | undefined => {
+  try {
+    return new URL(url).hostname
+  } catch {
+    return undefined
+  }
+}
+
+const shouldAddHeaders = (url: string, hostnames: string[]): boolean => {
+  const hostname = parseHostname(url)
+  if (!hostname) {
+    return false
+  }
+  return hostnames.includes(hostname)
+}
+
+/**
+ * Minimal contract the tracing-headers patch needs from a PostHog client:
+ * something that can report the current distinct and session ids.
+ */
+export interface TracingHeadersClient {
+  getDistinctId(): string
+  getSessionId(): string
+}
+
+type FetchFn = typeof fetch
+type PatchedFetch = FetchFn & { [PATCH_MARKER]?: { original: FetchFn } }
+
+/**
+ * Patches `globalThis.fetch` to inject `X-POSTHOG-DISTINCT-ID` and
+ * `X-POSTHOG-SESSION-ID` headers on requests whose hostname matches `hostnames`.
+ *
+ * Used by SDKs that run in environments with a WHATWG `fetch` (posthog-react-native,
+ * posthog-web) to link outgoing requests to the PostHog session — e.g. to link LLM
+ * traces captured by a backend to a frontend session replay.
+ *
+ * The wrapped fetch is tagged with a non-enumerable marker so that calling this
+ * again (on HMR, tests, or a second PostHog instance) unwraps the previous patch
+ * before rewrapping — preventing patches from stacking. Returns a function that
+ * restores the original fetch when called.
+ */
+export const patchFetchForTracingHeaders = (client: TracingHeadersClient, hostnames: string[]): (() => void) => {
+  const globalAny = globalThis as unknown as { fetch?: PatchedFetch }
+  const currentFetch = globalAny.fetch
+  if (!isFunction(currentFetch)) {
+    return () => {}
+  }
+
+  // If we already patched fetch ourselves, unwrap so the latest client's hostname list
+  // and session/distinct ids take effect without stacking patches.
+  //
+  // Limitation: we only unwrap our own immediate predecessor. If another library wraps fetch
+  // between two patch calls, their wrapper has no PATCH_MARKER, so we treat it as the original —
+  // meaning the earlier patch stays live underneath and headers could be written twice.
+  // This is considered out of scope; we rely on PostHog being initialised once per app.
+  const originalFetch: FetchFn = currentFetch[PATCH_MARKER]?.original ?? currentFetch
+
+  const wrappedFetch: PatchedFetch = async function (input, init) {
+    try {
+      const urlString =
+        typeof input === 'string'
+          ? input
+          : input instanceof URL
+            ? input.toString()
+            : input instanceof Request
+              ? input.url
+              : undefined
+      if (urlString && shouldAddHeaders(urlString, hostnames)) {
+        const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined))
+        const distinctId = client.getDistinctId()
+        const sessionId = client.getSessionId()
+        if (distinctId) {
+          headers.set(DISTINCT_ID_HEADER, distinctId)
+        }
+        if (sessionId) {
+          headers.set(SESSION_ID_HEADER, sessionId)
+        }
+        const initWithHeaders = { ...(init ?? {}), headers }
+        return originalFetch.call(globalAny, input, initWithHeaders)
+      }
+    } catch {
+      // If anything goes wrong, fall through to the original fetch without tracing headers.
+    }
+    return originalFetch.call(globalAny, input, init)
+  }
+
+  Object.defineProperty(wrappedFetch, PATCH_MARKER, {
+    value: { original: originalFetch },
+    enumerable: false,
+  })
+
+  globalAny.fetch = wrappedFetch
+
+  return () => {
+    if (globalAny.fetch === wrappedFetch) {
+      globalAny.fetch = originalFetch
+    }
+  }
+}

package/src/types.ts

@@ -191,6 +191,19 @@ export type PostHogCoreOptions = {
    * If a function returns null, the event will be dropped.
    */
   before_send?: BeforeSendFn | BeforeSendFn[]
+
+  /**
+   * A list of hostnames for which to inject PostHog tracing headers
+   * (X-POSTHOG-DISTINCT-ID, X-POSTHOG-SESSION-ID) on outgoing `fetch` requests.
+   *
+   * Use this to link requests made from your app to session replays and LLM traces
+   * in PostHog. When set, the global `fetch` is patched on initialization and the
+   * headers are added to requests whose hostname matches one of the entries.
+   *
+   * Requires the SDK to wire up `patchFetchForTracingHeaders` against this option
+   * (currently supported in posthog-react-native).
+   */
+  addTracingHeaders?: string[]
 }
 
 export enum PostHogPersistedProperty {