Platform 11 of 12·OS Layer 10 (Observability Layer)·Required in all deployment modes

Scope of this page. Reference material for the PostHog platform: what it is, what it is normally used for, and how and why Synedrix OS uses it. It is descriptive, not normative — where this page and a canonical spec in docs/os/ disagree, the canonical spec wins. Platform responsibilities are set by Tech Stack §10.

What PostHog is

PostHog describes itself as “the open source platform for building self-driving products”, which “provides every tool you need to build a successful product, and captures all the context agents need to proactively diagnose problems, uncover opportunities, and ship fixes.”

Everything in PostHog is built on one data model. Products are views over the same events, persons and properties:

ConceptOfficial definition
Event“An event is the core unit of data in PostHog. It represents an interaction a user has with your app or website.” An event carries an event name, a distinct_id, an ISO 8601 timestamp, and properties.
PropertyMetadata attached to an event, person or group, used for filtering, breakdowns, cohorts and targeting. Properties prefixed with $ are PostHog defaults ($current_url, $browser).
Person“People in PostHog represent the users behind your events.” People have person profiles with properties that can be filtered on, turned into cohorts, and used for feature flag and A/B test targeting.
Distinct ID“Every event in PostHog has a distinct ID – a unique identifier that groups events together. However, not every distinct ID has a person profile.” Events captured before identify is called use an anonymous distinct ID generated by the SDK; after identify, PostHog creates a person profile and links it to both the identified distinct ID and the earlier anonymous events from that session.
InsightA saved query over events and persons. The documented insight types are trends, funnels, retention, user paths, stickiness, lifecycle and correlation analysis. Insights are saved to dashboards, shared, and alerted on.
Feature flag“Feature flags let you ship code without shipping the feature. Wrap a change in a flag, roll it out to 1% of users, watch what happens, and turn it off the moment something looks wrong – no redeploy, no hotfix.” Targeting is “by person property, cohort, or group”, not only by percentage.
Experiment“Experiments let you test a change against a control and find out whether it actually worked.” Variants are defined, metrics chosen, and PostHog “randomizes your users, tracks their exposures, and runs the statistics”, Bayesian or frequentist.

The distinction that matters architecturally is event against person. An event is an immutable interaction with a timestamp and properties; a person is a mutable profile that events are attached to through distinct IDs. Product analytics is the aggregate view of events; feature flags and experiments are the targeting view of persons. Both read the same store, which is why an experiment needs no new instrumentation: “Because experiments run on the same events and feature flags you already have in PostHog, you don’t need new instrumentation to measure a result.”

The products PostHog documents on top of that model, in its own words:

  • Product analytics — “Product analytics answers what people actually do in your product.” Autocaptured or manually instrumented events, analysed by visualisation or SQL.
  • Feature flags — “Safely roll out features to select users or cohorts with feature flags.”
  • Experiments — “Test changes and measure their statistical impact on goal metrics.”
  • Session replay — “Session replay records what real users do in your product and plays it back like a DVR, with a synced DevTools panel showing console logs, network requests, and errors at the exact moment they happened.”
  • Surveys — “Ask anything with our collection of no-code survey templates, or build custom surveys with our survey builder”, targeted on “the same events, properties, cohorts, and feature flags you use everywhere else”.
  • Data warehouse — “The data warehouse brings your business data into PostHog and puts it next to your product data”, queryable “alongside your events, persons, and sessions in one SQL query”.

What PostHog is normally used for

The general-purpose cases PostHog’s own documentation leads with:

  • Understanding what users actually do — trends, funnels, retention and path analysis over autocaptured or explicitly instrumented events, saved to dashboards and alerted on when they move.
  • Shipping changes safely — wrapping a change in a flag, releasing it to a percentage or a targeted cohort, and turning it off without a redeploy.
  • Deciding whether a change worked — running an experiment on an existing flag and existing events, and getting a statistical result rather than an impression.
  • Diagnosing a specific failure — jumping from an insight into the session replay of the users behind it.
  • Asking users directly — surveys targeted by the same properties and cohorts used elsewhere.
  • Joining product data to business data — syncing external sources into the warehouse and querying them next to events in SQL.

The common thread is that PostHog owns behavioural questions about usage and outcome: who did what, how often, whether a change moved the number — not how the underlying system executed.

How Synedrix OS uses it

PostHog is the behavioural analytics platform of Synedrix OS and sits at Layer 10 of the twelve-layer taxonomy, alongside Langfuse and the operational-monitoring platforms. It is required in all three deployment modes.

Its access pattern is asynchronous write and read. Nothing on a workflow’s critical path blocks on PostHog. Analytics emission is fire-and-forget; the one synchronous dependency is a feature flag read, and that read must always have a declared fail-safe (see below).

flowchart LR
  n1([PostHog]):::term
  subgraph What it owns
    n2[Workflow analytics]:::agent
    n3[Feature flags]:::agent
    n4[A/B experiments]:::agent
    n5[Business decision analytics]:::agent
  end
  n1 --> n2
  subgraph What it does not own
    n6[Raw time-series and rolling temporal aggregates]:::warn
    n7[QuestDB]:::term
    n6 --> n7
    n8[Audit-grade invocation evaluation and review records]:::warn
    n9[Supabase PG17]:::term
    n8 --> n9
    n10[Whether a specific action is permitted]:::warn
    n11[Policy Guard Agent]:::term
    n10 --> n11
    n12[Immutable lineage and audit reconstruction]:::warn
    n13[Audit Lineage Agent]:::term
    n12 --> n13
  end
  n1 --> n6
  subgraph Why PostHog
    n14[One data model behind all four responsibilities]:::term
    n15[Behavioural questions genuinely are a distinct layer]:::term
    n16[SQL access to the underlying data]:::term
    n17[The core is open source and self-hostable]:::term
  end
  n1 --> n14

What it owns

Per Tech Stack §10, PostHog owns:

  • Workflow analytics
  • Feature flags
  • A/B experiments
  • Business decision analytics

Workflow analytics. Workflow and agent lifecycle events are emitted to PostHog as behavioural events carrying the canonical correlation identifiers. What this answers is the product-level question set: which workflows are actually run and how often, which are triggered and then abandoned, where a run stalls, which agents are invoked most, how often a human intervention point is reached and how often the human approves against rejects. The Agent Evaluation Spec states the split directly — PostHog answers “How is the agent being used? What workflows invoke it most?” A funnel over workflow lifecycle events is the natural shape for a governed workflow, because a governed workflow is a funnel: triggered → validated → agent-invoked → approval requested → approved → executed. The drop-off between two of those steps is a product signal, not an infrastructure signal.

Feature flags as a governed rollout mechanism. A flag is how a capability is progressively enabled for a concrete runtime without a redeploy, which makes it a Layer 12 (Business Instance Layer) control surface. Per the Responsibility Matrix, the OS owns the framework, the domain pack contributes the registry entries, and the business instance decides which workflows and agents are enabled. Flags are the runtime expression of that last column: enabling a new domain-pack agent for one instance before the rest, staging a workflow from shadow to advisory to acting, or holding an execute-scope capability behind an operator-set flag.

Two rules apply to any flag used this way:

  1. A flag read must declare a fail-safe. If PostHog is unreachable or the flag is unavailable, the workflow must route to the safe branch, not assume the permissive one. The Synedrix Trading pack states this explicitly for its live/paper platform selector: on flag failure it always routes to paper.
  2. A flag is not a policy engine. A flag decides whether a capability is switched on for this instance. It never decides whether a specific action is permitted — that is the Policy Guard Agent (os-agt-002), and routing an authority decision through a flag would bypass governance.

Experiments. Agent and prompt variants can be A/B tested at the behavioural level: variant A against variant B measured on task completion, human-approval rate, rework rate, escalation rate, time-to-outcome. The experiment runs on the flag that already gates the variant and the events already being emitted.

Business decision analytics. The Analytics Agent (os-agt-005) holds PostHog (read) in its systems_allowed and a PostHog event query tool, and reads it alongside QuestDB, Supabase and Langfuse to produce cross-domain reports. Its decision scope is recommend — it reports, it does not act.

What it does not own

Non-overlapping platform responsibility is the stated design principle of this stack, and Layer 10 is where the temptation to overlap is strongest, because three platforms all look like “monitoring”. They are not interchangeable:

ConcernOwner
LLM and agent trace spans, prompt versions, token and cost attribution, model-output evaluation and quality scoringLangfuse (Layer 10)
Infrastructure health, service dashboards, alerting, SLOs, threshold breaches and alert routingGrafana (Layer 10)
Raw time-series and rolling temporal aggregates (cost_drift_pct over time, trust_trend_30d, tool success-rate windows)QuestDB (Layer 7)
Audit-grade invocation, evaluation and review recordsSupabase PG17 (Layer 7)
Whether a specific action is permittedPolicy Guard Agent (os-agt-002)
Immutable lineage and audit reconstructionAudit & Lineage Agent (os-agt-008), read-only

The boundary against Langfuse is the one to hold most carefully, since both platforms have opinions about agent quality. Langfuse owns the LLM level: the trace span, the prompt version that produced it, the token cost, the evaluation score on the model output. PostHog owns the behavioural level: whether the workflow that contained that call was completed, repeated, abandoned, or overridden by a human. A hallucination score is a Langfuse fact. “Operators reject this agent’s proposals 40% of the time” is a PostHog fact. The Observability Metrics Spec §14 assigns trace-correlated metrics to Langfuse and audit-grade records to Supabase precisely so that the same number is not computed twice in two places with two answers.

The boundary against Grafana is between operational health and product outcome. “The n8n worker pool is saturated” is Grafana. “Nobody uses this workflow” is PostHog. A page at three in the morning is Grafana’s; a quarterly question about which domain pack is earning its keep is PostHog’s.

The boundary against QuestDB is between raw temporal truth and behavioural interpretation. QuestDB holds the high-throughput series and the materialised aggregates that dashboards read; PostHog holds cohort-shaped, person-and-event-shaped analysis. PostHog is not a general time-series database and must not be used as one.

How it is operated

Events reach PostHog through the event bus rather than through bespoke per-workflow instrumentation. Per the Event Taxonomy Standard, the observability layer consumes the same canonical envelope every other consumer does, and emission is not optional for the declared lifecycle events. Payloads carry identifiers and status, not full result bodies — the full record stays in Supabase.

The mapping onto PostHog’s data model is deliberate: the event is the workflow or agent lifecycle event, and the distinct ID is the identity the analysis is grouped by. Choosing what plays the part of “person” is a design decision per domain pack — an operator, a tenant, or a business entity — and it must be chosen once and held, because retention, funnels and flag targeting all derive from it.

Self-hosted PostHog instances send routine usage reports to PostHog’s own servers by default. PostHog documents these as containing “no identifiable or unique information from your users, only anonymized, aggregated data”, and documents an OPT_OUT_CAPTURE environment variable to “Disable sending product usage data to PostHog.” Any Mode 2 or Mode 3 deployment should set it explicitly and enforce the block at the network layer as well, per the Deployment Model Spec.

Why PostHog

  • One data model behind all four responsibilities. Analytics, flags and experiments in Synedrix OS are the same question asked three ways — is this capability being used, should it be on, did changing it help. A platform where flags and experiments read the same event store removes a class of instrumentation drift.
  • Flags are the missing runtime control for Layer 12. Business instances need to enable capability progressively without a deployment. A flag service that is already integrated with the analytics that measure the rollout is a better fit than a standalone flag service plus a separate analytics tool.
  • Behavioural questions genuinely are a distinct layer. Governed autonomy is judged on adoption and human override rates, not only on model accuracy and uptime. Neither Langfuse nor Grafana answers that question, and forcing either to do so collapses a boundary the architecture depends on.
  • SQL access to the underlying data. Insights are not the only exit path; the warehouse and SQL surface mean a report can be produced without exporting to a fourth system.
  • The core is open source and self-hostable — with material caveats, set out below, that the rest of the stack does not carry.

Deployment and licensing

Self-hosting. PostHog’s self-hosting page opens: “PostHog is open-source and freely available for anyone to host themselves. We offer a free Docker Compose deployment under an MIT license.” The documented paths today are:

  • Docker Compose “hobby” deploy — a single-line installer (bin/deploy-hobby) on Linux. Documented requirements are “something equivalent to a Hetzner VM with 4 vCPU, 16GB RAM, and more than 30GB storage”.
  • Self Host TUI — a terminal-UI binary, documented as beta, with interactive and CI modes.

Kubernetes is no longer an option for new deployments. The self-hosting docs state: “New deployments of PostHog’s paid open source product using Kubernetes are no longer supported.”

Scale and support caveats, in PostHog’s own words. These are stated on the self-hosting page, the open-source disclaimer, and the repository README:

  • “Open source deployments should scale to approximately 100k events per month, after which we recommend migrating to a PostHog Cloud.” (README)
  • Self-hosted open-source deployment “is made for hobbyists or hosting PostHog in weird and wonderful ways (like in your basement)”; it runs “on a single machine, and thus is unlikely to scale past a couple 100ks events without significant effort in scaling.” (disclaimer)
  • “We do not provide customer support or offer guarantees for open source deployments.” (README)
  • “Self-hosted customers cannot receive commercial support from PostHog. Because hosting environments can vary so widely, we cannot answer tickets and cannot help debug.” (disclaimer)
  • “We’re unable to support recovery from data loss.” (disclaimer)
  • “All paid-plan features are Cloud-only.” (self-hosting page)

The disclaimer enumerates what “Cloud-only” excludes from a self-hosted instance. It includes several capabilities that are not peripheral to the Synedrix OS use case: correlation analysis, advanced paths, lifecycle insights, group analytics, data pipelines, insight and dashboard subscriptions, more than two alerts, one-year event retention, multi-environment support, group experiments, downloading session recordings, SAML, RBAC, audit logs, and custom data retention.

Air-gapped. PostHog’s egress documentation states: “You can run the open-source version of PostHog in an air-gapped environment, though it does require internet access to use the installation script.” Self-hosted instances otherwise “routinely send usage reports to our servers”; OPT_OUT_CAPTURE is the documented environment variable to “Disable sending product usage data to PostHog.”

Licence — read this carefully. The PostHog repository is not uniformly MIT. Per its LICENSE:

  • “All content that resides under the ee/ directory of this repository, if that directory exists, is licensed under the license defined in ee/LICENSE.”
  • “Content outside of the above mentioned directories or restrictions above is available under the ‘MIT Expat’ license.”
  • ee/LICENSE is “The PostHog Enterprise license”. It permits modification for development and testing without a subscription, but production use requires “agreement to, and are in compliance with, the PostHog Subscription Terms of Service” and a valid Enterprise licence, and states that “it is forbidden to copy, merge, publish, distribute, sublicense, and/or sell the Software.”
  • PostHog maintains a separate posthog-foss repository, described in the README as “purged of all proprietary code and features”, for anyone who needs “absolutely 💯% FOSS”.

So the accurate statement is: the bulk of PostHog is MIT Expat; the ee/ directory is proprietary and requires a commercial licence for production use. The blanket description “PostHog is open source under MIT” describes the majority of the repository, not the repository.

Open item. Tech Stack §10 records PostHog as “open source under MIT” with a “self-hosted version [that] stores all analytics data locally”, and lists it as required in all deployment modes; the Deployment Model Spec inventory records it as MIT, self-hostable via “Docker / Kubernetes”. Three parts of that need correction against what PostHog documents today. First, the licence is mixed — MIT Expat outside ee/, PostHog Enterprise License inside it. Second, Kubernetes self-hosting is stated as no longer supported for new deployments; the officially documented paths are a Docker Compose hobby deploy and a beta TUI. Third, and most material, PostHog scopes that self-hosted path at roughly 100k events per month, describes it as intended for hobbyists, offers no support or guarantees, and places a set of features Cloud-only — including group analytics, correlation analysis, data pipelines, audit logs and custom data retention. The claim that the self-hosted version stores all analytics data locally remains true of what it does store, and Mode 3 remains technically reachable, but the officially supported path for PostHog is now cloud-first, which sits in tension with Principle 11 (Open by default, sovereign by design) and with Mode 3’s prohibition on external calls. This is a platform-selection decision, not a documentation fix, and it is not resolved by this page. It needs an explicit decision and a correction to the canonical stack and deployment documents.

Official documentation

Synedrix OS · Platform reference · PostHog