This document illustrates how XCMetrics manages the logs on the machine where builds are performed. The goal of XCMetrics (the tool being executed in a post-action scheme) is to fetch logs from Xcode’s directory, cache them and perform the upload to the backend service for later parsing and processing.
In order not to interfere with Xcode’s build logs directory (
~/Library/Developer/Xcode/DerivedData/ProjectName-svojrqwbcsautrwqbobafsapoqwe/Logs/Build/), we copy the logs to a separate cache directory that we can completely manage ourselves.
The directory is
~/Library/Caches/xcmetrics, where logs are placed in different namespaced directories based on the criteria described below. This is a possible layout of the cache directory:
│ ├── 0A391ECA-8B35-4E81-865E-FB6D43861384.xcactivitylog
│ ├── 8F069C22-27FA-4479-AF3C-9674677FC20D_UPLOADED.xcactivitylog
│ └── requests/
│ └── 814B2B39-1E50-4953-992C-AE94982D5B9A
Let’s break it down:
- At the top level, we have a directory for each project. If this directory doesn’t exist, for example the first time
XCMetricsis run in a new project, it will be automatically created. This allows XCMetrics to be used in multiple projects on the same machine, and avoid logs to conflict with each other.
- Logs are copied from Xcode’s directory to the project directory. If a log has been successfully uploaded on the first try,
_UPLOADEDwill be appended to its file name. This is done in order to keep track which logs have been cached already.
- If a log fails to upload (i.e: the backend service is not reachable), the request is written to the
requestsdirectory as a binary object containing the log itself along with all the metadata collected for that build. The original
xcactivitylogis renamed with
_UPLOADEDand then the request object will be automatically retried on the next run.
The following diagram better illustrates the flow of all the steps.
Xcode sometimes takes a few seconds to write the full log to disk, so XCMetrics can optionally wait for some time in order to always try and fetch the latest log (use the argument
--timeout to customize this behavior).
The following GIF shows the behavior when the upload is successful. As you can see, the log is cached in the
XCMetrics directory and marked as uploaded.
In case internet connectivity is absent or some other during the upload occurs, the log is marked as uploaded and cached offline for retry during the next run.