Files
swift-log/Sources/Logging/Docs.docc/UnderstandingLoggers.md
T
4121d24dbd documentation update and re-organization (#381)
Provide organization (aka curation) and abstracts for all of the public
types in the library.

### Motivation:

Updates to the documentation to fill in the missing abstracts for the
provided types, updating the language to follow Apple developer content
guidelines, and fixing smaller typos and grammar issues.

### Modifications:

Curation files added to provide organization for public types, ordering
the content to align with the narrative content provided earlier.
Updating API comments, adding abstracts and parameters where missing,
and moving some of the getting started content that was previously in
the main index into a separate article.

### Result:

starting point

```
   --- Experimental coverage output enabled. ---
                | Abstract        | Curated         | Code Listing
Types           | 69% (11/16)     | 38% (6/16)      | 25% (4/16)
Members         | 57% (54/94)     | 3.2% (3/94)     | 0.0% (0/94)
Globals         | 7.1% (1/14)     | 7.1% (1/14)     | 7.1% (1/14)
```

Updated:

```
                | Abstract        | Curated         | Code Listing
Types           | 94% (15/16)     | 94% (15/16)     | 38% (6/16)
Members         | 85% (80/94)     | 97% (91/94)     | 0.0% (0/94)
Globals         | 14% (2/14)      | 100% (14/14)    | 7.1% (1/14)
```

---------

Co-authored-by: Honza Dvorsky <honza@apple.com>
Co-authored-by: Franz Busch <privat@franz-busch.de>
2025-11-03 11:26:54 -08:00

2.6 KiB

Understanding Loggers and Log Handlers

Learn how to create and configure loggers, set log levels, and use metadata to add context to your log messages.

Overview

Create or retrieve a logger to get an instance for logging messages. Log messages have a level that you use to indicate the message's importance.

SwiftLog defines seven log levels, represented by Logger/Level, ordered from least to most severe:

  • Logger/Level/trace
  • Logger/Level/debug
  • Logger/Level/info
  • Logger/Level/notice
  • Logger/Level/warning
  • Logger/Level/error
  • Logger/Level/critical

Once a message is sent to a logger, a log handler processes it. The app using the logger configures the handler, usually for the environment in which that app runs, processing messages appropriate to that environment. If the app doesn't provide its own log handler, SwiftLog defaults to using a StreamLogHandler that outputs log messages to STDOUT.

Loggers

Loggers are used to emit log messages at different severity levels:

// Informational message
logger.info("Processing request")

// Something went wrong
logger.error("Houston, we have a problem")

Logger is a value type with value semantics, meaning that when you modify a logger's configuration (like its log level or metadata), it only affects that specific logger instance:

let baseLogger = Logger(label: "MyApp")

// Create a new logger with different configuration.
var requestLogger = baseLogger
requestLogger.logLevel = .debug
requestLogger[metadataKey: "request-id"] = "\(UUID())"

// baseLogger is unchanged. It still has default log level and no metadata
// requestLogger has debug level and request-id metadata.

This value type behavior makes loggers safe to pass between functions and modify without unexpected side effects.

Log Levels

Log levels can be changed per logger without affecting others:

var logger = Logger(label: "MyLogger")
logger.logLevel = .debug

For guidance on what level to use for a message, see doc:001-ChoosingLogLevels.

Logging Metadata

Metadata provides contextual information crucial for debugging:

var logger = Logger(label: "com.example.server")
logger[metadataKey: "request.id"] = "\(UUID())"
logger.info("Processing request")

Output:

2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED Processing request

Source vs Label

A Logger has an immutable label that identifies its creator, while each log message carries a source parameter that identifies where the message originated. Use source for filtering messages from specific subsystems.