macOS App Integration¶
Guance Application Monitoring collects metrics from macOS apps and visualizes the performance of each macOS app client.
Reading Path¶
- First-time integration: first choose an access method; for manual integration, see Quick Start
- Full integration: continue reading this document
- Initialization parameters: see SDK Initialization, RUM Configuration, Log Configuration, and Trace Configuration
- Custom capabilities: see Custom Tags and Custom Data Collection Rules
- Data model: see Application Data Collection
- Troubleshooting: see Troubleshooting
Prerequisites¶
Note
If the RUM Headless service is enabled, the prerequisites are configured automatically, and you can integrate the app directly.
For local environment deployments, complete the following data receiver configuration. For public DataWay, you do not need to deploy DataKit yourself.
- Install DataKit;
- Configure the RUM collector
App Integration¶
- Go to RUM > Create > macOS;
- Enter the app name;
- Enter the app ID;
- In Select Access Method, choose Agent Auto-Integration or Manual Integration, then complete Integration Configuration.
Choose an Access Method¶
On the app configuration page, select Agent Auto-Integration or Manual Integration, then complete Integration Configuration. For an existing app, go directly to the configuration page to continue integration.
| Access Method | Use Cases | Entry Point |
|---|---|---|
| Agent Auto-Integration | Let a coding assistant analyze the project and complete SDK integration | Copy the prompt generated in the console and run it with the coding assistant in the app code repository |
| Manual Integration | Install the SDK and configure parameters yourself | Confirm the data reporting method, then complete configuration by following this document and Quick Start |
Agent Auto-Integration¶
- On the configuration page for the current app, select Agent Auto-Integration.
- Copy the complete prompt from Integration Configuration, and make sure it uses the integration information for the current app.
- Open the coding assistant in the app code repository, paste the prompt, and let the Agent analyze the project and complete the SDK configuration according to the integration guide.
- Build and run the app, trigger operations such as page views, and verify in the Explorer for the current app that data is received.
If the page indicates that your personal API Key or temporary authorization code is not ready, complete the required information as prompted, and then copy the prompt again.
Manual Integration¶
On the app configuration page, select Manual Integration, and confirm the data reporting method:
- Public DataWay: receives RUM data directly; no DataKit collector installation is required.
- Local environment deployment: receives RUM data after the prerequisites are met.
Follow the Installation and Quick Start sections below to install, initialize, and verify the SDK. If an SDK configuration already exists, review and reuse it first to avoid duplicate initialization.
Installation¶
Source Code: https://github.com/GuanceCloud/datakit-macos
Demo: https://github.com/GuanceCloud/datakit-macos/Example
- Configure the
Podfile.
- In the directory containing the
Podfile, runpod installto install the SDK.
-
Select
PROJECT->Package Dependency, then click + underPackages. -
In the search box on the page that appears, enter
https://github.com/GuanceCloud/datakit-macos, which is the repository location. -
After Xcode successfully fetches the package, it displays the SDK configuration page.
Dependency Rule: We recommend selecting Up to Next Major Version.
Add To Project: Select the supported project.
After filling in the configuration, click Add Package and wait for loading to complete.
- In the
Choose Package Products for datakit-macosdialog, select the Target to which you want to add the SDK, and clickAdd Package. The SDK is now added successfully.
If your project is managed by SPM, add FTMacOSSDK as a dependency by adding dependencies to Package.swift.
```swift dependencies: [
.package(url: "https://github.com/GuanceCloud/datakit-macos.git", .upToNextMajor(from: "[latest_version]")) ] ```
Add Header File¶
Detailed Configuration Entry Points¶
Advanced Scenarios¶
FAQ¶
Crash Log Analysis¶
For crash log analysis and dSYM details, see Troubleshooting.
Include of non-modular header inside framework module error occurs¶
Because the SDK's .h files import .h files from dependent libraries, set the following:
Set Target -> Build Settings -> CLANG_ALLOW_NON_MODULAR_INCLUDES_IN_FRAMEWORK_MODULES to YES.