Tag every event with an optional random installation ID (0.3.0)

[dmccoystephenson]

Ports trace-client-java 0.5.0's per-installation ID to the C++ client, and bumps the client to 0.3.0 (TRACE_CLIENT_VERSION, header comment, CMake project version, User-Agent in the README).

What changes

• trace_client::InstallId — where an installation's ID comes from:
  • InstallId::of(id) — an ID the program stores itself. Trimmed; blank means none; over 255 bytes is handled exactly like an overlong version (no throw, client disabled with reason "unavailable").
  • InstallId::fromFile(path) — a random UUID kept in a file the program chooses.
  • Both fields set: the explicit id wins and the file is not touched.
• New constructor overload TraceClient(baseUrl, application, version, key, const InstallId &install, bool enabled = true, Logger logger = Logger()). The existing constructor is unchanged and sends no install tag.
• static std::string TraceClient::installIdFromFile(const std::string &path) — reads the first line that is 1–255 chars of [A-Za-z0-9_.-]; when the file is missing or has none, writes a fresh v4 UUID (parent directories created). A path that exists but cannot be read is never overwritten; any read/write failure yields an in-memory UUID for the run. Never throws.
• const std::string &TraceClient::installId() const — the ID in use; empty when disabled or none.
• Every event gets tag install after version is applied (detail::withInstall), unless the event carries its own install or already has 32 tags.
• The ID is resolved only after every opt-out (TRACE_USAGE_REPORTING / DO_NOT_TRACK, enabled = false, no key, unavailable), so a disabled client never generates or writes one. Calling installIdFromFile directly writes regardless, which the README and header comment say.
• No hidden default location, and zero new dependencies: C++11 <random>/<fstream> plus stat/mkdir (_stat/_mkdir on Windows); no std::filesystem.
• README: new section "Every event carries a random installation ID" (what is sent, where it lives, reset by deleting the file, opt-outs stop it, explicit-ID example); wire-format example updated.

Tests

Ten new tests in test/test_trace_client.cpp mirroring the Java ones: UUID v4 format, persist once + reuse (nested dirs created), first valid line read / invalid-only file replaced, unusable path (under a regular file, a directory, empty) → in-memory and nothing written, every event carries the file's ID, disabled clients (config, no key, unavailable, both env opt-outs) write nothing, explicit ID trimmed and wins over the file, blank = none / overlong rejected / exactly 255 accepted, event's own install wins, tag cap respected (helper and end to end).

Locally (g++ 9.4): make test at c++11, c++17 and c++2a → 41 tests, 0 failed checks; -fsanitize=address,undefined → 41/0; CMake build → 41/0. Not verifiable locally (left to CI): clang++, -fsanitize=thread (libtsan missing), libcurl transport, macOS, Windows/MSVC.

🤖 Generated with Claude Code

https://claude.ai/code/session_014ztkfamsbEqQfcu76me5SL

---

drafted by Claude on behalf of Daniel Stephenson