logdump(1) BSD General Commands Manual logdump(1)
NAME
logdump -- is used to dump .logarchives collected by sysdiagnose.
SYNOPSIS
logdump help | -h
logdump --archive path | --file path [--filter query] [--v | ---verbose]
[--source] [--style json|syslog]
DESCRIPTION
logdump is used to display the contents of system_logs.logarchive or
.tracev3 files.
Available options:
--archive path Pass the path to a .logarchive directory. If the archive
is from a newer system version, logdump will exit with
EX_DATAERR (65) and an error will be printed.
--file path Pass the path to a specific logdata.tracev3 file. If the
file is from a newer system version, logdump will exit
with EX_DATAERR (65) and an error will be printed.
--filter query Stream will filter messages based on the provided
(required) query argument. See section "FILTERING"
below.
--source Include symbol names and source line numbers for mes-
sages
--style style Output the content as a different style (i.e., json,
syslog). Using the type "raw" will dump only high-level
details.
FILTERING
Filtering via the --filter query option allows users to focus on messages
based on the provided query criteria. The query argument defines one or
more key/pattern clauses with the form 'type:"pattern"[,type:"pat-
tern"...]' (additional clauses separated by commas) where pattern is an
extended regular expression (see regex(3)) and type is one of the follow-
ing:
category Matches pattern with the specified category of the trace
entry. Only works with trace messages from the os_log(3)
APIs.
message Matches pattern with the message text, activity name, or user
action name of a log/trace entry.
process Matches pattern with the name of the process that originated
the log/trace entry.
sender Matches pattern with the name of the sender that originated
the log/trace entry. This could be a specific library,
framework, kext, or any valid mach-o that is executed.
subsystem Matches pattern with the specified subsystem of the trace
entry. Only works with trace messages from the os_log(3)
APIs.
In addition to multiple clauses per --filter query argument, more than
one --filter query argument may be provided. Clauses within an individual
--filter query argument will be joined using a logical AND, while multi-
ple --filter query arguments will be joined using a logical OR. Thus, the
following example:
logdump --filter 'process:"my_process",message:"unexpected"'
would result in logdump only displaying messages from the process named
"my_process" AND whose message text contained "unexpected", while the
following example
logdump --filter 'process:"my_process"' -filter 'message:"unexpected"'
would result in logdump only displaying messages from the process named
"my_process" OR those whose message text contained either "Error" or
"error".
ADDITIONAL FILTERING EXAMPLES
In order to filter os_log(3) messages from a specific subsystem, the fil-
ter query would look like this:
logdump --filter 'subsystem:"com.your_domain.your_subsystem_name"'
To filter a specific category of os_log(3) messages from that subsystem,
an additional query clause would be added, thus:
logdump --filter 'subsystem:"com.your_domain.your_subsystem_name",category:"desired_category"'
To further narrow down this filter to select only messages from that sub-
system and category containing the word "error":
logdump --filter 'subsystem:"com.your_domain.your_subsystem_name",category:"desired_category",message:"error"'
To filter messages from either of two categories from a single subsystem
will require passing two filter arguments:
logdump --filter 'subsystem:"com.your_domain.your_subsystem_name",category:"desired_category_1"' \
--filter 'subsystem:"com.your_domain.your_subsystem_name",category:"desired_category_2"'
or using a more complicated regex pattern, thus:
logdump --filter 'subsystem:"com.your_domain.your_subsystem_name",category:"(desired_category_1|desired_category_2)"'
would result in logdump only displaying messages from the process named
"my_process" OR those whose message text contained "unexpected".
NOTE: To avoid shell expansion of special characters in the regex(3) pat-
tern, query arguments must be enclosed in single quotes.
To filter messages from a single process:
logdump --filter 'process:"process_name"'
To filter messages from a single process OR messages containing the key-
word ALERT:
logdump --filter 'process:"process_name"' --filter 'message:"ALERT"'
To filter messages pertaining to the creation of an activity (see
os_activity_initiate(3)):
logdump --filter 'message:"activity_description"'
SEE ALSO
os_trace(3), os_log(3), os_activity_initiate(3), log(1), regex(3)
Darwin October 29, 2017 Darwin
Mac OS X 10.12.6 - Generated Sun Oct 29 07:46:03 CDT 2017