Swiftpack.co - Package - bitrise-io/trace-cocoa-sdk

Trace SDK

Bitrise statusCocoapodsCocoapods platformsMac CatalystCocoapodsCarthageSwift versionSPMTwitter URLJoin Slack groupBCH compliance

Catch bugs before they reach production — get detailed crash reports and monitor how your app is performing across the entire install base. When issues are detected we show you exactly what happened during the user session to locate, reproduce, and fix the problem as quickly as possible. Use Trace to:

  • Detect the problem: Know about issues before your users report them.
  • Assess the impact: Focus on resolving the issues which are most impactful to your users.
  • Trace the cause: Spend less time trying to reproduce issues.

Note: Following links requires the user to be signed-in and have the Trace addon

* Trace * Getting started guide * Trace configuration settings

Requirements

  • iOS 10.0+
  • Xcode 12.2+
  • Swift 5.3

Installation

Trace SDK doesn't contain any external dependencies but does depend on a few system frameworks such as:

  • SystemConfiguration.framework
  • libc++.tbd
  • libz.tbd

Each framework can be easier found in Xcode's framework list. These are currently the supported integration options:

Bitrise Workflow

Install from Bitrise workflow step site

Use Add trace SDK step to add the SDK to your project automatically. All the downloads, linking SDK and supporting system framework and libraries are done for you. The step must come before the Xcode Archive & Export step.

Install directly from the source code

Add the following step inside your bitrise.yml file if the step project is in your repo folder

- path::./step/:
    title: Add Trace SDK to Xcode project
    inputs:
    - lib_version: "latest"

If your using GIT use the following:

- git::https://github.com/bitrise-steplib/bitrise-step-add-trace-sdk.git@master:
    title: Add Trace SDK to Xcode project
    inputs:
    - lib_version: "latest"

CocoaPods

Optional: Setup pod

$ pod init

Add Trace SDK to the Podfile

# Podfile

target 'YOUR_TARGET_NAME' do
    pod 'BitriseTrace'
end

Replace YOUR_TARGET_NAME and then, in the Podfile directory, type:

$ pod install

Now that the SDK is set up in your workspace, add the collector token (bitrise_configuration.plist) found in the setting page or getting started page. Make sure this file is added to your application target.

Carthage

Add this to your Cartfile

github "bitrise-io/trace-cocoa-sdk"
$ carthage update

Once you have included the library in your Xcode project:

  • Select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar.
  • In the tab bar at the top of that window, open the "Build Settings" panel.
  • Search for Other Linker Flags or OTHER_LDFLAGS and enter -force_load '$(BUILT_PRODUCTS_DIR)/libTrace.a'
  • And that's it!

Carthage as a Static Library

Carthage defaults to building Trace as a Dynamic Library.

If you wish to build Trace as a Static Library using Carthage you may use the script below to manually modify the framework type before building with Carthage:

carthage update `Trace` --platform iOS --no-build
sed -i -e 's/MACH_O_TYPE = mh_dylib/MACH_O_TYPE = staticlib/g' Carthage/Checkouts/Trace/Trace.xcodeproj/project.pbxproj
trace build Trace --platform iOS

Swift Package Manager (iOS and Mac Catalyst compatible)

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler.

Add the library to your project using one of the following methods:

Using Package.swift with Swift CLI

dependencies: [
    .package(url: "https://github.com/bitrise-io/trace-cocoa-sdk.git", .upToNextMajor(from: "1.7.0"))
]

Add Trace SDK as a dependency inside your Package.swift file. Please look at the release section for the latest stable version of the SDK.

Using Xcode Swift package manager integration To add a package dependency to your Xcode project/workspace, select File > Swift Packages > Add Package Dependency and enter the repository URL https://github.com/bitrise-io/trace-cocoa-sdk.git.

Also, you can also navigate to your target’s General pane, and in the “Frameworks, Libraries, and Embedded Content” section, click the + button, select Add Other, and choose Add Package Dependency.

Adding `Other Linker Flags to application target

  • Select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar.
  • In the tab bar at the top of that window, open the "Build Settings" panel.
  • Search for Other Linker Flags or OTHER_LDFLAGS and enter -ObjC -l z -l c++

In your project add import Trace and call let trace = Trace.shared to start the SDK.

  • And that's it!

Manual

If you prefer not to use any of the aforementioned dependency managers, you can integrate Trace into your project manually.

Embedded static library at build time

  • Download libTrace.a static library assert from Github release page. Please select the first file under asset's called libTrace.a.
  • Drop the library at the root of your Xcode project. i.e same directory as your xcproject/xcworkspace project.
  • Next in Xcode, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar.
  • Now, In the tab bar at the top of that window, open the "Build Settings" panel.
  • Search for Other Linker Flags or OTHER_LDFLAGS and enter -force_load libTrace.a

Note: The code snippet assumes the library is in the same directory as yourxcproject/xcworkspaceproject. If you use a different location add the new path.

  • Click on the + button under the "Frameworks, Libraries and Embedded Content" section.
  • Add libz.tbd and libc++.tbd.
  • And that's it!

Embedded Xcode project

  • Open up Terminal, cd into your top-level project directory where Xcode project is stored.
  • Add Trace as a git submodule by running the following command:

$ git submodule add https://github.com/bitrise-io/trace-cocoa-sdk.git

  • Open the new trace-cocoa-sdk folder, and drag the Trace.xcodeproj (blue project file.xcodeproj) into the Project Navigator of your application's Xcode project. They should appear nested underneath your application's blue project icon.
  • Next, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar.
  • In the tab bar at the top of that window, open the "General" panel.
  • Click on the + button under the "Frameworks, Libraries and Embedded Content" section.
  • Add libTrace.a library from the search list.
  • Add libz.tbd and libc++.tbd as well.
  • Now, In the tab bar at the top of that window, open the "Build Settings" panel.
  • Search for Other Linker Flags or OTHER_LDFLAGS and enter -force_load '$(BUILT_PRODUCTS_DIR)/libTrace.a'

Note: don't worry about other attributes on the list.

  • And that's it!

Storage

SDk binaries is hosted on Firebase, download the latest version here or download a specific version by adding the version details inside the url i.e https://monitoring-sdk.firebaseapp.com/{MAJOR.MINOR.PITCH}/libTrace.a

By default navigating to the root of the SDK site will always redirect to latest version.

Common problems

C++ system library is not linked

  • Click on the + button under the "Frameworks, Libraries and Embedded Content" section.
  • Add libz.tbd and libc++.tbd.
  • And that's it!

Can't find Trace library

This error is caused by Xcode not being able to locate Trace library. By default, our installation guide uses the easiest approach. To resolve this error go to Other Linker Flags or OTHER_LDFLAGS in your application target and enter -force_load CORRECT_PATH_TO_libTrace.a'

Can't find collector token

Make sure bitrise_configuration.plist is included in your project and the target membership is set to the correct one.

Can't find collector token

[Bitrise:Trace/internalError] Bitrise configuration file is missing from Bundle.main [Bitrise:Trace/internalError] Application failed to read the configuration file, all data will be cached until it's resolved

Add the collector token (bitrise_configuration.plist) found in the setting page or getting started page. Make sure this file is added to your application target.

Limitations

-force_load and -all_load

.XCFramework does not currently allow developers to load a library at App launch. This only affects SPM packages only. No workaround are available right now.

Mac catalyst support

Mac catalyst support is only available in SPM and Manual installations as we should .XCFramework. Using lipo to create a static library does not work since it cannot understand architecture that are similar but have a different flavor to support Mac's.

Miscellaneous

Special thanks to

Karl Stenerud KSCrash crash reporting dependency, last commit: d8845bd622f4cf469ba65e9be42de116e1548478, branch: master, date: (18th August)

License

Trace is released under the MIT license. See LICENSE for details.

Github

link
Stars: 3

Dependencies

Used By

Total: 0

Releases

1.7.3 - 2020-09-24 14:53:03

Changes

  • Xcode 12.2 update
  • Add Mac Catalyst support to SPM and Manual installation using .XCFramework

Fixes

  • Fix symlink on Repo root after a deployment

1.7.2 - 2020-09-24 14:52:05

Changes

  • Xcode 12.2 update
  • Add Mac Catalyst support to SPM and Manual installation using .XCFramework

Fixes

  • Fix symlink on Repo root after a deployment

1.7.1 - 2020-09-23 15:01:38

Changes

  • Xcode 12.2 update
  • Add Mac Catalyst support to SPM and Manual installation using .XCFramework

Fixes

  • Fix symlink on Repo root after a deployment

1.7.0 - 2020-09-16 12:17:33

Changes

  • [784ae39] Remove swift head validation in favour of ObjC runtime

1.6.1 - 2020-08-27 18:54:09

Changes

  • Made sure all DB read/write used there own thread using perform method
  • Pass NSManagedObjectID instead of native DB object to avoid threading issue
  • Create new DB private context instead of reusing current context thread
  • Expose DB errors in logs

Fixes

  • Improved debug check i.e #if DEBUG || Debug || debug

1.6.0 - 2020-08-25 15:25:33

New

  • Added APM_INSTALLATION_SOURCE to plist file
  • Added configuration enabled to SDK

Changes

  • Nanosecond validator for traces
  • New validation checks before saving to DB
  • Validate swift SDK launch
  • Validate methods before calling them indirectly
  • Add extra leeway to finish method
  • KSCrash updated to the recent master branch. See on Readme file
  • Disable crash reporting in debug mode

Fixes

  • Improved log comments
  • Fixed naming conflicts coming from Xcode
  • Remove Zombie support as it's not ready for a production-grade app

1.5.0 - 2020-08-07 14:19:44

Changes

  • Moved trace object allocation to view lifecycle methods
  • validate trace before calling finish method
  • Updated log style
  • Improved traceability of crash reports

Fixes

  • Avoid restarting trace on disabled view classes

1.4.18 - 2020-08-05 16:42:54

Changes

  • Trace model validation
  • macCatalyst validation

Fixes

  • Corrected end timestamp for crash reporting

1.4.17 - 2020-08-04 10:13:01

Changes

  • Start time date log
  • Safari banned class updates
  • Avoid getting carrier info if running on a simulator

1.4.16 - 2020-07-29 13:42:36

Changes

  • [72c4dba] Span timing validation added. (#14)
  • Added minor support for Mac catalyst. (#13)
  • Updated readme. (#12)

1.4.15 - 2020-07-27 09:22:48

Changes

  • Removed extra logging and documentation.
  • Fallback if diskspace cannot be captured.
  • Capture CPU/memory metric on warm startup.

Fixed

  • Corrected session properties being reported to backend.

1.4.14 - 2020-07-22 14:13:34

Changes

  • Fetch hardware metric at launch
  • Removed .SystemMemoryBytes metric
  • Removed total value from memory metric

Fixed

  • Added network details in crashes

1.4.13 - 2020-07-21 12:44:18

Changes

  • Timestamp validator for debugging
  • SDK version added to all requests
  • Removed country carrier and unknowns
  • Made sure Session was the first object created in the SDK
  • Removed a few view controller methods that were not required for observation
  • Validation for background->foreground lifecycle handling
  • Removed metric object from ViewController

1.4.12 - 2020-07-17 18:48:26

Changes

  • Added basic support for Mac Catalyst
  • Timestamp validator
  • Attempt to fix Cocoapods trunk lag

1.4.11 - 2020-07-16 14:51:30

Changes

  • Updated BitriseTrace.podspec.json
  • Updated logs to be more consistent
  • Add fallback when disk persistent store fails
  • Reuse existing DB threads instead of creating one for each operation
  • Made it easier to point to a specific branch or commit when using Cocoapods

Fixes

  • Create a directory if it doesn't exist

1.4.10 - 2020-07-08 17:47:27

Changes

  • Updated BitriseTrace.podspec.json
  • Updated logs to be more consistent
  • Add fallback when disk persistent store fails
  • Reuse existing DB threads instead of creating one for each operation
  • Made it easier to point to a specific branch or commit when using Cocoapods

Fixes

  • Create a directory if it doesn't exist