OSLog is a unified logging system for the reading of historical data.

Posts under OSLog tag

40 Posts
Sort by:

Post

Replies

Boosts

Views

Activity

Your Friend the System Log
The unified system log on Apple platforms gets a lot of stick for being ‘too verbose’. I understand that perspective: If you’re used to a traditional Unix-y system log, you might expect to learn something about an issue by manually looking through the log, and the unified system log is way too chatty for that. However, that’s a small price to pay for all its other benefits. This post is my attempt to explain those benefits, broken up into a series of short bullets. Hopefully, by the end, you’ll understand why I’m best friends with the system log, and why you should be too! If you have questions or comments about this, start a new thread and tag it with OSLog so that I see it. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" Your Friend the System Log Apple’s unified system log is very powerful. If you’re writing code for any Apple platform, and especially if you’re working on low-level code, it pays to become friends with the system log! The Benefits of Having a Such Good Friend The public API for logging is fast and full-featured. And it’s particularly nice in Swift. Logging is fast enough to leave log points [1] enabled in your release build, which makes it easier to debug issues that only show up in the field. The system log is used extensively by the OS itself, allowing you to correlate your log entries with the internal state of the system. Log entries persist for a long time, allowing you to investigate an issue that originated well before you noticed it. Log entries are classified by subsystem, category, and type. Each type has a default disposition, which determines whether that log entry is enable and, if it is, whether it persists in the log store. You can customise this, based on the subsystem, category, and type, in four different ways: Install a configuration profile created by Apple (all platforms). Add an OSLogPreferences property to your app’s Info.plist (all platforms). Run the log tool with the config command (macOS only) Create and install a custom configuration profile with the com.apple.system.logging payload (macOS only). When you log a value, you may tag it as private. These values are omitted from the log by default but you can configure the system to include them. For information on how to do that, see Recording Private Data in the System Log. The Console app displays the system log. On the left, select either your local Mac or an attached iOS device. Console can open and work with log snapshots (.logarchive). It also supports surprisingly sophisticated searching. For instructions on how to set up your search, choose Help > Console Help. Console’s search field supports copy and paste. For example, to set up a search for the subsystem com.foo.bar, paste subsystem:com.foo.bar into the field. Console supports saved searches. Again, Console Help has the details. Console supports viewing log entries in a specific timeframe. By default it shows the last 5 minutes. To change this, select an item in the Showing popup menu in the pane divider. If you have a specific time range of interest, select Custom, enter that range, and click Apply. Instruments has os_log and os_signpost instruments that record log entries in your trace. Use this to correlate the output of other instruments with log points in your code. Instruments can also import a log snapshot. Drop a .logarchive file on to Instruments and it’ll import the log into a trace document, then analyse the log with Instruments’ many cool features. The log command-line tool lets you do all of this and more from Terminal. The log stream subcommand supports multiple output formats. The default format includes column headers that describe the standard fields. The last column holds the log message prefixed by various fields. For example: cloudd: (Network) [com.apple.network:connection] nw_flow_disconnected … In this context: cloudd is the source process. (Network) is the source library. If this isn’t present, the log came from the main executable. [com.apple.network:connection] is the subsystem and category. Not all log entries have these. nw_flow_disconnected … is the actual message. There’s a public API to read back existing log entries, albeit one with significant limitations on iOS (more on that below). Every sysdiagnose log includes a snapshot of the system log, which is ideal for debugging hard-to-reproduce problems. For more details on that, see Using a Sysdiagnose Log to Debug a Hard-to-Reproduce Problem. For general information about sysdiagnose logs, see Bug Reporting > Profiles and Logs. But you don’t have to use sysdiagnose logs. To create a quick snapshot of the system log, run the log tool with the collect subcommand. If you’re investigating recent events, use the --last argument to limit its scope. For example, the following creates a snapshot of log entries from the last 5 minutes: % sudo log collect --last 5m For more information, see: os > Logging OSLog log man page os_log man page (in section 3) os_log man page (in section 5) WWDC 2016 Session 721 Unified Logging and Activity Tracing [1] Well, most log points. If you’re logging thousands of entries per second, the very small overhead for these disabled log points add up. Foster Your Friendship Good friendships take some work on your part, and your friendship with the system log is no exception. Follow these suggestions for getting the most out of the system log. The system log has many friends, and it tries to love them the all equally. Don’t abuse that by logging too much. One key benefit of the system log is that log entries persist for a long time, allowing you to debug issues with their roots in the distant past. But there’s a trade off here: The more you log, the shorter the log window, and the harder it is to debug such problems. Put some thought into your subsystem and category choices. One trick here is to use the same category across multiple subsystems, allowing you to track issues as they cross between subsystems in your product. Or use one subsystem with multiple categories, so you can search on the subsystem to see all your logging and then focus on specific categories when you need to. Don’t use too many unique subsystem and context pairs. As a rough guide: One is fine, ten is OK, 100 is too much. Choose your log types wisely. The documentation for each OSLogType value describes the default behaviour of that value; use that information to guide your choices. Remember that disabled log points have a very low cost. It’s fine to leave chatty logging in your product if it’s disabled by default. No Friend Is Perfect The system log API is hard to wrap. The system log is so efficient because it’s deeply integrated with the compiler. If you wrap the system log API, you undermine that efficiency. For example, a wrapper like this is very inefficient: -*-*-*-*-*- DO NOT DO THIS -*-*-*-*-*- void myLog(const char * format, ...) { va_list ap; va_start(ap, format); char * str = NULL; vasprintf(&str, format, ap); os_log_debug(sLog, "%s", str); free(str); va_end(ap); } -*-*-*-*-*- DO NOT DO THIS -*-*-*-*-*- This is mostly an issue with the C API, because the modern Swift API is nice enough that you rarely need to wrap it. If you do wrap the C API, use a macro and have that pass the arguments through to the underlying os_log_xyz macro. iOS has very limited facilities for reading the system log. Currently, an iOS app can only read entries created by that specific process, using .currentProcessIdentifier scope. This is annoying if, say, the app crashed and you want to know what it was doing before the crash. What you need is a way to get all log entries written by your app (r. 57880434). There are two known bugs with the .currentProcessIdentifier scope. The first is that the .reverse option doesn’t work (r. 87622922). You always get log entries in forward order. The second is that the getEntries(with:at:matching:) method doesn’t honour its position argument (r. 87416514). You always get all available log entries. Xcode 15 beta has a shiny new console interface. For the details, watch WWDC 2023 Session 10226 Debug with structured logging. For some other notes about this change, search the Xcode 15 Beta Release Notes for 109380695. In older versions of Xcode the console pane was not a system log client (r. 32863680). Rather, it just collected and displayed stdout and stderr from your process. This approach had a number of consequences: The system log does not, by default, log to stderr. Xcode enabled this by setting an environment variable, OS_ACTIVITY_DT_MODE. The existence and behaviour of this environment variable is an implementation detail and not something that you should rely on. Xcode sets this environment variable when you run your program from Xcode (Product > Run). It can’t set it when you attach to a running process (Debug > Attach to Process). Xcode’s Console pane does not support the sophisticated filtering you’d expect in a system log client. When I can’t use Xcode 15, I work around the last two by ignoring the console pane and instead running Console and viewing my log entries there. If you don’t see the expected log entries in Console, make sure that you have Action > Include Info Messages and Action > Include Debug Messages enabled. The system log interface is available within the kernel but it has some serious limitations. Here’s the ones that I’m aware of: Prior to macOS 14.4, there was no subsystem or category support (r. 28948441). There is no support for annotations like {public} and {private}. Adding such annotations causes the log entry to be dropped (r. 40636781). The system log interface is also available to DriverKit drivers. For more advice on that front, see this thread. Metal shaders can log using the interface described in section 6.19 of the Metal Shading Language Specification. Revision History 2025-02-20 Added some info about DriverKit. 2024-10-22 Added some notes on interpreting the output from log stream. 2024-09-17 The kernel now includes subsystem and category support. 2024-09-16 Added a link to the the Metal logging interface. 2023-10-20 Added some Instruments tidbits. 2023-10-13 Described a second known bug with the .currentProcessIdentifier scope. Added a link to Using a Sysdiagnose Log to Debug a Hard-to-Reproduce Problem. 2023-08-28 Described a known bug with the .reverse option in .currentProcessIdentifier scope. 2023-06-12 Added a call-out to the Xcode 15 Beta Release Notes. 2023-06-06 Updated to reference WWDC 2023 Session 10226. Added some notes about the kernel’s system log support. 2023-03-22 Made some minor editorial changes. 2023-03-13 Reworked the Xcode discussion to mention OS_ACTIVITY_DT_MODE. 2022-10-26 Called out the Showing popup in Console and the --last argument to log collect. 2022-10-06 Added a link WWDC 2016 Session 721 Unified Logging and Activity Tracing. 2022-08-19 Add a link to Recording Private Data in the System Log. 2022-08-11 Added a bunch of hints and tips. 2022-06-23 Added the Foster Your Friendship section. Made other editorial changes. 2022-05-12 First posted.
0
0
8.2k
5d
Change the OSLog level that is written to Xcode console of a dependent library
I'd like to give control to the app developer that uses my library to select which level of logs they'd like to see from my lib (e.g. do they want to see all debug messages or just errors). I know there are filtering controls that Xcode gives us, but I'm wondering if there is a way to pull this off with code. Ideally the user callsite would look like MyLib(logLevel: .info). And then I would pass that info level somehow to OSLog. Today, I create my logger like this: let myLogger = Logger( subsystem: Bundle.main.bundleIdentifier ?? "UnknownApp", category: "MyLibrary" ) As far as I can tell, there is nothing I can then pass to my myLogger instance to configure the threshold level. I'm imagining an interface like: myLogger.logLevel(.warning) // Later... myLogger.debug("You won't see this") myLogger.error("But you will see this") Does OSLog and friends give us any ability to do this out of the box, or are we building little wrappers around OSLog to accomplish this? Thank you, Lou
0
0
132
5d
The options and position arguments do not work in the 'entriesEnumeratorWithOptions:position:predicate:error:' method of the OSLogStore object.
When I set the option parameter to OSLogEnumeratorReverse, the iteration order of OSLogEnumerator is still from front to back in time When I set the options parameter to 0 and the position parameter to the first 5 seconds of the current time, OSLogEnumerator can still iterate over the previous 5 seconds #import "ViewController.h" #import <OSLog/OSLog.h> @interface ViewController () @property(strong, nonatomic)OSLogStore *logStore; @property(strong, nonatomic)NSDateFormatter *formatter; @end @implementation ViewController - (void)viewDidLoad { [super viewDidLoad]; NSError *err = nil; self.logStore = [OSLogStore storeWithScope:OSLogStoreCurrentProcessIdentifier error:&err]; if (!self.logStore || err) { NSLog(@"error: %@", err); NSAssert(0, @""); } self.formatter = [[NSDateFormatter alloc] init]; [self.formatter setDateFormat:@"[yyyy-MM-dd HH:mm:ss:SSS]"]; } - (IBAction)addLog:(id)sender { static int i = 0; NSLog(@"[test] %@ this is a log with index:%d", [self.formatter stringFromDate:[NSDate date]], i++); } - (IBAction)printLogWithReverse:(id)sender { NSError *err = nil; NSPredicate *preeicate = [NSPredicate predicateWithFormat:@"composedMessage contains %@" argumentArray:@[@"[test]"]]; OSLogEnumerator *enumer = [self.logStore entriesEnumeratorWithOptions:OSLogEnumeratorReverse position:nil predicate:preeicate error:&err]; if (err) { NSLog(@"enumer error:%@", err); NSAssert(0, @""); } OSLogEntryLog *entry = nil; while (entry = [enumer nextObject]) { NSString *message = [entry composedMessage]; printf("log: %s\n", message.UTF8String); } } - (IBAction)printLogWithPosition:(id)sender { NSError *err = nil; NSPredicate *preeicate = [NSPredicate predicateWithFormat:@"composedMessage contains %@" argumentArray:@[@"[test]"]]; NSDate *posDate = [NSDate dateWithTimeIntervalSinceNow:-5]; OSLogPosition *pos = [self.logStore positionWithDate:posDate]; OSLogEnumerator *enumer = [self.logStore entriesEnumeratorWithOptions:0 position:pos predicate:preeicate error:&err]; if (err) { NSLog(@"enumer error:%@", err); NSAssert(0, @""); } const char *now = [self.formatter stringFromDate:[NSDate date]].UTF8String; const char *posStart = [self.formatter stringFromDate:posDate].UTF8String; OSLogEntryLog *entry = nil; while (entry = [enumer nextObject]) { NSString *message = [entry composedMessage]; printf("log(now:%s, pos:%s): %s\n", now, posStart, message.UTF8String); } } @end The method of - (IBAction)printLogWithReverse:(id)sender print result not reversed by time. log: [test] [2025-02-18 17:35:50:175] this is a log with index:0 log: [test] [2025-02-18 17:35:51:040] this is a log with index:1 log: [test] [2025-02-18 17:35:51:174] this is a log with index:2 log: [test] [2025-02-18 17:35:51:323] this is a log with index:3 log: [test] [2025-02-18 17:35:51:473] this is a log with index:4 log: [test] [2025-02-18 17:35:51:640] this is a log with index:5 log: [test] [2025-02-18 17:35:51:773] this is a log with index:6 log: [test] [2025-02-18 17:35:51:923] this is a log with index:7 The method of - (IBAction)printLogWithPosition:(id) print result should not contain the log from 5 seconds ago because I set the start time position in the position argument [test] [2025-02-18 17:43:58:741] this is a log with index:0 [test] [2025-02-18 17:43:58:940] this is a log with index:1 [test] [2025-02-18 17:43:59:458] this is a log with index:2 [test] [2025-02-18 17:43:59:923] this is a log with index:3 log(now:[2025-02-18 17:44:51:132], pos:[2025-02-18 17:44:46:032]): [test] [2025-02-18 17:43:58:741] this is a log with index:0 log(now:[2025-02-18 17:44:51:132], pos:[2025-02-18 17:44:46:032]): [test] [2025-02-18 17:43:58:940] this is a log with index:1 log(now:[2025-02-18 17:44:51:132], pos:[2025-02-18 17:44:46:032]): [test] [2025-02-18 17:43:59:458] this is a log with index:2 log(now:[2025-02-18 17:44:51:132], pos:[2025-02-18 17:44:46:032]): [test] [2025-02-18 17:43:59:923] this is a log with index:3
1
0
163
1w
Is there a way to turn off Network Extension Logs?
Hello, I'm developing a Transparent Proxy and I noticed that the Network Extension Framework logs in the Unified Logging System when my profile receives a flow, its source application, its destination endpoint, and my profile's decision regarding that flow. I worry that this may compromise the user's privacy. So is there a way that I can turn off these logs at least in Distribution Configurations?
3
0
215
1w
Copying logs to a syslog/graylog server
Hi: Our group would like to forward logs from our Macs in our integration/production environments to a central server. I haven't found any good documentation for this yet. Can anyone point me to a way to forward to a Graylog or syslog-based server? We're not against cobbling together an app or script using "log stream" to send the info ourselves, but that seems extreme for what I'd think is a very common use case.
1
0
174
2w
Unified Logging System in Go
Hi, I'm developing a multi-platform project in Windows, Mac and Linux. I am trying to create a wrapper class in Go that will query system information and history. I see that the Unified Logging System is a sophisticated way to get all sorts of kernel information (and even a long history including rotated logs). However, I am struggling to see how I can use the APIs in other languages aside from Swift itself (or C). I do not want to use the log or last commands to query information in separate child processes in my project. I would like to simply query the database itself, similar to using OSLog in Swift. If this is something that is entirely proprietary or not possible, let me know :)
4
0
285
3w
Missing logs in OSLogStore
Hello, I need to monitor the device for an activity that is not supported by ES framework. I can reliably monitor it using correct filters with log stream, for example sudo log stream --info --style compact --predicate 'category = "X"' But I need to provide that functionality through my application. Because of that, I made an instance of a log store, hoping I will be able to retrieve the necessary informations that way. The problem is that the messages are sometimes appearing and sometimes not. The log level I am interested in is info, which according to the docs The system stores info-level messages in memory buffers and, without a configuration change, purges the oldest messages as those buffers fill up. If I understand that correctly, the info messages are being written to the buffer and not the store, only sometimes reaching it. But also that should be modifiable with a configuration change? How could I make such change to always save info logs to the store and retrieve them?
1
0
136
3w
OS Logging says developer mode is disabled but its enabled
I'm trying to diagnose an issue with a Message Filtering Extension not working. The associated domain for the server is not currently publicly hosted, so the associated domains specified for the app are postpended with ?mode=developer On application installation I filtered OS logging by the swcd process and saw this logged: debug 08:40:01.125071-0800 swcd Skipping domain vz….qa….cl….ce….com?mode=developer because developer mode is disabled But developer mode IS enabled on the phone (Settings/Privacy &amp; Security/Developer Mode is set to On). Therefore why is swcd saying developer mode is disabled? Is the developer mode mentioned in the documentation not actually the Developer Mode in the iPhone's setting but something else? That wouldn't appear to be the case because the documentation explicitly states "Specifies that only devices in developer mode can access the domain." Full Documentation: https://developer.apple.com/documentation/BundleResources/Entitlements/com.apple.developer.associated-domains If you use a private web server, which is unreachable from the public internet, while developing your app, enable the alternate mode feature to bypass the CDN and connect directly to your server. To do this, add a query string to your associated domains entitlement, as shown in the following example: :?mode= developer Specifies that only devices in developer mode can access the domain. So I've: turned developer mode on for the device have added ?mode=developer to the domain am building/running using a developer certificate. But why does swcd log that developer mode is disabled?
2
0
251
Jan ’25
og/signpost messages lost due to high rates in live mode recording.
I'm getting literally hundreds and hundreds of these lines appearing in the Xcode console when running the app. What's the cause? Too much logging? (if so this didn't used to appear with earlier version of Xcode, I'm currently running Xcode 16.2) How to do this: "set IDELogRedirectionPolicy to oslogToStdio in the environment of the executable." And what does doing that do? <snip> 1 log/signpost messages lost due to high rates in live mode recording. To guarantee delivery of all logs, set IDELogRedirectionPolicy to oslogToStdio in the environment of the executable. 1 log/signpost messages lost due to high rates in live mode recording. To guarantee delivery of all logs, set IDELogRedirectionPolicy to oslogToStdio in the environment of the executable. <snip>
1
0
327
Dec ’24
Adding logging to a SwiftUI View's body var
Pretty sure this is a no-no, but asking just in case there's an easy way to make this work struct DocumentContentView: View { private static let logger = Logger( subsystem: "mySubsystem", category: String(describing: Self.self) ) var body: some View { VStack { Text("Hello") logger.trace("hello") } } } This code generates the following compile error at the logger.trace line buildExpression is unavailable: this expression does not conform to View I suspect every line of the body var (or any @ViewBuilder - designated code?) needs to 'return' a View. Is this correct? or more importantly any work arounds other than putting some/all of the view contents in a. func()?
2
0
644
Dec ’24
Persist OSLog in "Analytics & Improvements"
Hello Apple support, We are trying to figure out how to persist the activity logs and retrieve it. It seems the obvious place to find them is "Analytics &amp; Improvements" in settings. How are the .ips log generated? (OSLog?) What are the conditions for the iOS to store the logs? We are aware of this post, but no info on the storage of logs
4
0
380
Dec ’24
What is all this console spew, and how to manage it?
Something (or a lot) is janky about apps built for "My Mac - designed for iPad." Aside from things just not working, the amount of garbage spewed to the console during debugging is unmanageable. I can't see my own trace statements amongst screens and screens of repetitive nonsense. I right-clicked on it and set it to filter out errors, but I'd like to get notified of legitimate errors. Anyone employing a clever filtering method I'm not aware of?
4
0
404
Dec ’24
Memory leak when using OSLogStore in a loop
Hello, I am currently working on a project that involves periodically querying OSLog to forward system log entries to a backend. While the functionality generally operates as expected, I have encountered a memory leak in my application. Through testing, I have isolated the issue to the following simplified code example: #import <Foundation/Foundation.h> #import <OSLog/OSLog.h> int main(int argc, const char * argv[]) { @autoreleasepool { while(1) { NSError *error = nil; OSLogStore *logStore = [OSLogStore storeWithScope:OSLogStoreSystem error:&error]; if (!logStore) NSLog(@"Failed to create log store: %@", error); sleep(1); } } return 0; } When running this example, the application exhibits increasing memory usage, consuming an additional 100 to 200 KB per iteration, depending on whether the build is Debug or Release. Given that Automatic Reference Counting is enabled, I anticipated that the resources utilized by logStore would be automatically released at the end of each iteration. However, this does not appear to be the case. Am I using the API wrong? I would appreciate any insights or suggestions on how to resolve this issue. Thank you.
2
0
397
Nov ’24
What happened to logging in a Message Filter Extension on iOS 18?
If an app with a Message Filter Extension is run on an iPhone with iOS 18 installed then there's no logging output to the console (using print or NSLog), however there is logging in all previous versions of OS. Being able to view logging at run time for this component is essential as a debugging aid to see, for example, if the extension launches, if a text is handled locally or deferred to the network, to see if there's a network error, to examine the server response etc. Is there a specific reason it was disabled or is it accidental? Thank you
2
0
481
Oct ’24
Metal os_log not working
I wanted to try the new logging feature for Metal but could not get it to work. I modified the PerformingCalculationsOnAGPU example by adding os_log_default.log_debug("Hello thread: %d", index); to log the current thread id. But never saw any messages neither in the console nor in Xcode. I also added the -fmetal-enable-logging flag. I am running the Sequoia release candidate 15.0 (24A335) on M1 Max and Xcode 16.0 (16A242). What am I missing?
2
0
694
Sep ’24
Disable MusicKit logs without disabling manual Logs via Logger()
I want to switch from using print statements to using OSLog because of the filtering options and so on. I am using MusicKit. To mute all the log noise mostly coming from CoreData I pass these arguments on launch: -com.apple.CoreData.SQLDebug 0 -com.apple.CoreData.MigrationDebug 0 -com.apple.CoreData.ConcurrencyDebug 0 -com.apple.CoreData.CloudKitDebug 0 -com.apple.CoreData.Logging.stderr 0 This works for all the Core Data related warnings but I also need such an argument for MusicKit. Setting the environment variable OS_ACTIVITY_MODE to disable hides all the noise but also hides the log statements I sent via Logger().debug() for example. In particular these log messages appear in great quantities. Attempted to register account monitor for types client is not authorized to access: {( "com.apple.account.iTunesStore" )} <ICMonitoredAccountStore: 0x303c5c9f0> Failed to register for account monitoring. err=Error Domain=com.apple.accounts Code=7 "(null)" My application works fine and these log messages mean absolutely nothing to me. These two threads mention a similar problem but can't offer a solution. https://forums.developer.apple.com/forums/thread/720835 https://forums.developer.apple.com/forums/thread/743795 Thank you
2
0
591
Sep ’24
ERROR: Unrecognized attribute string flag '?' in attribute string "T@"NSString",?,R,C" for property debugDescription
Hello, I'm seeing many errors like this in the Xcode debug console when I build and run my app: ERROR: Unrecognized attribute string flag '?' in attribute string "T@"NSString",?,R,C" for property debugDescription The app project makes heavy use of Logger(), and I suspect it is related to that logging in some way, but I haven't been able to narrow down the issue to specific log calls. I have Category, Subsystem and Timestamp enabled in the Xcode console, but none of those are displayed for this output. What causes this? Or how can I better narrow down the source?
4
3
690
2w
How to Set IDEPreferLogStreaming Globally in Xcode 15.4
How do you fix this Xcode error whenever I create a new project it comes back. The fix is to add IDEPreferLogStreaming=YES but it only fixes for the current project. If I create new project it come back which is annoying to every time add it as YES. version: Xcode 15.4 I did try out Set this in Product->Scheme->Edit Scheme->Run->Arguments->Environment Variable IDELogRedirectionPolicy oslogToStdio OS_ACTIVITY_MODE disable For reference : Logging Error: Failed to initialize logging system. Log messages may be missing.? I tried these solutions from here
3
1
2.4k
Jul ’24
About cpu_resource_fatal
PLATFORM AND VERSION iOS Development environment: Xcode 15.0, macOS 14.4.1, Objective-C Run-time configuration: iOS 17.2.1, DESCRIPTION OF PROBLEM What is the general approach to analyzing cpu_resource_fatal.ips? Is there a standard way to analyze it? (Instruments are not available in this analysis, because this is only occurs on the customer's iPhone.) Also, can this file be symbolicate? Attachment file is a sample ips file. FjSoftPhone.cpu_resource_fatal-2024-06-21-150321.ips
1
0
722
Jul ’24