目录
- .githubDoc coverage3年前
- ImagesReadme: updated xcode console image2年前
- SourcesTrace: added TraceViewStyle flat and pretty, frame to stack, updated Tests2年前
- TestsTests: fix for test_trace_stack_depth_all_pretty2年前
- .editorconfigAdded .editorconfig4年前
- .gitignoreupdate ignore4年前
- LICENSEInitial commit4年前
- NetConsole.commandAdded NetConsole.command4年前
- Package.swiftPackage.swift: Added library DLogObjC3年前
- README.mdReadme: updated xcode console image2年前
邀请码
DLog
DLog is the development logger for Swift that supports emoji and colored text output, format and privacy options, pipelines, filtering, scopes, intervals, stack backtrace and more.
Getting started
By default
DLogprovides basic text console output:Outputs:
Where:
•- start sign (useful for filtering)23:59:11.710- timestamp (HH:mm:ss.SSS)[DLOG]- category tag (‘DLOG’ by default)[LOG]- log type tag (‘LOG’, ‘TRACE’, ‘DEBUG’ etc.)<DLog.swift:12>- location (file:line)Hello DLog!- messageYou can apply privacy and format options to your logged values:
Outputs:
DLogoutputs text logs tostdoutby default but you can use the other outputs such as:stderr, filter, file, OSLog, Net. For instance:Dlogsupports plain (by default), emoji and colored styles for text messages and you can set a needed one:Outputs:
Where
=>is pipeline operator and it can be used for creating a list of outputs:All log messages will be written to
stdoutfirst and the the error messages only to the file.Log levels
logLog a message:
Outputs:
infoLog an information message and helpful data:
Outputs:
traceLog the current function name and a message (if it is provided) to help in debugging problems during the development:
Outputs:
debugLog a debug message to help debug problems during the development:
Outputs:
warningLog a warning message that occurred during the execution of your code.
Outputs:
errorLog an error that occurred during the execution of your code.
Outputs:
assertSanity check and log a message (if it is provided) when a condition is false.
Outputs:
faultLog a critical bug that occurred during the execution in your code.
Outputs:
Privacy
Privacy options allow to manage the visibility of values in log messages.
publicIt applies to all values in log messages by default and the values will be visible in logs.
Outputs:
privateBecause users can have access to log messages that your app generates, use the
privateprivacy options to hide potentially sensitive information. For example, you might use it to hide or mask an account information or personal data.The standard
privateoption redacts a value with the generic string.Outputs:
private(mask: .hash)The mask option to redact a value with its hash value in the logs.
Outputs:
private(mask: .random)The mask option to redact a value with a random values for each symbol in the logs.
Outputs:
private(mask: .redact)The mask option to redact a value with a generic values for each symbol in the logs.
Outputs:
private(mask: .shuffle)The mask option to redact a value with a shuffled value from all symbols in the logs.
Outputs:
private(mask: .custom(value:))The mask option to redact a value with a custom string value in the logs.
Outputs:
private(mask: .reduce(length:))The mask option to redact a value with its reduced value of a provided length in the logs.
Outputs:
private(mask: .partial(first:, last:))The mask option to redact a value with its parts from start and end of provided lengths in the logs.
Outputs:
Formatters
DLog formats values in log messages based on the default settings, but you can apply custom formatting to your variables to make them more readable.
Date
The formatting options for date values.
date(dateStyle: DateFormatter.Style, timeStyle: DateFormatter.Style, locale: Locale?)The formatting options for Date values.
Outputs:
dateCustom(format: String)Format date with a custom format string.
Outputs:
Integer
The formatting options for integer (Int8, Int16, Int32, Int64, UInt8 etc.) values.
binaryDisplays an integer value in binary format.
Outputs:
octal(includePrefix: Bool)Displays an integer value in octal format with the specified parameters.
Outputs:
hex(includePrefix: Bool, uppercase: Bool)Displays an integer value in hexadecimal format with the specified parameters.
Outputs:
byteCount(countStyle: ByteCountFormatter.CountStyle, allowedUnits: ByteCountFormatter.Units)Format byte count with style and unit.
Outputs:
number(style: NumberFormatter.Style, locale: Locale?)Displays an integer value in number format with the specified parameters.
Outputs:
httpStatusCodeDisplays a localized string corresponding to a specified HTTP status code.
Outputs:
ipv4AddressDisplays an integer value (Int32) as IPv4 address.
Outputs:
time(unitsStyle: DateComponentsFormatter.UnitsStyle)
Displays a time duration from seconds.
Outputs:
date(dateStyle: DateFormatter.Style, timeStyle: DateFormatter.Style, locale: Locale?)
Displays date from seconds since 1970.
Outputs:
Float
The formatting options for double and floating-point numbers.
fixed(precision: Int)Displays a floating-point value in fprintf’s
%fformat with specified precision.Outputs:
hex(includePrefix: Bool, uppercase: Bool)Displays a floating-point value in hexadecimal format with the specified parameters.
Outputs:
exponential(precision: Int)Displays a floating-point value in fprintf’s
%eformat with specified precision.Outputs:
hybrid(precision: Int)Displays a floating-point value in fprintf’s
%gformat with the specified precision.Outputs:
number(style: NumberFormatter.Style, locale: Locale?)Displays a floating-point value in number format with the specified parameters.
Outputs:
time(unitsStyle: DateComponentsFormatter.UnitsStyle)
Displays a time duration from seconds.
Outputs:
date(dateStyle: DateFormatter.Style, timeStyle: DateFormatter.Style, locale: Locale?)
Displays date from seconds since 1970.
Outputs:
Bool
The formatting options for Boolean values.
binaryDisplays a boolean value as 1 or 0.
Outputs:
answerDisplays a boolean value as yes or no.
Outputs:
toggleDisplays a boolean value as on or off.
Outputs:
Data
The formatting options for Data.
ipv6Address
Pretty prints an IPv6 address from data.
Outputs:
text
Pretty prints text from data.
Outputs:
uuid
Pretty prints uuid from data.
Outputs:
raw
Pretty prints raw bytes from data.
Outputs:
Scope
scopeprovides a mechanism for grouping work that’s done in your program, so that can see all log messages related to a defined scope of your code in a tree view:Outputs:
Where:
[Loading]- Name of the scope.(0.330s)- Time duration of the scope in secs.You can get duration value of a finished scope programatically:
It’s possible to
enterandleavea scope asynchronously:Outputs:
Scopes can be nested one into one and that implements a global stack of scopes:
Outputs:
Interval
intervalmeasures performance of your code by a running time and logs a detailed message with accumulated statistics in seconds:Outputs:
Where:
average- Average time duration of all intervals.duration- The current time duration of the current interval.sorting- Name of the interval.You can also get the current interval’s duration and all its statistics programatically:
To measure asynchronous tasks you can use
beginandendmethods:Outputs:
Category
You can define category name to differentiate unique areas and parts of your app and DLog uses this value to categorize and filter related log messages. For example, you might define separate strings for your app’s user interface, data model, and networking code.
Outputs:
Configuration
You can apply your specific configuration to your category to change the default log messages appearance, visible info and details etc. (See more: Configuration )
For instance:
Outputs:
Metadata
In its most basic usage, metadata is useful for grouping log messages about the same subject together. For example, you can set the request ID of an HTTP request as metadata, and all the log lines about that HTTP request would show that request ID.
Logger metadata is a keyword list stored in the dictionary and it can be applied to the logger on creation or changed with its instance later, e.g.:
Outputs:
Where:
(id:12345,process:main)- key-value pairs of the current metadata.The same works with category and scope which copy its parent metadata on creation, but this copy can be changed later:
Outputs:
Outputs
Text
Textis a source output that generates text representation of log messages. It doesn’t deliver text to any target outputs (stdout, file etc.) and usually other outputs use it.It supports thee styles:
.plain- universal plain text.emoji- text with type icons for info, debug etc. (useful for XCode console).colored- colored text with ANSI escape codes (useful for Terminal and files)Outputs:
Colored text in Terminal:
You can also use shortcuts
.textPlain,.textEmojiand.textColoredto create the output:Standard
Standardis a target output that can output text messages to POSIX streams:stdout- Standard Outputstderr- Standard ErrorYou can also use shortcuts
.stdoutand.stderrto create the output for the logger:By default
StandardusesText(style: .plain)output as a source to write text to the streams but you can set other:Outputs:
File
Fileis a target output that writes text messages to a file by a provided path:By default
Fileoutput clears content of a opened file but if you want to append data to the existed file you should setappendparameter totrue:You can also use
.fileshortcut to create the output:Fileoutput usesText(style: .plain)as a source by default but you can change it:File “dlog.txt”:
OSLog
OSLogis a target output that writes messages to the Unified Logging System (https://developer.apple.com/documentation/os/logging) that captures telemetry from your app for debugging and performance analysis and then you can use various tools to retrieve log information such as:ConsoleandInstrumentsapps, command line toollogetc.To create
OSLogyou can use subsystem strings that identify major functional areas of your app, and you specify them in reverse DNS notation—for example,com.your_company.your_subsystem_name.OSLogusescom.dlog.loggersubsystem by default:You can also use
.oslogshortcut to create the output:All DLog’s methods map to the system logger ones with appropriate log levels e.g.:
Console.app with log levels:
DLog’s scopes map to the system logger activities:
Console.app with activities:
DLog’s intervals map to the system logger signposts:
Instruments.app with signposts:
Net
Netis a target output that sends log messages toNetConsoleservice that can be run from a command line on your machine. The service is provided as executable inside DLog package and to start it you should runsh NetConsole.command(or just click onNetConsole.commandfile) inside the package’s folder and then the service starts listening for incoming messages:Then the output connects and sends your log messages to
NetConsole:Terminal:
By default
NetusesText(style: .colored)output as a source but you can set other:And you can also use
.netshortcut to create the output for the logger.To connect to a specific instance of the service in your network you should provide an unique name to both
NetConsoleandNetoutput (“DLog” name is used by default).To run the
NetConsolewith a specific name run next command:In swift code you should set the same name:
More params of
NetConsoleyou can look at help:Pipeline
As described above
File,NetandStandardoutputs havesourceparameter in their initializers to set a source output that is very useful if we want to change an output by default:Actually any output has
sourceproperty:So that it’s possible to make a linked list of outputs:
Where
textis a source forstdandstdis a source forfile: text –> std –> file, and now each text message will be sent to bothstdandfileoutputs consecutive.Lets rewrite this shorter:
Where
=>is pipeline operator which defines a combined output from two outputs where the first one is a source and second is a target. So from example above emoji text messages will be written twice: first to standard output and then to the file.You can combine any needed outputs together and create a final chained output from multiple outputs and your messages will be forwarded to all of them one by one:
Filter
Filteror.filterrepresents a pipe output that can filter log messages by next available fields:time,category,type,fileName,funcName,line,textandscope. You can inject it to your pipeline where you need to log specific data only.Examples:
Outputs:
Outputs:
Outputs:
Outputs:
.disabledIt is the shared disabled logger constant that doesn’t emit any log message and it’s very useful when you want to turn off the logger for some build configuration, preference, condition etc.
The same can be done for disabling unnecessary log categories without commenting or deleting the logger’s functions:
The disabled logger continue running your code inside scopes and intervals:
Outputs:
Configuration
You can customize the logger’s output by setting which info from the logger should be used.
LogConfigis a root struct to configure the logger which contains common settings for log messages.For instance you can change the default view of log messages which includes a start sign, category, log type and location:
Outputs:
To new appearance that includes your start sign and timestamp only:
Outputs:
TraceConfigIt contains configuration values regarding to the
tracemethod which includes trace view options, thread and stack configurations.By default
tracemethod uses.compactview option to produce information about the current function name and thread info:Outputs:
But you can change it to show a function and queue names with pretty style:
Outputs:
ThreadConfigThe trace configuration has
threadConfigproperty to change view options of thread info. For instance the logger can print the current QoS of threads.Outputs:
StackConfigThe
tracemethod can output the call stack backtrace of the current thread at the moment this method was called. To enable this feature you should configure stack view options, style and depth withstackConfigproperty:Outputs:
IntervalConfigYou can change the view options of interval statistics with
intervalConfigproperty ofLogConfigto show needed information such as:.count,.min,.maxetc. Or you can use.allto output all parameters.Outputs:
Objective-C
DLog exposes all functionality to Objective-C via
DLogObjClibrary and it’s very useful in projects with mixed code so you can log messages, create scopes and intervals, share global loggers etc.Log levels
Also you can format log messages:
Output:
Scope
Interval
Category
Pipeline
Outputs:
Filter
Outputs:
Disabled
Installation
XCode project
Xcode > File > Add Packages...https://github.com/ikhvorost/DLog.gitimport DLogSwift Package
Add
DLogpackage dependency to yourPackage.swiftfile:License
DLog is available under the MIT license. See the LICENSE file for more info.