Hi Tony and others (if there are) ^^

I'm helping at the langserver-swift project and we'd like to have some cross-platform logging. And since I know for a fact that TraceLog does work on both Darwin and Linux, I'm thinking it might be the perfect tool for the job.

Yesterday when we were talking about this, Ryan said that we should be outputting the log messages to Unified logging on Darwin and to the systemd logging journal on Linux. I think that's reasonable. Is is possible to configure TraceLog to do that? I know close to nothing about system logs so please forgive me if I'm noobing too much here. I know I probably am :sweat_smile:

Okay. So I've asked in the forums about how to tackle the issue that @tonystone presented at #44 here:

I chose to keep it separate for one primary reason which is that I don't want to force all Linux users to have to install systemd-dev just to use TraceLog. There are many applications that do not have a need for that Writer and just want to link to TraceLog and go.

I think that you're right, Tony. But I feel like it's better to have it be included by default. If you agree, the method provided in the forums opens up a (mostly) clear way.

But here's my justification for wanting it be included by default: in a server environment, where you'd be more restrictive on what packages you install, you'd (almost certainly) want to put your log entries in the system journal so that's alright.

That leaves us with the desktop users, both in Mac and Linux, and the users in mobile Darwin (iOS, WatchOS) platforms.

Let's first tackle where the Darwin (both desktop and mobile) users lie right now. As it stands, the 4.0.0 release gives them os_log logging. If an app or library developer chooses to use it, no problem! And if they don't... good as well! The current TraceLog code wouldn't change at all.

That leaves us with the Linux desktop users. If you were in Windows, you'd be reticent to install anything and with good reason. But in Linux, specially if you're using apt-get (Debian) or another trusted, signed repository, you know it doesn't contain malicious software, and can verify the integrity of the binaries. The two main concerns would then be (a) Breaking another package or (b) Binary size. In the case of Python packages, (a) is completely justified because setting it up correctly requires a bit of black magic. In this case, with libsystemd-dev being a OS-provided library, that should never happen.

(b) Is the last concern. I went and looked up how much systemd-dev weighs, and it's less than 1 MB!, which is actually less than I expected :sweat_smile:.

So all in all, I think it makes sense for it to be included by default.

Now from an API standpoint, I think we should either:

• Include OS logging in both (Darwin, Linux) platforms by default.
• Not include OS logging in both platforms, by default, and include it with a compile-time option (e.g by reading an environment variable at the Package manifest).

This would make the API uniform in all platforms, which brings a lot of benefits. Take for example a library author who wants to use TraceLog in the current configuration for OS logging, who might be testing it only on MacOS first. Then when they try to port it to Linux, they find themselves having to use a bunch of #if os(...), #elseif statements because the TraceLog API they were using is not available under Linux.

If instead the API was uniform, when they started porting it to Linux they would install systemd-dev and after that everything would behave in exactly the same way as it does on MacOS. And that, I think, would be a great relief :relieved:

I will write up on ideas of how to implement this afterwards because my hands are very tired at the moment :sweat_smile:

Please, lemme know what you think :slightly_smiling_face:

Hi again :)

Not wanting to clutter up #44 unnecessarily, I've opened this issue.

I'm learning the basics of TraceLog by writing a Swift script. So far, it compiles, but I can't seem to be able to print the logs to stdout and I don't really know why. Here's what I have so far. I must be missing a config step or something?

Thanks :)

Description

• Replace main jazzy doc page readme with a doc index page specific to jazzy docs.
• Update description of TraceLog to match the jazzy docs.

Motivation and Context

Remove redundant information from the main docs page.

How Has This Been Tested?

Pages reviewed manually before check-in.

Checklist:

For all changes:

• [ ] Is there an issue associated with this PR? Is it referenced in the commit message?
• [x] Has your PR been rebased against the latest commit within the target branch (typically master)?
• [x] Is your initial contribution a single, squashed commit?

For code changes:

• [x] Avoid other runtime dependencies
• [x] Have you written or updated unit tests to verify your changes?
• [x] Have you ensured that the full suite of tests is executed via make tests in the cmake-build-debug` directory off the root of the project?
• [x] If applicable, have you updated the documentation?
• [x] If applicable, have you updated the CHANGELOG.md file?

For documentation related changes:

• [x] Have you ensured that format looks appropriate for the output in which it is rendered?

Note:

Please ensure that once the PR is submitted, you check travis-ci for build issues and submit an update to your PR as soon as possible.

The current implementation (as of this writing) of FileHandle in swift will call fatalError() for any thrown error during the write operation.

    public func write(_ data: Data) {
        data.enumerateBytes() { (bytes, range, stop) in
            do {
                try NSData.writeToFileDescriptor(self._fd, path: nil, buf: UnsafePointer<Void>(bytes.baseAddress!), length: bytes.count)
            } catch {
                fatalError("Write failure")
            }
        }
    }

TraceLog must be reliable and not have cases that will crash the app so we were compelled to write our own FileOutputStream class to replace the FileHandle foundation class. This also gives us the advantage of improved performance during writes.

See: https://bugs.swift.org/browse/SR-2138 for more information.

Added

• Added ByteOutputFormatter protocol to define formatters for use with byte output stream type Writers.
• Added TextFormat, an implementation of a TextOutputFormatter that formats its output based on a supplied template (this is the default formatter for Console and File output). - Added TextFormat, an implementation of a ByteOutputFormatter that formats its output based on a supplied template (this is the default formatter for Console and File output).
• Added ByteOutputWriter protocol to define types that write byte streams to their output and accept ByteOutputFormatter types to format the output.

Changed

• Changed ConsoleWriter to accept new ByteOutputFormatter instances allowing you to customize the output log format (default is TextFormat.)
• Changed FileWriter to accept new ByteOutputFormatter instances allowing you to customize the output log format (default is TextFormat.)
• Changed FileWriter archive file name date format to "yyyyMMdd-HHmm-ss-SSS".
  • This was done for maximum compatibility between platforms and can be overridden in the FileConfiguration object passed at init.

Fixing warnings from Swift 2.2 / Xcode 7.3:

• Removing ++ operator.
• Replacing old style debug identifiers (e.g. FILE) with new style (e.g. #file).

This will require projects with a dependency on TraceLog to use Xcode 7.3 (or greater) to support Swift 2.2 syntax. The pod will still remain backwards compatible to iOS 8.0.

Description

Fix new xcode warning 'Initialization of 'UnsafePointer' results in a dangling pointer'

Motivation and Context

How Has This Been Tested?

All existing tests have been run and have passed.

Checklist:

For all changes:

• [ ] Is there an issue associated with this PR? Is it referenced in the commit message?
• [x] Has your PR been rebased against the latest commit within the target branch (typically master)?
• [ ] Is your initial contribution a single, squashed commit?

For code changes:

• [x] Avoid other runtime dependencies
• [x] Have you written or updated unit tests to verify your changes?
• [x] Have you ensured that the full suite of tests is executed via make tests in the cmake-build-debug` directory off the root of the project?
• [x] If applicable, have you updated the documentation?
• [x] If applicable, have you updated the CHANGELOG.md file?

For documentation related changes:

• [ ] Have you ensured that format looks appropriate for the output in which it is rendered?

Note:

Please ensure that once the PR is submitted, you check travis-ci for build issues and submit an update to your PR as soon as possible.

Description

Prep for release 5.0.0

How Has This Been Tested?

All existing tests were run and passed.

Checklist:

For all changes:

• [ ] Is there an issue associated with this PR? Is it referenced in the commit message?
• [x] Has your PR been rebased against the latest commit within the target branch (typically master)?
• [ ] Is your initial contribution a single, squashed commit?

For code changes:

• [x] Avoid other runtime dependencies
• [x] Have you written or updated unit tests to verify your changes?
• [x] Have you ensured that the full suite of tests is executed via make tests in the cmake-build-debug` directory off the root of the project?
• [x] If applicable, have you updated the documentation?
• [x] If applicable, have you updated the CHANGELOG.md file?

For documentation related changes:

• [x] Have you ensured that format looks appropriate for the output in which it is rendered?

Note:

Please ensure that once the PR is submitted, you check travis-ci for build issues and submit an update to your PR as soon as possible.

Description

Additions to monitor protected data on iOS and allow buffering it not available. This allows TraceLog to be started up before Protected data is available giving you debug visibility into the app while in the locked state. Implements issue #100 for the fixed strategy.

Motivation and Context

Need the ability to log on iOS before protected data becomes available.

Checklist:

For all changes:

• [x] Is there an issue associated with this PR? Is it referenced in the commit message?
• [x] Has your PR been rebased against the latest commit within the target branch (typically master)?
• [ ] Is your initial contribution a single, squashed commit?

For code changes:

• [x] Avoid other runtime dependencies
• [ ] Have you written or updated unit tests to verify your changes?
• [x] Have you ensured that the full suite of tests is executed via make tests in the cmake-build-debug` directory off the root of the project?
• [x] If applicable, have you updated the documentation?
• [x] If applicable, have you updated the CHANGELOG.md file?

For documentation related changes:

• [ ] Have you ensured that format looks appropriate for the output in which it is rendered?

Note:

Please ensure that once the PR is submitted, you check travis-ci for build issues and submit an update to your PR as soon as possible.

Fixed the broken Quick Start Guide link under the Installation (CocoaPods) section.

Description

Changed the link from Quick Start Guide to quick-start-guide.

Motivation and Context

Fixes broken docs, massively reducing confusion! ;)

How Has This Been Tested?

Forked and confirmed that the link works.

Checklist:

For all changes:

• [ ] Is there an issue associated with this PR? Is it referenced in the commit message?
• [x] Has your PR been rebased against the latest commit within the target branch (typically master)?
• [x] Is your initial contribution a single, squashed commit?

For code changes:

• [ ] Avoid other runtime dependencies
• [ ] Have you written or updated unit tests to verify your changes?
• [ ] Have you ensured that the full suite of tests is executed via make tests in the cmake-build-debug` directory off the root of the project?
• [ ] If applicable, have you updated the documentation?
• [ ] If applicable, have you updated the CHANGELOG.md file?

For documentation related changes:

• [x] Have you ensured that format looks appropriate for the output in which it is rendered?

Note:

Please ensure that once the PR is submitted, you check travis-ci for build issues and submit an update to your PR as soon as possible.

Describe the solution you'd like Add checks specifically for iOS that monitor the protected state of the log file currently being written to and only write when it is available. this would use the new FailureReason to return .unavailable when the protected data is not available.

Describe alternatives you've considered None.

Describe the solution you'd like In order to control and limit space taken on disk for files written with the FileWriter, we should have a way to control the number and disposition of files created. these can take the form of an Archive (compress) and/or delete after a certain number of a file or a certain size of space taken is reached.

Describe alternatives you've considered None considered accept for doing nothing which is not an option for files that grow to large sizes due to verbose logging or simply time written to a single log file.