Add SwiftLog LogHandler conformance to DiagnosticsLogger (#150) by elio-Wang · Pull Request #212 · AvdLee/Diagnostics

elio-Wang · 2026-07-27T02:55:19Z

What

Adds DiagnosticsLogger.SwiftLogHandler, a LogHandler conformance for apple/swift-log, so projects already using SwiftLog can bridge their logs into the Diagnostics report with a single bootstrap call:

try DiagnosticsLogger.setup()

LoggingSystem.bootstrap { label in

    DiagnosticsLogger.SwiftLogHandler(label: label)

}

Resolves #150.

Changes

Package.swif — add apple/swift-log ≥ 1.6.0 dependency
DiagnosticsLogger.swift — make init() and standard public; add setup(_:) accepting a custom logger instance
SwiftLogHandler.swift (new) — LogHandler conformance; maps trace/debug/info/notice/warning → debug, error/critical → error
SwiftLogHandlerTests.swift (new) — tests for level mapping, metadata merging, and custom logger instances

Notes

@unchecked Sendable matches swift-log's own StreamLogHandler pattern — metadata / logLevel are set at bootstrap, not mutated across threads.
Diagnostics only has debug levels, so the mapping groups the lower SwiftLog levels into debug . Can be revisited if more levels are added later.

Allow DiagnosticsLogger to be used as a backing store for SwiftLog's LoggingSystem by providing a DiagnosticsLogger.SwiftLogHandler type. Projects already using SwiftLog can now seamlessly forward all log messages into the Diagnostics report. - Add swift-log as a package dependency - Make DiagnosticsLogger.init() and .standard public - Add setup(_:) overload accepting a custom logger instance - Add DiagnosticsLogger.SwiftLogHandler nested LogHandler type - Map SwiftLog levels to Diagnostics debug/error CSS classes - Add unit tests for the SwiftLog integration Resolves AvdLee#150

edorphy · 2026-07-29T01:50:24Z

The latest version of SwiftLog added task local logger and some other improvements, not to mention all the chances in between. 1.6.0 is quite old. Any reason to not push the dependency to a more recent version?

edorphy · 2026-07-29T01:53:13Z

+    /// | debug          | debug             |
+    /// | info           | debug             |
+    /// | notice         | debug             |
+    /// | warning        | debug             |


Warning might be more suitable as error. Though my next request if the library will be more diagnostic logger levels.

My rule of thumb, use warning for errors that are known, mitigated, and recoverable. They're still something to have observability into.

Agreed — I've updated the mapping so warning now routes to .error. The default is strict; developers can override via logLevel if they need a more lenient routing.

Regarding more granular diagnostic logger levels, I've put together a proposal in the comment below. Let me know if the direction works and I'll implement it.

edorphy · 2026-07-29T01:54:45Z

+        public init(
+            label: String,
+            logger: DiagnosticsLogger = .standard,
+            logLevel: Logger.Level = .debug,


Default should be the more strict level. If there were intermediate options I would have it be info. Debug logs typically don't belong in production.

Allow a developer to override but default on hardening the output.

Done. Changes:

Default logLevel bumped from .debug to .info — debug/trace won't show in production by default
Added a levelMapping closure parameter so developers can override the default mapping if needed
The default mapping keeps trace/debug → Diagnostics debug, and everything else → error.

edorphy · 2026-07-29T01:58:57Z

+                logger.log(
+                    LogItem(.debug(message: fullMessage), file: file, function: function, line: line)
+                )
+            case .error, .critical:


@AvdLee

Thoughts on enhancing the diagnostic logger api with more levels to facilitate more granularity?

I'm happy to receive that, yeah! The better we can support it, the better!

Do you want to support all levels of SwiftLog, OpenTelemetry, or a subset of both? It would be expanding the usage of the diagnostic logger quite a bit.

My preference would be to match SwiftLog, or a subset of it since that is what support is being added for.

https://github.com/apple/swift-log/blob/main/Sources/Logging/Logger.swift#L1187

Or

https://opentelemetry.io/docs/specs/otel/logs/api/#emit-a-logrecord

https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber

https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitytext

I'd go with matching SwiftLog's levels. It's the most natural fit since that's what we're bridging, and SwiftLog is already widely adopted in the Swift ecosystem. OpenTelemetry's 24-level SeverityNumber feels like overkill for a diagnostics log file.

For the mapping, I'd suggest:

SwiftLog Level Diagnostics Level

trace trace

debug debug

info info

notice info

warning warning

error error

critical error

This gives us 5 levels in DiagnosticsLogger (trace, debug, info, warning, error) — enough granularity for production diagnostics without being excessive. notice collapsing into info and critical into error keeps it pragmatic.

Happy to implement this if the direction looks right.
@edorphy @AvdLee

edorphy · 2026-07-29T02:03:18Z

+
+     public init() { }

    private static let logFileLocation: URL = FileManager.default.applicationSupportDirectory.appendingPathComponent("diagnostics_log.txt")


When I was looking at contributing to this issue, I wanted to also control the destination of the log file.

Maybe out of scope of this merge, but a tradeoff to giving a static default logger without being able to control the destination.

I would find it useful to inject the destination.

#195

@edorphy Regarding #195 and the ability to inject a custom log file destination — I looked at the code and logFileLocation is currently a hardcoded static let. My approach would be:

Convert it to an instance property, injectable via init(logFileLocation:)
Fall back to the default path when not provided, keeping backward compatibility
This is a different scope from the SwiftLog bridge in this PR, so I can open a separate PR for it. Would you prefer to have it bundled here or kept as a standalone PR?

elio-Wang · 2026-07-29T05:44:08Z

The latest version of SwiftLog added task local logger and some other improvements, not to mention all the chances in between. 1.6.0 is quite old. Any reason to not push the dependency to a more recent version?

No specific reason — I conservatively picked 1.6.0 as the minimum since that's the version I had locally when developing the handler. Happy to bump it.

Would you prefer pinning to the latest (≥ 1.14.0), or something in between like ≥ 1.6.0 with a note? Let me know and I'll push the update.

Address review feedback: 1.6.0 was outdated. No API changes needed — the SwiftLogHandler implementation only uses stable LogHandler APIs available since 1.6.0, so this is a minimum version bump only.

Per maintainer feedback, warning represents errors that are known, mitigated, and recoverable — they warrant error-level observability rather than being grouped with debug output. The default mapping now favors strictness; developers can override via the logLevel parameter if they prefer a more lenient routing.

- Default logLevel changed from .debug to .info so debug/trace logs are excluded from production output by default - Add LevelMapping closure parameter to SwiftLogHandler.init, allowing developers to override how SwiftLog levels map to Diagnostics output (debug vs error)

swift-log 1.15.0 makes StreamLogHandler initializers public and includes minor fixes. Keep the dependency current with the latest release.

elio-Wang requested a review from AvdLee as a code owner July 27, 2026 02:55

edorphy reviewed Jul 29, 2026

View reviewed changes

elio-Wang added 4 commits July 29, 2026 14:12

Bump swift-log minimum version to 1.14.0

2288536

Address review feedback: 1.6.0 was outdated. No API changes needed — the SwiftLogHandler implementation only uses stable LogHandler APIs available since 1.6.0, so this is a minimum version bump only.

Bump swift-log minimum version to 1.15.0

eda56a4

swift-log 1.15.0 makes StreamLogHandler initializers public and includes minor fixes. Keep the dependency current with the latest release.

Navigation Menu

Add SwiftLog LogHandler conformance to DiagnosticsLogger (#150) - #212

Add SwiftLog LogHandler conformance to DiagnosticsLogger (#150)#212
elio-Wang wants to merge 5 commits into
AvdLee:mainfrom
elio-Wang:feature/swift-log-handler

elio-Wang commented Jul 27, 2026

Uh oh!

edorphy commented Jul 29, 2026

Uh oh!

edorphy Jul 29, 2026

Uh oh!

elio-Wang Jul 29, 2026

Uh oh!

edorphy Jul 29, 2026

Uh oh!

elio-Wang Jul 30, 2026

Uh oh!

edorphy Jul 29, 2026

Uh oh!

AvdLee Jul 29, 2026

Uh oh!

edorphy Jul 29, 2026

Uh oh!

elio-Wang Jul 29, 2026

Uh oh!

edorphy Jul 29, 2026

Uh oh!

elio-Wang Jul 29, 2026

Uh oh!

elio-Wang commented Jul 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

SwiftLog Level	Diagnostics Level
trace	trace
debug	debug
info	info
notice	info
warning	warning
error	error
critical	error


		public init() { }

		private static let logFileLocation: URL = FileManager.default.applicationSupportDirectory.appendingPathComponent("diagnostics_log.txt")

Conversation

elio-Wang commented Jul 27, 2026

What

Changes

Notes

Uh oh!

edorphy commented Jul 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elio-Wang commented Jul 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants