Taking a sample in macOS

If an Omni app becomes unresponsive (“hangs”, “spins”, or “beachballs”), a sample of the app process will help us figure out why. To take a sample, open the Activity Monitor application (from the Utilities folder inside your Applications folder).

1. After opening Activity Monitor, make sure the CPU tab is selected.
2. Select the Omni application from the list. To find it easily, search for it using the search field at the top right.
3. Click the Action pop-up menu (looks like a gear) in the toolbar, then select Sample Process.
4. A new window will open to display the sample. When Activity Monitor finishes sampling, click Save… to save the result as a text file.

Attach this file to a message to our support team describing what you did directly before the app locked up, and we’ll do the rest!

What’s In a Sample?

An Activity Monitor sample is a brief snapshot of everything an application is doing at that particular moment. When this snapshot wraps up, the resulting text file will display a few different things.

First, the header will state how many samples were taken, over how many seconds. It will also report some information about the application—like its location on your computer and version—as well as which OS you’re running.

The second section is a call graph, show what functions the target application was running at the time, and how many times they were run over the duration of the sample. The final section will show a list of all the frameworks your software uses. Frameworks are small sections of code shared between apps that can help perform common tasks.

So what’s this all mean? Tough to say, to the untrained eye! In many cases that snapshot will look pretty boring—our app is listening to the operating system, or the user interface might be doing its own thing. During a hang, we may be able to pinpoint the cause of a problem by isolating a particular function that’s getting stuck. Figuring all this out will be our job, though.

Does This Sample Contain Any Information About Me?

The only personal information that’d be included in such a report would be the Path for your application. If you’d like, you can check this for yourself before sending in the sample by looking at the information in the first few rows of the sample, before the call graph. The path will most likely be rather benign, like:

/Applications/OmniFocus.app/Contents/MacOS/OmniFocus

…which obviously doesn’t contain any information about you. If you have the app installed in a custom location on your system, like a folder called Bob's Ultimate Weapon Blueprints, the path would reveal the name of this folder. In that case, consider first moving the application to another directory, or renaming the directory. (Or, you know, not creating an ultimate weapon.)