Skip to main content

Diagnostics & Error Reporting

Call Telemetry has a single toggle that controls outbound error reporting, diagnostics, and usage analytics. It is off by default. This page documents the toggle, what turning it on enables, how it behaves when outbound access is blocked, and exactly what is and is not captured. For the legal/subprocessor detail (who processes this data and how to request deletion), see Privacy, Data Processing & Telemetry Subprocessors.

Where the toggle lives​

  • First-boot wizard: a dedicated telemetry step presents the toggle as a card, off by default, with an affirmative opt-in call to action — "Enable error reporting & diagnostics (recommended)." No option is pre-selected; you choose on or off.
  • Settings: the same toggle is available under Settings > System & Infrastructure at any time, with an upgraded status view (below) and a telemetry-health panel showing recent send counts.
  • Headless/offline appliances: sudo ct telemetry show displays the current state; sudo ct telemetry set --enabled=true|false changes it without a browser session.
  • Support bundle: the current toggle state is included in every generated support bundle.

Every change made in Settings is written to a local audit log entry, independent of whether the change succeeded in reaching PostHog.

What "on" enables​

Turning the toggle on enables all four categories described in Privacy, Data Processing & Telemetry Subprocessors: errors, error-level logs, operational diagnostics, and usage analytics. There is no separate control today for enabling only a subset of these — see "What we don't do" below for why, and the environment kill switches for the one exception (error/log capture can be force-disabled independently by an operator).

An install-level toggle, set from the same wizard choice and editable in Settings, separately governs events that are not tied to any single organization — appliance startup, database connectivity, and scheduler health. This exists so a single-org assumption never silently attributes system-level events to the wrong organization (or to whichever organization happens to be first in the database) on a multi-org appliance.

Requested-vs-effective state​

Settings shows two states side by side, because the toggle you set and what actually happens can differ:

  • Requested: what the toggle is set to (on/off), from the organization's or the install's stored preference.
  • Effective: what is actually happening right now, accounting for:
    • No POSTHOG_PROJECT_TOKEN configured on the appliance (everything off, regardless of the requested state).
    • An environment kill switch forcing diagnostics off (see below).
    • Outbound network access to the PostHog endpoint being blocked or unreachable.

If requested and effective disagree, Settings shows why (missing token, kill switch, or blocked egress) so an administrator is never left wondering whether a toggle they enabled is actually doing anything.

Air-gapped and blocked-egress behavior​

On an air-gapped appliance, or one with firewalled/blocked egress to the PostHog endpoint, diagnostics degrade silently: send attempts fail without retry storms, without blocking the request or job that triggered them, and without filling logs with repeated connection-failure noise. The application does not depend on reaching PostHog for anything — normal operation is unaffected whether the toggle is on, off, or on-but-unreachable.

The effective state shown in Settings reflects this: an air-gapped install with the toggle requested "on" shows effective state "blocked" (or "no egress"), not "on," so support and administrators aren't misled about what data, if any, is actually reaching PostHog.

Environment-level kill switches​

Two environment variables let an operator force diagnostics behavior independent of the in-app toggle, useful for fleet-wide policy, CI/lab isolation, or an emergency stop:

VariableDefaultEffect
POSTHOG_BACKEND_ENABLEDEnabled automatically on a named release build outside CI; off in CIMaster switch for all backend telemetry. Set to false to force every category off appliance-wide, regardless of any org or install toggle.
POSTHOG_ERROR_TRACKING_ENABLEDOn when the backend switch above is onScoped kill switch for the error and error-level log categories only. Set to false to stop error/log capture while leaving operational diagnostics and usage analytics on the org toggle's setting.

These are appliance-level environment settings, not something set from the UI — they're for operators who need a fleet policy or an emergency stop that doesn't depend on every organization's individual setting.

Coverage statement — what is and is not captured​

Call Telemetry's error reporting is not a drop-in replacement for a dedicated crash-reporting SDK, and we don't claim feature parity with tools like Sentry. Here is the honest picture:

Captured today:

  • Unhandled backend (API) exceptions, with stack traces.
  • Error and critical-severity log lines.
  • Failing background job exceptions, with scrubbed job arguments/metadata.
  • Frontend (browser) unhandled JavaScript errors and unhandled promise rejections.
  • 5xx and network-failure API responses observed by the frontend (not expected 4xx responses, retries, or user-cancelled requests).

Not captured (known gaps, not planned near-term):

  • Errors inside web workers.
  • Errors thrown by cross-origin third-party scripts (browser security model blocks most detail here regardless of vendor).
  • Non-crash error returns — a function that returns an error value instead of throwing is not automatically captured.
  • Breadcrumbs (a timeline of preceding user actions/events leading up to an error).
  • Crash-free session/user rate metrics.
  • Session replay network request/response bodies — session replay, where enabled, never records request or response payloads, and console output is not recorded.

If you rely on any of the gaps above for an internal SLA or incident process, plan for that gap explicitly rather than assuming Call Telemetry's error reporting covers it.

Last updated on by Call Telemetry