This SDK is officially deprecated. Please switch to HockeyApp or consider MobileCenter.
You can find more about the transition from Application Insights to HockeyApp here and about how Mobile Center will be the future of HockeyApp here.
Please don't hesitate to get in touch via [email protected]. if you have questions.
This is the repository of the Mac SDK for Application Insights. Application Insights is a service that allows developers to keep their applications available, performing, and succeeding. The SDK enables you to send telemetry of various kinds (events, traces, page views, etc.) to the Application Insights service where your data can be visualized in the Azure Portal.
You can use the Application Insights for Mac tool to integrate the Application Insights Mac SDK into your existing apps. The SDK runs on devices with with OS X 10.8 or higher. You'll need a subscription to Microsoft Azure. (It's free until you want to send quite a lot of telemetry.)
The SDK runs on devices with OS X 10.8 or higher.
##Breaking Changes!
Version 1.0-beta.2 of the Application Insights for Mac comes with two major changes:
Crash Reporting and the API to send handled exceptions have been removed from the SDK. In addition, the Application Insights for Mac SDK is now deprecated.
The reason for this is that HockeyApp is now our major offering for mobile and cross-plattform crash reporting, beta distribution and user feedback. We are focusing all our efforts on enhancing the HockeySDK and adding telemetry features to make HockeyApp the best platform to build awesome apps. We've launched HockeyApp Preseason so you can try all the new bits yourself, including User Metrics.
We apologize for any inconvenience and please feel free to contact us at any time.
- Release Notes
- Requirements
- Setup
- Advanced Setup
- Developer Mode
- Basic Usage
- Advanced Usage
- Automatic collection of lifecycle events
- Set Custom Server Endpoint
- Documentation
- Contributing
- Contact
- Remove crash reporting. To add this feature to your app, we recommend to use HockeyApp which provides you with superior crash reporting, feedback, beta distribution and much more.
- Fixes an issue where pageview durations where incorrectly sent as days instead of as a string in the 'd:hh:mm:ss.fffffff' format. The relevant methods now take an
NSTimeIntervalparameter with the duration in seconds. - Fix session management & minor bug fixes
See here for the release notes of previous versions.
The SDK runs on devices with OS X 10.8 or higher.
We recommend integration of our binary into your Xcode project to setup Application Insights for your OS X app. For other ways to setup the SDK, see Advanced Setup. Also make sure that you code-sign your app as the SDK is writing data into the keychain. Non-sandboxed or non-code-signed apps will result in keychain dialogs to appear on startup of your app!
You can use the Application Insights for Mac tool to integrate the SDK, which provides you with a step-by-step wizard for this process. If you want to integrate the SDK manually, you can do that by following this steps:
To view your telemetry, you'll need an Application Insights resource in the Microsoft Azure Portal. You can either:
- Create a new resource; or
- If your app uses a web service, use the same resource you set up to monitor that. See setup for ASP.NET or for J2EE.
Open your resource and open the Essentials drop-down. Shortly, you'll need to copy the Instrumentation Key.
- Download the latest Application Insights for OSX framework which is provided as a zip-File.
- Unzip the file and you will see a folder called
ApplicationInsights.
From our experience, 3rd-party libraries usually reside inside a subdirectory (let's call our subdirectory Vendor), so if you don't have your project organized with a subdirectory for libraries, now would be a great start for it. To continue our example, create a folder called "Vendor" inside your project directory and move the unzipped ApplicationInsights-folder into it.
- We recommend to use Xcode's group-feature to create a group for 3rd-party-libraries similar to the structure of our files on disk. For example, similar to the file structure in 3.1 above, our projects have a group called
Vendor. - Make sure the
Project Navigatoris visible (⌘+1) - Drag & drop
ApplicationInsights.frameworkfrom your window in theFinderinto your project in Xcode and move it to the desired location in theProject Navigator(e.g. into the group calledVendor) - A popup will appear. Select
Create groups for any added foldersand set the checkmark for your target. Then clickFinish. - Select your project in the
Project Navigator(⌘+1). - Select your app target.
- Select the tab
Build Phases.- Click the
+button at the top and chooseAdd Copy Files. - Click the disclosure triangle next to the new build phase.
- Choose
Frameworksfrom the Destination list. - Drag
ApplicationInsights.frameworkfrom theProject Navigatorto the list in the new Copy Files phase.
- Click the
- Open the
Info.plistof your app target and add a new field of type String. Name itMSAIInstrumentationKeyand set your Application Insights instrumentation key as its value.
Objective-C
-
Open your
AppDelegate.mfile. -
Add the following line at the top of the file below your own
importstatements:#import <ApplicationInsightsOSX/ApplicationInsights.h>
-
Search for the method
application:didFinishLaunchingWithOptions: -
Add the following lines to setup and start the Application Insights SDK:
// Setup Application Insights SDK [[MSAIApplicationInsights sharedInstance] setup]; // Do some additional configuration if needed here ... [[MSAIApplicationInsights sharedInstance] start];
You can also use the following shortcuts:
[MSAIApplicationInsights setup]; [MSAIApplicationInsights start];
Swift
-
Open your
AppDelegate.swiftfile. -
Add the following line at the top of the file below your own import statements:
import ApplicationInsightsOSX
-
Search for the method
func applicationDidFinishLaunching(_ aNotification: NSNotification)
-
Add the following lines to setup and start the Application Insights SDK:
MSAIApplicationInsights.sharedInstance().setup() MSAIApplicationInsights.sharedInstance().start()
You can also use the following shortcuts:
MSAIApplicationInsights.setup() MSAIApplicationInsights.start()
Congratulation, now you're all set to use Application Insights! See Basic Usage on how to use Application Insights.
It is also possible to set the instrumentation key of your app in code. This will override the one you might have set in your Info.plist. To set it in code, MSAIApplicationInsights provides an overloaded constructor:
[MSAIApplicationInsights setupWithInstrumentationKey:@"{YOUR-INSTRUMENTATIONKEY}"];
//Do additional configuration
[MSAIApplicationInsights start];CocoaPods is a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party libraries like ApplicationInsights in your projects. To learn how to setup CocoaPods for your project, visit the official CocoaPods website.
[NOTE]
When adding Application Insights to your podfile without specifying the version, pod install will throw an error because using a pre-release version of a pod has to be specified explicitly.
As soon as Application Insights 1.0 is available, the version doesn't have to be specified in your podfile anymore.
Podfile
platform :osx, '10.8'
pod "ApplicationInsights-OSX", '1.0-beta.2'The following points need to be considered to use the Application Insights SDK with OS X Extensions:
- Each extension is required to use the same values for version (
CFBundleShortVersionString) and build number (CFBundleVersion) as the main app uses. (This is required only if you are using the sameMSAIInstrumentationKeyfor your app and extensions). - You need to make sure the SDK setup code is only invoked once. Since there is no
applicationDidFinishLaunching:equivalent andviewDidLoadcan run multiple times, you need to use a setup like the following example:
@interface TodayViewController () <NCWidgetProviding>
@property (nonatomic, assign) BOOL didSetupApplicationInsightsSDK;
@end
@implementation TodayViewController
- (void)viewDidLoad {
[super viewDidLoad];
if (!self.didSetupApplicationInsightsSDK) {
[MSAIApplicationInsights setup];
[MSAIApplicationInsights start];
self.didSetupApplicationInsightsSDK = YES;
}
}###5.1 Batching of data
The developer mode is enabled automatically in case the debugger is attached or if the app is running in the simulator. This will decrease the number of telemetry items sent in a batch (5 items) as well as the interval items when telemetry will be sent (3 seconds).
###5.2 Logging
We're all big fans of a clean debugging output without 3rd-party-SDKs messages piling up in the debugging view, right?! That's why Application Insights keeps log messages to a minimum (like critical errors) unless the developer specifically enables debug logging before starting the SDK:
[MSAIApplicationInsights setup]; //setup the SDK
[[MSAIApplicationInsights sharedInstance] setDebugLogEnabled:YES]; //enable debug logging
[MSAIApplicationInsights start]; //start using the SDKThis setting is ignored if the app is running in an app store environment, so the user's console won't be littered with our log messages.
[NOTE] The SDK is optimized to defer everything possible to a later time while making sure e.g. crashes on startup can also be caught and each module executes other code with a delay of some seconds. This ensures that applicationDidFinishLaunching: will process as fast as possible and the SDK will not block the startup sequence resulting in a possible kill by the watchdog process.
After you have set up the SDK as described above, the MSAITelemetryManager-instance is the central interface to track events, traces, metrics, or page views.
For an overview of how to use the API and view the results in the Application Insights resource, see API Overview. The examples are in Java, but the principles are the same.
// Send an event with custom properties and measurements data
[MSAITelemetryManager trackEventWithName:@"Hello World event!"
properties:@{@"Test property 1":@"Some value",
@"Test property 2":@"Some other value"}
measurements:@{@"Test measurement 1":@(4.8),
@"Test measurement 2":@(15.16),
@"Test measurement 3":@(23.42)}];
// Send a message
[MSAITelemetryManager trackTraceWithMessage:@"Test message"];
// Manually send page views (duration 200 ms)
[MSAITelemetryManager trackPageView:@"MyViewController"
duration:0.2
properties:@{@"Test measurement 1":@(4.8)}];
// Send custom metrics
[MSAITelemetryManager trackMetricWithName:@"Test metric" value:42.2];// Send an event with custom properties and measuremnts data
MSAITelemetryManager.trackEventWithName("Hello World event!",
properties:["Test property 1":"Some value",
"Test property 2":"Some other value"],
measurements:["Test measurement 1":4.8,
"Test measurement 2":15.16,
"Test measurement 3":23.42])
// Send a message
MSAITelemetryManager.trackTraceWithMessage("Test message")
// Manually send pageviews (duration 200 ms)
MSAITelemetryManager.trackPageView("MyViewController",
duration:0.2,
properties:["Test measurement 1":4.8])
// Send a message
MSAITelemetryManager.trackMetricWithName("Test metric", value:42.2)In the Azure portal, open the application resource that you created to get your instrumentation key. You'll see charts showing counts of page views and sessions. To see more:
- Click any chart to see more detail. You can create your own metric pages, set alerts, and filter and segment your data.
- Click Search to see individual trackEvent, trackTrace, and trackPageView messages.
The SDK also allows for some more advanced usages.
It is also possible to set so-called "common properties" that will then be automatically attached to all telemetry data items.
[MSAITelemetryManager setCommonProperties:@{@"custom info":@"some value"}];MSAITelemetryManager.setCommonProperties(["custom info":"some value"])Use the properties to segment and filter metric charts and filter searches.
Automatic collection of lifecycle events is enabled by default. This means that Application Insights automatically manages sessions for you.
By default, the Application Insights for Mac starts a new session when the containing app is restarted (this means a 'cold start', i.e. when the app has not already been in memory prior to being launched) or when it has been in the background for more than 20 seconds.
You can either change this timeframe:
[MSAIApplicationInsights setAppBackgroundTimeBeforeSessionExpires:60];Turn of automatic session management completely:
[MSAIApplicationInsights setAutoSessionManagementDisabled:YES];This then requires you to manage sessions manually:
[MSAIApplicationInsights renewSessionWithId:@"4815162342"];Normally, a random anonymous ID is automatically generated for every user of your app by the SDK. Alternatively you can set your own user ID or other user attributes, which will then be attached to all telemetry events:
[[MSAIApplicationInsights sharedInstance] setUserWithConfigurationBlock:^(MSAIUser *user) {
user.userId = @"your_user_id";
user.accountId = @"[email protected]";
}];You can also configure a different server endpoint for the SDK if needed using a full URL
[MSAIApplicationInsights setup]; //setup the SDK
[[MSAIApplicationInsights sharedInstance] setServerURL:@"https://YOURDOMAIN/path/subpath"];
[MSAIApplicationInsights start]; //start using the SDKOur documentation can be found on CocoaDocs.
We're looking forward to your contributions via pull requests.
Development environment
- Mac running the latest version of OS X
- Get the latest Xcode from the Mac App Store
- AppleDoc
- Cocoapods
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
You must sign a Contributor License Agreement before submitting your pull request. To complete the Contributor License Agreement (CLA), you will need to submit a request via the form and then electronically sign the CLA when you receive the email containing the link to the document. You need to sign the CLA only once to cover submission to any Microsoft OSS project.
If you have further questions or are running into trouble that cannot be resolved by any of the steps here, feel free to open a GitHub issue here or contact us at [email protected]