os_trace(3) Library Functions Manual os_trace(3)

os_trace, os_trace_debug, os_trace_error, os_trace_fault — trace message for the current activity

#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, ...);

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 identifier 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 specifically 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.

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;
}

os_activity_initiate(3), os_log(3)

Please note that os_trace is printf-like, but not printf-compatible. Format specifiers should be exactly matched to the types of the arguments being used to fill them.

June 2, 2016 Darwin