@posthog/core 1.34.0 → 1.35.1

package/src/logs/index.ts

@@ -1,18 +1,17 @@
 import type { LogAttributeValue } from '@posthog/types'
-import { buildOtlpLogRecord, buildOtlpLogsPayload } from './logs-utils'
+import { buildOtlpLogRecord, buildOtlpLogsPayload, buildResourceAttributes } from './logs-utils'
 import { Logger, PostHogPersistedProperty } from '../types'
-import type { PostHogCoreStateless } from '../posthog-core-stateless'
 import { isArray, safeSetTimeout } from '../utils'
-import type {
-  BeforeSendLogFn,
-  BufferedLogEntry,
-  CaptureLogOptions,
-  LogSdkContext,
-  ResolvedPostHogLogsConfig,
-} from './types'
+import type { BufferedLogEntry, CaptureLogOptions, LogSdkContext, LogsHost, ResolvedPostHogLogsConfig } from './types'
+
+// Caps the retry backoff at 2^6 = 64× the flush interval.
+const MAX_FLUSH_BACKOFF_EXPONENT = 6
 
 export class PostHogLogs {
   private _maxBufferSize: number
+  // Eviction cap; `_maxBufferSize` only triggers a flush. Collapses to
+  // `_maxBufferSize` when the host sets no separate value.
+  private _maxQueueSize: number
   private _flushIntervalMs: number
   // Mutable — halved on 413 to shrink the next POST, and ramped back up by
   // one record after each successful send so a one-off oversized payload
@@ -22,6 +21,12 @@ export class PostHogLogs {
   // Serializes concurrent flushes — the second caller awaits the first rather
   // than racing it and double-sending the same head-of-queue records.
   private _flushPromise: Promise<void> | null = null
+  // Head records evicted (FIFO) while a batch is in flight; the queue-advance
+  // subtracts these so it drops the sent records, not ones captured mid-send.
+  private _evictedSinceAdvance = 0
+  // Consecutive failed flushes; drives exponential backoff on the retry timer.
+  // A successful flush resets it to 0.
+  private _consecutiveFlushFailures = 0
 
   // Fixed-window rate cap. Tumbling (not sliding) for cheap arithmetic on the
   // hot path. Window rolls the first time `captureLog` fires after the window
@@ -34,7 +39,7 @@ export class PostHogLogs {
   private _droppedWarned = false
 
   constructor(
-    private readonly _instance: PostHogCoreStateless,
+    private readonly _instance: LogsHost,
     private readonly _config: ResolvedPostHogLogsConfig,
     private readonly _logger: Logger,
     private readonly _getContext: () => LogSdkContext,
@@ -47,12 +52,38 @@ export class PostHogLogs {
     private readonly _waitForStoragePersist: () => Promise<void> = () => Promise.resolve()
   ) {
     this._maxBufferSize = _config.maxBufferSize
+    // Never below the flush trigger: a smaller eviction cap would stop the
+    // size-based flush from ever firing. Collapses to `maxBufferSize` when unset.
+    this._maxQueueSize = Math.max(_config.maxQueueSize ?? _config.maxBufferSize, _config.maxBufferSize)
     this._flushIntervalMs = _config.flushIntervalMs
     this._maxBatchRecordsPerPost = _config.maxBatchRecordsPerPost
     this._rateCapWindowMs = _config.rateCapWindowMs
     this._maxLogsPerInterval = _config.maxLogsPerInterval
   }
 
+  /**
+   * Clears the flush timer and rate-cap state. The host owns the record queue
+   * and clears it separately (the browser empties its in-memory store).
+   */
+  reset(): void {
+    this._clearFlushTimer()
+    this._flushPromise = null
+    this._intervalWindowStart = 0
+    this._intervalLogCount = 0
+    this._droppedWarned = false
+    this._evictedSinceAdvance = 0
+    this._consecutiveFlushFailures = 0
+    this._maxBatchRecordsPerPost = this._config.maxBatchRecordsPerPost
+  }
+
+  // Call when connectivity is restored: clear the failure backoff and flush now,
+  // so records don't wait out a (possibly minutes-long) backoff delay after the
+  // network returns. The host owns connectivity detection (web: `online` event).
+  onReconnect(): void {
+    this._consecutiveFlushFailures = 0
+    this._flushInBackground()
+  }
+
   captureLog(options: CaptureLogOptions): void {
     if (this._instance.isDisabled) {
       return
@@ -70,8 +101,10 @@ export class PostHogLogs {
     if (filtered === null) {
       return
     }
-    // beforeSend could return a record with empty body — treat as drop.
+    // beforeSend could return a record with empty body — drop it, mirroring the
+    // null-return path so both beforeSend drops surface the same diagnostic.
     if (!filtered.body) {
+      this._logger.info(`Log was rejected in beforeSend function`)
       return
     }
 
@@ -196,6 +229,12 @@ export class PostHogLogs {
     let sentCount = 0
 
     while (queue.length > 0 && sentCount < originalQueueLength) {
+      // Reset per batch so the advance below counts only evictions during THIS
+      // batch's send. Evictions during the persist await or between iterations
+      // are already reflected in the next iteration's queue read, so they must
+      // not carry into the next batch's drop math.
+      this._evictedSinceAdvance = 0
+
       const batchSize = Math.min(queue.length, this._maxBatchRecordsPerPost)
       const batch = queue.slice(0, batchSize)
       const records = batch.map((e) => e.record)
@@ -250,36 +289,19 @@ export class PostHogLogs {
   }
 
   private async _persistQueueAdvance(consumed: number): Promise<void> {
-    // Re-read the queue in case captures landed mid-flush, then drop the head.
+    // Re-read in case captures landed mid-flush. Subtract head records the FIFO cap
+    // evicted during the send (already-sent records that left the queue), so we drop
+    // only the still-present sent records, not ones captured during the send.
+    const evicted = this._evictedSinceAdvance
+    const drop = Math.max(0, consumed - evicted)
     const refreshed = this._instance.getPersistedProperty<BufferedLogEntry[]>(PostHogPersistedProperty.LogsQueue) ?? []
-    this._instance.setPersistedProperty(PostHogPersistedProperty.LogsQueue, refreshed.slice(consumed))
-    // Wait for the advance to hit disk before the next batch sends, matching
-    // events' `flushStorage()` contract. Prevents duplicates if the app crashes
-    // after the HTTP success but before the queue-advance persists.
+    this._instance.setPersistedProperty(PostHogPersistedProperty.LogsQueue, refreshed.slice(drop))
+    // Persist before the next batch sends so a crash after HTTP success can't dupe.
     await this._waitForStoragePersist()
   }
 
-  /**
-   * OTLP resource attributes for every batch.
-   *
-   * Layout: user `resourceAttributes` spread first, then SDK-controlled
-   * keys layered on top so users cannot accidentally clobber them. Most logs
-   * backends index on `service.name` and `telemetry.sdk.*` for routing,
-   * SDK-version dashboards, and bug-correlation; letting a stray user key
-   * overwrite them silently breaks ingestion attribution. The dedicated
-   * `serviceName` / `environment` / `serviceVersion` config fields are the
-   * supported way to override `service.name` / `deployment.environment` /
-   * `service.version`.
-   */
   private _buildResourceAttributes(): Record<string, LogAttributeValue> {
-    return {
-      ...this._config.resourceAttributes,
-      'service.name': this._config.serviceName || 'unknown_service',
-      ...(this._config.environment && { 'deployment.environment': this._config.environment }),
-      ...(this._config.serviceVersion && { 'service.version': this._config.serviceVersion }),
-      'telemetry.sdk.name': this._instance.getLibraryId(),
-      'telemetry.sdk.version': this._instance.getLibraryVersion(),
-    }
+    return buildResourceAttributes(this._config, this._instance.getLibraryId(), this._instance.getLibraryVersion())
   }
 
   private _enqueue(entry: BufferedLogEntry): void {
@@ -290,28 +312,50 @@ export class PostHogLogs {
     }
 
     const queue = this._instance.getPersistedProperty<BufferedLogEntry[]>(PostHogPersistedProperty.LogsQueue) ?? []
-    if (queue.length >= this._maxBufferSize) {
+    // Drop the oldest only above the eviction cap, not at the flush trigger, so a
+    // burst is held while the async flush drains.
+    if (queue.length >= this._maxQueueSize) {
       queue.shift()
+      this._evictedSinceAdvance++
       this._logger.info('Logs queue is full, dropping oldest record.')
     }
     queue.push(entry)
     this._instance.setPersistedProperty(PostHogPersistedProperty.LogsQueue, queue)
 
-    // Threshold trigger: at-capacity means flushing now reclaims space before
-    // the next capture has to shift something out.
+    // Flush trigger: drain now rather than waiting for the timer. The queue may
+    // grow past this up to the eviction cap while the flush is in flight.
     if (queue.length >= this._maxBufferSize) {
       this._flushInBackground()
       return
     }
 
-    // Timer trigger: only arm one timer at a time. A subsequent enqueue within
-    // the window shouldn't reschedule — that would keep pushing the flush out.
-    if (!this._flushTimer) {
-      this._flushTimer = safeSetTimeout(() => {
-        this._flushTimer = undefined
-        this._flushInBackground()
-      }, this._flushIntervalMs)
+    // Arm one timer at a time; re-arming within the window would push the flush out.
+    this._armFlushTimer()
+  }
+
+  // Arms the flush timer if none is pending. One-shot: the callback clears the
+  // handle so the next enqueue (or a flush that left records) schedules again.
+  private _armFlushTimer(delayMs: number = this._flushIntervalMs): void {
+    if (this._flushTimer) {
+      return
     }
+    this._flushTimer = safeSetTimeout(() => {
+      this._flushTimer = undefined
+      this._flushInBackground()
+    }, delayMs)
+  }
+
+  // Retry delay after a flush that left records: the first retry is at the base
+  // interval, then exponential backoff (capped) so a sustained outage isn't
+  // retried every interval.
+  private _nextFlushDelay(): number {
+    const exponent = Math.min(Math.max(0, this._consecutiveFlushFailures - 1), MAX_FLUSH_BACKOFF_EXPONENT)
+    return this._flushIntervalMs * 2 ** exponent
+  }
+
+  private _hasQueuedRecords(): boolean {
+    const queue = this._instance.getPersistedProperty<BufferedLogEntry[]>(PostHogPersistedProperty.LogsQueue)
+    return !!queue && queue.length > 0
   }
 
   /**
@@ -371,9 +415,24 @@ export class PostHogLogs {
   }
 
   private _flushInBackground(): void {
-    void this.flush().catch((err) => {
-      this._logger.error('PostHog logs flush failed:', err)
-    })
+    void this.flush()
+      .then(
+        () => {
+          this._consecutiveFlushFailures = 0
+        },
+        (err) => {
+          this._consecutiveFlushFailures++
+          this._logger.error('PostHog logs flush failed:', err)
+        }
+      )
+      .finally(() => {
+        // Records remaining (transient failure or mid-flush captures) would otherwise
+        // sit undelivered on a quiet page; re-arm so the timer retries them, backing
+        // off on consecutive failures.
+        if (!this._instance.isDisabled && this._hasQueuedRecords()) {
+          this._armFlushTimer(this._nextFlushDelay())
+        }
+      })
   }
 
   private _clearFlushTimer(): void {

package/src/logs/logs-utils.ts

@@ -9,7 +9,7 @@ import type {
   OtlpSeverityEntry,
   OtlpSeverityText,
 } from '@posthog/types'
-import type { LogSdkContext } from './types'
+import type { LogSdkContext, ResolvedPostHogLogsConfig } from './types'
 import { isArray, isBoolean, isNull, isUndefined } from '../utils'
 
 // ============================================================================
@@ -168,6 +168,35 @@ export function buildOtlpLogRecord(options: CaptureLogOptions, sdkContext: LogSd
 // OTLP envelope construction
 // ============================================================================
 
+/**
+ * OTLP resource attributes for every batch, shared by the core flush path and
+ * SDK-specific paths that bypass it (e.g. the browser's synchronous sendBeacon
+ * drain). Having one builder keeps those paths from drifting.
+ *
+ * Layout: user `resourceAttributes` spread first, then SDK-controlled keys
+ * (`service.name`, `deployment.environment`, `service.version`,
+ * `telemetry.sdk.*`) layered on top so a stray user key can't clobber the
+ * ingestion-attribution keys. The dedicated `serviceName` / `environment` /
+ * `serviceVersion` config fields are the supported way to override the first
+ * three; each SDK resolves its own `service.name` default before this point, so
+ * the `unknown_service` fallback here only fires if a config slips through with
+ * an empty `serviceName`.
+ */
+export function buildResourceAttributes(
+  config: ResolvedPostHogLogsConfig,
+  scopeName: string,
+  scopeVersion: string
+): Record<string, LogAttributeValue> {
+  return {
+    ...config.resourceAttributes,
+    'service.name': config.serviceName || 'unknown_service',
+    ...(config.environment && { 'deployment.environment': config.environment }),
+    ...(config.serviceVersion && { 'service.version': config.serviceVersion }),
+    'telemetry.sdk.name': scopeName,
+    'telemetry.sdk.version': scopeVersion,
+  }
+}
+
 /**
  * Wraps a list of records in the OTLP `resourceLogs` envelope.
  *

package/src/logs/types.ts

@@ -11,6 +11,7 @@ export type {
   OtlpKeyValue,
   OtlpLogRecord,
   OtlpLogsPayload,
+  BeforeSendLogFn,
 } from '@posthog/types'
 
 /**
@@ -39,44 +40,34 @@ export interface LogSdkContext {
 import type { Logger as CaptureLoggerType } from '@posthog/types'
 export type CaptureLogger = CaptureLoggerType
 
-import type { LogAttributeValue, CaptureLogOptions, OtlpLogRecord } from '@posthog/types'
+import type {
+  LogAttributeValue,
+  CaptureLogOptions,
+  OtlpLogRecord,
+  OtlpLogsPayload,
+  BeforeSendLogFn,
+} from '@posthog/types'
+import type { PostHogPersistedProperty } from '../types'
+import type { SendLogsBatchOutcome } from '../posthog-core-stateless'
 
 export interface BufferedLogEntry {
   record: OtlpLogRecord
 }
 
 /**
- * Pre-send filter. Inspect, mutate, or drop a captured record before it
- * enters the rate-cap or the queue. Return the (possibly transformed) record
- * to keep it; return `null` to drop it.
- *
- * Configure as a single fn or an array. Arrays form a left-to-right chain:
- * each fn receives the previous fn's return value. A `null` from any link
- * short-circuits the chain and drops the record.
- *
- * Runs *before* the rate cap so dropped records don't consume the
- * per-interval budget. Throwing fns are logged and skipped — the chain
- * continues with the previous return value, so a buggy filter degrades to a
- * no-op rather than crashing `captureLog()`.
- *
- * @example Redact secrets from log bodies
- * ```ts
- * logs: {
- *   beforeSend: (record) => ({
- *     ...record,
- *     body: record.body.replace(/api_key=\S+/g, 'api_key=[REDACTED]'),
- *   }),
- * }
- * ```
- *
- * @example Drop noisy debug logs in production
- * ```ts
- * logs: {
- *   beforeSend: (record) => (record.level === 'debug' ? null : record),
- * }
- * ```
+ * The minimal host surface `PostHogLogs` depends on. `PostHogCoreStateless`
+ * satisfies it structurally (mobile/node); the browser supplies an adapter
+ * backed by its own persistence and request layer.
  */
-export type BeforeSendLogFn = (record: CaptureLogOptions) => CaptureLogOptions | null
+export interface LogsHost {
+  readonly isDisabled: boolean
+  readonly optedOut: boolean
+  getPersistedProperty<T>(key: PostHogPersistedProperty): T | undefined
+  setPersistedProperty<T>(key: PostHogPersistedProperty, value: T | null): void
+  _sendLogsBatch(payload: OtlpLogsPayload): Promise<SendLogsBatchOutcome>
+  getLibraryId(): string
+  getLibraryVersion(): string
+}
 
 /**
  * Configuration for the logs feature on `new PostHog(key, { logs: ... })`.
@@ -87,7 +78,7 @@ export interface PostHogLogsConfig {
   /**
    * Service name attached to every record as the OTLP `service.name`
    * resource attribute. Used by the Logs UI for filtering / grouping.
-   * Default: `'unknown_service'`.
+   * Defaults to `'unknown_service'` when unset.
    */
   serviceName?: string
 
@@ -121,11 +112,11 @@ export interface PostHogLogsConfig {
   flushIntervalMs?: number
 
   /**
-   * Max records held in memory before the queue evicts the oldest on push
-   * (FIFO). Bounds memory footprint and on-disk-queue size. When the buffer
-   * hits this size, an immediate flush is triggered to reclaim space; if
-   * the flush hasn't completed before the next capture, the oldest record
-   * is shifted out. Default: 100.
+   * Number of buffered records that triggers an immediate flush. Records also
+   * flush on the periodic interval and on `shutdown()`. The queue can grow past
+   * this while an async flush is in flight (e.g. during a synchronous burst); a
+   * separate, larger memory backstop evicts the oldest only once the queue
+   * exceeds the per-interval rate cap. Default: 100.
    */
   maxBufferSize?: number
 
@@ -182,6 +173,10 @@ export interface PostHogLogsConfig {
 // Flat names internally — public API uses `rateCap: { maxLogs, windowMs }`.
 export interface ResolvedPostHogLogsConfig extends Omit<PostHogLogsConfig, 'rateCap'> {
   maxBufferSize: number
+  // Eviction cap: the queue drops the oldest record once it exceeds this. Separate
+  // from `maxBufferSize` (the flush trigger) so a burst is held, not evicted, while
+  // the async flush drains. Defaults to `maxBufferSize` when unset.
+  maxQueueSize?: number
   flushIntervalMs: number
   maxBatchRecordsPerPost: number
   rateCapWindowMs: number

package/src/posthog-core.ts

@@ -1052,6 +1052,9 @@ export abstract class PostHogCore extends PostHogCoreStateless {
     return result?.variant ?? result?.enabled
   }
 
+  /**
+   * @deprecated Use `getFeatureFlagResult()` instead, which returns the flag value and payload from a single evaluation.
+   */
   getFeatureFlagPayload(key: string): JsonType | undefined {
     const result = this._getFeatureFlagResult(key, { missingFlagBehavior: 'getFeatureFlagPayload', sendEvent: false })
     return result?.payload