Skip to content

Latest commit

 

History

History
146 lines (111 loc) · 13.7 KB

TELEMETRY.md

File metadata and controls

146 lines (111 loc) · 13.7 KB

Usage statistics, crash reports and feedback

Pinky sends its developers anonymous usage statistics (counts) and crash reports after it quits unexpectedly, and lets the person send feedback as a GitHub issue. This page lists everything each one holds, where it is kept and how to turn it off. The client is in internal/telemetry; the backend that receives usage statistics and crash reports is the Cloudflare Worker in worker/.

What never leaves the computer in usage statistics and crash reports: what is on a phone's screen, what is typed, app names, phone names, serial numbers and other phone identifiers, PINs, file names, task names and anything else about the person. Usage statistics are counters with fixed names; nothing the person or a phone produces becomes a name.

Turning it off

  • Settings › Privacy › Share anonymous usage statistics and crash reports turns both off. Turning it off also forgets what was counted and not yet sent; crash reports then stay on the computer.
  • DO_NOT_TRACK=1 in the environment (any value but 0, false, no or off) stops both, whatever the setting.
  • PINKY_TELEMETRY_URL=- sends nothing.
  • Development builds (go run ./cmd/pinky, go build: version 0.0.0-dev) send nothing unless PINKY_TELEMETRY_URL names a backend. With --fake (scripted fake phones) nothing is counted; crash reports still go out.

The setting is on by default, and Pinky shows no note about it on the first run: Settings › Privacy, this page and the README say so. What's shared in Settings › Privacy shows the usage report as it would go out at that moment.

Usage statistics

About once a day (at most once every 24 hours, and only while Pinky runs), Pinky posts one report:

{
  "install_id": "8c1f0e6b2a7d4e5f9a0b1c2d3e4f5a6b",
  "version": "0.2.0",
  "os": "macos",
  "os_version": "27.2",
  "arch": "arm64",
  "period_start": "2026-11-07T09:00:00Z",
  "period_end": "2026-11-08T09:12:00Z",
  "counts": {
    "app.starts": 2,
    "phones.android.wifi": 1,
    "phones.ios.usb": 1,
    "phones.max_online": 2,
    "runs.started": 5,
    "runs.agent.claude_code": 5,
    "runs.done": 4,
    "tools.phone_tap": 31,
    "results.settled": 52,
    "needs.approval.asked": 2,
    "needs.approval.allow_once": 1,
    "needs.approval.deny": 1
  }
}
  • install_id is a random number made on the first run. It keeps one computer's reports together; it is not tied to the person, their Apple ID, the computer's name or its hardware. Deleting telemetry.json makes a new one.
  • os_version is macOS's version, Windows' version and build, or a Linux distribution and its version (from /etc/os-release).
  • Crash reports carry no install id, so they cannot be matched to usage statistics.

The counters

Each counter counts within the report's period. <platform> is android, ios or other, and android_emulator or ios_simulator for virtual phones, which count apart from phones; the words in a name come from the lists below, never from a phone or the person.

Counter What it counts
app.starts, daemon.starts Pinky started, as the app or as the background daemon
crashes.app, crashes.daemon crashes found at the next start (the crash report itself is separate, below)
exits.unclean.app, exits.unclean.daemon runs that ended without quitting and without a crash: killed, force-quit, the power went out
phones.<platform>.usb, .wifi, .other different phones seen, by connection
phones.<platform>.os.<major> different phones seen, by the first number of their system version (17, 27)
phones.<platform>.backend.<name> different phones seen, by how Pinky drives them: scrcpy, companion, adb, coredevice, wda, mirroring, other
phones.<platform>.state.<state> different phones that waited for setup: unauthorized (not trusted yet), needs_setup
phones.max_online the most phones connected at once
runs.started, .done, .stopped, .failed, .paused agent tasks, and how they ended (paused: the person took over)
runs.agent.<agent> agent tasks by agent product: claude_code, claude, codex, cursor, windsurf, vs_code, gemini_cli, goose, cline, zed, opencode, continue, mcp_inspector, agent (no name given) or other
runs.remote, runs.background agent tasks over HTTP (remote agents), and on a background display
agents.connected.<agent> MCP sessions, by agent product as above
agents.scope.<mode> scopes the person gave agents: everything, read_only, watch_only, apps
tools.<tool> tool calls, by tool: phone_connect, phone_tap, … (Pinky's own tool names; anything else is other)
results.<status> tool results, by status: settled, uncertain, blocked_by_policy, approval_denied, approval_pending, stale, user_took_over, paused, stopped, device_locked, device_needs_setup, ok (a result without a status); by error code: error.device_offline, error.device_paused, error.lease_held, error.scope_denied, error.not_found, error.unsupported, error.invalid_argument, error.internal, error.other
needs.<kind>.asked what Pinky asked the person: approval, new_agent (an agent's first connection), handoff, unlock
needs.approval.rule.<rule> approvals by the rule that asked, for Pinky's built-in rules (payments, messages, commits, installs_and_links, calls, settings_changes, phone_settings, every_action, …); the person's own rules count as custom
needs.<kind>.<answer> how the person answered: allow_once, allow_task, allow_always, deny, take_over, or error
needs.<kind>.unanswered needs that went away without an answer (timed out, or the agent left)
unlock.<result> unlocking a phone from the computer: ok, wrong_pin, no_pin, cancelled, no_keychain, unavailable, locked, offline, not_found, timeout, unsupported, failed
person.take_over, .hand_back, .stop, .stop_all the person taking a phone over, handing it back, stopping a task, and Stop all
pairing.qr.started, .paired, .cancelled; pairing.code.paired pairing a phone over Wi-Fi, by QR code or with a code; a failure counts as pairing.qr.<error> or pairing.code.<error>
companion.installed, companion.install.<error> installing the Android companion app
background.turned_on, .turned_off background displays switched in Pinky
history.exported, history.export.<error>, history.wiped exporting activity, and deleting all of it

<error> is one of cancelled, timeout, unsupported, offline, locked, not_found, unavailable or failed: errors are sorted into these kinds and their messages are never kept.

A phone counts once a period in each bucket. To tell phones apart, Pinky keeps a salted hash of each phone's id in telemetry.json; the hashes and the salt never leave the computer, and the report carries only how many phones each bucket saw.

Crash reports

Each Pinky process that runs the gateway (the app, or pinky daemon) asks the Go runtime to copy any crash (an unrecovered panic or a fatal error) to a file of its own in the data folder (runtime/debug.SetCrashOutput). A clean exit removes the file. At the next start Pinky finds the files of processes that are gone; those with a crash in them become crash reports, which go out at once while the setting is on, and the others count as exits.unclean.*. A report holds:

Field
id, process the run (app-<start>-<pid>), and app or daemon
version Pinky's version
os, os_version, arch, go_version the computer's system
started, crashed when the run started and crashed
reason the crash's first line, such as panic: runtime error: index out of range [3] with length 3 or SIGSEGV: segmentation violation. For fatal errors the runtime prints its message before the copy starts, so the reason is then the function that failed, or the line from daemon.log for a daemon that pinky mcp started
stack what the runtime printed (up to 256 KB): function names, Pinky's source files and line numbers

The home folder, the user's name, e-mail and IP addresses, long hex strings (tokens) and similar are taken out of the reason and the stack before the report is saved. With the setting off, reports stay in the data folder, where feedback's diagnostics mention the last one; at most 10 are kept, none longer than 30 days.

Feedback

Help › Send Feedback…, Send Feedback… in the menu bar icon's menu, and Send feedback… under Settings' sections open a form: a title (optional), a message, and Attach diagnostics (on by default), with Review to read exactly what is attached. Open on GitHub opens a new issue in DIYgod/pinky with all of it filled in (the Feedback issue form); the person reads it there and submits it with their GitHub account. Issues are public. Nothing is sent until they submit it on GitHub.

Diagnostics hold:

  • Pinky's version, the computer's system, whether usage statistics are on, and the last crash's reason when there is one;
  • the settings that change how Pinky behaves (the approval preset, read-only mode, unlocking from the computer, hiding codes, recording, how long activity is kept, remote agents, developer mode) and the video decoder;
  • each connected phone's platform, system version, model, connection, backend and state;
  • Tailscale's state on the computer, the Android devices on its tailnet (online or not, which are Pinky's phones, by model, and whether Pinky reaches them), and each Android phone's Use away from home (on or off, and what keeps it from being set up); the tailnet's name and the devices' names are left out;
  • the end of pinky.log and daemon.log, as much as fits in the issue's address (the last 300 lines at most).

Phone ids and the names people give their phones, the home folder, the user's name, e-mail and IP addresses, long hex strings, adb's Wi-Fi names for phones, and the values of log fields that may name apps, tasks, files or what a screen showed (app=, task=, name=, path=, …) are replaced with placeholders such as <phone-1> and <redacted>. A link to GitHub holds about 7 KB, so older log lines are left out when they do not fit; Copy puts the message and the whole diagnostics on the clipboard, to paste into the issue or send another way.

Where it is kept

In Pinky's data folder (macOS ~/Library/Application Support/Pinky, Linux ~/.local/share/pinky, Windows %LOCALAPPDATA%\Pinky, or $PINKY_HOME/data):

File
telemetry.json the install id, the counters since the last report, the hashes of the phones seen, when the last report went out
crashes/<process>-<start>-<pid>.run one per running process; its crash, if it crashes
crashes/<id>.json a crash report not sent yet
crashes/<id>.unclean a run that ended without quitting, until it is counted

All are readable only by the user. Settings › Privacy's choice is UsageStats in settings.json.

Where it goes

Usage statistics and crash reports are posted as JSON over HTTPS to the backend's /v1/usage and /v1/crash, with User-Agent: Pinky/<version> (<os>; <arch>). A report that fails to go out is tried again later (after an hour, doubling up to a day); one the backend refuses (HTTP 4xx) is dropped.

The backend is a Cloudflare Worker with a D1 database (worker/), at https://pinky-telemetry.rss3.workers.dev. It checks each report's shape and size, stores it, and keeps usage reports for 400 days and crash reports for 180. It does not store IP addresses or any request header, and has Workers Logs off; Cloudflare sees the address of the connection, as any server would, and the Worker uses it for a minute to limit how often one address may report.

The backend's address is telemetry.Endpoint in internal/telemetry/telemetry.go (a build may set it with -ldflags "-X github.com/DIYgod/pinky/internal/telemetry.Endpoint=…"), or PINKY_TELEMETRY_URL. The client talks to it through the telemetry.Backend interface, so another backend can replace it.

Checking it

Automated: go test ./internal/telemetry ./ui (the crash tests run the test binary again as a child that panics, hits a fatal error, exits or hangs), go test -tags e2e -run TestTelemetryInTheApp ./cmd/pinky (the app over MyGo's automation socket with a fake backend: Send Feedback's GitHub link, a SIGQUIT crash sent at the next start, a clean quit that leaves nothing; it needs the screen unlocked), and node --test plus ./smoke.sh in worker/ (worker/README.md).

By hand, with a release build (make app; development builds send nothing):

  • Settings › Privacy shows Share anonymous usage statistics and crash reports (on) and What's shared, which shows the report with counters such as app.starts.
  • DO_NOT_TRACK=1 build/pinky/darwin-arm64/Pinky.app/Contents/MacOS/Pinky: the switch reads Off: DO_NOT_TRACK is set on this computer.
  • Help › Send Feedback…, write something, Open on GitHub: the browser opens a new issue in DIYgod/pinky with the Feedback form filled in (the message, the version line, the diagnostics). This needs the form on main, a feedback label for it to apply, and, for people other than the repository's members, the repository to be public.
  • kill -QUIT $(pgrep -x Pinky), then open Pinky again: within a minute worker/report.sh crashes lists the crash, SIGQUIT: quit.
  • A day after the first run, worker/report.sh lists this computer's install among the installs, with its counters.