: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 { createHash, randomUUID } from 'node:crypto'
import { z } from 'zod'
import type { AccessKey } from '@/posthog/access-key'
import { posthogFile, type Credentials } from '@/posthog/credentials'
import { VERSION } from '@/version'
import type { Mode } from './agent'
import { parseJsonOrUndefined } from './json'
import type { Env, Runtime } from './runtime'
import type { Schema } from './schema'
// PostHog's own project, where posthog-cli release builds send their events too.
export const DEFAULT_TELEMETRY_TOKEN = 'sTMFPsFhdP1Ssg'
const TELEMETRY_HOST = 'https://us.i.posthog.com'
// posthog-cli's timeout. A CLI must not hang on its own analytics.
const SEND_TIMEOUT_MS = 5000
const ID_FILE = 'hog-telemetry-id'
const IDENTITY_FILE = 'hog-telemetry-identity.json'
const LOOKUP_TIMEOUT_MS = 2000
const DAY_MS = 24 * 60 * 60 * 1000
type EnvCheck = (env: Env) => boolean
const has =
(name: string): EnvCheck =>
(env) =>
Boolean(env[name])
// First match wins. Platforms that also set the variables of another one come first: Depot CI
// before GitHub Actions, Harness and Woodpecker before Drone. Vercel sets VERCEL outside builds too.
const CI_PROVIDERS: ReadonlyArray<readonly [provider: string, check: EnvCheck]> = [
['depot-ci', has('DEPOT_JOB_URL')],
['harness', has('HARNESS_BUILD_ID')],
['woodpecker', (env) => env.CI === 'woodpecker'],
['github-actions', has('GITHUB_ACTIONS')],
['gitlab', has('GITLAB_CI')],
['circleci', has('CIRCLECI')],
['buildkite', has('BUILDKITE')],
['jenkins', has('JENKINS_URL')],
['travis', has('TRAVIS')],
['bitbucket', has('BITBUCKET_COMMIT')],
['azure-pipelines', has('TF_BUILD')],
['aws-codebuild', has('CODEBUILD_BUILD_ARN')],
['google-cloud-build', has('BUILDER_OUTPUT')],
['vercel', (env) => Boolean(env.VERCEL && env.CI)],
['netlify', has('NETLIFY')],
['cloudflare-pages', has('CF_PAGES')],
['cloudflare-workers', has('WORKERS_CI')],
['render', has('RENDER')],
['railway', has('RAILWAY_SERVICE_ID')],
['heroku-ci', has('HEROKU_TEST_RUN_ID')],
['expo-eas', has('EAS_BUILD')],
['bitrise', has('BITRISE_IO')],
['xcode-cloud', has('CI_XCODE_CLOUD')],
['codemagic', has('CM_BUILD_ID')],
['semaphore', has('SEMAPHORE')],
['drone', has('DRONE')],
['teamcity', has('TEAMCITY_VERSION')],
['appveyor', has('APPVEYOR')],
]
// Vendors that run GitHub Actions jobs on their own machines. Some of these variables hold tokens,
// so hog only checks that they are set.
const runnerName =
(prefix: string): EnvCheck =>
(env) =>
env.RUNNER_NAME?.startsWith(prefix) === true
const CI_RUNNERS: ReadonlyArray<readonly [runner: string, check: EnvCheck]> = [
['depot', (env) => has('DEPOT_ORG_ID')(env) || runnerName('depot-')(env)],
['blacksmith', has('BLACKSMITH_VM_ID')],
['namespace', (env) => has('NSC_CACHE_PATH')(env) || runnerName('nsc-runner-')(env)],
['warpbuild', has('WARPBUILD_RUNNER_VERIFICATION_TOKEN')],
['ubicloud', has('UBICLOUD_CACHE_URL')],
['runs-on', has('RUNS_ON_RUNNER_NAME')],
['cirun', runnerName('cirun-')],
]
export function detectCi(env: Env): { provider: string | null; runner: string | null } {
const provider = CI_PROVIDERS.find(([, check]) => check(env))?.[0] ?? null
const runner = CI_RUNNERS.find(([, check]) => check(env))?.[0] ?? env.RUNNER_ENVIRONMENT ?? null
return { provider, runner }
}
interface QueuedEvent {
event: string
properties: Record<string, unknown>
timestamp: string
}
interface Identity {
distinctId?: string
organization?: string
project?: string
}
const CachedIdentitySchema = z.object({
checkedAt: z.number(),
distinctId: z.string().optional(),
organization: z.string().optional(),
project: z.string().optional(),
})
type CachedIdentity = z.output<typeof CachedIdentitySchema>
// hog writes this file itself, so a cache it can't read is broken and hog starts a new one.
const IdentityCacheSchema = z.record(z.string(), CachedIdentitySchema)
// Only PostHog Cloud users exist in the project telemetry goes to.
function isCloudHost(host: string): boolean {
const { hostname } = new URL(host)
return hostname === 'posthog.com' || hostname.endsWith('.posthog.com')
}
// A field hog can't read, such as a null organization, reads as missing, so the event loses only
// that field.
const Text = z.string().min(1).optional().catch(undefined)
const IdentityUser = z.object({ distinct_id: Text, organization: z.object({ id: Text }).optional().catch(undefined) })
const IdentityProject = z.object({ organization: Text, uuid: Text })
// Usage events for the PostHog team. They belong to the PostHog Cloud user whose key hog uses, and
// to a random install ID otherwise. Events carry no argument or option values and no error messages,
// only names, counts and error codes.
export class Telemetry {
private readonly queue: QueuedEvent[] = []
private enabled: boolean
readonly invocationId = randomUUID()
commandName: string | undefined
credentials: (() => Promise<Credentials>) | undefined
constructor(
private readonly runtime: Runtime,
private readonly mode: Mode,
enabled: boolean
) {
this.enabled = enabled && runtime.telemetryToken !== undefined
}
get isEnabled(): boolean {
return this.enabled
}
disable(): void {
this.enabled = false
this.queue.length = 0
}
capture(event: string, properties: Record<string, unknown> = {}): void {
if (this.enabled) {
this.queue.push({ event, properties, timestamp: new Date(this.runtime.now()).toISOString() })
}
}
async flush(debug = false): Promise<void> {
if (!this.enabled || this.queue.length === 0) {
return
}
const key = (await this.credentials?.().catch(() => undefined))?.key
const identity = key ? await this.identity(key) : undefined
const installId = await this.installId()
const distinctId = identity?.distinctId ?? installId
const groups = Object.fromEntries(
Object.entries({ organization: identity?.organization, project: identity?.project }).filter(
([, key]) => key !== undefined
)
)
const common = {
...this.commonProperties(),
install_id: installId,
// A self-hosted project ID means nothing in PostHog Cloud and would tie the install to that instance.
env_id: key && isCloudHost(key.host) ? key.projectId : null,
...(identity?.distinctId ? {} : { $process_person_profile: false }),
...(Object.keys(groups).length > 0 ? { $groups: groups } : {}),
}
const batch = this.queue.splice(0).map(({ event, properties, timestamp }) => ({
event,
timestamp,
distinct_id: distinctId,
properties: { ...common, ...properties },
}))
try {
const response = await this.runtime.fetch(new URL('/batch/', TELEMETRY_HOST), {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ api_key: this.runtime.telemetryToken, batch }),
signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
})
if (debug) {
this.runtime.writeStderr(`[debug] telemetry: sent ${batch.length} events, ${response.status}\n`)
}
} catch (error) {
if (debug) {
this.runtime.writeStderr(
`[debug] telemetry: not sent: ${error instanceof Error ? error.message : error}\n`
)
}
}
}
private commonProperties(): Record<string, unknown> {
const env = this.runtime.env
const ci = detectCi(env)
return {
$lib: 'hog',
$lib_version: VERSION,
cli: 'hog',
cli_version: VERSION,
invocation_id: this.invocationId,
command_name: this.commandName,
os: process.platform,
arch: process.arch,
runtime_version: process.versions.bun,
is_ci: env.CI !== undefined || ci.provider !== null,
ci_provider: ci.provider,
ci_runner: ci.runner,
is_terminal: this.runtime.stdoutIsTTY,
agent: this.mode.agent ?? null,
output_format: this.mode.format,
}
}
// Looks the user up once per key and keeps the answer for 30 days, or a day when PostHog had
// none, so most runs send no extra request. A key without the scopes stays anonymous.
private async identity(key: AccessKey): Promise<Identity | undefined> {
if (!isCloudHost(key.host)) {
return undefined
}
let path: string
try {
path = posthogFile(this.runtime, IDENTITY_FILE)
} catch {
return undefined
}
const cacheKey = createHash('sha256').update(`${key.host}\n${key.projectId}\n${key.loginKey}`).digest('hex')
let cache: Record<string, CachedIdentity> = {}
try {
cache = parseJsonOrUndefined(await this.runtime.readFile(path), IdentityCacheSchema) ?? {}
} catch {
// No cache yet.
}
const cached = cache[cacheKey]
const now = this.runtime.now()
if (cached && now - cached.checkedAt < (cached.distinctId ? 30 : 1) * DAY_MS) {
return cached
}
const identity = await this.lookup(key)
// Entries old enough to be looked up again anyway are dropped, so logins that ended don't pile up.
cache = Object.fromEntries(Object.entries(cache).filter(([, entry]) => now - entry.checkedAt < 30 * DAY_MS))
cache[cacheKey] = { ...identity, checkedAt: now }
try {
await this.runtime.writePrivateFile(path, JSON.stringify(cache))
} catch {
// Unwritable home: the next run looks it up again.
}
return identity
}
private async lookup(key: AccessKey): Promise<Identity> {
const get = async <T>(path: string, schema: Schema<T>): Promise<T | undefined> => {
try {
const response = await this.runtime.fetch(new URL(path, key.host), {
headers: { Authorization: `Bearer ${key.token}` },
signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS),
})
return response.ok ? parseJsonOrUndefined(await response.text(), schema) : undefined
} catch {
return undefined
}
}
const [user, project] = await Promise.all([
get('/api/users/@me/', IdentityUser),
get(`/api/projects/${key.projectId}/`, IdentityProject),
])
return {
distinctId: user?.distinct_id,
organization: project?.organization ?? user?.organization?.id,
project: project?.uuid,
}
}
// A random ID kept next to the credentials, so usage counts machines instead of runs. It says
// nothing about the person. Without a home folder, each run counts on its own.
private async installId(): Promise<string> {
let path: string
try {
path = posthogFile(this.runtime, ID_FILE)
} catch {
return this.invocationId
}
try {
const stored = (await this.runtime.readFile(path)).trim()
if (stored) {
return stored
}
} catch {
// No ID yet.
}
const id = randomUUID()
try {
await this.runtime.writePrivateFile(path, `${id}\n`)
} catch {
return this.invocationId
}
return id
}
}