:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
use std::hash::{Hash, Hasher};
use chrono::{DateTime, Utc};
use metrics::Counter;
use quick_cache::{sync, DefaultHashBuilder, Equivalent, Lifecycle, UnitWeighter};
use crate::{
metrics_consts::{
CACHE_EVICTIONS, CACHE_HITS, CACHE_MISSES, CACHE_REPLACEMENTS, UPDATES_CACHE,
},
types::{EventProperty, GroupType, PropertyParentType, PropertyValueType, Update},
};
// Per-subcache eviction observer. The `stats` feature of quick_cache is not
// enabled, so all cache hit/miss/eviction signal in this service comes from
// explicit metrics emitted here and in `contains_key`.
//
// quick_cache also calls `on_evict` with the old entry when `insert` finds the
// key already resident, so this counter includes the in-place replacements
// `Cache::insert` makes on purpose. Those are counted separately as
// CACHE_REPLACEMENTS; capacity evictions are the difference.
//
// Counter handles are resolved once at construction and reused: these paths run
// per update (and `on_evict` runs under the shard write lock), so a registry
// lookup per increment is measurable CPU. The metrics recorder must be installed
// before `Cache::new`, because a handle resolved earlier is a no-op forever.
#[derive(Clone)]
struct EvictingLifecycle {
evictions: Counter,
}
impl<K, V> Lifecycle<K, V> for EvictingLifecycle {
type RequestState = ();
fn begin_request(&self) -> Self::RequestState {}
fn on_evict(&self, _state: &mut Self::RequestState, _key: K, _val: V) {
self.evictions.increment(1);
}
}
type SubCache<K, V> = sync::Cache<K, V, UnitWeighter, DefaultHashBuilder, EvictingLifecycle>;
struct SubCacheEntry<K: Eq + Hash + Clone, V: Clone> {
cache: SubCache<K, V>,
hits: Counter,
misses: Counter,
replacements: Counter,
}
impl<K: Eq + Hash + Clone, V: Clone> SubCacheEntry<K, V> {
// Writes exactly what a plain `insert` would, and reports whether the write
// replaced a resident entry. quick_cache `replace` with `soft: false` takes
// the same `insert_existing` path as `insert` on a resident key (same
// segment, same `referenced` bump, same `on_evict`), and only differs by
// failing when the key is not resident. That failure is how a concurrent
// remove between the caller's peek and this write stays uncounted: the
// value then goes in through `insert`, as it would have anyway.
fn write(&self, key: K, value: V, peeked_resident: bool) -> InsertOutcome {
if !peeked_resident {
self.cache.insert(key, value);
return InsertOutcome::Inserted;
}
match self.cache.replace(key, value, false) {
Ok(()) => {
self.replacements.increment(1);
InsertOutcome::Replaced
}
Err((key, value)) => {
self.cache.insert(key, value);
InsertOutcome::Inserted
}
}
}
}
/// What `Cache::insert` did with an update. Only `Unchanged` skips the write,
/// and it does so on exactly the guards that predate this bookkeeping.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum InsertOutcome {
/// The row identity was not resident and is now.
Inserted,
/// The identity was resident and quick_cache replaced the entry in place,
/// whether or not the value differs.
Replaced,
/// A guard rejected the update before any write: an older or equal eventdef
/// bucket, or an untyped property over a typed one.
Unchanged,
}
fn build_subcache<K: Eq + Hash + Clone, V: Clone>(
capacity: usize,
label: &'static str,
) -> SubCacheEntry<K, V> {
let cache = sync::Cache::with(
capacity,
capacity as u64,
UnitWeighter,
DefaultHashBuilder::default(),
EvictingLifecycle {
evictions: metrics::counter!(CACHE_EVICTIONS, &[("cache", label)]),
},
);
SubCacheEntry {
cache,
hits: metrics::counter!(CACHE_HITS, &[("cache", label)]),
misses: metrics::counter!(CACHE_MISSES, &[("cache", label)]),
replacements: metrics::counter!(CACHE_REPLACEMENTS, &[("cache", label)]),
}
}
// Cache keys carry only the row identity Postgres enforces uniqueness on, and
// everything else about an update lives in the cache VALUE. Keying on the full
// update struct made every field variation a separate entry: a property whose
// detected type flips (null values, a stray "true", a date-looking string)
// occupied one slot per variant, and every event definition abandoned a dead
// entry each time its floored last_seen bucket rolled over.
/// Identity of a `posthog_eventdefinition` row. The floored `last_seen_at`
/// bucket is the cache value, so a rollover replaces it in place.
#[derive(Clone, Debug, Hash, Eq, PartialEq)]
struct EventDefKey {
team_id: i32,
project_id: i64,
name: String,
}
// Borrowed lookup forms. `contains_key` runs per update, so building an owned
// key (two String allocations) per lookup is measurable; these hash and compare
// identically to their owned counterparts. Field order must match the owned
// struct declaration, because the derived Hash hashes fields in that order.
struct EventDefKeyRef<'a> {
team_id: i32,
project_id: i64,
name: &'a str,
}
impl Hash for EventDefKeyRef<'_> {
fn hash<H: Hasher>(&self, state: &mut H) {
self.team_id.hash(state);
self.project_id.hash(state);
self.name.hash(state);
}
}
impl Equivalent<EventDefKey> for EventDefKeyRef<'_> {
fn equivalent(&self, key: &EventDefKey) -> bool {
self.team_id == key.team_id && self.project_id == key.project_id && self.name == key.name
}
}
/// Identity of a `posthog_propertydefinition` row: the ON CONFLICT key of the
/// upsert. Group types are keyed by name so the Unresolved form the producer
/// caches and the Resolved form the writer works with address the same entry.
/// The detected property type is the cache value: `None` upgrades to `Some`
/// with one write (mirroring the guarded DO UPDATE), any other flip is a no-op
/// for Postgres and stays a cache hit.
#[derive(Clone, Debug, Hash, Eq, PartialEq)]
struct PropDefKey {
team_id: i32,
project_id: i64,
name: String,
event_type: PropertyParentType,
group_name: Option<String>,
}
struct PropDefKeyRef<'a> {
team_id: i32,
project_id: i64,
name: &'a str,
event_type: PropertyParentType,
group_name: Option<&'a str>,
}
impl Hash for PropDefKeyRef<'_> {
fn hash<H: Hasher>(&self, state: &mut H) {
self.team_id.hash(state);
self.project_id.hash(state);
self.name.hash(state);
self.event_type.hash(state);
self.group_name.hash(state);
}
}
impl Equivalent<PropDefKey> for PropDefKeyRef<'_> {
fn equivalent(&self, key: &PropDefKey) -> bool {
self.team_id == key.team_id
&& self.project_id == key.project_id
&& self.name == key.name
&& self.event_type == key.event_type
&& self.group_name == key.group_name.as_deref()
}
}
fn group_name(group: &GroupType) -> &str {
match group {
GroupType::Unresolved(name) | GroupType::Resolved(name, _) => name,
}
}
pub struct Cache {
eventdefs: SubCacheEntry<EventDefKey, DateTime<Utc>>,
eventprops: SubCacheEntry<EventProperty, ()>,
propdefs: SubCacheEntry<PropDefKey, Option<PropertyValueType>>,
removed: Counter,
not_cached: Counter,
}
// TODO: next iter, try using unsync::Cache(s) here and manage sync access to each
// manually. This enables implementing new batch insert/remove APIs on this wrapper,
// since we rarely want to work with just one cache entry at a time in propdefs. I
// suspect small-batch updates would further reduce internal cache lock contention
// that can slow down our batch write threads, esp. when a write fails and we evict
impl Cache {
pub fn new(
eventdefs_capacity: usize,
eventprops_capacity: usize,
propdefs_capacity: usize,
) -> Self {
Self {
eventdefs: build_subcache(eventdefs_capacity, "eventdefs"),
eventprops: build_subcache(eventprops_capacity, "eventprops"),
propdefs: build_subcache(propdefs_capacity, "propdefs"),
removed: metrics::counter!(UPDATES_CACHE, &[("action", "removed")]),
not_cached: metrics::counter!(UPDATES_CACHE, &[("action", "not_cached")]),
}
}
pub fn eventdefs_len(&self) -> usize {
self.eventdefs.cache.len()
}
pub fn eventprops_len(&self) -> usize {
self.eventprops.cache.len()
}
pub fn propdefs_len(&self) -> usize {
self.propdefs.cache.len()
}
/// True when the cached state already covers this update, meaning the write
/// it stands for would change nothing in Postgres.
///
/// Lookups go through quick_cache `peek`, which does not mark the entry
/// referenced. Identity keys keep the working set within capacity and the
/// reader-side batch filter drops rows Postgres already has, so eviction
/// recency cannot change outcomes and a cache miss costs a filtered probe,
/// not a useless write. Marking every probe only adds S3-FIFO promotion
/// work under the shard locks on the hottest path in the service. If a
/// subcache pins at full again with an eroding hit rate, grow its capacity
/// instead of re-adding per-probe marking.
pub fn contains_key(&self, key: &Update) -> bool {
let (covered, hits, misses) = match key {
Update::Event(def) => {
let lookup = EventDefKeyRef {
team_id: def.team_id,
project_id: def.project_id,
name: &def.name,
};
// Only a bucket newer than the cached one demands a re-issue.
// Producers interleave, so an update from the previous bucket
// can be checked after a rollover was cached; the newer write
// already refreshed the row, so the older update stays covered.
let covered = self
.eventdefs
.cache
.peek(&lookup)
.is_some_and(|bucket| bucket >= def.last_seen_at);
(covered, &self.eventdefs.hits, &self.eventdefs.misses)
}
Update::EventProperty(ep) => (
self.eventprops.cache.peek(ep).is_some(),
&self.eventprops.hits,
&self.eventprops.misses,
),
Update::Property(def) => {
let lookup = PropDefKeyRef {
team_id: def.team_id,
project_id: def.project_id,
name: &def.name,
event_type: def.event_type,
group_name: def.group_type_index.as_ref().map(group_name),
};
let covered = match self.propdefs.cache.peek(&lookup) {
// An untyped cached row upgrades once when a typed sighting
// arrives; every other combination cannot change the row.
Some(cached) => !(cached.is_none() && def.property_type.is_some()),
None => false,
};
(covered, &self.propdefs.hits, &self.propdefs.misses)
}
};
if covered {
hits.increment(1);
} else {
misses.increment(1);
}
covered
}
// Both valued subcaches only move forward: a newer last_seen bucket, or a
// None to Some type upgrade. Concurrent producers interleave their
// contains_key/insert pairs, so an insert can arrive after another producer
// cached fresher state; replacing that state would make the next sighting
// miss and re-issue a write Postgres treats as a no-op. The peek-then-insert
// pairs below race too, but losing that race costs one redundant upsert.
//
// Every write that reaches quick_cache here is the same write with or
// without the outcome bookkeeping: an equal value re-inserted over a
// resident key still goes through, so the entry keeps the `referenced`
// credit quick_cache grants on that path. The peek only decides whether
// the write is issued as a `replace` (counted) or an `insert`.
//
// The peek and the write are separate lock acquisitions. A concurrent
// producer can insert the same new key in between, which makes the second
// write an uncounted replacement. That race is the one already measured by
// DUPLICATES_IN_BATCH and is far too rare to move the replacement counter.
pub fn insert(&self, key: Update) -> InsertOutcome {
match key {
Update::Event(def) => {
let lookup = EventDefKeyRef {
team_id: def.team_id,
project_id: def.project_id,
name: &def.name,
};
let cached = self.eventdefs.cache.peek(&lookup);
if cached.is_some_and(|bucket| bucket >= def.last_seen_at) {
return InsertOutcome::Unchanged;
}
let key = EventDefKey {
team_id: def.team_id,
project_id: def.project_id,
name: def.name,
};
self.eventdefs
.write(key, def.last_seen_at, cached.is_some())
}
Update::EventProperty(ep) => {
let resident = self.eventprops.cache.peek(&ep).is_some();
self.eventprops.write(ep, (), resident)
}
Update::Property(def) => {
let lookup = PropDefKeyRef {
team_id: def.team_id,
project_id: def.project_id,
name: &def.name,
event_type: def.event_type,
group_name: def.group_type_index.as_ref().map(group_name),
};
let cached = self.propdefs.cache.peek(&lookup);
if def.property_type.is_none() && matches!(cached, Some(Some(_))) {
return InsertOutcome::Unchanged;
}
let key = PropDefKey {
team_id: def.team_id,
project_id: def.project_id,
name: def.name,
event_type: def.event_type,
group_name: def.group_type_index.map(|g| match g {
GroupType::Unresolved(name) | GroupType::Resolved(name, _) => name,
}),
};
self.propdefs
.write(key, def.property_type, cached.is_some())
}
}
}
// we don't return the retrieved KV since propdefs doesn't require it
pub fn remove(&self, key: &Update) {
let removed = match key {
Update::Event(def) => self
.eventdefs
.cache
.remove(&EventDefKeyRef {
team_id: def.team_id,
project_id: def.project_id,
name: &def.name,
})
.is_some(),
Update::EventProperty(ep) => self.eventprops.cache.remove(ep).is_some(),
Update::Property(def) => self
.propdefs
.cache
.remove(&PropDefKeyRef {
team_id: def.team_id,
project_id: def.project_id,
name: &def.name,
event_type: def.event_type,
group_name: def.group_type_index.as_ref().map(group_name),
})
.is_some(),
};
if removed {
self.removed.increment(1);
} else {
self.not_cached.increment(1);
}
}
}