Telemetry Facade Pattern

When to invoke

• Starting a new project and designing the logger / tracker / metrics interface.
• About to introduce OSLog and any tracking / analytics at the same time.
• Wanting to preserve flexibility for "swap the tracking provider later".
• User asks "should Logger and Tracking be separate", "how should the event interface look".

Default decisions

A single Telemetry target

• Create one Telemetry target inside the SwiftPM Package.
• It contains:
• TelemetryEvent value type (enum / struct, Sendable)
• TelemetrySink protocol:

    public protocol TelemetrySink: Sendable {
        func receive(_ event: TelemetryEvent) async
    }

• The main facade — choose the type per the table below. The facade fans out to multiple sinks.

• Default sinks (see below)

Call sites describe only "what happened"

telemetry.observe(.sessionCompleted(id: sessionId, durationMs: 12_345))

• The call site doesn't know who will consume the event.
• Swapping providers / adding sinks only requires replacing a sink; call sites change nothing.

Default sink set

public struct NoOpTrackingSink: TelemetrySink {
    public init() {}
    public func receive(_ event: TelemetryEvent) async { /* intentionally empty */ }
}

Composition root wiring

• The App target's DI composition root injects sinks into the facade.
• Sinks are failure-isolated (one sink throwing or timing out must not stop the others) but not order-free: the facade forwards in array order, and a sink that reads state another sink writes must come after it (see trap 2).

For the six composition-root wiring traps (existing-but-unwired sinks, sink ordering, blocking I/O on the gameplay path, late-binding, sink-fired vs terminal-call-succeeded — GKLeaderboard.submitScore / GKAchievement.report never reached — and MetricKitSink's OS-version-dependent base class), read references/wiring-traps.md.

Rationale

• Decouples call sites from consumers: v1 can use telemetry.observe(...) with no external tracking, and a future TelemetryDeck / in-house pipeline only swaps the sink.
• OSLog + Tracking + MetricKit + GameCenter are all "event streams"; one unified interface is easier to maintain than four separate ones.
• Easy to test: inject a fake sink and assert on the event stream.

Deviation considerations

• Minimal App, OSLog only: you can skip the Telemetry target and use Logger directly. But if you anticipate adding tracking / metrics later, building the facade up front pays off.
• *Need routing between sinks* (e.g. a MetricKit payload re-emitted into TrackingSink): handle routing inside the facade; call sites still unchanged.
• Cross-platform (Android / Linux): facade interface stays platform-neutral; sink implementations are per-platform.

Verification checklist

• The Telemetry target is standalone; UI / Engine don't directly depend on anything beyond OSLog.
• TelemetryEvent is a value type, Sendable.
• A default NoOpTrackingSink is provided and wired in the composition root.
• Tests assert on event streams via fake sinks, not by parsing OSLog output.
• **The live composition root's sinks array actually contains every sink you

intend to fire** (not just that the sink type exists) — the "existing-but-unwired" failure mode.

• Read/write-dependent sinks are ordered so writers precede readers, with a test

pinning the order.

• I/O sinks on a gameplay-reachable completion path forward non-blocking; the

interactive path is never frozen by a sink's CloudKit/GameKit work.

• The terminal platform call (GameKit/StoreKit) is reached and device-verified —

not just the sink.

Related skills

• oslog-logger-defaults: the concrete OSLogSink implementation dependency.
• apple-three-piece-analytics: each piece corresponds to one sink.
• swiftpm-modularization: why Telemetry is its own target.
• Official sources: when verifying or updating a factual or version-sensitive claim, read references/official-docs.md.