XCLogParser

XCLogParser is a CLI tool that parses the SLF serialization format used by Xcode and xcodebuild to store its Build and Test logs (xcactivitylog files).

You can find more information about the format used in the logs here. You can also check Erick Camacho's talk at AltConf 2019 about it.

The tool supports creating reports of different kinds to analyze the content of the logs. XCLogParser can give a lot of insights in regards to build times for every module and file in your project, warnings, errors and unit tests results.

This is an example of a report created from the Build Log of the Kickstarter iOS open source app.

How and Why

XCLogParser is written as a SPM executable and it supports three commands:

1. Dump the contents of an xcactivitylog into a JSON document.
2. Parse the contents of an xcactivitylog into different kind of reports (json, flatJson, summaryJson, chromeTracer, issues and html).
3. Dump the Manifest contents of a LogStoreManifest.plist file into a JSON document.

Depending on your needs, there are various use-cases where XCLogParser can help you:

• Understanding and detailed tracking of build times.
• Automatically retrieve unit test results, warnings and errors.
• Build other developer tools for usage outside Xcode.
• Automatically and continuously data delivery for historic analysis.

Installation

You can compile the executable with the command rake build[debug] or rake build[release] or simply use the Swift Package Manager commands directly. You can also run rake install to install the executable in your /usr/local/bin directory.

Homebrew

$ brew install xclogparser

We are currently working on adding more installation options.

Xcode Integration

You can automate the parsing of xcactivitylog files with a post-scheme build action. In this way, the last build log can be parsed as soon as a build finishes. To do that, open the scheme editor in a project and expand the "Build" panel on the left side. You can then add a new "Post-action" run script and invoke the xclogparser executable with the required parameters:

xclogparser parse --project MyApp --reporter html

This script assumes that the xclogparser executable is installed and present in your PATH.

The run script is executed in a temporary directory by Xcode, so you may find it useful to immediately open the generated output with open MyAppLogs at the end of the script. The Finder will automatically open the output folder after a build completes and you can then view the generated HTML page that contains a nice visualization of your build! ✨

Tips & Tricks

1. Errors thrown in post-action run scripts are silenced, so it could be hard to notice simple mistakes.
2. Since Xcode 11, xcodebuild only generates the .xcactivitylog build logs when the option -resultBundlePath is present. If you're compiling with that command and not with Xcode, be sure to set that option to a valid path ending in .xcresult.
3. Xcode likes to wait for all subprocesses to exit before completing the build. For this reason, you may notice a delayed "Build Succeeded" message if your post-scheme action is taking too long to execute. You can workaround this by offloading the execution to another script in the background and immediately close the input, output and error streams in order to let Xcode and xcodebuild finish cleanly. Create the following launcher script and invoke it from your post-scheme action as follows launcher command-that-parses-the-log-here:

   #!/bin/sh
   
   # The first argument is the directory of the executable you want to run.
   # The following arguments are directly forwarded to the executable.
   # We execute the command in the background and immediately close the input, output
   # and error streams in order to let Xcode and xcodebuild finish cleanly.
   # This is done to prevent Xcode and xcodebuild being stuck in waiting for all
   # subprocesses to end before exiting.
   executable=$1
   shift;
   $executable "$@" <&- >&- 2>&- &
   

4. The post-scheme action is not executed in case the build fails. An undocumented feature in Xcode allows you to execute it even in this case. Set the attribute runPostActionsOnFailure to YES in your scheme's BuildAction as follows:

   <BuildAction buildImplicitDependencies='YES' parallelizeBuildables='YES' runPostActionsOnFailure='YES'>
   

Log Types

Build Logs

The xcactivitylog files are created by Xcode/xcodebuild a few seconds after a build completes. The log is placed in the DerivedData/YourProjectName-UUID/Logs/Build directory. It is a binary file in the SLF format compressed with gzip.

In the same directory, you will find a LogStoreManifest.plist file with the list of xcactivitylog files generated for the project. This file can be monitored in order to get notified every time a new log is ready.

Test Logs

The test logs are created inside the DerivedData/YourProjectName-UUID/Logs/Test directory. Xcode and xcodebuild create different logs. You can find a good description about which ones are created in this blog post.

Features

Dump Command

Dumps the whole content of an xcactivitylog file as JSON document. You can use this command if you want to have a raw but easy to parse representation of a log.

Examples:

xclogparser dump --file path/to/log.xcactivitylog --output activity.json
xclogparser dump --project MyProject --output activity.json --redacted

An example output has been omitted for brevity since it can contain a lot of information regarding a build.

<details> <summary>Available parameters</summary>

| Parameter Name | Description | Required | |-----|---|-----| | --file | The path to the xcactivitylog. | No * | | --project | The name of the project if you don't know the path to the log. The tool will try to find the latest Build log in a folder that starts with that name inside the DerivedData directory. Use --strictProjectName for stricter name matching. | No * | | --workspace | The path to the xcworkspace file if you don't know the path to the log. It will generate the folder name for the project in the DerivedData folder using Xcode's hash algorithm and it will try to locate the latest Build Log inside that directory. | No * | | --xcodeproj | The path to the xcodeproj file if you don't know the path to the log and if the project doesn't have a xcworkspace file. It will generate the folder name for the project in the DerivedData folder using Xcode's hash algorithm and it will try to locate the latest Build Log inside that directory. | No * | | --derived_data | The path to the derived data folder if you are using xcodebuild to build your project with the -derivedDataPath option. | No | | --output | If specified, the JSON file will be written to the given path. If not defined, the command will output to the standard output. | No | | --redacted | If specified, the username will be replaced by the word redacted in the file paths contained in the logs. Useful for privacy reasons but slightly decreases the performance. | No | | --without_build_specific_info | If specified, build specific information will be removed from the logs (for example bolnckhlbzxpxoeyfujluasoupft will be removed from DerivedData/Product-bolnckhlbzxpxoeyfujluasoupft/Build ). Useful for grouping logs by its content. | No | | --strictProjectName | Used in conjunction with --project. If specified, a stricter name matching will be done for the project name. | No |

No *: One of --file, --project, --workspace, --xcodeproj parameters is required.

</details>

Parse Command

Parses the build information from a xcactivitylog and converts it into different representations such as a JSON file, flat JSON file, summary JSON file, issues JSON file, Chrome Tracer file or a static HTML page.

This command supports parsing additional data if some flags are passed to Xcode/xcodebuild:

1. swiftc reported compilation times. For using that feature, you need to build your project with the options -Xfrontend -debug-time-expression-type-checking and -Xfrontend -debug-time-function-bodies.
2. ld64's statistics output. The statistics info can be generated by adding -Xlinker -print_statistics to Xcode's "Other Linker Flags" and it's useful for tracking linking time regression.
3. Clang's time trace data. When the -ftime-trace flag is specified, clang will generate a json tracing file for each translation unit and XCLogParser will collect them and add its data to the parser output.

Examples:

xclogparser parse --project MyApp --reporter json --output build.json
xclogparser parse --file /path/to/log.xcactivitylog --reporter chromeTracer
xclogparser parse --workspace /path/to/MyApp.xcworkspace --derived_data /path/to/custom/DerivedData --reporter html --redacted

Example output available in the reporters section.

<details> <summary>Available parameters</summary>

| Parameter Name | Description | Required | |-----|---|-----| | `--rep