: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
import { Counter, Histogram, Summary, exponentialBuckets } from 'prom-client'
import { InternalPerson } from '~/types'
export const personPropertiesSizeViolationCounter = new Counter({
name: 'person_properties_size_violations_total',
help: 'Number of person properties size violations',
labelNames: ['violation_type'],
})
export const oversizedPersonPropertiesTrimmedCounter = new Counter({
name: 'oversized_person_properties_trimmed',
help: 'Number of oversized person properties trimmed',
labelNames: ['result'],
})
export const personMethodCallsPerBatchHistogram = new Histogram({
name: 'person_method_calls_per_batch',
help: 'Number of calls to each person store method per distinct ID per batch',
labelNames: ['method'],
buckets: [0, 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, Infinity],
})
export const personDatabaseOperationsPerBatchHistogram = new Histogram({
name: 'person_database_operations_per_batch',
help: 'Number of database operations per distinct ID per batch',
labelNames: ['operation'],
buckets: [0, 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, Infinity],
})
export const personResolveKeysPerCallHistogram = new Histogram({
name: 'person_resolve_keys_per_call',
help: 'Distinct ids sent in one distinct-id-to-person resolve call, by persons backend and call site, before transport retries',
labelNames: ['backend', 'site'],
buckets: [1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, Infinity],
})
export const totalPersonUpdateLatencyPerBatchHistogram = new Histogram({
name: 'total_person_update_latency_per_batch_seconds',
help: 'Total latency of person update per distinct ID per batch',
labelNames: ['update_type'],
buckets: exponentialBuckets(0.025, 4, 7),
})
export const personCacheOperationsCounter = new Counter({
name: 'person_cache_operations_total',
help: 'Total number of cache hits and misses',
labelNames: ['cache', 'operation'],
})
export const personFetchForCheckingCacheOperationsCounter = new Counter({
name: 'person_fetch_for_checking_cache_operations_total',
help: 'Number of operations on the fetchForChecking cache',
labelNames: ['operation'],
})
export const personFetchForUpdateCacheOperationsCounter = new Counter({
name: 'person_fetch_for_update_cache_operations_total',
help: 'Number of operations on the fetchForUpdate cache',
labelNames: ['operation'],
})
export const personOperationLatencyByVersionSummary = new Summary({
name: 'person_operation_latency_by_version',
help: 'Latency distribution of person by version',
labelNames: ['operation', 'version_bucket'],
})
export const personPropertyKeyUpdateCounter = new Counter({
name: 'person_property_key_update_total',
help: 'Number of person updates triggered by this property value changing.',
labelNames: ['key'],
})
export const personMergeFailureCounter = new Counter({
name: 'person_merge_failure_total',
help: 'Number of person merges that failed',
labelNames: ['call'], // $identify, $create_alias, $merge_dangerously
})
export const personCacheSizeHistogram = new Histogram({
name: 'person_cache_size',
help: 'Size of the person cache',
buckets: [0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000, 10000, Infinity],
})
export const personOptimisticUpdateConflictsPerBatchCounter = new Counter({
name: 'person_optimistic_update_conflicts_per_batch_total',
help: 'Number of optimistic update conflicts per batch',
})
// Flush instrumentation metrics
export const personFlushOperationsCounter = new Counter({
name: 'person_flush_operations_total',
help: 'Total number of flush operations by outcome',
labelNames: ['db_write_mode', 'outcome'], // outcome: success, error, fallback
})
export const personFlushLatencyHistogram = new Histogram({
name: 'person_flush_latency_seconds',
help: 'Latency of flush operations',
labelNames: ['db_write_mode'],
buckets: exponentialBuckets(0.001, 2, 12), // 1ms to ~4s
})
export const personFlushBatchSizeHistogram = new Histogram({
name: 'person_flush_batch_size',
help: 'Number of person updates processed in a single flush',
labelNames: ['db_write_mode'],
buckets: [0, 1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, Infinity],
})
export const personWriteMethodAttemptCounter = new Counter({
name: 'person_write_method_attempt_total',
help: 'Number of attempts for each write method',
labelNames: ['db_write_mode', 'method', 'outcome'], // method: no_assert, assert_version; outcome: success, retry, fallback
})
export const personFallbackOperationsCounter = new Counter({
name: 'person_fallback_operations_total',
help: 'Number of fallback operations triggered',
labelNames: ['db_write_mode', 'fallback_reason'], // fallback_reason: max_retries, error, conflict
})
export const personShadowModeComparisonCounter = new Counter({
name: 'person_shadow_mode_comparison_total',
help: 'Person shadow mode comparison results between measuring and batch stores',
labelNames: ['outcome_type'],
})
export const personShadowModeReturnIntermediateOutcomeCounter = new Counter({
name: 'person_shadow_mode_return_intermediate_outcome_total',
help: 'Person shadow mode intermediate comparison results for updatePersonForUpdate and updatePersonForMerge methods',
labelNames: ['method', 'outcome'],
})
export function getVersionBucketLabel(version: number): string {
if (version === 0) {
return 'v0'
}
if (version <= 50) {
return 'v1-50'
}
if (version <= 100) {
return 'v51-100'
}
if (version <= 1000) {
return 'v101-1000'
}
if (version <= 10000) {
return 'v1001-10000'
}
if (version <= 100000) {
return 'v10001-100000'
}
if (version <= 1000000) {
return 'v100001-1000000'
}
return 'v1000001+'
}
export function observeLatencyByVersion(person: InternalPerson | undefined, start: number, operation: string) {
if (!person) {
return
}
const versionBucket = getVersionBucketLabel(person.version)
personOperationLatencyByVersionSummary.labels(operation, versionBucket).observe(performance.now() - start)
}
export const personhogStoreShadowSkipsCounter = new Counter({
name: 'personhog_store_shadow_skips_total',
help: 'Shadowed writes skipped because the person does not exist in the personhog world yet',
labelNames: ['verb'],
})
export const personhogStoreShadowErrorsCounter = new Counter({
name: 'personhog_store_shadow_errors_total',
help: 'Personhog shadow-side store verb failures by verb and error class; shadow errors never fail the batch',
labelNames: ['verb', 'error'],
})
export const personhogStoreShadowDivergenceCounter = new Counter({
name: 'personhog_store_shadow_divergence_total',
help: 'Answers where the shadow backend disagreed with the authoritative one, by verb and by the field that differed',
labelNames: ['verb', 'field'],
})
export const personhogStoreShadowComparedCounter = new Counter({
name: 'personhog_store_shadow_compared_total',
help: 'Shadow answers actually compared against the authoritative one, the denominator for the divergence rate',
labelNames: ['verb'],
})
export const personhogStoreShadowFoldRedriveCounter = new Counter({
name: 'personhog_store_shadow_fold_redrive_total',
help: 'Per-pair shadow merges re-driven after a fold the authoritative side executed aborted on the shadow, by outcome',
labelNames: ['outcome'],
})
export const personhogStoreShadowMergeRedriveCounter = new Counter({
name: 'personhog_store_shadow_merge_redrive_total',
help: 'Shadow merges re-driven at a flush after their retries ended unsettled: settled, deferred to a later flush, or dropped; abandoned counts a re-queue at the ceiling before the final outcome',
labelNames: ['outcome'],
})
export const personhogStoreShadowCreateRetriesCounter = new Counter({
name: 'personhog_store_shadow_create_retries_total',
help: 'Shadow create attempts past the first (retried) and creates that landed after a retry (recovered); one that misses its deadline counts under personhog_store_shadow_errors_total',
labelNames: ['outcome'],
})
export const personhogStoreShadowCompareFailedCounter = new Counter({
name: 'personhog_store_shadow_compare_failed_total',
help: 'Shadow comparisons that threw, which is a fault in the comparison rather than in either backend',
labelNames: ['verb'],
})
export const personhogStoreShadowDurationSeconds = new Histogram({
name: 'personhog_store_shadow_duration_seconds',
help: 'Wall time the shadowed personhog side of a store verb adds to the event pipeline, by verb',
labelNames: ['verb'],
buckets: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
})
export const personProfileUpdateOutcomeCounter = new Counter({
name: 'person_profile_update_outcome_total',
help: 'Outcome of person profile update operations at event level',
labelNames: ['outcome'], // outcome: changed, ignored, no_change, unsupported
})
export const personProfileIgnoredPropertiesCounter = new Counter({
name: 'person_profile_ignored_properties_total',
help: 'Count of specific properties that were ignored during person profile updates at event level',
labelNames: ['property'],
})
export const personProfileBatchUpdateOutcomeCounter = new Counter({
name: 'person_profile_batch_update_outcome_total',
help: 'Outcome of person profile update operations at batch level',
labelNames: ['outcome'], // outcome: changed, ignored, no_change
})
export const personProfileBatchIgnoredPropertiesCounter = new Counter({
name: 'person_profile_batch_ignored_properties_total',
help: 'Count of specific properties that were ignored during person profile updates at batch level',
labelNames: ['property'],
})
export const personCreateConflictResolvedCounter = new Counter({
name: 'person_create_conflict_resolved_total',
help: 'Person creations that lost the (team_id, uuid) key, by how the conflict was resolved',
// uuid: resolved to the row already holding the uuid, after recovery by distinct ID found nothing
// none: the holder was gone by the time we looked, so the create failed
labelNames: ['resolved_by'],
})
export const personStrayDistinctIdTombstonedCounter = new Counter({
name: 'person_stray_distinct_id_tombstoned_total',
help: 'Live distinct id mappings on a tombstoned person that a write tombstoned so it could reuse the distinct id',
labelNames: ['operation'],
})
export const personJsonFieldSizeHistogram = new Histogram({
name: 'person_json_field_size_bytes',
help: 'Approximate size in bytes of serialized JSON fields (using string length as proxy for performance)',
labelNames: ['operation', 'field'], // operation: createPerson, updatePerson; field: properties, properties_last_updated_at, properties_last_operation
buckets: [100, 500, 1024, 4096, 8192, 16384, 32768, 65536, 131072, 262144, 524288, 1048576], // 100B, 500B, 1KB, 4KB, 8KB, 16KB, 32KB, 64KB, 128KB, 256KB, 512KB, 1MB
})