Inherits from NSObject
Conforms to DDLogFormatter
Declared in DDDispatchQueueLogFormatter.h

Overview

This class provides a log formatter that prints the dispatch_queue label instead of the mach_thread_id.

A log formatter can be added to any logger to format and/or filter its output. You can learn more about log formatters here: Documentation/CustomFormatters.md

A typical NSLog (or DDTTYLogger) prints detailed info as [<process_id>:<thread_id>]. For example:

2011-10-17 20:21:45.435 AppName[19928:5207] Your log message here

Where: - 19928 = process id - 5207 = thread id (mach_thread_id printed in hex)

When using grand central dispatch (GCD), this information is less useful. This is because a single serial dispatch queue may be run on any thread from an internally managed thread pool. For example:

2011-10-17 20:32:31.111 AppName[19954:4d07] Message from my_serial_dispatch_queue 2011-10-17 20:32:31.112 AppName[19954:5207] Message from my_serial_dispatch_queue 2011-10-17 20:32:31.113 AppName[19954:2c55] Message from my_serial_dispatch_queue

This formatter allows you to replace the standard [box:info] with the dispatch_queue name. For example:

2011-10-17 20:32:31.111 AppName[img-scaling] Message from my_serial_dispatch_queue 2011-10-17 20:32:31.112 AppName[img-scaling] Message from my_serial_dispatch_queue 2011-10-17 20:32:31.113 AppName[img-scaling] Message from my_serial_dispatch_queue

If the dispatch_queue doesn’t have a set name, then it falls back to the thread name. If the current thread doesn’t have a set name, then it falls back to the mach_thread_id in hex (like normal).

Note: If manually creating your own background threads (via NSThread/alloc/init or NSThread/detachNeThread), you can use [[NSThread currentThread] setName:(NSString *)].

Method declarations that make it easier to extend/modify DDDispatchQueueLogFormatter

Tasks

Other Methods

  • – init

    Standard init method. Configure using properties as desired.

  •   minQueueLength

    The minQueueLength restricts the minimum size of the [detail box]. If the minQueueLength is set to 0, there is no restriction.

    property
  •   maxQueueLength

    The maxQueueLength restricts the number of characters that will be inside the [detail box]. If the maxQueueLength is 0, there is no restriction.

    property
  • – replacementStringForQueueLabel:

    Sometimes queue labels have long names like “com.apple.main-queue”, but you’d prefer something shorter like simply “main”.

  • – setReplacementString:forQueueLabel:

OverridableMethods Methods

Properties

maxQueueLength

@property (assign, atomic) NSUInteger maxQueueLength
Discussion

The maxQueueLength restricts the number of characters that will be inside the [detail box]. If the maxQueueLength is 0, there is no restriction.

For example, say a dispatch_queue has a label of “diskIO”:

If the maxQueueLength is 0: [diskIO] If the maxQueueLength is 4: [disk] If the maxQueueLength is 5: [diskI] If the maxQueueLength is 6: [diskIO] If the maxQueueLength is 7: [diskIO] If the maxQueueLength is 8: [diskIO]

The default maxQueueLength is 0 (no maximum, so [detail box] won’t be truncated).

If you want every [detail box] to have the exact same width, set both minQueueLength and maxQueueLength to the same value.

Declared In

DDDispatchQueueLogFormatter.h

minQueueLength

@property (assign, atomic) NSUInteger minQueueLength
Discussion

The minQueueLength restricts the minimum size of the [detail box]. If the minQueueLength is set to 0, there is no restriction.

For example, say a dispatch_queue has a label of “diskIO”:

If the minQueueLength is 0: [diskIO] If the minQueueLength is 4: [diskIO] If the minQueueLength is 5: [diskIO] If the minQueueLength is 6: [diskIO] If the minQueueLength is 7: [diskIO ] If the minQueueLength is 8: [diskIO ]

The default minQueueLength is 0 (no minimum, so [detail box] won’t be padded).

If you want every [detail box] to have the exact same width, set both minQueueLength and maxQueueLength to the same value.

Declared In

DDDispatchQueueLogFormatter.h

Instance Methods

formatLogMessage:

- (NSString *)formatLogMessage:(DDLogMessage *)logMessage
Discussion

Formatters may optionally be added to any logger. This allows for increased flexibility in the logging environment. For example, log messages for log files may be formatted differently than log messages for the console.

For more information about formatters, see the “Custom Formatters” page: Documentation/CustomFormatters.md

The formatter may also optionally filter the log message by returning nil, in which case the logger will not log the message.

Declared In

DDLog.h

init

- (instancetype)init
Discussion

Standard init method. Configure using properties as desired.

Declared In

DDDispatchQueueLogFormatter.h

queueThreadLabelForLogMessage:

- (NSString *)queueThreadLabelForLogMessage:(DDLogMessage *)logMessage

replacementStringForQueueLabel:

- (NSString *)replacementStringForQueueLabel:(NSString *)longLabel
Discussion

Sometimes queue labels have long names like “com.apple.main-queue”, but you’d prefer something shorter like simply “main”.

This method allows you to set such preferred replacements. The above example is set by default.

To remove/undo a previous replacement, invoke this method with nil for the ‘shortLabel’ parameter.

Declared In

DDDispatchQueueLogFormatter.h

setReplacementString:forQueueLabel:

- (void)setReplacementString:(NSString *)shortLabel forQueueLabel:(NSString *)longLabel

stringFromDate:

- (NSString *)stringFromDate:(NSDate *)date