Broadcast: Skill for Claude Code

Broadcast Logging Best Practices

Use this skill when integrating Broadcast into a Swift project. Treat Broadcast as an external reusable logging library; do not assume you are modifying Broadcast itself unless the user explicitly asks to work on the library.

Before making non-trivial Broadcast changes or integrations, read the current Broadcast README and relevant DocC articles in Sources/Broadcast/Documentation.docc/ so examples, API choices, and terminology match the library's public guidance.

Integration Workflow

1. Add Broadcast as a dependency using the host project's normal package workflow.
2. Import Broadcast where logging is configured or called.
3. Create a shared Log instance from one or more destinations.
4. For app or app-specific package code, prefer one immutable app or package-scoped global let log so SwiftUI and non-SwiftUI surfaces share the same destination graph.
5. Use Broadcast's built-in Log.Payload helper factories for common typed values, then add app-specific Log.Category values and app-specific Log.Payload helpers in the integrating app or app-specific logging package.
6. Replace important free-form logs with structured logs where they help explain user-visible behavior, support diagnostics, startup, sync, entitlement, routing, persistence, or network decisions.
7. Validate with the host project's normal build and test commands.

Core APIs

• Log fans out one log call to one or more destinations.
• LoggingDestination is the write-only sink protocol whose primitive is log(_ record:); Broadcast provides default debug, info, warn, error, and fault convenience methods that create records.
• BufferedLoggingDestination extends LoggingDestination with records() for destinations that need access to canonical records, plus overridable default logs() text export.
• ConsoleLogger writes process-local output through Apple's unified logging system and is available only on Apple platforms.
• SessionLogger buffers logs in memory for the current process.
• MultiSessionLogger buffers canonical Log.Record values across launches when Broadcast's default MultiSessionLogging package trait is enabled. It currently uses Boutique on Apple platforms; use it only when the host app has configured the required persistence.
• SwiftLogDestination forwards Broadcast records into apple/swift-log when Broadcast is built with the SwiftLogging package trait. Use it when Broadcast should remain the call-site API but an app or server also needs records delivered to a configured swift-log backend.
• Log.Signal describes the intent of a structured log. Defaults include .action, .state, .event, .metric, and .diagnostic.
• Log.Category describes a human-readable subsystem or area.
• Log.Payload stores typed key-value diagnostics and exposes public typed initializers plus helper factories such as .string, .bool, .int, .uuid, .url, .date, .duration, .error, .count, .id, and .timestamp so call-sites do not need to format values manually.
• Log.Record is the identifiable timestamped semantic structured log value that destinations format through recordFormatter, which defaults to Broadcast's standard single-line format; records create a UUID and current timestamp by default.
• Log.Record.Formatter is the type-erased destination-level formatter for structured Log.Record values.
• Built-in Log.Record format styles include .default, .json, .tokenOptimized, and .canonicalLogLine.
• Log.DateProvider supplies dates for buffered loggers, and Log.Timestamp.FormatStyle formats those dates; Log.Timestamp defaults to the current date and is available as Log.Timestamp.now, but fixed date providers are still the deterministic-test path for logger output.