Compare commits

..
3 Commits
Author SHA1 Message Date
Saul Baro Ruiz 5d66f7ba25 Fix function being dropped on source-less trace (#185)
Motivation:

When using the recently re-introduced source-less version of trace, the function parameter that reaches the underlying LogHandler is wrong.

Modifications:

Pass the function parameter to trace with source parameter.

Result:

With these changes, the function parameter that reaches the underlying LogHandler has the correct value.
2021-03-03 14:35:32 +09:00
tomer doron c7988420c2 add docker setup for 5.4 and nightly (#183)
motivation: CI for 5.4 and latest

changes: add docker setup files for 5.4 and main nightly images
2021-02-27 10:58:11 +09:00
Johannes Weiss 7d1d4e29ea drop Swift 4.x info from the readme (#182) 2021-02-26 06:16:35 +09:00
5 changed files with 40 additions and 80 deletions

No files matched your search

-77
View File
@@ -1,7 +1,5 @@
# SwiftLog
A Logging API package for Swift. Version `1.0.0` requires Swift 5.0 but there is a version `0.x.y` series available for Swift 4 to ease your transition towards Swift 5. If you intend to use or support SwiftLog for Swift 4, please check the [paragraph](#help-i-need-swift-4) at the end of the document.
First things first: This is the beginning of a community-driven open-source project actively seeking contributions, be it code, documentation, or ideas. Apart from contributing to `SwiftLog` itself, there's another huge gap at the moment: `SwiftLog` is an _API package_ which tries to establish a common API the ecosystem can use. To make logging really work for real-world workloads, we need `SwiftLog`-compatible _logging backends_ which then either persist the log messages in files, render them in nicer colors on the terminal, or send them over to Splunk or ELK.
What `SwiftLog` provides today can be found in the [API docs][api-docs].
@@ -28,7 +26,6 @@ and to your application/library target, add `"Logging"` to your `dependencies`,
.target(name: "BestExampleApp", dependencies: [
.product(name: "Logging", package: "swift-log")
],
```
@@ -205,80 +202,6 @@ around between libraries to preserve metadata and the like.
If you want to filter all log messages originating from a certain subsystem, filter by `source` which defaults to the module that is emitting the
log message.
## SwiftLog for Swift 4
<a name="help-i-need-swift-4"></a>
First of, SwiftLog 1.0.x and SwiftLog 0.0.x are mostly compatible so don't be afraid. In fact, SwiftLog 0.0.0 is the same source code as SwiftLog 1.0.0 with a few changes made to make it Swift 4 compatible.
### How can I use SwiftLog 0 library or application?
If you have a application or a library that needs to be compatible with both Swift 4 and 5, then we recommend using the following in your `Package.swift`:
```swift
.package(url: "https://github.com/apple/swift-log.git", Version("0.0.0") ..< Version("2.0.0")),
```
This will instruct SwiftPM to allow any SwiftLog 0 and any SwiftLog 1 version. This is an unusual form because usually packages don't support multiple major versions of a package. Because SwiftLog 0 and 1 are mostly compatible however, this should not be a real issue and will enable everybody to get the best. If compiled with a Swift 4 compiler, this will be a SwiftLog 0 version but if compiled with a Swift 5 compiler everybody will get the best experience and performance delivered by SwiftLog 1.
In most cases, there is only one thing you need to remember: Always use _string literals_ and _string interpolations_ in the log methods and don't rely on the fact that SwiftLog 0 also allows `String`.
Good:
```swift
logger.info("hello world")
```
Bad:
```swift
let message = "hello world"
logger.info(message)
```
If you have a `String` that you received from elsewhere, please use
```swift
logger.info("\(stringIAlreadyHave)")
```
For more details, have a look in the next section.
### What are the differences between SwiftLog 1 and 0?
- SwiftLog 0 does not use `@inlinable`.
- Apart from accepting `Logger.Message` for the message, SwiftLog 0 has a `String` overload.
- In SwiftLog 0, `Logger.Message` is not `ExpressibleByStringLiteral` or `ExpressibleByStringInterpolation`.
- In SwiftLog 0, `Logger.MetadataValue` is not `ExpressibleByStringLiteral` or `ExpressibleByStringInterpolation`.
#### Why these differences?
##### @inlinable
Swift 4.0 & 4.1 don't support `@inlinable`, so SwiftLog 0 can't use them.
##### Logger.Message
Because all Swift 4 versions don't have a (non-deprecated) mechanism for a type to be `ExpressibleByStringInterpolation` we couldn't make `Logger.Message` expressible by string literals. Unfortunately, the most basic form of our logging API is `logger.info("Hello \(world)")`. For this to work however, `"Hello \(world)"` needs to be accepted and because we can't make `Logger.Message` `ExpressibleByStringInterpolation` we added an overload for all the logging methods to also accept `String`. In most cases, you won't even notice that with SwiftLog 0 you're creating a `String` (which is then transformed to a `Logger.Message`) and with SwiftLog 1 you're creating a `Logger.Message` directly. That is because both `String` and `Logger.Message` will accept all forms of string literals and string interpolations.
Unfortunately, there is code that will make this seemingly small difference visible. If you write
```swift
let message = "Hello world"
logger.info(message)
```
then this will only work in SwiftLog 0 and not in SwiftLog 1. Why? Because SwiftLog 1 will want a `Logger.Message` but `let message = "Hello world"` will make `message` to be of type `String` and in SwiftLog 1, the logging methods don't accept `String`s.
So if you intend to be compatible with SwiftLog 0 and 1 at the same time, please make sure to always use a _string literal_ or a _string interpolation_ inside of the logging methods.
In the case that you already have a `String` handy that you want to log, don't worry at all, just use
```swift
let message = "Hello world"
logger.info("\(message)")
```
and again, you will be okay with SwiftLog 0 and 1.
## Design
This logging API was designed with the contributors to the Swift on Server community and approved by the [SSWG (Swift Server Work Group)](https://swift.org/server/) to the 'sandbox level' of the SSWG's [incubation process](https://github.com/swift-server/sswg/blob/master/process/incubation.md).
+1 -1
View File
@@ -176,7 +176,7 @@ extension Logger {
public func trace(_ message: @autoclosure () -> Logger.Message,
metadata: @autoclosure () -> Logger.Metadata? = nil,
file: String = #file, function: String = #function, line: UInt = #line) {
self.trace(message(), metadata: metadata(), source: nil, file: file, line: line)
self.trace(message(), metadata: metadata(), source: nil, file: file, function: function, line: line)
}
/// Log a message passing with the `Logger.Level.debug` log level.
+5 -2
View File
@@ -17,8 +17,11 @@ RUN apt-get update && apt-get install -y wget
RUN apt-get update && apt-get install -y lsof dnsutils netcat-openbsd net-tools curl jq # used by integration tests
# ruby and jazzy for docs generation
RUN apt-get update && apt-get install -y ruby ruby-dev libsqlite3-dev
RUN gem install jazzy --no-ri --no-rdoc
RUN apt-get update && apt-get install -y ruby ruby-dev libsqlite3-dev build-essential
# switch of gem docs building
RUN echo "gem: --no-document" > ~/.gemrc
# jazzy no longer works on xenial as ruby is too old.
RUN if [ "${ubuntu_version}" != "xenial" ] ; then gem install jazzy; fi
# tools
RUN mkdir -p $HOME/.tools
+17
View File
@@ -0,0 +1,17 @@
version: "3"
services:
runtime-setup:
image: swift-log:20.04-5.4
build:
args:
base_image: "swiftlang/swift:nightly-5.4-focal"
test:
image: swift-log:20.04-5.4
environment: []
#- SANITIZER_ARG=--sanitize=thread
shell:
image: swift-log:20.04-5.4
+17
View File
@@ -0,0 +1,17 @@
version: "3"
services:
runtime-setup:
image: swift-log:20.04-main
build:
args:
base_image: "swiftlang/swift:nightly-main-focal"
test:
image: swift-log:20.04-main
environment: []
#- SANITIZER_ARG=--sanitize=thread
shell:
image: swift-log:20.04-main