Без опису

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917
  1. // Software License Agreement (BSD License)
  2. //
  3. // Copyright (c) 2010-2016, Deusty, LLC
  4. // All rights reserved.
  5. //
  6. // Redistribution and use of this software in source and binary forms,
  7. // with or without modification, are permitted provided that the following conditions are met:
  8. //
  9. // * Redistributions of source code must retain the above copyright notice,
  10. // this list of conditions and the following disclaimer.
  11. //
  12. // * Neither the name of Deusty nor the names of its contributors may be used
  13. // to endorse or promote products derived from this software without specific
  14. // prior written permission of Deusty, LLC.
  15. #import <Foundation/Foundation.h>
  16. #if OS_OBJECT_USE_OBJC
  17. #define DISPATCH_QUEUE_REFERENCE_TYPE strong
  18. #else
  19. #define DISPATCH_QUEUE_REFERENCE_TYPE assign
  20. #endif
  21. @class AWSDDLogMessage;
  22. @class AWSDDLoggerInformation;
  23. @protocol AWSDDLogger;
  24. @protocol AWSDDLogFormatter;
  25. /**
  26. * Define the standard options.
  27. *
  28. * We default to only 4 levels because it makes it easier for beginners
  29. * to make the transition to a logging framework.
  30. *
  31. * More advanced users may choose to completely customize the levels (and level names) to suite their needs.
  32. * For more information on this see the "Custom Log Levels" page:
  33. * Documentation/CustomLogLevels.md
  34. *
  35. * Advanced users may also notice that we're using a bitmask.
  36. * This is to allow for custom fine grained logging:
  37. * Documentation/FineGrainedLogging.md
  38. *
  39. * -- Flags --
  40. *
  41. * Typically you will use the LOG_LEVELS (see below), but the flags may be used directly in certain situations.
  42. * For example, say you have a lot of warning log messages, and you wanted to disable them.
  43. * However, you still needed to see your error and info log messages.
  44. * You could accomplish that with the following:
  45. *
  46. * static const AWSDDLogLevel ddLogLevel = AWSDDLogFlagError | AWSDDLogFlagInfo;
  47. *
  48. * When LOG_LEVEL_DEF is defined as ddLogLevel.
  49. *
  50. * Flags may also be consulted when writing custom log formatters,
  51. * as the AWSDDLogMessage class captures the individual flag that caused the log message to fire.
  52. *
  53. * -- Levels --
  54. *
  55. * Log levels are simply the proper bitmask of the flags.
  56. *
  57. * -- Booleans --
  58. *
  59. * The booleans may be used when your logging code involves more than one line.
  60. * For example:
  61. *
  62. * if (LOG_VERBOSE) {
  63. * for (id sprocket in sprockets)
  64. * AWSDDLogVerbose(@"sprocket: %@", [sprocket description])
  65. * }
  66. *
  67. * -- Async --
  68. *
  69. * Defines the default asynchronous options.
  70. * The default philosophy for asynchronous logging is very simple:
  71. *
  72. * Log messages with errors should be executed synchronously.
  73. * After all, an error just occurred. The application could be unstable.
  74. *
  75. * All other log messages, such as debug output, are executed asynchronously.
  76. * After all, if it wasn't an error, then it was just informational output,
  77. * or something the application was easily able to recover from.
  78. *
  79. * -- Changes --
  80. *
  81. * You are strongly discouraged from modifying this file.
  82. * If you do, you make it more difficult on yourself to merge future bug fixes and improvements from the project.
  83. * Instead, create your own MyLogging.h or ApplicationNameLogging.h or CompanyLogging.h
  84. *
  85. * For an example of customizing your logging experience, see the "Custom Log Levels" page:
  86. * Documentation/CustomLogLevels.md
  87. **/
  88. /**
  89. * Flags accompany each log. They are used together with levels to filter out logs.
  90. */
  91. typedef NS_OPTIONS(NSUInteger, AWSDDLogFlag){
  92. /**
  93. * 0...00001 AWSDDLogFlagError
  94. */
  95. AWSDDLogFlagError = (1 << 0),
  96. /**
  97. * 0...00010 AWSDDLogFlagWarning
  98. */
  99. AWSDDLogFlagWarning = (1 << 1),
  100. /**
  101. * 0...00100 AWSDDLogFlagInfo
  102. */
  103. AWSDDLogFlagInfo = (1 << 2),
  104. /**
  105. * 0...01000 AWSDDLogFlagDebug
  106. */
  107. AWSDDLogFlagDebug = (1 << 3),
  108. /**
  109. * 0...10000 AWSDDLogFlagVerbose
  110. */
  111. AWSDDLogFlagVerbose = (1 << 4)
  112. };
  113. /**
  114. * Log levels are used to filter out logs. Used together with flags.
  115. */
  116. typedef NS_ENUM(NSUInteger, AWSDDLogLevel){
  117. /**
  118. * No logs
  119. */
  120. AWSDDLogLevelOff = 0,
  121. /**
  122. * Error logs only
  123. */
  124. AWSDDLogLevelError = (AWSDDLogFlagError),
  125. /**
  126. * Error and warning logs
  127. */
  128. AWSDDLogLevelWarning = (AWSDDLogLevelError | AWSDDLogFlagWarning),
  129. /**
  130. * Error, warning and info logs
  131. */
  132. AWSDDLogLevelInfo = (AWSDDLogLevelWarning | AWSDDLogFlagInfo),
  133. /**
  134. * Error, warning, info and debug logs
  135. */
  136. AWSDDLogLevelDebug = (AWSDDLogLevelInfo | AWSDDLogFlagDebug),
  137. /**
  138. * Error, warning, info, debug and verbose logs
  139. */
  140. AWSDDLogLevelVerbose = (AWSDDLogLevelDebug | AWSDDLogFlagVerbose),
  141. /**
  142. * All logs (1...11111)
  143. */
  144. AWSDDLogLevelAll = NSUIntegerMax
  145. };
  146. NS_ASSUME_NONNULL_BEGIN
  147. /**
  148. * Extracts just the file name, no path or extension
  149. *
  150. * @param filePath input file path
  151. * @param copy YES if we want the result to be copied
  152. *
  153. * @return the file name
  154. */
  155. NSString * __nullable AWSDDExtractFileNameWithoutExtension(const char *filePath, BOOL copy);
  156. /**
  157. * The THIS_FILE macro gives you an NSString of the file name.
  158. * For simplicity and clarity, the file name does not include the full path or file extension.
  159. *
  160. * For example: AWSDDLogWarn(@"%@: Unable to find thingy", THIS_FILE) -> @"MyViewController: Unable to find thingy"
  161. **/
  162. #ifndef THIS_FILE
  163. #define THIS_FILE (AWSDDExtractFileNameWithoutExtension(__FILE__, NO))
  164. #endif
  165. /**
  166. * The AWS_THIS_FILE macro gives you an NSString of the file name.
  167. * Provided for convenience in case of name conflicts of the THIS_FILE macro with CocoaLumberjack.
  168. *
  169. * For example: AWSDDLogWarn(@"%@: Unable to find thingy", AWS_THIS_FILE) -> @"MyViewController: Unable to find thingy"
  170. **/
  171. #define AWS_THIS_FILE (AWSDDExtractFileNameWithoutExtension(__FILE__, NO))
  172. /**
  173. * The THIS_METHOD macro gives you the name of the current objective-c method.
  174. *
  175. * For example: AWSDDLogWarn(@"%@ - Requires non-nil strings", THIS_METHOD) -> @"setMake:model: requires non-nil strings"
  176. *
  177. * Note: This does NOT work in straight C functions (non objective-c).
  178. * Instead you should use the predefined __FUNCTION__ macro.
  179. **/
  180. #define THIS_METHOD NSStringFromSelector(_cmd)
  181. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  182. #pragma mark -
  183. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  184. /**
  185. * The main class, exposes all logging mechanisms, loggers, ...
  186. * For most of the users, this class is hidden behind the logging functions like `AWSDDLogInfo`
  187. */
  188. @interface AWSDDLog : NSObject
  189. /**
  190. * Returns the singleton `AWSDDLog`.
  191. * The instance is used by `AWSDDLog` class methods.
  192. */
  193. @property (class, nonatomic, strong, readonly) AWSDDLog *sharedInstance;
  194. /**
  195. * Log level setting.
  196. */
  197. @property (nonatomic, assign) AWSDDLogLevel logLevel;
  198. /**
  199. * Provides access to the underlying logging queue.
  200. * This may be helpful to Logger classes for things like thread synchronization.
  201. **/
  202. @property (class, nonatomic, DISPATCH_QUEUE_REFERENCE_TYPE, readonly) dispatch_queue_t loggingQueue;
  203. /**
  204. * Logging Primitive.
  205. *
  206. * This method is used by the macros or logging functions.
  207. * It is suggested you stick with the macros as they're easier to use.
  208. *
  209. * @param asynchronous YES if the logging is done async, NO if you want to force sync
  210. * @param level the log level
  211. * @param flag the log flag
  212. * @param context the context (if any is defined)
  213. * @param file the current file
  214. * @param function the current function
  215. * @param line the current code line
  216. * @param tag potential tag
  217. * @param format the log format
  218. */
  219. + (void)log:(BOOL)asynchronous
  220. level:(AWSDDLogLevel)level
  221. flag:(AWSDDLogFlag)flag
  222. context:(NSInteger)context
  223. file:(const char *)file
  224. function:(const char *)function
  225. line:(NSUInteger)line
  226. tag:(id __nullable)tag
  227. format:(NSString *)format, ... NS_FORMAT_FUNCTION(9,10);
  228. /**
  229. * Logging Primitive.
  230. *
  231. * This method is used by the macros or logging functions.
  232. * It is suggested you stick with the macros as they're easier to use.
  233. *
  234. * @param asynchronous YES if the logging is done async, NO if you want to force sync
  235. * @param level the log level
  236. * @param flag the log flag
  237. * @param context the context (if any is defined)
  238. * @param file the current file
  239. * @param function the current function
  240. * @param line the current code line
  241. * @param tag potential tag
  242. * @param format the log format
  243. */
  244. - (void)log:(BOOL)asynchronous
  245. level:(AWSDDLogLevel)level
  246. flag:(AWSDDLogFlag)flag
  247. context:(NSInteger)context
  248. file:(const char *)file
  249. function:(const char *)function
  250. line:(NSUInteger)line
  251. tag:(id __nullable)tag
  252. format:(NSString *)format, ... NS_FORMAT_FUNCTION(9,10);
  253. /**
  254. * Logging Primitive.
  255. *
  256. * This method can be used if you have a prepared va_list.
  257. * Similar to `log:level:flag:context:file:function:line:tag:format:...`
  258. *
  259. * @param asynchronous YES if the logging is done async, NO if you want to force sync
  260. * @param level the log level
  261. * @param flag the log flag
  262. * @param context the context (if any is defined)
  263. * @param file the current file
  264. * @param function the current function
  265. * @param line the current code line
  266. * @param tag potential tag
  267. * @param format the log format
  268. * @param argList the arguments list as a va_list
  269. */
  270. + (void)log:(BOOL)asynchronous
  271. level:(AWSDDLogLevel)level
  272. flag:(AWSDDLogFlag)flag
  273. context:(NSInteger)context
  274. file:(const char *)file
  275. function:(const char *)function
  276. line:(NSUInteger)line
  277. tag:(id __nullable)tag
  278. format:(NSString *)format
  279. args:(va_list)argList NS_SWIFT_NAME(log(asynchronous:level:flag:context:file:function:line:tag:format:arguments:));
  280. /**
  281. * Logging Primitive.
  282. *
  283. * This method can be used if you have a prepared va_list.
  284. * Similar to `log:level:flag:context:file:function:line:tag:format:...`
  285. *
  286. * @param asynchronous YES if the logging is done async, NO if you want to force sync
  287. * @param level the log level
  288. * @param flag the log flag
  289. * @param context the context (if any is defined)
  290. * @param file the current file
  291. * @param function the current function
  292. * @param line the current code line
  293. * @param tag potential tag
  294. * @param format the log format
  295. * @param argList the arguments list as a va_list
  296. */
  297. - (void)log:(BOOL)asynchronous
  298. level:(AWSDDLogLevel)level
  299. flag:(AWSDDLogFlag)flag
  300. context:(NSInteger)context
  301. file:(const char *)file
  302. function:(const char *)function
  303. line:(NSUInteger)line
  304. tag:(id __nullable)tag
  305. format:(NSString *)format
  306. args:(va_list)argList NS_SWIFT_NAME(log(asynchronous:level:flag:context:file:function:line:tag:format:arguments:));
  307. /**
  308. * Logging Primitive.
  309. *
  310. * This method can be used if you manualy prepared AWSDDLogMessage.
  311. *
  312. * @param asynchronous YES if the logging is done async, NO if you want to force sync
  313. * @param logMessage the log message stored in a `AWSDDLogMessage` model object
  314. */
  315. + (void)log:(BOOL)asynchronous
  316. message:(AWSDDLogMessage *)logMessage NS_SWIFT_NAME(log(asynchronous:message:));
  317. /**
  318. * Logging Primitive.
  319. *
  320. * This method can be used if you manualy prepared AWSDDLogMessage.
  321. *
  322. * @param asynchronous YES if the logging is done async, NO if you want to force sync
  323. * @param logMessage the log message stored in a `AWSDDLogMessage` model object
  324. */
  325. - (void)log:(BOOL)asynchronous
  326. message:(AWSDDLogMessage *)logMessage NS_SWIFT_NAME(log(asynchronous:message:));
  327. /**
  328. * Since logging can be asynchronous, there may be times when you want to flush the logs.
  329. * The framework invokes this automatically when the application quits.
  330. **/
  331. + (void)flushLog;
  332. /**
  333. * Since logging can be asynchronous, there may be times when you want to flush the logs.
  334. * The framework invokes this automatically when the application quits.
  335. **/
  336. - (void)flushLog;
  337. /**
  338. * Loggers
  339. *
  340. * In order for your log statements to go somewhere, you should create and add a logger.
  341. *
  342. * You can add multiple loggers in order to direct your log statements to multiple places.
  343. * And each logger can be configured separately.
  344. * So you could have, for example, verbose logging to the console, but a concise log file with only warnings & errors.
  345. **/
  346. /**
  347. * Adds the logger to the system.
  348. *
  349. * This is equivalent to invoking `[AWSDDLog addLogger:logger withLogLevel:AWSDDLogLevelAll]`.
  350. **/
  351. + (void)addLogger:(id <AWSDDLogger>)logger;
  352. /**
  353. * Adds the logger to the system.
  354. *
  355. * This is equivalent to invoking `[AWSDDLog addLogger:logger withLogLevel:AWSDDLogLevelAll]`.
  356. **/
  357. - (void)addLogger:(id <AWSDDLogger>)logger;
  358. /**
  359. * Adds the logger to the system.
  360. *
  361. * The level that you provide here is a preemptive filter (for performance).
  362. * That is, the level specified here will be used to filter out logMessages so that
  363. * the logger is never even invoked for the messages.
  364. *
  365. * More information:
  366. * When you issue a log statement, the logging framework iterates over each logger,
  367. * and checks to see if it should forward the logMessage to the logger.
  368. * This check is done using the level parameter passed to this method.
  369. *
  370. * For example:
  371. *
  372. * `[AWSDDLog addLogger:consoleLogger withLogLevel:AWSDDLogLevelVerbose];`
  373. * `[AWSDDLog addLogger:fileLogger withLogLevel:AWSDDLogLevelWarning];`
  374. *
  375. * `AWSDDLogError(@"oh no");` => gets forwarded to consoleLogger & fileLogger
  376. * `AWSDDLogInfo(@"hi");` => gets forwarded to consoleLogger only
  377. *
  378. * It is important to remember that Lumberjack uses a BITMASK.
  379. * Many developers & third party frameworks may define extra log levels & flags.
  380. * For example:
  381. *
  382. * `#define SOME_FRAMEWORK_LOG_FLAG_TRACE (1 << 6) // 0...1000000`
  383. *
  384. * So if you specify `AWSDDLogLevelVerbose` to this method, you won't see the framework's trace messages.
  385. *
  386. * `(SOME_FRAMEWORK_LOG_FLAG_TRACE & AWSDDLogLevelVerbose) => (01000000 & 00011111) => NO`
  387. *
  388. * Consider passing `AWSDDLogLevelAll` to this method, which has all bits set.
  389. * You can also use the exclusive-or bitwise operator to get a bitmask that has all flags set,
  390. * except the ones you explicitly don't want. For example, if you wanted everything except verbose & debug:
  391. *
  392. * `((AWSDDLogLevelAll ^ AWSDDLogLevelVerbose) | AWSDDLogLevelInfo)`
  393. **/
  394. + (void)addLogger:(id <AWSDDLogger>)logger withLevel:(AWSDDLogLevel)level;
  395. /**
  396. * Adds the logger to the system.
  397. *
  398. * The level that you provide here is a preemptive filter (for performance).
  399. * That is, the level specified here will be used to filter out logMessages so that
  400. * the logger is never even invoked for the messages.
  401. *
  402. * More information:
  403. * When you issue a log statement, the logging framework iterates over each logger,
  404. * and checks to see if it should forward the logMessage to the logger.
  405. * This check is done using the level parameter passed to this method.
  406. *
  407. * For example:
  408. *
  409. * `[AWSDDLog addLogger:consoleLogger withLogLevel:AWSDDLogLevelVerbose];`
  410. * `[AWSDDLog addLogger:fileLogger withLogLevel:AWSDDLogLevelWarning];`
  411. *
  412. * `AWSDDLogError(@"oh no");` => gets forwarded to consoleLogger & fileLogger
  413. * `AWSDDLogInfo(@"hi");` => gets forwarded to consoleLogger only
  414. *
  415. * It is important to remember that Lumberjack uses a BITMASK.
  416. * Many developers & third party frameworks may define extra log levels & flags.
  417. * For example:
  418. *
  419. * `#define SOME_FRAMEWORK_LOG_FLAG_TRACE (1 << 6) // 0...1000000`
  420. *
  421. * So if you specify `AWSDDLogLevelVerbose` to this method, you won't see the framework's trace messages.
  422. *
  423. * `(SOME_FRAMEWORK_LOG_FLAG_TRACE & AWSDDLogLevelVerbose) => (01000000 & 00011111) => NO`
  424. *
  425. * Consider passing `AWSDDLogLevelAll` to this method, which has all bits set.
  426. * You can also use the exclusive-or bitwise operator to get a bitmask that has all flags set,
  427. * except the ones you explicitly don't want. For example, if you wanted everything except verbose & debug:
  428. *
  429. * `((AWSDDLogLevelAll ^ AWSDDLogLevelVerbose) | AWSDDLogLevelInfo)`
  430. **/
  431. - (void)addLogger:(id <AWSDDLogger>)logger withLevel:(AWSDDLogLevel)level;
  432. /**
  433. * Remove the logger from the system
  434. */
  435. + (void)removeLogger:(id <AWSDDLogger>)logger;
  436. /**
  437. * Remove the logger from the system
  438. */
  439. - (void)removeLogger:(id <AWSDDLogger>)logger;
  440. /**
  441. * Remove all the current loggers
  442. */
  443. + (void)removeAllLoggers;
  444. /**
  445. * Remove all the current loggers
  446. */
  447. - (void)removeAllLoggers;
  448. /**
  449. * Return all the current loggers
  450. */
  451. @property (class, nonatomic, copy, readonly) NSArray<id<AWSDDLogger>> *allLoggers;
  452. /**
  453. * Return all the current loggers
  454. */
  455. @property (nonatomic, copy, readonly) NSArray<id<AWSDDLogger>> *allLoggers;
  456. /**
  457. * Return all the current loggers with their level (aka AWSDDLoggerInformation).
  458. */
  459. @property (class, nonatomic, copy, readonly) NSArray<AWSDDLoggerInformation *> *allLoggersWithLevel;
  460. /**
  461. * Return all the current loggers with their level (aka AWSDDLoggerInformation).
  462. */
  463. @property (nonatomic, copy, readonly) NSArray<AWSDDLoggerInformation *> *allLoggersWithLevel;
  464. /**
  465. * Registered Dynamic Logging
  466. *
  467. * These methods allow you to obtain a list of classes that are using registered dynamic logging,
  468. * and also provides methods to get and set their log level during run time.
  469. **/
  470. /**
  471. * Returns an array with the classes that are using registered dynamic logging
  472. */
  473. @property (class, nonatomic, copy, readonly) NSArray<Class> *registeredClasses;
  474. /**
  475. * Returns an array with the classes names that are using registered dynamic logging
  476. */
  477. @property (class, nonatomic, copy, readonly) NSArray<NSString*> *registeredClassNames;
  478. /**
  479. * Returns the current log level for a certain class
  480. *
  481. * @param aClass `Class` param
  482. */
  483. + (AWSDDLogLevel)levelForClass:(Class)aClass;
  484. /**
  485. * Returns the current log level for a certain class
  486. *
  487. * @param aClassName string param
  488. */
  489. + (AWSDDLogLevel)levelForClassWithName:(NSString *)aClassName;
  490. /**
  491. * Set the log level for a certain class
  492. *
  493. * @param level the new level
  494. * @param aClass `Class` param
  495. */
  496. + (void)setLevel:(AWSDDLogLevel)level forClass:(Class)aClass;
  497. /**
  498. * Set the log level for a certain class
  499. *
  500. * @param level the new level
  501. * @param aClassName string param
  502. */
  503. + (void)setLevel:(AWSDDLogLevel)level forClassWithName:(NSString *)aClassName;
  504. @end
  505. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  506. #pragma mark -
  507. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  508. /**
  509. * This protocol describes a basic logger behavior.
  510. * Basically, it can log messages, store a logFormatter plus a bunch of optional behaviors.
  511. * (i.e. flush, get its loggerQueue, get its name, ...
  512. */
  513. @protocol AWSDDLogger <NSObject>
  514. /**
  515. * The log message method
  516. *
  517. * @param logMessage the message (model)
  518. */
  519. - (void)logMessage:(AWSDDLogMessage *)logMessage NS_SWIFT_NAME(log(message:));
  520. /**
  521. * Formatters may optionally be added to any logger.
  522. *
  523. * If no formatter is set, the logger simply logs the message as it is given in logMessage,
  524. * or it may use its own built in formatting style.
  525. **/
  526. @property (nonatomic, strong) id <AWSDDLogFormatter> logFormatter;
  527. @optional
  528. /**
  529. * Since logging is asynchronous, adding and removing loggers is also asynchronous.
  530. * In other words, the loggers are added and removed at appropriate times with regards to log messages.
  531. *
  532. * - Loggers will not receive log messages that were executed prior to when they were added.
  533. * - Loggers will not receive log messages that were executed after they were removed.
  534. *
  535. * These methods are executed in the logging thread/queue.
  536. * This is the same thread/queue that will execute every logMessage: invocation.
  537. * Loggers may use these methods for thread synchronization or other setup/teardown tasks.
  538. **/
  539. - (void)didAddLogger;
  540. /**
  541. * Since logging is asynchronous, adding and removing loggers is also asynchronous.
  542. * In other words, the loggers are added and removed at appropriate times with regards to log messages.
  543. *
  544. * - Loggers will not receive log messages that were executed prior to when they were added.
  545. * - Loggers will not receive log messages that were executed after they were removed.
  546. *
  547. * These methods are executed in the logging thread/queue given in parameter.
  548. * This is the same thread/queue that will execute every logMessage: invocation.
  549. * Loggers may use the queue parameter to set specific values on the queue with dispatch_set_specific() function.
  550. **/
  551. - (void)didAddLoggerInQueue:(dispatch_queue_t)queue;
  552. /**
  553. * See the above description for `didAddLoger`
  554. */
  555. - (void)willRemoveLogger;
  556. /**
  557. * Some loggers may buffer IO for optimization purposes.
  558. * For example, a database logger may only save occasionaly as the disk IO is slow.
  559. * In such loggers, this method should be implemented to flush any pending IO.
  560. *
  561. * This allows invocations of AWSDDLog's flushLog method to be propogated to loggers that need it.
  562. *
  563. * Note that AWSDDLog's flushLog method is invoked automatically when the application quits,
  564. * and it may be also invoked manually by the developer prior to application crashes, or other such reasons.
  565. **/
  566. - (void)flush;
  567. /**
  568. * Each logger is executed concurrently with respect to the other loggers.
  569. * Thus, a dedicated dispatch queue is used for each logger.
  570. * Logger implementations may optionally choose to provide their own dispatch queue.
  571. **/
  572. @property (nonatomic, DISPATCH_QUEUE_REFERENCE_TYPE, readonly) dispatch_queue_t loggerQueue;
  573. /**
  574. * If the logger implementation does not choose to provide its own queue,
  575. * one will automatically be created for it.
  576. * The created queue will receive its name from this method.
  577. * This may be helpful for debugging or profiling reasons.
  578. **/
  579. @property (nonatomic, readonly) NSString *loggerName;
  580. @end
  581. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  582. #pragma mark -
  583. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  584. /**
  585. * This protocol describes the behavior of a log formatter
  586. */
  587. @protocol AWSDDLogFormatter <NSObject>
  588. @required
  589. /**
  590. * Formatters may optionally be added to any logger.
  591. * This allows for increased flexibility in the logging environment.
  592. * For example, log messages for log files may be formatted differently than log messages for the console.
  593. *
  594. * For more information about formatters, see the "Custom Formatters" page:
  595. * Documentation/CustomFormatters.md
  596. *
  597. * The formatter may also optionally filter the log message by returning nil,
  598. * in which case the logger will not log the message.
  599. **/
  600. - (NSString * __nullable)formatLogMessage:(AWSDDLogMessage *)logMessage NS_SWIFT_NAME(format(message:));
  601. @optional
  602. /**
  603. * A single formatter instance can be added to multiple loggers.
  604. * These methods provides hooks to notify the formatter of when it's added/removed.
  605. *
  606. * This is primarily for thread-safety.
  607. * If a formatter is explicitly not thread-safe, it may wish to throw an exception if added to multiple loggers.
  608. * Or if a formatter has potentially thread-unsafe code (e.g. NSDateFormatter),
  609. * it could possibly use these hooks to switch to thread-safe versions of the code.
  610. **/
  611. - (void)didAddToLogger:(id <AWSDDLogger>)logger;
  612. /**
  613. * A single formatter instance can be added to multiple loggers.
  614. * These methods provides hooks to notify the formatter of when it's added/removed.
  615. *
  616. * This is primarily for thread-safety.
  617. * If a formatter is explicitly not thread-safe, it may wish to throw an exception if added to multiple loggers.
  618. * Or if a formatter has potentially thread-unsafe code (e.g. NSDateFormatter),
  619. * it could possibly use these hooks to switch to thread-safe versions of the code or use dispatch_set_specific()
  620. .* to add its own specific values.
  621. **/
  622. - (void)didAddToLogger:(id <AWSDDLogger>)logger inQueue:(dispatch_queue_t)queue;
  623. /**
  624. * See the above description for `didAddToLogger:`
  625. */
  626. - (void)willRemoveFromLogger:(id <AWSDDLogger>)logger;
  627. @end
  628. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  629. #pragma mark -
  630. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  631. /**
  632. * This protocol describes a dynamic logging component
  633. */
  634. @protocol AWSDDRegisteredDynamicLogging
  635. /**
  636. * Implement these methods to allow a file's log level to be managed from a central location.
  637. *
  638. * This is useful if you'd like to be able to change log levels for various parts
  639. * of your code from within the running application.
  640. *
  641. * Imagine pulling up the settings for your application,
  642. * and being able to configure the logging level on a per file basis.
  643. *
  644. * The implementation can be very straight-forward:
  645. *
  646. * ```
  647. * + (int)ddLogLevel
  648. * {
  649. * return ddLogLevel;
  650. * }
  651. *
  652. * + (void)ddSetLogLevel:(AWSDDLogLevel)level
  653. * {
  654. * ddLogLevel = level;
  655. * }
  656. * ```
  657. **/
  658. @property (class, nonatomic, readwrite, setter=ddSetLogLevel:) AWSDDLogLevel ddLogLevel;
  659. @end
  660. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  661. #pragma mark -
  662. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  663. #ifndef NS_DESIGNATED_INITIALIZER
  664. #define NS_DESIGNATED_INITIALIZER
  665. #endif
  666. /**
  667. * Log message options, allow copying certain log elements
  668. */
  669. typedef NS_OPTIONS(NSInteger, AWSDDLogMessageOptions){
  670. /**
  671. * Use this to use a copy of the file path
  672. */
  673. AWSDDLogMessageCopyFile = 1 << 0,
  674. /**
  675. * Use this to use a copy of the function name
  676. */
  677. AWSDDLogMessageCopyFunction = 1 << 1,
  678. /**
  679. * Use this to use avoid a copy of the message
  680. */
  681. AWSDDLogMessageDontCopyMessage = 1 << 2
  682. };
  683. /**
  684. * The `AWSDDLogMessage` class encapsulates information about the log message.
  685. * If you write custom loggers or formatters, you will be dealing with objects of this class.
  686. **/
  687. @interface AWSDDLogMessage : NSObject <NSCopying>
  688. {
  689. // Direct accessors to be used only for performance
  690. @public
  691. NSString *_message;
  692. AWSDDLogLevel _level;
  693. AWSDDLogFlag _flag;
  694. NSInteger _context;
  695. NSString *_file;
  696. NSString *_fileName;
  697. NSString *_function;
  698. NSUInteger _line;
  699. id _tag;
  700. AWSDDLogMessageOptions _options;
  701. NSDate *_timestamp;
  702. NSString *_threadID;
  703. NSString *_threadName;
  704. NSString *_queueLabel;
  705. }
  706. /**
  707. * Default `init` for empty messages.
  708. */
  709. - (instancetype)init NS_DESIGNATED_INITIALIZER;
  710. /**
  711. * Standard init method for a log message object.
  712. * Used by the logging primitives. (And the macros use the logging primitives.)
  713. *
  714. * If you find need to manually create logMessage objects, there is one thing you should be aware of:
  715. *
  716. * If no flags are passed, the method expects the file and function parameters to be string literals.
  717. * That is, it expects the given strings to exist for the duration of the object's lifetime,
  718. * and it expects the given strings to be immutable.
  719. * In other words, it does not copy these strings, it simply points to them.
  720. * This is due to the fact that __FILE__ and __FUNCTION__ are usually used to specify these parameters,
  721. * so it makes sense to optimize and skip the unnecessary allocations.
  722. * However, if you need them to be copied you may use the options parameter to specify this.
  723. *
  724. * @param message the message
  725. * @param level the log level
  726. * @param flag the log flag
  727. * @param context the context (if any is defined)
  728. * @param file the current file
  729. * @param function the current function
  730. * @param line the current code line
  731. * @param tag potential tag
  732. * @param options a bitmask which supports AWSDDLogMessageCopyFile and AWSDDLogMessageCopyFunction.
  733. * @param timestamp the log timestamp
  734. *
  735. * @return a new instance of a log message model object
  736. */
  737. - (instancetype)initWithMessage:(NSString *)message
  738. level:(AWSDDLogLevel)level
  739. flag:(AWSDDLogFlag)flag
  740. context:(NSInteger)context
  741. file:(NSString *)file
  742. function:(NSString * __nullable)function
  743. line:(NSUInteger)line
  744. tag:(id __nullable)tag
  745. options:(AWSDDLogMessageOptions)options
  746. timestamp:(NSDate * __nullable)timestamp NS_DESIGNATED_INITIALIZER;
  747. /**
  748. * Read-only properties
  749. **/
  750. /**
  751. * The log message
  752. */
  753. @property (readonly, nonatomic) NSString *message;
  754. @property (readonly, nonatomic) AWSDDLogLevel level;
  755. @property (readonly, nonatomic) AWSDDLogFlag flag;
  756. @property (readonly, nonatomic) NSInteger context;
  757. @property (readonly, nonatomic) NSString *file;
  758. @property (readonly, nonatomic) NSString *fileName;
  759. @property (readonly, nonatomic) NSString * __nullable function;
  760. @property (readonly, nonatomic) NSUInteger line;
  761. @property (readonly, nonatomic) id __nullable tag;
  762. @property (readonly, nonatomic) AWSDDLogMessageOptions options;
  763. @property (readonly, nonatomic) NSDate *timestamp;
  764. @property (readonly, nonatomic) NSString *threadID; // ID as it appears in NSLog calculated from the machThreadID
  765. @property (readonly, nonatomic) NSString *threadName;
  766. @property (readonly, nonatomic) NSString *queueLabel;
  767. @end
  768. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  769. #pragma mark -
  770. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  771. /**
  772. * The `AWSDDLogger` protocol specifies that an optional formatter can be added to a logger.
  773. * Most (but not all) loggers will want to support formatters.
  774. *
  775. * However, writting getters and setters in a thread safe manner,
  776. * while still maintaining maximum speed for the logging process, is a difficult task.
  777. *
  778. * To do it right, the implementation of the getter/setter has strict requiremenets:
  779. * - Must NOT require the `logMessage:` method to acquire a lock.
  780. * - Must NOT require the `logMessage:` method to access an atomic property (also a lock of sorts).
  781. *
  782. * To simplify things, an abstract logger is provided that implements the getter and setter.
  783. *
  784. * Logger implementations may simply extend this class,
  785. * and they can ACCESS THE FORMATTER VARIABLE DIRECTLY from within their `logMessage:` method!
  786. **/
  787. @interface AWSDDAbstractLogger : NSObject <AWSDDLogger>
  788. {
  789. // Direct accessors to be used only for performance
  790. @public
  791. id <AWSDDLogFormatter> _logFormatter;
  792. dispatch_queue_t _loggerQueue;
  793. }
  794. @property (nonatomic, strong, nullable) id <AWSDDLogFormatter> logFormatter;
  795. @property (nonatomic, DISPATCH_QUEUE_REFERENCE_TYPE) dispatch_queue_t loggerQueue;
  796. // For thread-safety assertions
  797. /**
  798. * Return YES if the current logger uses a global queue for logging
  799. */
  800. @property (nonatomic, readonly, getter=isOnGlobalLoggingQueue) BOOL onGlobalLoggingQueue;
  801. /**
  802. * Return YES if the current logger uses the internal designated queue for logging
  803. */
  804. @property (nonatomic, readonly, getter=isOnInternalLoggerQueue) BOOL onInternalLoggerQueue;
  805. @end
  806. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  807. #pragma mark -
  808. ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
  809. @interface AWSDDLoggerInformation : NSObject
  810. @property (nonatomic, readonly) id <AWSDDLogger> logger;
  811. @property (nonatomic, readonly) AWSDDLogLevel level;
  812. + (AWSDDLoggerInformation *)informationWithLogger:(id <AWSDDLogger>)logger
  813. andLevel:(AWSDDLogLevel)level;
  814. @end
  815. NS_ASSUME_NONNULL_END