: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 { P, match } from 'ts-pattern'
import { isObject } from 'lib/utils/guards'
import { isPostHogProperty } from '~/taxonomy/taxonomy'
import {
ErrorEventProperties,
ErrorTrackingException,
ErrorTrackingRelease,
ErrorTrackingRuntime,
ErrorTrackingStackFrame,
ErrorTrackingStackFrameRecord,
ExceptionAttributes,
FingerprintRecordPart,
} from './types'
export function getRuntimeFromLib(lib?: string | null): ErrorTrackingRuntime {
switch (lib?.toLowerCase()) {
case 'posthog-python':
return 'python'
case 'posthog-node':
case 'analytics-node':
case 'posthog-edge':
return 'node'
case 'posthog-js':
case 'web':
case 'js':
return 'web'
case 'posthog-go':
case 'analytics-go':
return 'go'
case 'posthog-php':
case 'posthog-laravel':
return 'php'
case 'posthog-rs':
return 'rust'
case 'posthog-dotnet':
return 'dotnet'
case 'posthog-android':
return 'android'
case 'posthog-ios':
case 'ios-widget':
return 'ios'
case 'posthog-react-native':
return 'react-native'
case 'posthog-dart':
return 'dart'
case 'posthog-flutter':
return 'flutter'
case 'posthog-elixir':
return 'elixir'
// posthog-server is the current java server SDK identifier; posthog-java is the
// tombstoned legacy SDK, kept so already-ingested events still resolve.
case 'posthog-server':
case 'posthog-java':
case 'analytics-java':
return 'java'
case 'posthog-kmp':
return 'kotlin'
default:
return 'unknown'
}
}
export function concatValues(
attrs: ExceptionAttributes | null,
...keys: (keyof ExceptionAttributes)[]
): string | undefined {
if (!attrs) {
return undefined
}
const definedKeys = keys.filter((key) => attrs[key])
if (definedKeys.length == 0) {
return undefined
}
return definedKeys.map((key) => attrs[key]).join(' ')
}
function nonEmptyString(value: unknown): string | undefined {
return typeof value === 'string' && value.length > 0 ? value : undefined
}
export function getExceptionAttributes(properties: Record<string, any>): ExceptionAttributes {
const {
$lib: lib,
$lib_version: libVersion,
$browser_version: browserVersion,
$os_version: osVersion,
$sentry_url: sentryUrl,
$exception_level: level,
$cymbal_errors: ingestionErrors,
} = properties
let type = properties.$exception_type
let value = properties.$exception_message
let synthetic: boolean | undefined = properties.$exception_synthetic
const url: string | undefined = properties.$current_url
const exceptionList: ErrorTrackingException[] | undefined = getExceptionList(properties)
if (!type) {
// we have seen in production that we managed to get `value = {}`
// so even though this is typed as a string
// it might not be!
type = exceptionList?.[0]?.type ? stringify(exceptionList?.[0]?.type) : undefined
}
if (!value) {
// we have seen in production that we managed to get `value = {}`
// so even though this is typed as a string
// it might not be!
value = exceptionList?.[0]?.value ? stringify(exceptionList?.[0]?.value) : undefined
}
if (synthetic == undefined) {
synthetic = exceptionList?.[0]?.mechanism?.synthetic
}
const handled = exceptionList?.[0]?.mechanism?.handled ?? false
const runtime: ErrorTrackingRuntime = getRuntimeFromLib(lib)
const appNamespace = properties.$app_namespace
const appVersion = properties.$app_version
// Misbehaving SDKs can send non-string values, which would crash PropertyIcon's lowercase lookup.
const browser = nonEmptyString(properties.$browser)
// Mobile SDKs report the platform in $os_name and leave $os unset; web SDKs do the opposite.
const os = nonEmptyString(properties.$os_name) ?? nonEmptyString(properties.$os)
return {
type,
value,
synthetic,
runtime,
lib,
libVersion,
browser,
browserVersion,
os,
osVersion,
url,
sentryUrl,
handled,
level,
ingestionErrors,
appNamespace,
appVersion,
}
}
export function getExceptionTypeAndValue(properties: ErrorEventProperties): {
type?: string
value?: string
} {
const [exception] = Array.isArray(properties.$exception_list) ? properties.$exception_list : []
const type = properties.$exception_types?.[0] || properties.$exception_type || exception?.type
const value = properties.$exception_values?.[0] || properties.$exception_message || exception?.value
return {
type: type ? stringify(type) : undefined,
value: value ? stringify(value) : undefined,
}
}
export function getExceptionList(properties: ErrorEventProperties): ErrorTrackingException[] {
const { $sentry_exception } = properties
let exceptionList: ErrorTrackingException[] = processExceptionList(properties.$exception_list)
// exception autocapture sets $exception_list for all exceptions.
// If it's not present, then this is probably a sentry exception. Get this list from the sentry_exception
if (!exceptionList?.length && $sentry_exception) {
if (Array.isArray($sentry_exception.values)) {
exceptionList = $sentry_exception.values
}
}
return exceptionList
}
function processExceptionList(exceptionList: ErrorTrackingException[] = []): ErrorTrackingException[] {
exceptionList = ensureStringExceptionValues(exceptionList)
exceptionList = ensureFrameIdFormat(exceptionList)
return exceptionList
}
function ensureFrameIdFormat(exceptionList: ErrorTrackingException[]): ErrorTrackingException[] {
return exceptionList.map((exception) => {
const stacktrace = exception.stacktrace
if (!stacktrace || !Array.isArray(stacktrace.frames)) {
return exception
}
const frames = stacktrace.frames.filter(isFrameObject).map((frame) => ({
...frame,
raw_id: typeof frame.raw_id === 'string' && frame.raw_id ? coerceLegacyRawId(frame.raw_id) : frame.raw_id,
}))
return { ...exception, stacktrace: { ...stacktrace, frames } }
})
}
function isFrameObject(frame: unknown): frame is ErrorTrackingStackFrame {
return isObject(frame)
}
function isExceptionObject(exception: unknown): exception is ErrorTrackingException {
return isObject(exception)
}
function coerceLegacyRawId(rawId: string): string {
return rawId.includes('/') ? rawId : `${rawId}/0`
}
export function getFingerprintRecords(properties: ErrorEventProperties): FingerprintRecordPart[] {
const { $exception_fingerprint_record } = properties
return $exception_fingerprint_record || []
}
export function getAdditionalProperties(
properties: ErrorEventProperties,
isCloudOrDev: boolean | undefined
): Record<string, unknown> {
return Object.fromEntries(
Object.entries(properties).filter(([key]) => {
return key === 'version' || !isPostHogProperty(key, isCloudOrDev)
})
)
}
function getStringProperty(properties: ErrorEventProperties, key: string): string | undefined {
const value = properties[key]
return typeof value === 'string' && value.length > 0 ? value : undefined
}
export function getSessionId(properties: ErrorEventProperties): string | undefined {
// $session_id can arrive malformed (e.g. a numeric timestamp) from misbehaving SDKs.
// Only a non-empty string is a usable session id; anything else means "no session".
return getStringProperty(properties, '$session_id')
}
export function getTraceId(properties: ErrorEventProperties): string | undefined {
return getStringProperty(properties, '$trace_id')
}
export function getSpanId(properties: ErrorEventProperties): string | undefined {
return getStringProperty(properties, '$span_id')
}
export function getRecordingStatus(properties: ErrorEventProperties): string | undefined {
return properties['$recording_status'] as string | undefined
}
/**
* Normalize Cymbal's event-level release snapshot to the release API shape used by the UI.
* The event property uses `timestamp`, while release API responses use `created_at`.
*/
export function getExceptionRelease(properties: ErrorEventProperties): ErrorTrackingRelease | undefined {
const release: unknown = properties['$exception_release']
if (!release || typeof release !== 'object' || Array.isArray(release)) {
return undefined
}
const candidate = release as Record<string, unknown>
if (
typeof candidate.id !== 'string' ||
typeof candidate.version !== 'string' ||
typeof candidate.timestamp !== 'string'
) {
return undefined
}
const metadata =
candidate.metadata && typeof candidate.metadata === 'object' && !Array.isArray(candidate.metadata)
? (candidate.metadata as ErrorTrackingRelease['metadata'])
: undefined
return {
id: candidate.id,
version: candidate.version,
created_at: candidate.timestamp,
project: typeof candidate.project === 'string' ? candidate.project : undefined,
metadata,
}
}
// Only posthog-js (`web`) and posthog-node (`posthog-node`, `posthog-edge`) report `$release_id`.
// Other libraries that share their runtime, such as analytics-node, never send it.
const LIBS_REPORTING_RELEASE_ID: ReadonlySet<string> = new Set(['web', 'posthog-node', 'posthog-edge'])
// Uploaded symbol sets without a release leave the SDK's `$release_id` as the only source of a release.
// A symbol set fetched by URL never carries one, so it cannot signal a missing `$release_id`.
// A frame with no loaded record still could, so the answer stays unknown until every frame has one.
export function isReleaseIdMissingFromSDK(
properties: ErrorEventProperties,
frames: ErrorTrackingStackFrame[],
stackFrameRecords: Record<string, ErrorTrackingStackFrameRecord>
): boolean {
if (!properties || properties['$release_id'] || getExceptionRelease(properties)) {
return false
}
if (!LIBS_REPORTING_RELEASE_ID.has(String(properties['$lib'] ?? '').toLowerCase())) {
return false
}
const records = frames.map((frame) => stackFrameRecords[frame.raw_id])
if (records.some((record) => !record)) {
return false
}
const uploadedSymbolSets = records.filter(
(record) => !!record.symbol_set_ref && !isFetchedSymbolSetRef(record.symbol_set_ref)
)
return uploadedSymbolSets.length > 0 && uploadedSymbolSets.every((record) => !record.release)
}
function isFetchedSymbolSetRef(ref: string): boolean {
return ref.startsWith('http://') || ref.startsWith('https://')
}
// we had a bug where SDK was sending non-string values for exception value
function ensureStringExceptionValues(exceptionList: ErrorTrackingException[]): ErrorTrackingException[] {
if (!Array.isArray(exceptionList)) {
return []
}
return exceptionList.filter(isExceptionObject).map((exception) => ({
...exception,
value: stringify(exception.value),
}))
}
export function stringify(value: any): string {
if (typeof value === 'string') {
return value
}
try {
return JSON.stringify(value)
} catch {}
try {
return value.toString()
} catch {}
return ''
}
export function formatFunctionName(
frame: Pick<ErrorTrackingStackFrame, 'module' | 'resolved_name' | 'lang' | 'mangled_name'>
): string | undefined {
const functionName: string | undefined = frame.resolved_name ?? frame.mangled_name ?? undefined
return match([frame.lang, frame.module, functionName])
.with(['java', P.string, P.string], ([_, module, functionName]) => `${module}.${functionName}`)
.with(['java', P.string, P.nullish], ([_, module]) => `${module}`)
.otherwise(() => functionName)
}
export function getInstructionAddress(frame: Pick<ErrorTrackingStackFrame, 'junk_drawer'>): string | null {
const address = frame.junk_drawer?.raw_frame?.instruction_addr
if (typeof address !== 'string') {
return null
}
// SDKs can send a padded or blank address, which would render as an empty frame row
const trimmed = address.trim()
return trimmed.length > 0 ? trimmed : null
}
export function formatResolvedName(
frame: Pick<ErrorTrackingStackFrame, 'module' | 'resolved_name' | 'lang'>
): string | null {
if (!frame.resolved_name || frame.resolved_name === '?') {
return null
}
return frame.module && frame.lang === 'java' ? `${frame.module}.${frame.resolved_name}` : frame.resolved_name
}
export function formatType(exception: Pick<ErrorTrackingException, 'module' | 'type' | 'stacktrace'>): string {
const frames = exception.stacktrace?.frames
const hasJavaFrames = Array.isArray(frames) && frames.some((frame) => frame.lang === 'java')
return exception.module && hasJavaFrames ? `${exception.module}.${exception.type}` : exception.type
}
export function formatExceptionDisplay(
exception: Pick<ErrorTrackingException, 'module' | 'type' | 'stacktrace' | 'value'>
): string {
return `${formatType(exception)}${exception.value ? `: ${exception.value}` : ''}`
}