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).
Metal shaders can log using the interface described in section 6.19 of the Metal Shading Language Specification.
Revision History
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.
OSLog
RSS for tagOSLog is a unified logging system for the reading of historical data.
Posts under OSLog tag
42 Posts
Sort by:
Post
Replies
Boosts
Views
Activity
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
Requirement:- Crash my MacOs laptop such that my crashes get collected in the /Library/Logs/DiagnosticReports folders. But the crash shouldn't hamper my laptop's performace.
I read that we had an approach to cause a kernel panic, but I'm really concerned about the state that this would put my device in. Any advice would be helpful, thanks.
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?
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
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?
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
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
I installed Xcode 16 beta on Sonoma 14.5 and tried to run my app on the simulator, but it's practically impossible to use. It's extremely slow and unresponsive.
After doing some research, I noticed that launching any application causes the simulator to flood the system with logs. This triggers the diagnosticd process, which increases memory and CPU usage, worsening over time. The memory usage peaked at 10GB before I decided to close the simulator.
Has anyone else experienced this issue? Is there any solution for this?
I've read the definitive "Recording Private Data in the System Log" by @eskimo and the words at man 5 os_log and written code to, specifically, turn on "Enable-Private-Data" in my app.
My application is a command line and I've configured Xcode to insert what I believe to be the appropriate incantations in an Info.plist file into the unstructured executable binary. When I run the app with Terminal, I see <private> output in the Console app where I expect values to be displayed in a public manner.
Nothing I've read says that <key>Enable-Private-Data</key><true/> doesn't apply to command line apps, and my own understanding of the value of of the logging mechanism rejects that notion because logging is performed all over macOS, not just in a ***.app environment.
A this point, I'm firmly convinced this unexpected behavior is of my own doing, but I have paused the search for my (probably embarrassing) mistake, to write this note because of a 1% doubt I'm wrong.
I'd be very happy to receive the, expected, assurance that logging configuration via an embedded Info.plist in a command line app does influence logging behavior. With that assurance, I'll know it's my problem and I'll search/find/fix. On there way there, I'll create the simplest command line app that exhibits this anomaly -- which will likely reveal my error and, if not, it'll be fodder for a bug report.
Embedding an Info.plist into a command line app is a tad out of the ordinary but I've done it before (using Xcode or SPM) to carry knowledge into a CLI via a mainBundle.infoDictionary .. and in the particular case described above, I've printed that infoDictionary to show the successful embedding, viz:
. . . .
"OSLogPreferences": {
"com.ramsaycons" = {
"DEFAULT-OPTIONS" = {
"Enable-Private-Data" = 1;
};
};
},
. . . .
Sonoma 14.5 / Xcode 15.4 / MBP (Apple M1 Max)
with the latest Xcode that runs with Mac OS 14.5 Developer Beta has messages with a time and date in them There are also some other fields of an indeterminate origin/type.
"2024-05-06 15:37:32.383996-0500 RoomPlanExampleApp[24190:1708576] [CAMetalLayerDrawable texture] should not be called after already presenting this drawable. Get a nextDrawable instead."
specifically I need to know how the string [24190:1708576] relates to a location in my application so I can act on the message. I certainly can't find the text in the "[CAMetalLayerDrawable texture]". field anywhere in the user documentation OR the Development documentation. In order for a diagnostic message to be Actionable and remedied by a user it must identify the module and source line of the initiating code and there must be accessible documentation for users to access to get an explanation of potential remedies.. This interface fails to supply enough information to diagnose the problem. The label in [CAMetalLayerDrawable texture] cannot even be found in a search of the package information attached to the Xcode Release paired with the IOS and Mac OS system releases.
Hello,
I use Preview to quickly test functionalities. However I found that the unified logging does not output to Preview console. So I had to do both log.debug and print. Is there a way to enable logging to Preview console?
To help with debugging on a customers machine, this terminal command records log entries for my app and writes 'em to disk.
log stream --predicate 'process=="Sleep Aid"' --style compact > ~/Desktop/Sleep\ Aid.log
In my app I have a function that does something similar to the above with a NSTask, and then I ask the customer to repeat the action that causes the problem. However for one customer, the file is created, but apart from it saying it's being filter by process, nothing else is written.
Is there some new security setting that can prevent an app from getting its own logging data, or in this case even prevent the customer from using terminal and the above command to get the log data?
This is similar also.
https://forums.developer.apple.com/forums/thread/743803
Or should I be filing a radar about a potential bug?
I have read several times
https://developer.apple.com/forums/thread/705868
https://developer.apple.com/forums/thread/705810
https://developer.apple.com/documentation/os/logging/generating_log_messages_from_your_code#3665948
From what I understand code like this:
import SwiftUI
import OSLog
struct ContentView: View {
private static let logger = Logger(subsystem: "HCP", category: "ContentView")
var myprivateData: Date { Date() }
var myprivateData2: String { "bank-account-111-222-333" }
let myprivateData3: String = "bank-account-111-222-333"
var body: some View {
VStack {
Image(systemName: "globe")
.imageScale(.large)
.foregroundStyle(.tint)
Text("Hello, world!")
}
.padding()
.onAppear(perform: {
Self.logger.info("test info")
Self.logger.info("test info \(myprivateData)")
Self.logger.info("test info \(myprivateData2)")
Self.logger.info("test info \(myprivateData3)")
Self.logger.info("test info")
Self.logger.info("test info \(myprivateData, privacy: .private)")
Self.logger.info("test info \(myprivateData2, privacy: .private)")
Self.logger.info("test info \(myprivateData3, privacy: .private)")
})
}
}
Should result in somewhat redacted log messages, so my expectation would be that dynamic strings
Self.logger.info("test info1")
Self.logger.info("test info2 \(myprivateData)")
Self.logger.info("test info3 \(myprivateData2)")
Self.logger.info("test info4 \(myprivateData3)")
would result in logs like:
info 21:29:07.877698+0200 TestOsLogger test info1
info 21:29:07.877757+0200 TestOsLogger test info2 <private>
info 21:29:07.877800+0200 TestOsLogger test info3 <private>
info 21:29:07.877835+0200 TestOsLogger test info4 <private>
instead I get
info 21:29:07.874356+0200 TestOsLogger test info1
info 21:29:07.877531+0200 TestOsLogger test info2 <private>
info 21:29:07.877615+0200 TestOsLogger test info3 bank-account-111-222-333
info 21:29:07.877656+0200 TestOsLogger test info4 bank-account-111-222-333
where clearly date object got redacted, but string not really.
Adding privacy: .private helps here, but it is still a different behavior from what I expected after reading docs.
Is that a change or rather my misunderstanding? Eskimo for the rescue?
Since MacOS 14.4 I've been having trouble seeing logs emitted from my applications with oslog. For example:
#import <Foundation/Foundation.h>
#include <os/log.h>
int main(int argc, const char * argv[]) {
@autoreleasepool {
os_log_error(OS_LOG_DEFAULT, "Hello World!");
}
return 0;
}
When I compile and run this in Xcode I do see the log message in Xcode itself. But I'm not able to see anything with log stream --source --predicate "eventMessage contains 'Hello'" or the Console.app if I run the same program in Xcode or outside. I do see logs from other applications on the same machine so it's not completely down.
Any suggestions on how to debug this? Perhaps something missing in the project that would "enable" logging?
My requirement is here-
1- We need to implement functionality in my iOS app to do call (cellular call) without user interaction.
2- We need to implement functionality in my iOS app to send normal message to particular phone number without user interaction.
3- Fetch OS log (NOT MY APPLICATION LOG). we need to fetch OS log when cellular call going on in device this log need to collect in my iOS app for identify the network strength and other things like call is connected and disconnect etc. Thanks
I have an iOS app that uses os_signpost API for instrumentation.
When I profile it from Xcode on real iOS device, it works as expected.
When I profile its macCatalyst variant (using the identical code) on the same Mac where Xcode is running, the os_signpost Instrument does not show anything, not even the Apple provided signposts that are otherwise visible on the iOS.
How do I make it work?
The new Xcode 15.3 Release Candidate produces errors with strict concurrency checking that the usual pattern of using OSLog with a static property like static let logger = Logger(...) is not safe.
"Static property 'logger' is not concurrency-safe because it is not either conforming to 'Sendable' or isolated to a global actor; this is an error in Swift 6"
Is Logger thread safe and just not marked Sendable? Would it be "safe" to use nonisolated(unsafe) static let logger = Logger(...)?
I am using sudo log collect --device-udid {device-udid} --last 7m command to collect console.app logs .
But it seems only info and error logs are getting collected in logarchive file even though I can se debug level logs getting printed in console.app .
How we can change the level to collect debug level logs as well from console app.
Options log collect command have -:
--device Collect logs from first device found
--device-name Collect logs from device with the given name
--device-udid Collect logs from device with the given UDID
--last [m|h|d] Collect logs starting [m|h|d] ago
-output Output log archive to the given path
--size [k|m] Limit log collection to the given size
--start Collect logs starting at the given time
There is no way to provide debug level in command .
I've encountered an issue while reviewing logs from my device and hope someone here can shed some light on it. In the process of diagnosing an application behavior, I noticed that some entries in my logs are marked as , specifically next to bundle IDs, which makes it challenging to understand which app or process is involved.
Here are the relevant log entries:
Feb 21 17:40:53 vCw-2 suggestd(CoreSuggestionsInternals)[30399] <Notice>: SGDSuggestManager: realtimeSuggestionsForMailOrMessageWithHash: com.apple.MobileSMS : <private>
Feb 21 17:40:53 vCw-2 suggestd(CoreSuggestionsInternals)[30399] <Notice>: SGDSuggestManager: realtimeSuggestionsForMailOrMessageWithHash: <private>: results: (null)
Feb 21 17:40:53 vCw-2 suggestd(CoreSuggestionsInternals)[30399] <Notice>: SGDSuggestManager: realtimeSuggestionsForMailOrMessageWithHash: com.apple.MobileSMS : <private>
Feb 21 17:40:53 vCw-2 suggestd(CoreSuggestionsInternals)[30399] <Notice>: SGDSuggestManager: starting dissection.
The identification of this hidden bundle ID is essential for allowing the specific iMessage Business Chat feature to function as intended in our MDM-managed devices.
Does anyone have insights into why the bundle ID might be hidden or how to uncover it? Are there tools or methods available that could help me identify this bundle ID for MDM whitelist configuration purposes?
I appreciate any guidance or recommendations you can provide. Thank you for your time and assistance.
Background
I have a SwiftUI app that uses OSLog and the new Logger framework. In my SwiftUI views, I would like to use something like Self._logChanges() to help debug issues.
After some trial and error, I can see the messages appear in the System console log for the app I am debugging using the com.apple.SwiftUI subsystem.
Problem
I'd like to see those same messages directly in Xcode's console window so I can filter them as needed. How do I do that?
Thanks! -Patrick