macOS ULS (im_maculs)
This module natively collects Apple logs from Apple’s unified logging system (ULS) on macOS. ULS logs are typically used for application debugging and performance analysis. ULS logs are also available on iOS, tvOS, and watchOS. See Apple’s Logging documentation for more information.
The im_maculs module supports the following chunk tags as described in this open source project.
Value | Identifier |
---|---|
0x1000 |
Header |
0x6001 |
Firehose |
0x6002 |
Oversize |
0x6003 |
StateDump |
0x600b |
Catalog |
0x600d |
ChunkSet |
0x6004 |
SimpleDump |
The im_maculs module is only available on macOS 10.12 and later. |
Logs from Apple’s unified logging system (ULS) are stored in a proprietary undocumented format. As a result, some fields might not be parsed by the module, leading to missing data in the output. To display a corresponding message when an unrecognized message is encountered, use the PrintDiagnosticErrors directive. |
Configuration
The im_maculs module accepts the following directives in addition to the common module directives.
Optional directives
Specifies the maximum number of simultaneously opened file descriptors. It does not affect the amount of data kept in memory. For optimum efficiency, it is recommended to use at least 20 active files (the default value). The minimum supported value is 2. |
|||||||||||||||||||||||||||||||||||||||
Specifies the maximum size of cache for |
|||||||||||||||||||||||||||||||||||||||
This boolean directive defaults to |
|||||||||||||||||||||||||||||||||||||||
Specifies how frequently, in seconds, the module will check the monitored directory for new files.
The default value is |
|||||||||||||||||||||||||||||||||||||||
Specifies in seconds how often to check for new log entries.
Fractional values are allowed. The default value is |
|||||||||||||||||||||||||||||||||||||||
This optional boolean directive instructs the module to only read logs that arrive after NXLog Agent is started.
This directive comes into effect if a saved position is not found, for example on the first start, or when the SavePos directive is The following matrix shows the outcome of this directive in conjunction with the SavePos directive:
|
|||||||||||||||||||||||||||||||||||||||
This optional directive specifies whether diagnostic messages should be printed.
This directive is useful for troubleshooting missing data in the output due to unrecognized input data.
If this directive is not specified, it defaults to |
|||||||||||||||||||||||||||||||||||||||
If this boolean directive is set to
|
|||||||||||||||||||||||||||||||||||||||
This optional directive specifies the root path of |
|||||||||||||||||||||||||||||||||||||||
This optional directive specifies root path of |
|||||||||||||||||||||||||||||||||||||||
This optional directive specifies the root path of |
Fields
The following fields are used by im_maculs.
$raw_event
(type: string)-
A list of event fields in key-value pairs.
$activityIdentifier
(type: integer)-
A numeric ID for an activity.
$bootUUID
(type: string)-
The boot UUID of the event.
$category
(type: string)-
The category used to log an event. Only works with log messages generated with os_log(3) APIs.
$eventMessage
(type: string)-
The message for that log entry.
$EventTime
(type: datetime)-
The date and time of the event.
$eventType
(type: string)-
The type of event: logEvent, signpostEvent or stateEvent.
$formatString
(type: string)-
This gives the format string used to convert variable content into a string for output.
$machTimestamp
(type: string)-
The number of Mach system clock ticks, which is effectively elapsed nanoseconds.
$messageType
(type: string)-
Type of the logged message e.g. Default, Info, Activity, Debug, Error, Fault and Loss.
$parentActivityIdentifier
(type: integer)-
A numeric ID for the parent activity.
$processID
(type: integer)-
The ID of the process that originated the event.
$processImagePath
(type: string)-
The full path of the process that originated the event.
$processImageUUID
(type: string)-
The UUID of the process that originated the event.
$senderImagePath
(type: string)-
The full path of the library, framework, kernel extension, or mach-o image, that originated the event.
$senderImageUUID
(type: string)-
The UUID of the library, framework, kernel extension, or mach-o image, that originated the event.
$senderProgramCounter
(type: integer)-
The program counter of the library, framework, kernel extension, or mach-o image, that originated the event.
$signpostID
(type: string)-
A numeric ID for a Signpost.
$signpostName
(type: string)-
A string name for a Signpost.
$signpostScope
(type: string)-
A Signpost scope string, such as
thread
,process
orsystem
.
$signpostType
(type: string)-
The Signpost type:
begin
,end
, orevent
.
$subsystem
(type: string)-
The subsystem used to log an event. Only works with log messages generated with os_log(3) APIs.
$threadID
(type: string)-
The ID of the thread that originated the event.
$traceID
(type: string)-
The ID of a trace event
$TTL
(type: integer)-
The time-to-live (TTL) of the log message.
Examples
With this configuration, NXLog Agent will collect all available ULS logs from hundreds of log sources.
<Input in>
Module im_maculs
UUIDTextPath "/var/db/uuidtext"
TimeSyncPath "/var/db/diagnostics/timesync"
TraceV3Path "/var/db/diagnostics"
Caching TRUE
CacheSize 256M
PollInterval 1.0
DirCheckInterval 2.0
ActiveFiles 20
SavePos FALSE
ReadFromLast FALSE
</Input>