os_trace(3) [mojave man page]
os_trace(3) BSD Library Functions Manual os_trace(3) NAME
os_trace, os_trace_debug, os_trace_error, os_trace_fault -- trace message for the current activity SYNOPSIS
#include <os/trace.h> void os_trace(const char *format, ...); void os_trace_debug(const char *format, ...); void os_trace_error(const char *format, ...); void os_trace_fault(const char *format, ...); DESCRIPTION
This interface is deprecated and replaced by os_log(3). os_trace and its variants use a memory-only buffer to store the provided trace message. Trace messages are correlated based on a new identi- fier assigned when an activity is created by the system, see os_activity_initiate(3). The identifier is automatically carried across GCD and XPC boundaries. This identifier provides a correlation point for intra and inter-process work based on that activity. Trace messages should never be done in tight loops as they may overrun the buffer pushing relevant trace messages out. Loss of those entries reduces the effectiveness of the trace mechanism. The API was designed to prevent strings from being recorded in the buffers for performance and privacy protection. See os_log(3) for string and object support, among other features. The os_trace API set only supports scalar types (float,double, etc.). All unsupported types will emit UNSUP to the trace output. The format string length does not factor into the trace buffer memory, although there is a maximum supported length of 100 characters. Inappropriate use of strings in messages: os_trace("user %s logged in from hostname %s", username, host); Will output: user UNSUP logged in from hostname UNSUP There are four (4) types of trace messages: default, debug, error, and fault. os_trace is a "default" trace message. The default category of messages are always recorded into the memory buffers regardless of the state of the process. Limit use to messages that would help diagnose a failure, crash, etc. os_trace("issue query for record type: %d, timeout: %d", recType, timeout); os_trace_debug is a "debug" trace message. The debug category of messages are only recorded if the process is under a debugger or is specif- ically requested to include debug messages. Debug messages should be used for development use while debugging a problem. os_trace_error is an "error" trace message. The error category of messages should be used when a process encounters a soft-error (i.e., an unexpected error that was successfully avoided). os_trace_fault is a "fault" trace message. The fault category of messages should be used when a process is about to crash or would otherwise crash but recovered. This call causes a collection of all buffers related to activity that triggered the fault. The buffers are analyzed and may be provided in crash/spin reports. EXAMPLES
Example use of trace messages. #include <os/trace.h> #include <pwd.h> uid_t uid; os_trace("looking up user %d", uid); struct passwd *pwd = getpwuid(uid); if (pwd == NULL) { os_trace_error("failed to lookup user %d", uid); return ENOENT; } error = _openPref(pwd->pw_name, pwd->pw_dir); if (error) { os_trace_error("failed to open prefs %d", error); return error; } CAVEATS
Please note that os_trace is printf-like, but not printf-compatible. Format specifiers should be exactly matched to the types of the argu- ments being used to fill them. SEE ALSO
os_log(3), os_log_create(3), os_activity_initiate(3) Darwin June 2, 2016 Darwin
Check Out this Related Man Page
os_log(3) BSD Library Functions Manual os_log(3) NAME
os_log, os_log_info, os_log_debug, os_log_error, os_log_fault -- log a message scoped by the current activity (if present) SYNOPSIS
#include <os/log.h> void os_log(os_log_t log, const char *format, ...); void os_log_info(os_log_t log, const char *format, ...); void os_log_debug(os_log_t log, const char *format, ...); void os_log_error(os_log_t log, const char *format, ...); void os_log_fault(os_log_t log, const char *format, ...); DESCRIPTION
The unified logging system provides a single, efficient, high performance set of APIs for capturing log messages across all levels of the system. This unified system centralizes the storage of log data in memory and in a data store on disk. The system implements global set- tings that govern logging behavior and persistence, while at the same time providing fine-grained control during debugging via the log(1) command-line tool and through the use of custom logging configuration profiles. Log messages are viewed using the Console app in /Applica- tions/Utilities/ and the log(1) command-line tool. Logging and activity tracing are integrated to make problem diagnosis easier. If activ- ity tracing is used while logging, related messages are automatically correlated. The unified logging system considers dynamic strings and complex dynamic objects to be private, and does not collect them automatically. To ensure the privacy of users, it is recommended that log messages consist strictly of static strings and numbers, which are collected automat- ically by the system. In situations where it is necessary to capture a dynamic string, and it would not compromise user privacy, you may explicitly declare the string public by using the public keyword in the log format string. For example, %{public}s. Log arguments can also be specified as private by using the private keyword in the log format string. For example, %{private}d. To format a log message, use a printf(3) format string. You may also use the "%@" format specifier for use with Obj-C/CF/Swift objects, and %.*P which can be used to decode arbitrary binary data. The logging system also supports custom decoding of values by denoting value types inline in the format %{value_type}d. The built-in value type decoders are: Value type Custom specifier Example output BOOL %{BOOL}d YES bool %{bool}d true darwin.errno %{darwin.errno}d [32: Broken pipe] darwin.mode %{darwin.mode}d drwxr-xr-x darwin.signal %{darwin.signal}d [sigsegv: Segmentation Fault] time_t %{time_t}d 2016-01-12 19:41:37 timeval %{timeval}.*P 2016-01-12 19:41:37.774236 timespec %{timespec}.*P 2016-01-12 19:41:37.2382382823 bitrate %{bitrate}d 123 kbps iec-bitrate %{iec-bitrate}d 118 Kibps uuid_t %{uuid_t}.16P 10742E39-0657-41F8-AB99-878C5EC2DCAA sockaddr %{network:sockaddr}.*P fe80::f:86ff:fee9:5c16 in_addr %{network:in_addr}d 127.0.0.1 in6_addr %{network:in6_addr}.16P fe80::f:86ff:fee9:5c16 Use os_log and its variants to log messages to the system datastore based on rules defined by the os_log_t object, see os_log_create(3). Generally, use the OS_LOG_DEFAULT constant to perform logging using the system defined behavior. Create a custom log object when you want to tag messages with a specific subsystem and category for the purpose of filtering, or to customize the logging behavior of your subsystem with a profile for debugging purposes. os_log is a "default" type of log message that always captured in memory or on disk from system. Limit use to messages that would help diag- nose a failure, crash, etc. for production installations. os_log_info is an "info" type of log message used for additional information. Depending on configuration these messages may be enabled and only captured in memory. They can be optionally configured to persist to disk using a profile or via tools. os_log_debug is a "debug" type of log message that is only recorded when it is specifically requested by tools or configured as such. Debug messages should be used for development use, i.e., additional information that is typically only useful during code development. os_log_error is an "error" type of log message that is related to the local process or framework. If a specific os_activity_id_t is present on the thread, that activity will be captured with all messages available and saved as a snapshot of the error event. os_log_fault is a "fault" type of log message that may involve system-services or multiple processes. If a specific os_activity_id_t is present on a thread, that activity will be captured with all messages available from all involved processes and saved as a snapshot of the fault event. EXAMPLES
Example use of log messages. #include <os/log.h> #include <pwd.h> #include <errno.h> int main(int argc, const char * argv[]) { uid_t uid; os_log(OS_LOG_DEFAULT, "Standard log message."); os_log_info(OS_LOG_DEFAULT, "Additional info for troubleshooting."); os_log_debug(OS_LOG_DEFAULT, "Debug level messages."); struct passwd *pwd = getpwuid(uid); if (pwd == NULL) { os_log_error(OS_LOG_DEFAULT, "failed to lookup user %d", uid); return ENOENT; } } SEE ALSO
log(1), os_log_create(3), os_activity_initiate(3) Darwin June 2, 2016 Darwin