macOS builds of apple-docs use Sentry telemetry to understand failures, improve reliability, and learn which parts of Apple documentation are useful. Linux builds use a no-op telemetry implementation. Telemetry is enabled by default on macOS and can be disabled by setting TELEMETRY_DISABLED=true.
Telemetry follows an explicit allowlist model and is enabled by default. Set TELEMETRY_DISABLED=true to opt out:
- Capture only fields that have been reviewed and approved.
- Treat new commands, arguments, and metadata as private by default.
- Collect the minimum context needed to reproduce failures.
- Prefer stable, structured fields over raw text and payloads.
- Keep expected user mistakes out of error monitoring.
- Apply privacy controls before data leaves the process and again at ingestion.
Adding a CLI argument does not automatically add it to telemetry.
Unexpected transport, decoding, and rendering failures are reported. Error values are replaced with a generic message while retaining the error type, stack trace, release, environment, and approved command context.
Invalid commands, missing required arguments, invalid flags, and command-level validation errors are user errors. They are not reported as application errors.
Instrumented commands start a console.command transaction and opt in to a fixed set of fields.
| Command | Captured fields |
|---|---|
types view |
Command name, documentation type, technology, and JSON output mode |
types list |
Command name, technology, and JSON output mode |
types search |
Command name, technology, and JSON output mode |
technologies list |
Command name and JSON output mode |
support catalog and content commands |
Command name and JSON output mode |
cache clean |
Command name |
agent skills list |
Command name |
agent skills get |
Command name |
Documentation type and technology values are captured because they identify public Apple documentation and are required to reproduce page-specific failures. Support paths, guide names, category filters, glossary queries and terms, and agreement identifiers are not attached to command context. Agent Skill installation and removal do not start command transactions or attach skill names and installation paths as command context.
Other positional values are excluded unless explicitly approved.
Application logs use apple/swift-log with the Sentry Swift Log handler. Messages are selected from a fixed allowlist and contain only approved command metadata.
Source file paths, function names, arbitrary metadata, interpolated values, and unapproved log messages are removed before transmission.
A command invocation adds one breadcrumb to subsequent errors. Its message and category are fixed, and its data is restricted to the approved command context.
Automatic system and network breadcrumbs are disabled.
The CLI records:
apple_docs.technology.requestedto measure technology popularity.apple_docs.type.requestedto measure type popularity within a technology.apple_docs.response.sizeto monitor Apple documentation response sizes.apple_docs.technology.catalog.countto monitor the size of the technology catalog.apple_docs.type.catalog.countto monitor direct type counts in technology root documents.apple_docs.type.search.result.countto monitor the number of search matches.
Metric names and attributes are allowlisted. Type and technology are the only variable popularity dimensions.
The CLI does not intentionally send:
- Raw process arguments or type search queries.
- Support lookup paths, identifiers, category filters, or glossary queries and terms.
- Environment variables.
- User identity or account information.
- IP addresses or geographic location.
- Hostnames or persistent device identifiers.
- Request or response headers.
- Cookies or authentication values.
- Query strings.
- Request or response bodies.
- Apple documentation page contents.
- Local file paths.
- Agent Skill names requested by the user.
Automatic network, file I/O, failed-request, and performance instrumentation is disabled. Command transactions are created manually so their data remains within the allowlist.
Before transmission, the SDK:
- Disables default PII collection.
- Removes user, request, server, extra, and arbitrary tag data from error events.
- Restricts event contexts, breadcrumbs, logs, metrics, and spans.
- Reduces native frame and debug-image paths to filenames.
- Replaces error values with a generic message.
Sentry ingestion also prevents IP storage, applies default data scrubbing, and removes geographic information. These server-side controls are a backstop rather than a substitute for SDK-side filtering.
Release builds upload matching dSYMs to Sentry so native stack traces can be symbolicated. Uploads run only for release builds, use an organization token stored in GitHub Actions secrets, and fail the release workflow if authentication or processing fails.
Source context is included because this repository is public. Auth tokens and other upload credentials must never be committed or printed.
Set the environment variable before invoking the CLI:
TELEMETRY_DISABLED=true apple-docs types view String --technology SwiftThe value true is matched case-insensitively. When disabled, Sentry is not initialized and SDK calls are skipped so command output remains unchanged.
Before adding a field or signal:
- State the production question it answers.
- Confirm that an existing error, trace, log, or metric does not already answer it.
- Decide whether the value can contain personal, local, credential, or user-authored data.
- Add only the minimum approved fields to the command context and relevant allowlists.
- Verify enabled and disabled command output.
- Trigger the signal and inspect the stored event for unexpected fields.
When uncertain whether a value is sensitive, do not capture it.