Skip to content

: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.

feat(hog): send anonymous usage telemetry (#125526)

Rafael Audibert4e514390ece3
diff --git a/hog/README.md b/hog/README.md
index b94a438ec4f5..b75b91ffe438 100644
--- a/hog/README.md
+++ b/hog/README.md
@@ -48,9 +48,8 @@ First, the commands that make hog a complete CLI:
Then, once the commands above work:
-- [ ] Telemetry: the `posthog cli command run` and `error_tracking_cli_sourcemaps_upload_*` events posthog-cli sends.
- [ ] Callers: the SDKs, build plugins and scripts that run `posthog-cli` with its arguments. Move them to hog, or give hog a `posthog-cli` entry point that translates the arguments.
-- [ ] Distribution: a binary for each platform, macOS signing and notarization, the npm package, the Homebrew formula, `hog update`, and CI on Linux and Windows.
+- [ ] Distribution: a binary for each platform, macOS signing and notarization, the npm package, the Homebrew formula, `hog update`, CI on Linux and Windows.
Not planned:
@@ -77,22 +76,39 @@ Exit codes: 0 on success, 1 when a command fails, 2 for a usage error.
Every option below works on any command, and each has an environment variable.
A flag beats the environment variable, which beats `posthog.json`.
-| Option | Environment | `posthog.json` | What it does |
-| ------------------------- | --------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `--host <url>` | `HOG_HOST` | `host` | The PostHog host to use instead of the one in your credentials |
-| `--dotenv-file <path>` | `HOG_DOTENV_FILE` | | Read credentials from this file when the environment has none |
-| `-o, --output <format>` | `HOG_OUTPUT` | | `text` or `json` |
-| `--raw` | `HOG_RAW` | | Print a command's full result as JSON |
-| `--debug` | `HOG_DEBUG` | | Print each HTTP request, its status and duration to stderr |
-| `--no-fail` | `HOG_NO_FAIL` | `cli.noFail` | Exit with code 0 when a command fails or reports a problem, such as `diff` finding drift. Usage errors still exit with code 2 |
-| `--skip-ssl-verification` | `HOG_SKIP_SSL_VERIFICATION` | | Accept any TLS certificate, for a self-signed self-hosted PostHog |
-| `--rate-limit <requests>` | `HOG_RATE_LIMIT` | `cli.rateLimit` | The most requests per minute. No limit by default |
-| | `HOG_DRY_RUN` | | Turns on `--dry-run` for every command that has one, and fails the commands that write without one |
+| Option | Environment | `posthog.json` | What it does |
+| ------------------------- | ---------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `--host <url>` | `HOG_HOST` | `host` | The PostHog host to use instead of the one in your credentials |
+| `--dotenv-file <path>` | `HOG_DOTENV_FILE` | | Read credentials from this file when the environment has none |
+| `-o, --output <format>` | `HOG_OUTPUT` | | `text` or `json` |
+| `--raw` | `HOG_RAW` | | Print a command's full result as JSON |
+| `--debug` | `HOG_DEBUG` | | Print each HTTP request, its status and duration to stderr |
+| `--no-fail` | `HOG_NO_FAIL` | `cli.noFail` | Exit with code 0 when a command fails or reports a problem, such as `diff` finding drift. Usage errors still exit with code 2 |
+| `--skip-ssl-verification` | `HOG_SKIP_SSL_VERIFICATION` | | Accept any TLS certificate, for a self-signed self-hosted PostHog |
+| `--no-telemetry` | `HOG_NO_TELEMETRY`, `DO_NOT_TRACK` | `cli.telemetry` | Send no anonymous usage data. See [Telemetry](#telemetry) |
+| `--rate-limit <requests>` | `HOG_RATE_LIMIT` | `cli.rateLimit` | The most requests per minute. No limit by default |
+| | `HOG_DRY_RUN` | | Turns on `--dry-run` for every command that has one, and fails the commands that write without one |
`--host` and `HOG_HOST` override the host of every credential source. `host` in `posthog.json` never sends your credentials elsewhere: `hog auth login` uses it, and other commands stop when your credentials are for another host.
Commands that only read run as usual in a dry run, and `auth login` and `auth logout` fail.
hog reads only the `HOG_` names. posthog-cli's `POSTHOG_CLI_` variables, `POSTHOG_HOME` and `POSTHOG_RELEASE_MODE` don't count.
+## Telemetry
+
+hog sends usage events to PostHog, so the team can see who uses which commands and where they fail.
+
+- `posthog cli command run`, once per command, the same event posthog-cli sends: the command, exit code, duration, the names of the options passed, the detected agent, the CI provider and runner (such as GitHub Actions on Depot or Blacksmith), the OS, and counts from the result, such as rows returned or endpoints pushed.
+- `$exception` when a command fails, with the error code, message, hint and HTTP status. A message can name a file, or quote part of a query or an API answer.
+- `error_tracking_cli_sourcemaps_upload_started`, `_finished` and `_endpoint_fallback`, as in posthog-cli.
+
+With a PostHog Cloud key, events belong to your PostHog user, organization and project, the same ones the web app uses.
+hog looks them up once per key with `/api/users/@me/` and `/api/projects/<id>/`, and keeps the answer in `~/.posthog/hog-telemetry-identity.json` for 30 days.
+Without a key, with a self-hosted PostHog, or with a key that can't read those, events belong to a random ID in `~/.posthog/hog-telemetry-id`.
+Usage events never carry argument or option values or API keys.
+
+Telemetry is on by default and goes to the same PostHog project as posthog-cli's.
+Turn it off with `--no-telemetry`, `HOG_NO_TELEMETRY=1`, `DO_NOT_TRACK=1`, or `"cli": { "telemetry": false }` in `posthog.json`.
+
## posthog.json
Project settings live in `posthog.json`, which hog looks for from the current folder up to the git root.
diff --git a/hog/posthog.schema.json b/hog/posthog.schema.json
index ceefab5770b4..223033090ae3 100644
--- a/hog/posthog.schema.json
+++ b/hog/posthog.schema.json
@@ -83,6 +83,10 @@
"description": "Exit with code 0 when a command fails, like --no-fail. HOG_NO_FAIL overrides it.",
"type": "boolean"
},
+ "telemetry": {
+ "description": "false stops hog from sending anonymous usage data to PostHog for everyone working in this folder.",
+ "type": "boolean"
+ },
"rateLimit": {
"description": "The most requests hog sends per minute, like --rate-limit. HOG_RATE_LIMIT overrides it.",
"type": "integer",
diff --git a/hog/src/cli.ts b/hog/src/cli.ts
index ec6bb2baa32a..b37d0314d236 100644
--- a/hog/src/cli.ts
+++ b/hog/src/cli.ts
@@ -12,14 +12,16 @@ import {
type Legacy,
type OptionSpec,
} from '@/core/command'
-import { loadConfig } from '@/core/config'
+import { findConfig, loadConfig } from '@/core/config'
import { Context } from '@/core/context'
import { EXIT_FAILURE, EXIT_USAGE, HogError } from '@/core/errors'
-import { DRY_RUN_ENV, envFlag, GLOBAL_OPTIONS, networkRuntime, resolveGlobals } from '@/core/globals'
+import { DRY_RUN_ENV, envFlag, GLOBAL_OPTIONS, networkRuntime, optOutFlag, resolveGlobals } from '@/core/globals'
import { Output } from '@/core/output'
import type { Runtime } from '@/core/runtime'
+import { Telemetry } from '@/core/telemetry'
import { kebabCase } from '@/core/text'
import { ApiError } from '@/posthog/api'
+import { resolveCredentials } from '@/posthog/credentials'
import { VERSION } from '@/version'
const ROOT_HELP = `
@@ -116,23 +118,42 @@ async function readArgument(runtime: Runtime, name: string, value: string): Prom
return text
}
-function commandPath(command: Commander): string {
- const names: string[] = []
- for (let current: Commander | null = command; current?.parent; current = current.parent) {
- names.unshift(current.name())
- }
- return names.join(' ')
-}
-
interface RunState {
exitCode: number
noFail?: boolean
+ debug?: boolean
+ options?: string[]
+ command?: string
+ properties?: Record<string, unknown>
+}
+
+// commander reads `--no-fail` as turning off an option named `fail`, so `noFail` is set from it.
+function negatedFlags(flags: Record<string, unknown>): Record<string, unknown> {
+ const resolved = { ...flags }
+ for (const name of Object.keys(GLOBAL_OPTIONS)) {
+ const positive = /^no([A-Z].*)$/.exec(name)?.[1]
+ if (positive) {
+ const key = positive.charAt(0).toLowerCase() + positive.slice(1)
+ resolved[name] = flags[key] === false ? true : undefined
+ }
+ }
+ return resolved
}
-function createProgram(runtime: Runtime, mode: Mode, state: RunState): Commander {
+// The flags the caller typed, by name. Values never leave, and neither does anything commander
+// didn't parse as an option, such as a query that starts with dashes.
+function usedOptions(command: Commander): string[] {
+ const negated: Record<string, string> = { fail: 'no-fail', telemetry: 'no-telemetry' }
+ return Object.keys(command.optsWithGlobals())
+ .filter((key) => command.getOptionValueSourceWithGlobals(key) === 'cli')
+ .map((key) => negated[key] ?? kebabCase(key))
+ .sort()
+}
+
+function createProgram(runtime: Runtime, mode: Mode, state: RunState, telemetry: Telemetry): Commander {
const out = new Output(runtime, mode)
- function addRunnable(command: Commander, node: Command): void {
+ function addRunnable(command: Commander, node: Command, path: string): void {
const argEntries = Object.entries(node.args ?? {})
for (const [name, spec] of argEntries) {
command.argument(argumentSyntax(name, spec), spec.description)
@@ -147,12 +168,17 @@ function createProgram(runtime: Runtime, mode: Mode, state: RunState): Commander
command.action(async (...params: unknown[]) => {
const self = params.at(-1) as Commander
- const flags = self.optsWithGlobals()
- // commander reads `--no-fail` as turning off an option named `fail`.
- flags.noFail = flags.fail === false ? true : undefined
+ state.command = path
+ telemetry.commandName = path.replaceAll(/[ -]/g, '_')
+ state.options = usedOptions(self)
const config = node.allowsInvalidConfig ? undefined : loadConfig(runtime)
- const globals = resolveGlobals(flags, runtime.env, (await config)?.config)
+ const globals = resolveGlobals(negatedFlags(self.optsWithGlobals()), runtime.env, (await config)?.config)
state.noFail = globals.noFail === true
+ state.debug = globals.debug === true
+ if (globals.noTelemetry) {
+ telemetry.disable()
+ }
+ telemetry.credentials = () => resolveCredentials({ ...runtime, writeStderr: () => {} }, globals)
const commandRuntime = networkRuntime(runtime, globals)
const options = self.opts()
if (envFlag(runtime.env, DRY_RUN_ENV)) {
@@ -161,7 +187,7 @@ function createProgram(runtime: Runtime, mode: Mode, state: RunState): Commander
} else if (node.writes) {
throw new HogError(
'dry_run_unsupported',
- `\`hog ${commandPath(self)}\` has no dry run, and HOG_DRY_RUN is set.`,
+ `\`hog ${path}\` has no dry run, and HOG_DRY_RUN is set.`,
'Unset HOG_DRY_RUN to run it, or leave the command out of the dry run.',
EXIT_USAGE
)
@@ -174,7 +200,7 @@ function createProgram(runtime: Runtime, mode: Mode, state: RunState): Commander
args[name] = spec.stdin && value !== undefined ? await readArgument(runtime, name, value) : value
}
- const ctx = new Context(commandRuntime, globals, mode, COMMANDS, config)
+ const ctx = new Context(commandRuntime, globals, mode, COMMANDS, config, telemetry)
let result: unknown
try {
result = await node.run({ args, options, ctx })
@@ -189,16 +215,21 @@ function createProgram(runtime: Runtime, mode: Mode, state: RunState): Commander
out.json(result)
}
state.exitCode = node.exitCode?.(result) ?? 0
+ state.properties = {
+ dry_run: options.dryRun === true,
+ ...node.telemetry?.({ result, args, options } as never),
+ }
})
}
- function addNode(parent: Commander, name: string, node: Command | Group | Legacy): void {
+ function addNode(parent: Commander, name: string, node: Command | Group | Legacy, prefix = ''): void {
const command = parent.command(name).description(node.description)
+ const path = prefix ? `${prefix} ${name}` : name
switch (node.kind) {
case 'group':
command.aliases(node.aliases ?? [])
for (const [childName, child] of Object.entries(node.commands)) {
- addNode(command, childName, child)
+ addNode(command, childName, child, path)
}
return
case 'legacy':
@@ -206,7 +237,7 @@ function createProgram(runtime: Runtime, mode: Mode, state: RunState): Commander
command.helpGroup(LEGACY_HELP_GROUP)
return
case 'command':
- addRunnable(command, node)
+ addRunnable(command, node, path)
}
}
@@ -246,6 +277,7 @@ type Token = ReturnType<typeof parseArgs>['tokens'] extends (infer T)[] | undefi
interface PreParsed {
format: OutputFormat | undefined
noFail: boolean
+ noTelemetry: boolean
tokens: Token[]
}
@@ -268,7 +300,7 @@ function preParse(argv: readonly string[]): PreParsed {
})
const output = values.output
const format = GLOBAL_OPTIONS.output.choices.find((choice) => choice === output)
- return { format, noFail: values['no-fail'] === true, tokens }
+ return { format, noFail: values['no-fail'] === true, noTelemetry: values['no-telemetry'] === true, tokens }
}
function findLegacy(tokens: Token[]): LegacyRoute | undefined {
@@ -367,6 +399,20 @@ function toHogError(caught: unknown): HogError {
return new HogError('internal_error', caught instanceof Error ? caught.message : String(caught))
}
+// Read without the schema, so an opt-out still counts in a file another check rejects. A file
+// that isn't JSON stops the command later, with telemetry on.
+async function configOptsOut(runtime: Runtime): Promise<boolean> {
+ const path = await findConfig(runtime)
+ if (path === undefined) {
+ return false
+ }
+ try {
+ return (JSON.parse(await runtime.readFile(path)) as { cli?: { telemetry?: unknown } })?.cli?.telemetry === false
+ } catch {
+ return false
+ }
+}
+
function safeEnvFlag(env: Runtime['env'], names: readonly string[]): boolean {
try {
return envFlag(env, names) === true
@@ -375,36 +421,109 @@ function safeEnvFlag(env: Runtime['env'], names: readonly string[]): boolean {
}
}
+// `$exception` frames for a bug, with file names only, so one bug groups together wherever hog is installed.
+function stackFrames(error: unknown): Record<string, unknown>[] {
+ const stack = error instanceof Error ? (error.stack ?? '') : ''
+ return stack
+ .split('\n')
+ .slice(1)
+ .map((line) => /at (?:(.+?) \()?(.+?):(\d+):(\d+)\)?$/.exec(line.trim()))
+ .filter((match): match is RegExpExecArray => match !== null)
+ .map(([, fn, file, line, column]) => ({
+ platform: 'node:javascript',
+ function: fn ?? '<anonymous>',
+ filename: file!.split(/[\\/]/).at(-1),
+ lineno: Number(line),
+ colno: Number(column),
+ in_app: !file!.includes('node_modules'),
+ }))
+ .reverse()
+}
+
+// Messages and hints can hold paths, setting values and API response text, so like posthog-cli the
+// event carries only the error code, its HTTP details and, for a bug, the stack.
+function captureFailure(telemetry: Telemetry, command: string | undefined, error: HogError, cause: unknown): void {
+ const status = error instanceof ApiError ? error.status : undefined
+ const bug = !(cause instanceof HogError)
+ telemetry.capture('$exception', {
+ $exception_list: [
+ {
+ type: bug && cause instanceof Error ? cause.name : error.code,
+ value: error.code,
+ mechanism: { type: 'generic', handled: !bug },
+ ...(bug ? { stacktrace: { type: 'raw', frames: stackFrames(cause) } } : {}),
+ },
+ ],
+ // A bug groups by its stack, so two different bugs in one command stay apart.
+ ...(bug
+ ? {}
+ : { $exception_fingerprint: ['hog', command ?? 'unknown', error.code, status].filter(Boolean).join(':') }),
+ error_code: error.code,
+ http_status: status ?? null,
+ api_error_type: error instanceof ApiError ? (error.type ?? null) : null,
+ })
+}
+
export async function run(argv: readonly string[], runtime: Runtime): Promise<number> {
- const { format, noFail, tokens } = preParse(argv)
+ const { format, noFail, noTelemetry, tokens } = preParse(argv)
const terminal = { isTTY: runtime.stdoutIsTTY, hasColors: runtime.stdoutHasColors, columns: runtime.stdoutColumns }
const envFormat = GLOBAL_OPTIONS.output.choices.find((choice) => choice === runtime.env.HOG_OUTPUT)
const mode = resolveMode(runtime.env, terminal, format ?? envFormat)
const state: RunState = { exitCode: 0 }
- const program = createProgram(runtime, mode, state)
+ const telemetry = new Telemetry(
+ runtime,
+ mode,
+ !(
+ noTelemetry ||
+ optOutFlag(runtime.env, GLOBAL_OPTIONS.noTelemetry.env) ||
+ (runtime.telemetryToken !== undefined && (await configOptsOut(runtime)))
+ )
+ )
+ const program = createProgram(runtime, mode, state, telemetry)
if (argv.length === 0) {
program.outputHelp()
return 0
}
+ const started = runtime.now()
const commandIndex = tokens.find((token) => token.kind === 'positional')?.index
const isHelp = commandIndex !== undefined && argv[commandIndex] === 'help'
const args = isHelp ? [...argv.slice(0, commandIndex), ...argv.slice(commandIndex + 1), '--help'] : [...argv]
+ let exitCode: number
+ let failure: HogError | undefined
try {
const legacy = findLegacy(isHelp ? preParse(args).tokens : tokens)
if (legacy) {
+ state.command = legacy.path
throw notPorted(args, legacy)
}
await program.parseAsync(args, { from: 'user' })
// --no-fail also covers a result that reports a problem, like a failed push or a stale SDK.
- return state.noFail && state.exitCode === EXIT_FAILURE ? 0 : state.exitCode
+ exitCode = state.noFail && state.exitCode === EXIT_FAILURE ? 0 : state.exitCode
} catch (caught) {
if (caught instanceof CommanderError && caught.exitCode === 0) {
return 0
}
- const error = toHogError(caught)
- new Output(runtime, mode).error(error)
+ failure = toHogError(caught)
+ new Output(runtime, mode).error(failure)
+ if (failure.exitCode === EXIT_FAILURE && failure.code !== 'not_ported') {
+ captureFailure(telemetry, state.command, failure, caught)
+ }
const ignore = state.noFail ?? (noFail || safeEnvFlag(runtime.env, GLOBAL_OPTIONS.noFail.env))
- return ignore && error.exitCode === EXIT_FAILURE ? 0 : error.exitCode
+ exitCode = ignore && failure.exitCode === EXIT_FAILURE ? 0 : failure.exitCode
}
+
+ // posthog-cli's usage event, so one dashboard covers both CLIs. Option names only, never values.
+ telemetry.capture('posthog cli command run', {
+ command_path: state.command ?? null,
+ exit_code: exitCode,
+ // Before --no-fail, so a push that reports failures still counts as one.
+ success: failure === undefined && state.exitCode === 0,
+ error_code: failure?.code ?? null,
+ duration_ms: runtime.now() - started,
+ options: state.options ?? [],
+ ...state.properties,
+ })
+ await telemetry.flush(state.debug)
+ return exitCode
}
diff --git a/hog/src/commands/api/call.ts b/hog/src/commands/api/call.ts
index 08291c873075..d7315c67db4c 100644
--- a/hog/src/commands/api/call.ts
+++ b/hog/src/commands/api/call.ts
@@ -90,4 +90,6 @@ export default defineCommand({
}
throw toHogError(result.error, tool.name)
},
+
+ telemetry: ({ args, options }) => ({ tool: args.tool, confirm: options.confirm === true }),
})
diff --git a/hog/src/commands/api/info.ts b/hog/src/commands/api/info.ts
index 66ef9193fddb..bfc4464a20ed 100644
--- a/hog/src/commands/api/info.ts
+++ b/hog/src/commands/api/info.ts
@@ -60,4 +60,6 @@ export default defineCommand({
}
out.line(out.style(`Run \`hog api schema ${result.name} <field>\` to see a nested field.`, 'dim'))
},
+
+ telemetry: ({ args }) => ({ tool: args.tool }),
})
diff --git a/hog/src/commands/endpoints/diff.ts b/hog/src/commands/endpoints/diff.ts
index a494c0a2fa3d..9ceeb5cb0943 100644
--- a/hog/src/commands/endpoints/diff.ts
+++ b/hog/src/commands/endpoints/diff.ts
@@ -53,4 +53,10 @@ export default defineCommand({
},
exitCode: (result) => (result.problems.length > 0 || !result.plan.every(inSync) ? 1 : 0),
+
+ telemetry: ({ result }) => ({
+ file_count: result.plan.length,
+ changed: result.plan.filter((item) => !inSync(item)).length,
+ invalid_count: result.problems.length,
+ }),
})
diff --git a/hog/src/commands/endpoints/list.ts b/hog/src/commands/endpoints/list.ts
index 4fd30514e13b..af2d1802a3ad 100644
--- a/hog/src/commands/endpoints/list.ts
+++ b/hog/src/commands/endpoints/list.ts
@@ -35,4 +35,6 @@ export default defineCommand({
agent({ result, out }) {
out.jsonLines(result.endpoints.map(summary))
},
+
+ telemetry: ({ result }) => ({ endpoint_count: result.endpoints.length }),
})
diff --git a/hog/src/commands/endpoints/pull.ts b/hog/src/commands/endpoints/pull.ts
index b4ae8f37b16d..8530d512e5ef 100644
--- a/hog/src/commands/endpoints/pull.ts
+++ b/hog/src/commands/endpoints/pull.ts
@@ -196,4 +196,11 @@ export default defineCommand({
},
exitCode: (result) => (result.problems.length > 0 ? 1 : 0),
+
+ telemetry: ({ result, options }) => ({
+ status: result.status,
+ all: options.all === true,
+ endpoint_count: result.plan.length,
+ written: result.written.length,
+ }),
})
diff --git a/hog/src/commands/endpoints/push.ts b/hog/src/commands/endpoints/push.ts
index 7c5982913e2c..2616195743be 100644
--- a/hog/src/commands/endpoints/push.ts
+++ b/hog/src/commands/endpoints/push.ts
@@ -127,4 +127,13 @@ export default defineCommand({
result.outcomes.some((outcome) => outcome.status === 'failed')
? 1
: 0,
+
+ telemetry: ({ result }) => ({
+ status: result.status,
+ file_count: result.plan.length,
+ invalid_count: result.problems.length,
+ created: result.outcomes.filter((outcome) => outcome.status === 'created').length,
+ updated: result.outcomes.filter((outcome) => outcome.status === 'updated').length,
+ failed: result.outcomes.filter((outcome) => outcome.status === 'failed').length,
+ }),
})
diff --git a/hog/src/commands/endpoints/run.ts b/hog/src/commands/endpoints/run.ts
index b2fe3b1e6bb6..e44728a057d6 100644
--- a/hog/src/commands/endpoints/run.ts
+++ b/hog/src/commands/endpoints/run.ts
@@ -142,4 +142,10 @@ export default defineCommand({
agent({ result, out }) {
out.jsonLines(result.results ?? [])
},
+
+ telemetry: ({ result, args, options }) => ({
+ source: args.name === undefined ? 'file' : 'endpoint',
+ variable_count: options.var?.length ?? 0,
+ row_count: result.results?.length ?? 0,
+ }),
})
diff --git a/hog/src/commands/query/run.ts b/hog/src/commands/query/run.ts
index 4d101b7666e5..4d7158afd322 100644
--- a/hog/src/commands/query/run.ts
+++ b/hog/src/commands/query/run.ts
@@ -64,4 +64,10 @@ export default defineCommand({
agent({ result, out }) {
out.jsonLines(result.results ?? [])
},
+
+ telemetry: ({ result }) => ({
+ row_count: result.results?.length ?? 0,
+ column_count: result.columns?.length ?? 0,
+ has_more: result.hasMore === true,
+ }),
})
diff --git a/hog/src/commands/schema/pull.ts b/hog/src/commands/schema/pull.ts
index 1297c7d4635d..822c4112db34 100644
--- a/hog/src/commands/schema/pull.ts
+++ b/hog/src/commands/schema/pull.ts
@@ -160,4 +160,9 @@ export default defineCommand({
agent({ result, out }) {
out.jsonLines(result.languages)
},
+
+ telemetry: ({ result }) => ({
+ languages: result.languages.map((pulled) => pulled.language),
+ written: result.languages.filter((pulled) => pulled.status === 'written').length,
+ }),
})
diff --git a/hog/src/commands/schema/status.ts b/hog/src/commands/schema/status.ts
index abc9b4c73af1..208bfd7682f8 100644
--- a/hog/src/commands/schema/status.ts
+++ b/hog/src/commands/schema/status.ts
@@ -83,4 +83,9 @@ export default defineCommand({
exitCode: (result) =>
result.languages.length > 0 && result.languages.every((entry) => entry.status === 'up_to_date') ? 0 : 1,
+
+ telemetry: ({ result }) => ({
+ languages: result.languages.map((entry) => (isLanguage(entry.language) ? entry.language : 'unknown')),
+ statuses: result.languages.map((entry) => entry.status),
+ }),
})
diff --git a/hog/src/core/command.ts b/hog/src/core/command.ts
index 561e5685379d..230a4adee4cc 100644
--- a/hog/src/core/command.ts
+++ b/hog/src/core/command.ts
@@ -16,6 +16,9 @@ export interface ArgumentSpec {
interface OptionSource {
env?: readonly string[]
config?: string
+ // The posthog.json key means the opposite of the option, as `cli.telemetry: false` for --no-telemetry.
+ negate?: boolean
+ lenient?: boolean
}
export type OptionSpec =
@@ -79,6 +82,9 @@ interface CommandDefinition<Args, Options, Result> {
human?(input: RenderInput<Args, Options, Result>): void
// What agents, pipes and `-o json` see. Defaults to the result as one line of JSON.
agent?(input: RenderInput<Args, Options, Result>): void
+ // Extra properties for the anonymous usage event: counts and names from the result, never
+ // values, paths or text the caller typed.
+ telemetry?(input: CommandInput<Args, Options> & { result: Result }): Record<string, unknown>
// The exit code for a result. Defaults to 0. Failures throw a HogError instead.
exitCode?(result: Result): number
}
diff --git a/hog/src/core/config.ts b/hog/src/core/config.ts
index 9fcd75fcb7aa..e5ffa4f002b2 100644
--- a/hog/src/core/config.ts
+++ b/hog/src/core/config.ts
@@ -82,6 +82,12 @@ export const PostHogConfig = z
.boolean()
.optional()
.describe('Exit with code 0 when a command fails, like --no-fail. HOG_NO_FAIL overrides it.'),
+ telemetry: z
+ .boolean()
+ .optional()
+ .describe(
+ 'false stops hog from sending anonymous usage data to PostHog for everyone working in this folder.'
+ ),
rateLimit: z
.number()
.int()
diff --git a/hog/src/core/context.ts b/hog/src/core/context.ts
index 57933cc11cc7..bbaecdc7cb21 100644
--- a/hog/src/core/context.ts
+++ b/hog/src/core/context.ts
@@ -9,6 +9,7 @@ import { loadConfig, type LoadedConfig } from './config'
import type { GlobalOptions } from './globals'
import type { Prompts } from './prompts'
import type { Runtime } from './runtime'
+import { Telemetry } from './telemetry'
// What a command's `run` gets besides its own arguments and options. It has no output on
// purpose: `run` returns data, and the command's `human` and `agent` views print it.
@@ -23,7 +24,8 @@ export class Context {
readonly globals: GlobalOptions,
readonly mode: Mode,
readonly tree: CommandTree,
- loaded?: Promise<LoadedConfig | undefined>
+ loaded?: Promise<LoadedConfig | undefined>,
+ readonly telemetry: Telemetry = new Telemetry(runtime, mode, false)
) {
this.loaded = loaded
}
diff --git a/hog/src/core/globals.ts b/hog/src/core/globals.ts
index 831aa6129e2c..338fbe820c9d 100644
--- a/hog/src/core/globals.ts
+++ b/hog/src/core/globals.ts
@@ -48,6 +48,14 @@ export const GLOBAL_OPTIONS = {
env: ['HOG_SKIP_SSL_VERIFICATION'],
description: 'Accept any TLS certificate, for a self-hosted PostHog with a self-signed one',
},
+ noTelemetry: {
+ type: 'boolean',
+ env: ['HOG_NO_TELEMETRY', 'DO_NOT_TRACK'],
+ config: 'cli.telemetry',
+ negate: true,
+ lenient: true,
+ description: 'Send no anonymous usage data to PostHog',
+ },
rateLimit: {
type: 'string',
placeholder: 'requests',
@@ -87,6 +95,16 @@ export function envFlag(env: Env, names: readonly string[]): boolean | undefined
return undefined
}
+// For opt-outs shared with other tools, like DO_NOT_TRACK: any value but an explicit "no" opts out,
+// and an unknown value never breaks a command.
+export function optOutFlag(env: Env, names: readonly string[]): boolean | undefined {
+ const set = names.map((name) => env[name]?.trim().toLowerCase()).filter((value) => value !== undefined)
+ if (set.length === 0) {
+ return undefined
+ }
+ return set.some((value) => !FALSE_VALUES.has(value))
+}
+
function envValue(env: Env, names: readonly string[]): { name: string; value: string } | undefined {
for (const name of names) {
const value = env[name]
@@ -113,7 +131,9 @@ export function resolveGlobals(
const envNames = spec.env ?? []
let value: unknown = flags[name]
let source = `--${kebabCase(name)}`
- if (value === undefined && spec.type === 'boolean') {
+ if (value === undefined && spec.type === 'boolean' && spec.lenient) {
+ value = optOutFlag(env, envNames)
+ } else if (value === undefined && spec.type === 'boolean') {
value = envFlag(env, envNames)
source = envNames.find((envName) => env[envName] !== undefined) ?? source
} else if (value === undefined) {
@@ -123,7 +143,7 @@ export function resolveGlobals(
}
const configured = spec.config === undefined ? undefined : configValue(config, spec.config)
if (value === undefined && configured !== undefined) {
- value = spec.type === 'string' ? String(configured) : configured
+ value = spec.type === 'string' ? String(configured) : spec.negate ? !configured : configured
source = `${spec.config} in posthog.json`
}
if (spec.type === 'string' && spec.choices && value !== undefined && !spec.choices.includes(String(value))) {
diff --git a/hog/src/core/runtime.ts b/hog/src/core/runtime.ts
index e9126c1417cc..3a3c2e394526 100644
--- a/hog/src/core/runtime.ts
+++ b/hog/src/core/runtime.ts
@@ -7,6 +7,7 @@ import type { ApiToolLibrary } from '@posthog/mcp/src/cli/library-types'
import { HogError } from './errors'
import { clackPrompts, type Prompts } from './prompts'
+import { DEFAULT_TELEMETRY_TOKEN } from './telemetry'
export type Env = Readonly<Record<string, string | undefined>>
@@ -47,6 +48,8 @@ export interface Runtime {
// Resolves to false when no browser could be started, for example on a server without one.
openUrl: (url: string) => Promise<boolean>
prompts: Prompts
+ // The project token for anonymous usage events. Undefined turns them off, as in tests.
+ telemetryToken: string | undefined
// Accepts any TLS certificate from here on, for every request, including the API tools' own.
skipTlsVerification: () => void
// The MCP server's tool catalog, which `hog api` browses and calls. Loaded on first use: it is large.
@@ -150,6 +153,7 @@ export function processRuntime(): Runtime {
}
},
prompts: clackPrompts(),
+ telemetryToken: DEFAULT_TELEMETRY_TOKEN,
skipTlsVerification: () => {
// Runs only for --skip-ssl-verification, posthog-cli's opt-in flag for self-hosted certificates.
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0' // nosemgrep: trailofbits.generic.node-disable-certificate-validation.node-disable-certificate-validation
diff --git a/hog/src/core/telemetry.test.ts b/hog/src/core/telemetry.test.ts
new file mode 100644
index 000000000000..fb41e598d8b7
--- /dev/null
+++ b/hog/src/core/telemetry.test.ts
@@ -0,0 +1,212 @@
+import { describe, expect, test } from 'bun:test'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { runHog, TEST_CREDENTIALS, type HogRun } from '@/testing'
+
+import { SMALL_MAPPING } from '../../test/parity/fixtures'
+import { detectCi } from './telemetry'
+
+const TELEMETRY = 'https://us.i.posthog.com/batch/'
+const ON = { telemetryToken: 'phc_test' }
+const AGENT = { ...TEST_CREDENTIALS, CLAUDECODE: '1' }
+
+function events(
+ result: HogRun
+): { event: string; distinct_id: string; timestamp: string; properties: Record<string, any> }[] {
+ return result.requests.filter((request) => request.url === TELEMETRY).flatMap((request: any) => request.body.batch)
+}
+
+describe('telemetry', () => {
+ test('a command sends one usage event with option names and no values', async () => {
+ const result = await runHog(['endpoints', 'run', 'by-type', '--var', 'secret=hunter2'], {
+ ...ON,
+ env: AGENT,
+ respond: (url) =>
+ url === TELEMETRY
+ ? { status: 200, body: {} }
+ : { status: 200, body: { columns: ['n'], results: [[1]] } },
+ })
+ expect(events(result)).toEqual([
+ {
+ event: 'posthog cli command run',
+ distinct_id: expect.any(String),
+ timestamp: expect.any(String),
+ properties: expect.objectContaining({
+ command_name: 'endpoints_run',
+ command_path: 'endpoints run',
+ success: true,
+ exit_code: 0,
+ options: ['var'],
+ source: 'endpoint',
+ variable_count: 1,
+ env_id: null,
+ agent: 'claude-code',
+ $process_person_profile: false,
+ }),
+ },
+ ])
+ expect(JSON.stringify(result.requests.filter((request) => request.url === TELEMETRY))).not.toContain('hunter2')
+ })
+
+ test.each([
+ ['a query that starts with dashes', ['query', 'run', '--secret-customer query']],
+ ['a value that starts with dashes', ['et', 'release', '--release-version', '--secret-customer']],
+ ])('%s never reaches telemetry', async (_name, argv) => {
+ const result = await runHog(argv, { ...ON, env: AGENT, respond: () => ({ status: 200, body: {} }) })
+ expect(events(result).length).toBeGreaterThan(0)
+ expect(JSON.stringify(events(result))).not.toContain('secret-customer')
+ })
+
+ test.each([
+ ['with no identity cache', {}],
+ // A broken cache must not fail the command.
+ ['with a cache that is not an object', { '/home/test/.posthog/hog-telemetry-identity.json': 'null' }],
+ ])(
+ 'a PostHog Cloud key ties events to its user and groups, and hog looks them up once, %s',
+ async (_name, files) => {
+ const cloud = { ...AGENT, HOG_HOST: 'https://us.posthog.com' }
+ const respond = (url: string): { status: number; body: unknown } =>
+ url.endsWith('/api/users/@me/')
+ ? { status: 200, body: { distinct_id: 'user-1', organization: { id: 'org-current' } } }
+ : url.endsWith('/api/projects/7/')
+ ? { status: 200, body: { uuid: 'project-uuid', organization: 'org-1' } }
+ : { status: 200, body: {} }
+ const first = await runHog(['commands'], { ...ON, env: cloud, respond, files })
+ const second = await runHog(['commands'], { ...ON, env: cloud, respond, files: first.files })
+
+ for (const result of [first, second]) {
+ const [event] = events(result)
+ expect(event!.distinct_id).toBe('user-1')
+ expect(event!.properties).toMatchObject({
+ env_id: '7',
+ $groups: { organization: 'org-1', project: 'project-uuid' },
+ })
+ expect(event!.properties).not.toHaveProperty('$process_person_profile')
+ }
+ expect(second.requests.filter((request) => request.url !== TELEMETRY)).toEqual([])
+ }
+ )
+
+ test.each([
+ [
+ 'a GitHub-hosted job',
+ { GITHUB_ACTIONS: 'true', RUNNER_ENVIRONMENT: 'github-hosted' },
+ 'github-actions',
+ 'github-hosted',
+ ],
+ [
+ 'a Blacksmith runner',
+ { GITHUB_ACTIONS: 'true', RUNNER_ENVIRONMENT: 'self-hosted', BLACKSMITH_VM_ID: 'vm' },
+ 'github-actions',
+ 'blacksmith',
+ ],
+ ['a Depot runner', { GITHUB_ACTIONS: 'true', RUNNER_NAME: 'depot-abc123' }, 'github-actions', 'depot'],
+ [
+ 'Depot CI, which looks like GitHub Actions too',
+ { DEPOT_JOB_URL: 'https://depot.dev/x', GITHUB_ACTIONS: 'true' },
+ 'depot-ci',
+ null,
+ ],
+ ['Harness, which also sets Drone variables', { HARNESS_BUILD_ID: '1', DRONE: 'true' }, 'harness', null],
+ ['a Vercel build', { VERCEL: '1', CI: '1' }, 'vercel', null],
+ ['a Vercel function, which is not CI', { VERCEL: '1' }, null, null],
+ ['Cloudflare Workers Builds', { WORKERS_CI: '1' }, 'cloudflare-workers', null],
+ ])('detects %s', (_name, env, provider, runner) => {
+ expect(detectCi(env)).toEqual({ provider, runner })
+ })
+
+ test('the install ID stays the same across runs', async () => {
+ const first = await runHog(['commands'], { ...ON, env: AGENT })
+ const second = await runHog(['commands'], { ...ON, env: AGENT, files: first.files })
+ expect(events(second)[0]!.distinct_id).toBe(events(first)[0]!.distinct_id)
+ expect(first.files['/home/test/.posthog/hog-telemetry-id']).toBe(`${events(first)[0]!.distinct_id}\n`)
+ })
+
+ test.each([
+ ['HOG_NO_TELEMETRY', ['commands'], { HOG_NO_TELEMETRY: '1' }, {}],
+ ['DO_NOT_TRACK', ['commands'], { DO_NOT_TRACK: '1' }, {}],
+ ['--no-telemetry', ['commands', '--no-telemetry'], {}, {}],
+ ['--no-telemetry on a usage error', ['nope', '--no-telemetry'], {}, {}],
+ ['cli.telemetry in posthog.json', ['commands'], {}, { '/work/posthog.json': '{"cli":{"telemetry":false}}' }],
+ ['cli.telemetry on a usage error', ['nope'], {}, { '/work/posthog.json': '{"cli":{"telemetry":false}}' }],
+ [
+ 'cli.telemetry in a posthog.json with an unknown key',
+ ['commands'],
+ {},
+ { '/work/posthog.json': '{"cli":{"telemetry":false},"newerSetting":1}' },
+ ],
+ ['DO_NOT_TRACK with a value hog does not know', ['commands'], { DO_NOT_TRACK: 'please' }, {}],
+ ])('%s turns telemetry off', async (_name, argv, env, files) => {
+ const result = await runHog(argv, { ...ON, env: { ...AGENT, ...env }, files })
+ expect(events(result)).toEqual([])
+ expect(result.files['/home/test/.posthog/hog-telemetry-id']).toBeUndefined()
+ })
+
+ test.each([
+ ['a missing endpoint', 404, 'not_found', 'hog:endpoints get:not_found:404'],
+ ['a key without the scope', 403, 'permission_denied', 'hog:endpoints get:permission_denied:403'],
+ ])('%s sends its code and status, never the message', async (_name, status, code, fingerprint) => {
+ const result = await runHog(['endpoints', 'get', 'missing'], {
+ ...ON,
+ env: AGENT,
+ respond: (url) =>
+ url === TELEMETRY
+ ? { status: 200, body: {} }
+ : { status, body: { type: 'invalid_request', code, detail: 'Private detail /Users/me/app' } },
+ })
+
+ const [exception, run] = events(result)
+ expect(exception!.properties).toMatchObject({
+ $exception_list: [{ type: code, value: code }],
+ $exception_fingerprint: fingerprint,
+ http_status: status,
+ })
+ expect(JSON.stringify(events(result))).not.toContain('Private detail')
+ expect(run!.properties).toMatchObject({ success: false, error_code: code, exit_code: 1 })
+ })
+
+ test('a posthog.json hog cannot parse stops the command, and telemetry still reports it', async () => {
+ const result = await runHog(['endpoints', 'list'], {
+ ...ON,
+ env: AGENT,
+ files: { '/work/posthog.json': '{"cli":' },
+ respond: () => ({ status: 200, body: {} }),
+ })
+ expect(result.exitCode).toBe(1)
+ expect(events(result).map((event) => [event.event, event.properties.error_code])).toEqual([
+ ['$exception', 'invalid_config'],
+ ['posthog cli command run', 'invalid_config'],
+ ])
+ })
+
+ test('an upload sends the posthog-cli upload events', async () => {
+ const folder = mkdtempSync(join(tmpdir(), 'hog-telemetry-'))
+ writeFileSync(join(folder, 'mapping.txt'), SMALL_MAPPING)
+ const result = await runHog(
+ ['et', 'upload', 'mapping.txt', '--map-id', 'map-1', '--release-name', 'app', '--release-version', '1'],
+ {
+ ...ON,
+ env: AGENT,
+ cwd: folder,
+ useDisk: true,
+ respond: (url) => {
+ if (url.includes('/releases/hash/')) {
+ return { status: 200, body: { id: 'release-1', hash_id: 'h', version: '1', project: 'app' } }
+ }
+ return url.endsWith('/bulk_check_upload/')
+ ? { status: 200, body: { chunk_ids_to_upload: [] } }
+ : { status: 200, body: {} }
+ },
+ }
+ )
+ expect(result.exitCode).toBe(0)
+ const uploads = events(result).filter((event) => event.event.startsWith('error_tracking_cli'))
+ expect(uploads.map((event) => [event.event, event.properties.type, event.properties.file_count])).toEqual([
+ ['error_tracking_cli_sourcemaps_upload_started', 'proguard', 1],
+ ['error_tracking_cli_sourcemaps_upload_finished', 'proguard', 1],
+ ])
+ expect(uploads[1]!.properties).toMatchObject({ success: true, skipped_already_present: 1, uploaded: 0 })
+ })
+})
diff --git a/hog/src/core/telemetry.ts b/hog/src/core/telemetry.ts
new file mode 100644
index 000000000000..b3368961d3e2
--- /dev/null
+++ b/hog/src/core/telemetry.ts
@@ -0,0 +1,294 @@
+import { createHash, randomUUID } from 'node:crypto'
+
+import { posthogFile, type Credentials } from '@/posthog/credentials'
+import { VERSION } from '@/version'
+
+import type { Mode } from './agent'
+import type { Env, Runtime } from './runtime'
+
+// 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
+}
+
+interface CachedIdentity extends Identity {
+ checkedAt: number
+}
+
+// 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')
+}
+
+const text = (value: unknown): string | undefined => (typeof value === 'string' && value ? value : undefined)
+
+// 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 credentials = await this.credentials?.().catch(() => undefined)
+ const identity = credentials ? await this.identity(credentials) : 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: credentials && isCloudHost(credentials.host) ? credentials.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(credentials: Credentials): Promise<Identity | undefined> {
+ if (!isCloudHost(credentials.host)) {
+ return undefined
+ }
+ let path: string
+ try {
+ path = posthogFile(this.runtime, IDENTITY_FILE)
+ } catch {
+ return undefined
+ }
+ const key = createHash('sha256')
+ .update(`${credentials.host}\n${credentials.projectId}\n${credentials.apiKey}`)
+ .digest('hex')
+ let cache: Record<string, CachedIdentity> = {}
+ try {
+ const parsed: unknown = JSON.parse(await this.runtime.readFile(path))
+ // A cache that isn't an object is broken, so hog starts a new one instead of failing the command.
+ if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+ cache = parsed as Record<string, CachedIdentity>
+ }
+ } catch {
+ // No cache yet.
+ }
+ const cached = cache[key]
+ const now = this.runtime.now()
+ if (cached && now - cached.checkedAt < (cached.distinctId ? 30 : 1) * DAY_MS) {
+ return cached
+ }
+ const identity = await this.lookup(credentials)
+ cache[key] = { ...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(credentials: Credentials): Promise<Identity> {
+ const get = async (path: string): Promise<Record<string, any> | undefined> => {
+ try {
+ const response = await this.runtime.fetch(new URL(path, credentials.host), {
+ headers: { Authorization: `Bearer ${credentials.apiKey}` },
+ signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS),
+ })
+ return response.ok ? ((await response.json()) as Record<string, any>) : undefined
+ } catch {
+ return undefined
+ }
+ }
+ const [user, project] = await Promise.all([
+ get('/api/users/@me/'),
+ get(`/api/projects/${credentials.projectId}/`),
+ ])
+ return {
+ distinctId: text(user?.distinct_id),
+ organization: text(project?.organization) ?? text(user?.organization?.id),
+ project: text(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
+ }
+}
diff --git a/hog/src/error-tracking/run.ts b/hog/src/error-tracking/run.ts
index 7e06ddafe58a..ec52ce4934cb 100644
--- a/hog/src/error-tracking/run.ts
+++ b/hog/src/error-tracking/run.ts
@@ -151,7 +151,14 @@ export class Session {
constructor(private readonly ctx: Context) {}
getClient(): Promise<SymbolSetClient> {
- this.client ??= this.ctx.credentials().then((credentials) => new SymbolSetClient(this.ctx.runtime, credentials))
+ this.client ??= this.ctx
+ .credentials()
+ .then(
+ (credentials) =>
+ new SymbolSetClient(this.ctx.runtime, credentials, () =>
+ this.ctx.telemetry.capture('error_tracking_cli_sourcemaps_upload_endpoint_fallback')
+ )
+ )
return this.client
}
}
@@ -562,16 +569,45 @@ export async function upload(
groups.set(key, [item])
}
}
- for (const group of groups.values()) {
- const client = await session.getClient()
- const outcome = await client.upload(
- group.map((item) => item.upload),
- { concurrency: options.concurrency, ...group[0]!.policy }
- )
- for (const [chunkId, status] of outcome.status) {
- statuses.set(chunkId, status)
+ // posthog-cli's upload events, so its dashboards keep working. `type` was plain or hermes there.
+ const kinds: Record<string, number> = {}
+ for (const item of planned) {
+ kinds[item.artifact.kind] = (kinds[item.artifact.kind] ?? 0) + 1
+ }
+ const kindNames = Object.keys(kinds)
+ const uploadProperties = {
+ type: kindNames.length === 1 ? (kindNames[0] === 'js' ? 'plain' : kindNames[0]) : 'mixed',
+ kinds,
+ file_count: planned.length,
+ total_bytes: planned.reduce((sum, item) => sum + item.upload.data.length, 0),
+ }
+ ctx.telemetry.capture('error_tracking_cli_sourcemaps_upload_started', uploadProperties)
+ const uploadStarted = ctx.runtime.now()
+ const finished = (error?: unknown): void => {
+ const counts = [...statuses.values()]
+ ctx.telemetry.capture('error_tracking_cli_sourcemaps_upload_finished', {
+ ...uploadProperties,
+ duration_ms: ctx.runtime.now() - uploadStarted,
+ success: error === undefined,
+ uploaded: counts.filter((status) => status === 'uploaded').length,
+ skipped_already_present: counts.filter((status) => status === 'already_present').length,
+ skipped_too_large: counts.filter((status) => status === 'too_large').length,
+ error_code: error === undefined ? null : error instanceof HogError ? error.code : 'internal_error',
+ })
+ }
+ try {
+ for (const group of groups.values()) {
+ const client = await session.getClient()
+ await client.upload(
+ group.map((item) => item.upload),
+ { concurrency: options.concurrency, ...group[0]!.policy, progress: statuses }
+ )
}
+ } catch (error) {
+ finished(error)
+ throw error
}
+ finished()
let deletedMaps: string[] = []
if (options.deleteAfter && jsUploadable) {
diff --git a/hog/src/error-tracking/upload.ts b/hog/src/error-tracking/upload.ts
index 07496a6a01ad..65b97277bb44 100644
--- a/hog/src/error-tracking/upload.ts
+++ b/hog/src/error-tracking/upload.ts
@@ -24,6 +24,8 @@ export interface UploadOptions {
force: boolean
skipOnConflict: boolean
concurrency?: number
+ // Filled as chunks finish, so a caller still sees what a failed run uploaded.
+ progress?: Map<string, UploadStatus>
}
export interface UploadOutcome {
@@ -143,7 +145,8 @@ export class SymbolSetClient {
constructor(
private readonly runtime: Runtime,
- private readonly credentials: Credentials
+ private readonly credentials: Credentials,
+ private readonly onFallback: () => void = () => {}
) {
this.throttle = new Throttle(runtime, RATE_LIMIT_PER_MINUTE)
}
@@ -201,7 +204,7 @@ export class SymbolSetClient {
options: UploadOptions,
runId: string
): Promise<UploadOutcome> {
- const status = new Map<string, UploadStatus>()
+ const status = options.progress ?? new Map<string, UploadStatus>()
const contentHashes = new Map<string, string>()
const kept: (SymbolSetUpload & { hash: string })[] = []
for (const upload of uploads) {
@@ -388,8 +391,9 @@ export class SymbolSetClient {
`Object storage answered ${response.status}: ${await response.text()}`
)
}
- if (useFallback && primaryTransportErrors >= 2 && fallbackTransportErrors === 0) {
+ if (useFallback && primaryTransportErrors >= 2 && fallbackTransportErrors === 0 && !this.preferFallback) {
this.preferFallback = true
+ this.onFallback()
}
}).catch((error) => {
throw new HogError(
diff --git a/hog/src/posthog/api.ts b/hog/src/posthog/api.ts
index 4fbbb20fc4e7..d589eca37e17 100644
--- a/hog/src/posthog/api.ts
+++ b/hog/src/posthog/api.ts
@@ -69,6 +69,10 @@ export class ApiError extends HogError {
) {
super(code, message, hint)
}
+
+ override withHint(hint: string): ApiError {
+ return new ApiError(this.status, this.type, this.code, this.message, hint)
+ }
}
export class PostHogApi {
diff --git a/hog/src/testing.ts b/hog/src/testing.ts
index 360dc35db9cf..c0a25feccc34 100644
--- a/hog/src/testing.ts
+++ b/hog/src/testing.ts
@@ -21,6 +21,7 @@ export interface FakeRuntimeOptions {
// Answers every API request. Without it, requests fail with HTTP 500. A string body is sent
// as is, for JSON that JSON.stringify can't produce.
respond?: (url: string, body: unknown) => { status: number; body: unknown }
+ telemetryToken?: string
// The MCP tool catalog `hog api` loads. Without it, loading the catalog fails the test.
apiTools?: ApiToolLibrary
}
@@ -136,6 +137,7 @@ export function fakeRuntime(options: FakeRuntimeOptions = {}): FakeRuntime {
return true
},
prompts: fakePrompts([...(options.answers ?? [])]),
+ telemetryToken: options.telemetryToken,
skipTlsVerification: () => {
tls.verify = false
},