[tigh-latte]

Usage telemetry stack, part 2 of 6. Builds on #568. Next: #570.

Description

This PR adds core/usage/, the code that decides what a usage event can contain. Nothing calls it yet.

• event.py lists every property that can leave the machine, with its type and the question it answers. A value with the wrong type, or a property that isn't listed, is dropped. The list properties (flags, flags_typed, envvars, aliases_used) must be lists of strings; anything else is left out rather than sent one character at a time.
• identity.py and state.py keep a random install ID in telemetry.json on laptops. CI runs, containers and the Docker image never keep an ID, and get a new one on every run. No event ever creates a PostHog person profile. Every change to telemetry.json holds an inter-process lock, so two CLI runs can't undo each other, for example by putting back an install ID that telemetry reset just deleted. If the lock is busy for more than 0.5 s the write is skipped rather than delaying the command.
• environment.py detects CI providers and containers.
• notice.py holds the one-time, versioned notice printed on stderr.
• settings.py holds the developer switches: test project key and host, log mode, the install ID switch, internal tagging and the CI sample rate.

What one event captures

Property	Example	Purpose
command	list packages	Command use
flags, flags_typed	["page_size"], ["-F", "--page-size"]	Flag use, including which spelling was typed
aliases_used	["ls"]	Alias use
envvars	["CLOUDSMITH_API_KEY"]	Which CLI env vars are set (names only)
source_<setting>	source_api_key: env	Where a setting came from: flag, env, config_file, config_profile, credentials_file, credentials_profile
auth_source	keyring	Login method
output_format	json	Output format
outcome, exit_code, api_status	api_error, 1, 404	How the run ended
duration_ms	557	Speed
cli_version, channel, environment	1.30.0, homebrew, production	Version adoption, install channel, release vs development build
os, os_version, python_version, arch	Darwin, 25.6, 3.13, arm64	Platform support
persona, ci, ci_provider, stdout_tty	ci, true, github_actions, false	Human, CI or agent (agent arrives in #573)
first_run, install_id_persisted	true, true	Onboarding and retention
sample_rate, internal, schema_version	100, unset, 1	Scaling sampled counts, excluding our own use, schema changes
$geoip_disable, $process_person_profile	true, false	No location lookup, no person profile

Never captured: argument values, file names, package, repository or workspace names, credentials, setting values, hostnames, usernames, free text, or IP-derived location.

Sentry and PostHog: what each holds

Data	Sentry	PostHog
Command path, CLI version, channel, OS, Python	Yes	Yes
Exception type, scrubbed message, stack frames	Yes	No
Flags, aliases, env var names, setting sources, login method	No	Yes (names only)
Outcome, exit code, API status, duration	No	Yes
Persona, CI provider	No	Yes
Install ID	No	Yes, laptops only

Notice text

The Cloudsmith CLI collects pseudonymous usage data: which commands run, how they end and how long they take, plus CLI, Python and OS versions. It never collects argument values, file names, credentials or account names. A random install ID is kept on this machine so repeat use can be counted; see it with 'cloudsmith telemetry id' and replace it with 'cloudsmith telemetry reset'.
To opt out, set CLOUDSMITH_NO_TELEMETRY=1 or DO_NOT_TRACK=1, or add 'telemetry = false' to config.ini. To see exactly what is sent, set CLOUDSMITH_TELEMETRY=log.
Learn more: https://docs.cloudsmith.com/developer-tools/cli
Nothing was sent for this command. This notice will not be shown again.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Other (please describe)

Additional Notes

N/A: no behaviour change, because nothing calls this code until #571.

🤖 Generated with Claude Code