-
Notifications
You must be signed in to change notification settings - Fork 2
/
finegrainedlogging.html
429 lines (398 loc) · 23.4 KB
/
finegrainedlogging.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
<!DOCTYPE html>
<html lang="en">
<head>
<title>FineGrainedLogging Reference</title>
<link rel="stylesheet" type="text/css" href="css/jazzy.css" />
<link rel="stylesheet" type="text/css" href="css/highlight.css" />
<meta charset='utf-8'>
<script src="js/jquery.min.js" defer></script>
<script src="js/jazzy.js" defer></script>
<script src="js/lunr.min.js" defer></script>
<script src="js/typeahead.jquery.js" defer></script>
<script src="js/jazzy.search.js" defer></script>
</head>
<body>
<a title="FineGrainedLogging Reference"></a>
<header>
<div class="content-wrapper">
<p><a href="index.html">CocoaLumberjack 3.7.0 Docs</a> (64% documented)</p>
<p class="header-right"><a href="https://github.com/CocoaLumberjack/CocoaLumberjack"><img src="img/gh.png"/>View on GitHub</a></p>
<p class="header-right">
<form role="search" action="search.json">
<input type="text" placeholder="Search documentation" data-typeahead>
</form>
</p>
</div>
</header>
<div class="content-wrapper">
<p id="breadcrumbs">
<a href="index.html">CocoaLumberjack Reference</a>
<img id="carat" src="img/carat.png" />
FineGrainedLogging Reference
</p>
</div>
<div class="content-wrapper">
<nav class="sidebar">
<ul class="nav-groups">
<li class="nav-group-name">
<a href="Guides.html">Guides</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="arc.html">ARC</a>
</li>
<li class="nav-group-task">
<a href="appcode-support.html">AppCode-support</a>
</li>
<li class="nav-group-task">
<a href="architecture.html">Architecture</a>
</li>
<li class="nav-group-task">
<a href="combineloggers.html">CombineLoggers</a>
</li>
<li class="nav-group-task">
<a href="customcontext.html">CustomContext</a>
</li>
<li class="nav-group-task">
<a href="customformatters.html">CustomFormatters</a>
</li>
<li class="nav-group-task">
<a href="customloglevels.html">CustomLogLevels</a>
</li>
<li class="nav-group-task">
<a href="customloggers.html">CustomLoggers</a>
</li>
<li class="nav-group-task">
<a href="dynamicloglevels.html">DynamicLogLevels</a>
</li>
<li class="nav-group-task">
<a href="faq.html">FAQ</a>
</li>
<li class="nav-group-task">
<a href="finegrainedlogging.html">FineGrainedLogging</a>
</li>
<li class="nav-group-task">
<a href="gettingstarted.html">GettingStarted</a>
</li>
<li class="nav-group-task">
<a href="logfilemanagement.html">LogFileManagement</a>
</li>
<li class="nav-group-task">
<a href="perloggerloglevels.html">PerLoggerLogLevels</a>
</li>
<li class="nav-group-task">
<a href="peruserloglevels.html">PerUserLogLevels</a>
</li>
<li class="nav-group-task">
<a href="performance.html">Performance</a>
</li>
<li class="nav-group-task">
<a href="problemsolution.html">ProblemSolution</a>
</li>
<li class="nav-group-task">
<a href="readme.html">README</a>
</li>
<li class="nav-group-task">
<a href="xcodecolors.html">XcodeColors</a>
</li>
<li class="nav-group-task">
<a href="xcodetricks.html">XcodeTricks</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Classes.html">Classes</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Classes/CLIColor.html">CLIColor</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDASLLogCapture.html">DDASLLogCapture</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDASLLogger.html">DDASLLogger</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDAbstractDatabaseLogger.html">DDAbstractDatabaseLogger</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDAbstractLogger.html">DDAbstractLogger</a>
</li>
<li class="nav-group-task">
<a href="Classes.html#/c:objc(cs)DDAtomicCounter">DDAtomicCounter</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDContextBlacklistFilterLogFormatter.html">DDContextBlacklistFilterLogFormatter</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDContextWhitelistFilterLogFormatter.html">DDContextWhitelistFilterLogFormatter</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDDispatchQueueLogFormatter.html">DDDispatchQueueLogFormatter</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDFileLogger.html">DDFileLogger</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDLog.html">DDLog</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDLogFileFormatterDefault.html">DDLogFileFormatterDefault</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDLogFileInfo.html">DDLogFileInfo</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDLogFileManagerDefault.html">DDLogFileManagerDefault</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDLogMessage.html">DDLogMessage</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDLoggerInformation.html">DDLoggerInformation</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDMultiFormatter.html">DDMultiFormatter</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDOSLogger.html">DDOSLogger</a>
</li>
<li class="nav-group-task">
<a href="Classes/DDTTYLogger.html">DDTTYLogger</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Constants.html">Constants</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Constants.html#/c:@CocoaLumberjackVersionNumber">CocoaLumberjackVersionNumber</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@CocoaLumberjackVersionString">CocoaLumberjackVersionString</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@DDLoggerNameASL">DDLoggerNameASL</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@DDLoggerNameFile">DDLoggerNameFile</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@DDLoggerNameOS">DDLoggerNameOS</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@DDLoggerNameTTY">DDLoggerNameTTY</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@DDQualityOfServiceBackground">DDQualityOfServiceBackground</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@DDQualityOfServiceDefault">DDQualityOfServiceDefault</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@DDQualityOfServiceUnspecified">DDQualityOfServiceUnspecified</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@DDQualityOfServiceUserInitiated">DDQualityOfServiceUserInitiated</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@DDQualityOfServiceUserInteractive">DDQualityOfServiceUserInteractive</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@DDQualityOfServiceUtility">DDQualityOfServiceUtility</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@kDDASLDDLogValue">kDDASLDDLogValue</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@kDDASLKeyDDLog">kDDASLKeyDDLog</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@kDDDefaultLogFilesDiskQuota">kDDDefaultLogFilesDiskQuota</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@kDDDefaultLogMaxFileSize">kDDDefaultLogMaxFileSize</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@kDDDefaultLogMaxNumLogFiles">kDDDefaultLogMaxNumLogFiles</a>
</li>
<li class="nav-group-task">
<a href="Constants.html#/c:@kDDDefaultLogRollingFrequency">kDDDefaultLogRollingFrequency</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Enums.html">Enumerations</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Enums/DDDispatchQueueLogFormatterMode.html">DDDispatchQueueLogFormatterMode</a>
</li>
<li class="nav-group-task">
<a href="Enums/DDLogFlag.html">DDLogFlag</a>
</li>
<li class="nav-group-task">
<a href="Enums/DDLogLevel.html">DDLogLevel</a>
</li>
<li class="nav-group-task">
<a href="Enums/DDLogMessageOptions.html">DDLogMessageOptions</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Protocols.html">Protocols</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Protocols/DDAtomicCountable.html">DDAtomicCountable</a>
</li>
<li class="nav-group-task">
<a href="Protocols/DDLogFileManager.html">DDLogFileManager</a>
</li>
<li class="nav-group-task">
<a href="Protocols/DDLogFormatter.html">DDLogFormatter</a>
</li>
<li class="nav-group-task">
<a href="Protocols/DDLogger.html">DDLogger</a>
</li>
<li class="nav-group-task">
<a href="Protocols/DDRegisteredDynamicLogging.html">DDRegisteredDynamicLogging</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Type%20Definitions.html">Type Definitions</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Type%20Definitions.html#/c:DDTTYLogger.h@T@DDColor">DDColor</a>
</li>
<li class="nav-group-task">
<a href="Type%20Definitions.html#/c:DDLoggerNames.h@T@DDLoggerName">DDLoggerName</a>
</li>
<li class="nav-group-task">
<a href="Type%20Definitions.html#/c:DDDispatchQueueLogFormatter.h@T@DDQualityOfServiceName">DDQualityOfServiceName</a>
</li>
</ul>
</li>
<li class="nav-group-name">
<a href="Functions.html">Functions</a>
<ul class="nav-group-tasks">
<li class="nav-group-task">
<a href="Functions.html#/c:@F@DDExtractFileNameWithoutExtension">DDExtractFileNameWithoutExtension</a>
</li>
<li class="nav-group-task">
<a href="Functions.html#/c:DDTTYLogger.h@F@DDMakeColor">DDMakeColor</a>
</li>
</ul>
</li>
</ul>
</nav>
<article class="main-content">
<section>
<section class="section">
<p>When you need something more advanced than simple log levels.</p>
<h3 id='introduction' class='heading'>Introduction</h3>
<p>Most of us are familiar with log levels. They are simple to understand, and they’re used in almost every logging framework. However, there are times when something more advanced is desired. Something more fine grained.</p>
<h4 id='example-1' class='heading'>Example #1:</h4>
<p>You have a large source code file that you are debugging. The code is logically separated into 7 different sub-components. One of these sub-components is having issues. So you’d like to enable some extra logging, but you don’t want to see all the log statements from the other 6 sub-components. That would be too much junk to filter through. Wouldn’t it be nice if your logging framework was tailored to fit the logical separations in your code?</p>
<h4 id='example-2' class='heading'>Example #2:</h4>
<p>You’re adding a new feature to your application. The implementation of this feature spans across several different files. Something isn’t quite working right and you’d like to enable some extra logging, but you only want to see log statements related to this new feature. The problem is, there are a bunch of other log statements in these files. You don’t want to remove them. You just want a little bit extra fine-grained control.</p>
<p>Not a problem. Lumberjack can help!</p>
<h3 id='details' class='heading'>Details</h3>
<p>If you look closely at the definitions in the <code>DDLogLegacyMacros</code> header file, you’ll notice something interesting:</p>
<pre class="highlight objective_c"><code><span class="cp">#define LOG_FLAG_ERROR (1 << 0) // 0...00001
#define LOG_FLAG_WARN (1 << 1) // 0...00010
#define LOG_FLAG_INFO (1 << 2) // 0...00100
#define LOG_FLAG_DEBUG (1 << 3) // 0...01000
#define LOG_FLAG_VERBOSE (1 << 4) // 0...10000
</span>
<span class="cp">#define LOG_ERROR (ddLogLevel & LOG_FLAG_ERROR) // Bitwise AND
</span></code></pre>
<p>Lumberjack is actually using a bitmask! And it is only using 5 bits. This means that every other bit is <strong>reserved for you</strong>.</p>
<p>The Lumberjack framework actually comes with a sample Xcode project that demonstrates fine-grained logging. The demo project is based upon example #2 above. Here is how it works:</p>
<p>Imagine you have a series of related timers. The calculation of these timers is complicated, and are thus spread across multiple files. However, they are related. In our example we have two different categories of timers. One for “food” and another for “sleep”.</p>
<p>So we want all of our logging related to our food timers to be grouped together. This way it can be enabled/disabled independently of the rest of the logging within the various files. And we want the same solution applied to our sleep timers as well.</p>
<p>So we create our own logging header file to be used by our application. We’ll call it “MYLog.h”:</p>
<pre class="highlight objective_c"><code><span class="cp">#import "DDLog.h"
</span>
<span class="c1">// The first 5 bits are being used by the standard levels (0 - 4)
// All other bits are fair game for us to use.
</span>
<span class="cp">#define LOG_FLAG_FOOD_TIMER (1 << 5) // 0...0100000
#define LOG_FLAG_SLEEP_TIMER (1 << 6) // 0...1000000
</span>
<span class="cp">#define LOG_FOOD_TIMER (ddLogLevel & LOG_FLAG_FOOD_TIMER)
#define LOG_SLEEP_TIMER (ddLogLevel & LOG_FLAG_SLEEP_TIMER)
</span>
<span class="cp">#define DDLogFoodTimer(frmt, ...) ASYNC_LOG_OBJC_MAYBE(ddLogLevel, LOG_FLAG_FOOD_TIMER, 0, frmt, ##__VA_ARGS__)
#define DDLogSleepTimer(frmt, ...) ASYNC_LOG_OBJC_MAYBE(ddLogLevel, LOG_FLAG_SLEEP_TIMER, 0, frmt, ##__VA_ARGS__)
</span>
<span class="c1">// Now we decide which flags we want to enable in our application
</span>
<span class="cp">#define LOG_FLAG_TIMERS (LOG_FLAG_FOOD_TIMER | LOG_FLAG_SLEEP_TIMER))
</span></code></pre>
<p>Now we have two new macros that can be used in our application.</p>
<ul>
<li>DDLogFoodTimer(…)</li>
<li>DDLogSleepTimer(…)</li>
</ul>
<p>We also defined LOG_FLAG_TIMERS which can be used to enable both loggers. LOG_FLAG_FOOD_TIMER | LOG_FLAG_SLEEP_TIMER = 0100000 | 1000000 = 1100000</p>
<p>Then in our source code files we just make sure that our ddLogLevel bitmask has the flags set to enable logging for our timers:</p>
<pre class="highlight objective_c"><code><span class="cp">#import "MYLog.h"
</span>
<span class="k">static</span> <span class="k">const</span> <span class="kt">int</span> <span class="n">ddLogLevel</span> <span class="o">=</span> <span class="n">LOG_LEVEL_WARN</span> <span class="o">|</span> <span class="n">LOG_FLAG_TIMERS</span><span class="p">;</span>
<span class="p">...</span>
<span class="n">DDLogFoodTimer</span><span class="p">(</span><span class="s">@"TimerTwo: Hungry - Need Food"</span><span class="p">);</span>
</code></pre>
<h3 id='how-many-fine-grained-options-are-available' class='heading'>How many fine-grained options are available?</h3>
<p>As many as you want.</p>
<p>The ddLogLevel variable is declared as an int. This means that on most systems it will be 32 bits. Since the normal log level stuff is taking up 4 bits, this gives you 28 bits to work with.</p>
<p>But if that isn’t enough, you could change it to be a 64-bit value, or you could simply add another variable. The macros have been designed to make it easy for you to plug in your own custom stuff.</p>
<p>For example, let’s say you wanted to have 30 fine-grained log options. No problem. Just do something like this.</p>
<pre class="highlight objective_c"><code><span class="cp">#define LOG_FLAG_CAT (1 << 0) // 0...00001
#define LOG_FLAG_DOG (1 << 1) // 0...00010
</span>
<span class="cp">#define LOG_CAT (ddLogLevel2 & LOG_FLAG_CAT)
#define LOG_DOG (ddLogLevel2 & LOG_FLAG_DOG)
</span>
<span class="cp">#define DDLogCat(frmt, ...) ASYNC_LOG_OBJC_MAYBE(ddLogLevel2, LOG_FLAG_CAT, 0, frmt, ##__VA_ARGS__)
#define DDLogDog(frmt, ...) ASYNC_LOG_OBJC_MAYBE(ddLogLevel2, LOG_FLAG_DOG, 0, frmt, ##__VA_ARGS__)
</span></code></pre>
<p>All we had to do was use a new variable - ddLogLevel2.</p>
<p>You should also note that you aren’t restricted to the 4 pre-defined log levels. You can define them however you want. Learn more in the <a href="CustomLogLevels.md">Custom Log Levels</a> page.</p>
<h3 id='swift-equivalent' class='heading'>Swift equivalent</h3>
<p>Thanks to @omerlh, we have a Swift equivalent for this feature.</p>
<ol>
<li>Create another enum</li>
</ol>
<pre class="highlight swift"><code><span class="kd">public</span> <span class="kd">enum</span> <span class="kt">CustomLogFlags</span> <span class="p">:</span> <span class="kt">UInt</span><span class="p">{</span>
<span class="k">case</span> <span class="n">test</span> <span class="o">=</span> <span class="mb">0b0100000</span>
<span class="p">}</span>
</code></pre>
<ol>
<li>Then set the log level</li>
</ol>
<pre class="highlight swift"><code><span class="kt">DDLog</span><span class="o">.</span><span class="n">logLevel</span> <span class="o">=</span> <span class="kt">DDLogLevel</span><span class="p">(</span><span class="nv">rawValue</span><span class="p">:</span> <span class="kt">DDLogLevel</span><span class="o">.</span><span class="n">error</span><span class="o">.</span><span class="n">rawValue</span> <span class="o">|</span> <span class="kt">CustomLogFlags</span><span class="o">.</span><span class="n">test</span><span class="o">.</span><span class="n">rawValue</span><span class="p">)</span> <span class="p">??</span> <span class="kt">DDLogLevel</span><span class="o">.</span><span class="n">error</span>
</code></pre>
<ol>
<li>Now you can log messages using the new log level:</li>
</ol>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">logLevel</span> <span class="o">=</span> <span class="kt">DDLogFlag</span><span class="p">(</span><span class="nv">rawValue</span><span class="p">:</span> <span class="kt">CustomLogFlags</span><span class="o">.</span><span class="n">test</span><span class="o">.</span><span class="n">rawValue</span><span class="p">)</span>
<span class="k">let</span> <span class="nv">logMsg</span> <span class="o">=</span> <span class="kt">DDLogMessage</span><span class="p">(</span><span class="nv">message</span><span class="p">:</span> <span class="nf">message</span><span class="p">(),</span> <span class="nv">level</span><span class="p">:</span> <span class="n">logLevel</span><span class="p">,</span> <span class="nv">flag</span><span class="p">:</span> <span class="n">flag</span><span class="p">,</span> <span class="nv">context</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="nv">file</span><span class="p">:</span> <span class="n">file</span><span class="p">,</span> <span class="nv">function</span><span class="p">:</span> <span class="n">function</span><span class="p">,</span> <span class="nv">line</span><span class="p">:</span> <span class="n">line</span><span class="p">,</span>
<span class="nv">tag</span><span class="p">:</span> <span class="n">tag</span><span class="p">,</span> <span class="nv">options</span><span class="p">:</span> <span class="kt">DDLogMessageOptions</span><span class="p">(</span><span class="nv">rawValue</span><span class="p">:</span> <span class="mi">0</span><span class="p">),</span> <span class="nv">timestamp</span><span class="p">:</span> <span class="kc">nil</span><span class="p">)</span>
<span class="kt">DDLog</span><span class="o">.</span><span class="nf">log</span><span class="p">(</span><span class="n">logAsync</span><span class="p">,</span> <span class="nv">message</span><span class="p">:</span> <span class="n">logMsg</span><span class="p">)</span>
</code></pre>
<p>Details can be found:</p>
<ul>
<li><a href="https://stackoverflow.com/questions/44627804/fine-grained-logging-when-using-cocoalumberjack-in-swift/44692158#44692158">https://stackoverflow.com/questions/44627804/fine-grained-logging-when-using-cocoalumberjack-in-swift/44692158#44692158</a></li>
<li><a href="https://github.com/CocoaLumberjack/CocoaLumberjack/issues/876">https://github.com/CocoaLumberjack/CocoaLumberjack/issues/876</a></li>
</ul>
</section>
</section>
<section id="footer">
<p>© 2020 <a class="link" href="https://github.com/CocoaLumberjack/CocoaLumberjack" target="_blank" rel="external">CocoaLumberjack</a>. All rights reserved. (Last updated: 2020-11-21)</p>
<p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.13.6</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external">Realm</a> project.</p>
</section>
</article>
</div>
</body>
</div>
</html>