: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
feat(hogli): stamp session, command kind, and rerun on telemetry events (#122357)
Georges-Antoine Assi3576d5bc3d47
diff --git a/tools/hogli-commands/README.md b/tools/hogli-commands/README.mdindex 644382759af6..75f9f7dcb2fe 100644--- a/tools/hogli-commands/README.md+++ b/tools/hogli-commands/README.md@@ -50,7 +50,7 @@ That's it. No side-effect imports, no central registration list to maintain.`config.boot_modules` in `hogli.yaml` lists modules imported once at startup. They register hooks via `hogli.hooks`:- `hogli_commands.prechecks` — declares the `migrations` precheck (used by `dev:start`).-- `hogli_commands.telemetry_props` — adds PostHog environment props (`environment`, `actor`, `agent`, `is_agent`, `git_hook`, `in_flox`, `is_worktree`, `is_posthog_dev`, `process_manager`, `has_devenv_config`, `repo_sha`, `repo_commit_date`) to every `command_started` / `command_completed` event.+- `hogli_commands.telemetry_props` — adds PostHog environment props (`environment`, `actor`, `agent`, `is_agent`, `git_hook`, `in_flox`, `is_worktree`, `is_posthog_dev`, `process_manager`, `has_devenv_config`, `repo_sha`, `repo_commit_date`, `git_branch`, `pr_number`, `command_kind`, `session_id`, `session_id_source`, `is_rerun`) to every `command_started` / `command_completed` event.- `hogli_commands.hint_hook` — shows a contextual hint after successful commands.Add a new boot module by creating a file that calls one of the `register_*` helpers from `hogli.hooks` at import time, then list it under `config.boot_modules:`. Keep these modules import-light: the precheck handler in `prechecks.py` is the canonical example of deferring its heavy import until the handler actually fires.diff --git a/tools/hogli-commands/hogli_commands/telemetry_props.py b/tools/hogli-commands/hogli_commands/telemetry_props.pyindex 05816ea02e24..5fa8c9e4bfc0 100644--- a/tools/hogli-commands/hogli_commands/telemetry_props.py+++ b/tools/hogli-commands/hogli_commands/telemetry_props.py@@ -11,10 +11,18 @@ from __future__ import annotationsimport osimport reimport sys+import jsonimport time+import fcntl+import socket+import hashlib+import secretsimport functools+import contextlibimport subprocessimport configparser+from collections.abc import Iterator, Sequence+from dataclasses import dataclassfrom pathlib import Pathfrom typing import Any, Literal@@ -22,6 +30,8 @@ from hogli.hooks import register_telemetry_propertiesfrom hogli.manifest import REPO_ROOTfrom hogli.telemetry import _load_config, _save_config, is_ci+from hogli_commands.test_runner import runs_on_playwright+_POSTHOG_DEV_CACHE_TTL_SECONDS = 30 * 86400 # 30 days@@ -54,6 +64,46 @@ _STANDARD_AGENT_ENV_VARS = ("AI_AGENT", "AGENT")_ACTOR_ENV_VAR = "HOGLI_ACTOR"+# Ordered like _AGENT_ENV_MARKERS: posthog-code runs claude or codex inside its task run,+# so the task run id must win over the session id of the inner harness.+_AGENT_SESSION_ENV_VARS = (+ "HOGLI_SESSION_ID",+ "POSTHOG_TASK_RUN_ID",+ "CLAUDE_CODE_SESSION_ID",+ "CODEX_THREAD_ID",+)++_PR_NUMBER_ENV_VARS = ("HOGLI_PR_NUMBER", "GITHUB_PR_NUMBER", "BUILDKITE_PULL_REQUEST")+_GITHUB_PULL_REF = re.compile(r"^refs/pull/(\d+)/")++_TELEMETRY_STATE_PATH = Path.home() / ".hogli" / "telemetry_state.json"+_STATE_LOCK_ATTEMPTS = 5+_STATE_LOCK_RETRY_SECONDS = 0.002+_RERUN_WINDOW_SECONDS = 30 * 60+_MAX_RECORDED_RUNS = 200+# The terminal session cache is keyed by the session leader pid. After this idle age the+# pid can belong to a new terminal, so the id is derived again from the leader start time.+_TERMINAL_SESSION_TTL_SECONDS = 12 * 3600+_MAX_CACHED_TERMINAL_SESSIONS = 50++CommandKind = Literal[+ "verify-lint",+ "verify-typecheck",+ "verify-test",+ "verify-preflight",+ "verify-e2e",+ "build",+ "run-stack",+ "devbox",+ "other",+]++_RUN_STACK_COMMANDS = frozenset(+ {"start", "up", "wait", "stop", "down", "dev:up", "services:ready", "db:migrate", "migrations:run"}+)+_LINT_COMMANDS = frozenset({"tool:ruff", "migrations:check"})+_NOT_TESTS = frozenset({"test:quarantine"})+def _declared(var: str) -> str:"""Self-declared label from *var*, normalized so a sloppy export ('Sandbox ')@@ -221,6 +271,225 @@ def _is_posthog_dev() -> bool:return is_member+def classify_command(command: str | None, argv: Sequence[str] = ()) -> CommandKind:+ """Bucket a hogli command by the kind of work it does, so verification loops can be counted.++ *argv* holds the arguments after the command name. ``hogli test`` dispatches on its+ paths, so a path the test runner hands to Playwright makes it an e2e run.+ """+ if not command:+ return "other"+ segments = command.split(":")+ prefix = segments[0]+ leaf = segments[-1]+ if command == "ci:preflight":+ return "verify-preflight"+ if command == "test:e2e" or (+ command == "test" and any(runs_on_playwright(arg) for arg in argv if not arg.startswith("-"))+ ):+ return "verify-e2e"+ if "typecheck" in leaf or "mypy" in leaf:+ return "verify-typecheck"+ if command not in _NOT_TESTS and (prefix == "test" or leaf == "test"):+ return "verify-test"+ if prefix in {"lint", "format"} or "lint" in segments or command in _LINT_COMMANDS:+ return "verify-lint"+ if prefix == "build" or leaf == "build":+ return "build"+ if prefix == "devbox":+ return "devbox"+ if command in _RUN_STACK_COMMANDS or prefix in {"start", "docker", "check"}:+ return "run-stack"+ return "other"+++@dataclass(frozen=True)+class RecordedRun:+ session_id: str+ kind: str+ at: float+++def is_rerun(runs: Sequence[RecordedRun], session_id: str, kind: str, now: float) -> bool:+ """Whether *kind* already ran in *session_id* within the rerun window before *now*."""+ return any(+ run.session_id == session_id and run.kind == kind and 0 <= now - run.at <= _RERUN_WINDOW_SECONDS for run in runs+ )+++def _recent_runs(runs: Sequence[RecordedRun], now: float) -> list[RecordedRun]:+ recent = [run for run in runs if 0 <= now - run.at <= _RERUN_WINDOW_SECONDS]+ return recent[-_MAX_RECORDED_RUNS:]+++def _state_lock() -> Iterator[None]:+ """Serialize the state read-modify-write across hogli processes.++ Gives up after a few milliseconds and runs unlocked, because a lost rerun record+ costs less than a delayed command.+ """+ handle = None+ try:+ _TELEMETRY_STATE_PATH.parent.mkdir(parents=True, exist_ok=True)+ handle = _TELEMETRY_STATE_PATH.with_name(f"{_TELEMETRY_STATE_PATH.name}.lock").open("a")+ for attempt in range(_STATE_LOCK_ATTEMPTS):+ try:+ fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)+ break+ except BlockingIOError:+ if attempt < _STATE_LOCK_ATTEMPTS - 1:+ time.sleep(_STATE_LOCK_RETRY_SECONDS)+ except Exception:+ pass+ try:+ yield+ finally:+ if handle is not None:+ handle.close()+++def _load_state() -> dict[str, Any]:+ try:+ state = json.loads(_TELEMETRY_STATE_PATH.read_text())+ return state if isinstance(state, dict) else {}+ except Exception:+ return {}+++def _save_state(state: dict[str, Any]) -> None:+ """Write through a rename so a concurrent hogli process never reads a partial file."""+ try:+ _TELEMETRY_STATE_PATH.parent.mkdir(parents=True, exist_ok=True)+ tmp = _TELEMETRY_STATE_PATH.with_name(f"{_TELEMETRY_STATE_PATH.name}.{os.getpid()}.tmp")+ tmp.write_text(json.dumps(state))+ tmp.replace(_TELEMETRY_STATE_PATH)+ except Exception:+ pass+++def _parse_runs(raw: Any) -> list[RecordedRun]:+ runs: list[RecordedRun] = []+ for entry in raw if isinstance(raw, list) else []:+ try:+ session_id, kind, at = entry+ runs.append(RecordedRun(session_id=str(session_id), kind=str(kind), at=float(at)))+ except Exception:+ continue+ return runs+++def _proc_start_time(pid: int) -> str | None:+ """Start time of *pid* from ``/proc``, which tells apart two terminals that got the same pid."""+ try:+ stat = Path(f"/proc/{pid}/stat").read_text()+ # Field 2 is the command name and can contain spaces, so split after its closing paren.+ return stat.rsplit(")", 1)[1].split()[19]+ except Exception:+ return None+++def _ps_start_time(pid: int) -> str | None:+ try:+ result = subprocess.run(["ps", "-o", "lstart=", "-p", str(pid)], capture_output=True, text=True, timeout=1)+ started = result.stdout.strip()+ return started if result.returncode == 0 and started else None+ except Exception:+ return None+++def _terminal_session_id(state: dict[str, Any], now: float) -> str | None:+ """Stable id for the terminal session, shared by every hogli call made in it.++ The session leader (the login shell, or the harness that spawned the shell) outlives+ each hogli process. Where ``/proc`` gives the leader start time cheaply, every call+ checks it, so a recycled leader pid gets a new id. Elsewhere the cache in *state*+ keeps the ``ps`` call off most invocations.+ """+ try:+ leader = os.getsid(0)+ except Exception:+ return None+ started = _proc_start_time(leader)+ cache = state.get("terminal_sessions")+ cache = cache if isinstance(cache, dict) else {}+ cached = cache.get(str(leader))+ if (+ started is None+ and isinstance(cached, dict)+ and now - float(cached.get("seen", 0)) < _TERMINAL_SESSION_TTL_SECONDS+ ):+ session_id = str(cached.get("id"))+ else:+ started = started or _ps_start_time(leader)+ if started is None:+ return None+ digest = hashlib.sha256(f"{socket.gethostname()}|{leader}|{started}".encode()).hexdigest()+ session_id = f"term-{digest[:16]}"+ cache[str(leader)] = {"id": session_id, "seen": now}+ newest = sorted(cache.items(), key=lambda item: float(item[1].get("seen", 0)), reverse=True)+ state["terminal_sessions"] = dict(newest[:_MAX_CACHED_TERMINAL_SESSIONS])+ return session_id+++def _agent_session_id(state: dict[str, Any]) -> str | None:+ for var in _AGENT_SESSION_ENV_VARS:+ value = os.environ.get(var, "").strip()+ if value:+ salt = state.get("session_salt")+ if not isinstance(salt, str) or not salt:+ salt = secrets.token_hex(16)+ state["session_salt"] = salt+ digest = hashlib.sha256(f"{salt}|{value}".encode()).hexdigest()+ return f"agent-{digest[:16]}"+ return None+++def _session_properties(command: str | None) -> dict[str, Any]:+ """Session, command kind, and rerun flag for this invocation.++ Cached per process, so command_started, command_completed and ci_preflight_run+ report the same values and the run is recorded once. A second record would make+ the invocation count as its own rerun.+ """+ kind = classify_command(command, sys.argv[2:])+ props: dict[str, Any] = {"command_kind": kind, "session_id": None, "session_id_source": None, "is_rerun": None}+ try:+ now = time.time()+ with _state_lock():+ state = _load_state()+ session_id = _agent_session_id(state)+ source = "agent" if session_id else None+ if session_id is None:+ session_id = _terminal_session_id(state, now)+ source = "terminal"+ if session_id is None:+ return props+ runs = _parse_runs(state.get("runs"))+ props.update(+ session_id=session_id, session_id_source=source, is_rerun=is_rerun(runs, session_id, kind, now)+ )+ recorded = _recent_runs([*runs, RecordedRun(session_id=session_id, kind=kind, at=now)], now)+ state["runs"] = [[run.session_id, run.kind, run.at] for run in recorded]+ _save_state(state)+ except Exception:+ pass+ return props+++def _pr_number() -> int | None:+ """PR number from the environment only, because a ``gh`` call on every command is too slow."""+ match = _GITHUB_PULL_REF.match(os.environ.get("GITHUB_REF", ""))+ if match:+ return int(match.group(1))+ for var in _PR_NUMBER_ENV_VARS:+ value = os.environ.get(var, "").strip()+ if value.isdigit():+ return int(value)+ return None++def _posthog_telemetry_properties(command: str | None = None) -> dict[str, Any]:# Agent-driven traffic (e.g. skills running metabase:query) otherwise# swamps human usage stats.@@ -237,6 +506,8 @@ def _posthog_telemetry_properties(command: str | None = None) -> dict[str, Any]:"is_posthog_dev": _is_posthog_dev(),"process_manager": _infer_process_manager(command),"git_branch": _git_branch(),+ "pr_number": _pr_number(),+ **_session_properties(command),**_repo_commit_properties(),}diff --git a/tools/hogli-commands/hogli_commands/test_runner.py b/tools/hogli-commands/hogli_commands/test_runner.pyindex 248447104afb..217e673e0141 100644--- a/tools/hogli-commands/hogli_commands/test_runner.py+++ b/tools/hogli-commands/hogli_commands/test_runner.py@@ -565,6 +565,14 @@ def _detect_directory(dir_path: str) -> TestRunConfig:)+def runs_on_playwright(file_path: str) -> bool:+ """Whether `hogli test <file_path>` hands the path to Playwright, resolved from the current directory."""+ try:+ return detect_test_type(_resolve_to_repo_relative(file_path)).test_type == "playwright"+ except click.UsageError:+ return False++def detect_test_type(file_path: str) -> TestRunConfig:"""Detect the test type from a file or directory path and return run configuration.diff --git a/tools/hogli-commands/hogli_commands/tests/test_commands.py b/tools/hogli-commands/hogli_commands/tests/test_commands.pyindex 2bdaebf791c2..845c65c068a9 100644--- a/tools/hogli-commands/hogli_commands/tests/test_commands.py+++ b/tools/hogli-commands/hogli_commands/tests/test_commands.py@@ -4,14 +4,17 @@ from __future__ import annotationsimport jsonimport time+import fcntlimport pytestfrom unittest.mock import patch+from hogli.manifest import REPO_ROOTfrom hogli_commands.telemetry_props import (_AGENT_ENV_MARKERS,_DEVBOX_ENV_MARKERS,_STANDARD_AGENT_ENV_VARS,+ RecordedRun,_detect_actor,_detect_agent,_detect_environment,@@ -19,6 +22,9 @@ from hogli_commands.telemetry_props import (_is_posthog_dev,_repo_commit,_repo_commit_properties,+ _session_properties,+ classify_command,+ is_rerun,)@@ -201,3 +207,122 @@ class TestIsPosthogDev:assert _is_posthog_dev() is Truemock_email.assert_called_once()assert json.loads(_config_dir.read_text())["is_posthog_org_member"] is True+++class TestClassifyCommand:+ @pytest.mark.parametrize(+ ("command", "argv", "expected"),+ [+ ("ci:preflight", [], "verify-preflight"),+ ("test:e2e", [], "verify-e2e"),+ ("test", ["playwright/e2e/insights.spec.ts"], "verify-e2e"),+ ("test", ["posthog/api/test/test_team.py"], "verify-test"),+ ("test", ["posthog/api/test/test_playwright_setup.py"], "verify-test"),+ ("test:python", [], "verify-test"),+ ("desktop:test", [], "verify-test"),+ ("test:quarantine", [], "other"),+ ("desktop:typecheck", [], "verify-typecheck"),+ ("lint", [], "verify-lint"),+ ("lint:workflows", [], "verify-lint"),+ ("format:python", [], "verify-lint"),+ ("product:lint", [], "verify-lint"),+ ("product:lint:owners", [], "verify-lint"),+ ("desktop:lint:fix", [], "verify-lint"),+ ("tool:ruff", [], "verify-lint"),+ ("build:openapi", [], "build"),+ ("phrocs:build", [], "build"),+ ("start", [], "run-stack"),+ ("start:backend", [], "run-stack"),+ ("up", ["-d"], "run-stack"),+ ("docker:services:up", [], "run-stack"),+ ("devbox:start", [], "devbox"),+ ("metabase:query", [], "other"),+ (None, [], "other"),+ ],+ )+ def test_classification(self, command, argv, expected) -> None:+ assert classify_command(command, argv) == expected++ def test_a_spec_named_from_inside_the_playwright_directory_is_e2e(self, monkeypatch) -> None:+ monkeypatch.chdir(REPO_ROOT / "playwright")+ assert classify_command("test", ["e2e/insights.spec.ts"]) == "verify-e2e"+++class TestIsRerun:+ NOW = 1_000_000.0++ @pytest.mark.parametrize(+ ("runs", "expected"),+ [+ ([], False),+ ([RecordedRun(session_id="s1", kind="verify-test", at=NOW - 60)], True),+ ([RecordedRun(session_id="s1", kind="verify-test", at=NOW - 30 * 60)], True),+ ([RecordedRun(session_id="s1", kind="verify-test", at=NOW - 30 * 60 - 1)], False),+ ([RecordedRun(session_id="s2", kind="verify-test", at=NOW - 60)], False),+ ([RecordedRun(session_id="s1", kind="verify-lint", at=NOW - 60)], False),+ ([RecordedRun(session_id="s1", kind="verify-test", at=NOW + 60)], False),+ ],+ ids=[+ "first_run",+ "same_session_same_kind",+ "window_edge_inclusive",+ "outside_window",+ "other_session",+ "other_kind",+ "clock_skew_future_entry",+ ],+ )+ def test_decision(self, runs, expected) -> None:+ assert is_rerun(runs, "s1", "verify-test", self.NOW) is expected+++class TestSessionProperties:+ @pytest.fixture(autouse=True)+ def _isolated_state(self, monkeypatch, tmp_path):+ monkeypatch.setattr("hogli_commands.telemetry_props._TELEMETRY_STATE_PATH", tmp_path / "state.json")+ monkeypatch.setenv("CLAUDE_CODE_SESSION_ID", "sess-1")+ for var in ("HOGLI_SESSION_ID", "POSTHOG_TASK_RUN_ID"):+ monkeypatch.delenv(var, raising=False)+ monkeypatch.setattr("sys.argv", ["hogli", "lint"])+ _session_properties.cache_clear()+ yield+ _session_properties.cache_clear()++ def test_next_process_in_session_is_a_rerun_but_repeated_hook_calls_are_not(self) -> None:+ assert _session_properties("lint")["is_rerun"] is False+ assert _session_properties("lint")["is_rerun"] is False+ _session_properties.cache_clear()+ rerun = _session_properties("lint")+ assert rerun == {+ "command_kind": "verify-lint",+ "session_id": rerun["session_id"],+ "session_id_source": "agent",+ "is_rerun": True,+ }+ assert rerun["session_id"].startswith("agent-")+ assert "sess-1" not in rerun["session_id"]++ def test_corrupt_state_file_does_not_raise(self, tmp_path) -> None:+ (tmp_path / "state.json").write_text('{"runs": [["only-two", 1], "junk"], "terminal_sessions": 3}')+ assert _session_properties("lint")["is_rerun"] is False++ def test_held_state_lock_does_not_block_the_command(self, tmp_path) -> None:+ with (tmp_path / "state.json.lock").open("a") as holder:+ fcntl.flock(holder, fcntl.LOCK_EX)+ assert _session_properties("lint")["is_rerun"] is False+ fcntl.flock(holder, fcntl.LOCK_UN)+ _session_properties.cache_clear()+ assert _session_properties("lint")["is_rerun"] is True++ def test_recycled_leader_pid_gets_a_new_terminal_id(self, monkeypatch) -> None:+ for var in ("CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID"):+ monkeypatch.delenv(var, raising=False)+ monkeypatch.setattr("os.getsid", lambda _pid: 4242)+ monkeypatch.setattr("hogli_commands.telemetry_props._proc_start_time", lambda _pid: "1000")+ first = _session_properties("lint")["session_id"]+ _session_properties.cache_clear()+ monkeypatch.setattr("hogli_commands.telemetry_props._proc_start_time", lambda _pid: "2000")+ second = _session_properties("lint")+ assert first is not None and first.startswith("term-")+ assert second["session_id"] != first+ assert second["is_rerun"] is False