Merge pull request #33 from amco/1.0

Create 1.0.0 release

CHANGELOG.md

@@ -1,3 +1,94 @@
+### Version 1.0.0
+
+This is a major revision which means **APIs will break**. It is not backwards compatible with 0.1.x releases. Code from 0.1.x branches will no longer be supported. Please update!
+
+#### Demo Project
+
+* Added descriptions and examples on how to use various features to demo project
+
+#### Metrics
+
+* Added `metricNamed:valued:` to `LibratoMetric` (https://github.com/amco/librato-iOS/commit/0e10150892820ab7185bbd7752a2ec564d0cc458)
+* Added `metricNamed:valued:source:measureTime:` to `LibratoMetric` (https://github.com/amco/librato-iOS/commit/0e10150892820ab7185bbd7752a2ec564d0cc458)
+* Fixed `metricTime` not being set when passed in via `metricNamed:valued:options:` (https://github.com/amco/librato-iOS/commit/0e10150892820ab7185bbd7752a2ec564d0cc458)
+* Changed metrics to extend Mantle instead of `NSObject` (https://github.com/amco/librato-iOS/commit/e418ff7c1dd824c55529d0588ae6677a5a4b7062)
+* Changed `isValidValue` from instance to class method
+* Changed maximum metric age from one year to fifteen minutes (Librato Metric rules) (https://github.com/amco/librato-iOS/commit/53fbe0bee6a22e34b698f212d01a188ea40b9468)
+* Added automatic collection of device, OS, app and Librato library metrics when a `Librato` instance is initialized (https://github.com/amco/librato-iOS/commit/5ce4d5d16b49dd5a09e21c5e09eb48881157c0d4)
+* Fixed `LibratoClient.metrics` to report queued metrics instead of blank `NSDictionary`
+* Fixed queue firing `removeAllObjects` when `clear`ing instead of overwriting with new `NSMutableDictonary` so dictionary children are `release`d. (https://github.com/amco/librato-iOS/commit/704c245a1710ac6989d13d8b54d50d24206d8c53)
+
+#### Collections
+
+* Added `LibratoMetricCollection` which contains metrics based on type and handles conversion of metrics into structured JSON (https://github.com/amco/librato-iOS/commit/704c245a1710ac6989d13d8b54d50d24206d8c53)
+
+#### Initialization
+
+* Added `NSAsserts` in Librato, LibratoMetric and LibratoGaugeMetric `init` to disable use in favor of their custom initialization methods (https://github.com/amco/librato-iOS/commit/ebc4dcd5ed976607f1e13acff5cdaa9fdcf26adb)
+
+#### Submission
+
+* Added `add:` interface which is preferred over `submit:`
+* Changed manual submission to an optional command as queues are automatically submitted on a configurable interval (https://github.com/amco/librato-iOS/commit/fda9cbaeaa4525e61bff0c53932d94b2a6c47190)
+* Added global block handlers for submission success and failure (https://github.com/amco/librato-iOS/commit/e3e095cb26579446400e9ac61a33fb9e940ef8da)
+* Changed queue to clear just before firing submission instead of after successful submission to prevent accidental double submission (https://github.com/amco/librato-iOS/commit/5ce4d5d16b49dd5a09e21c5e09eb48881157c0d4)
+* Note: Queue is not cached before clearing, would could be useful if submission fails to re-queue items
+
+#### Offline
+
+* Added prevention of metrics submission if device is offline  (https://github.com/amco/librato-iOS/commit/704c245a1710ac6989d13d8b54d50d24206d8c53)
+* Added automatic queue submission when internet becomes available
+* Added storage of queue in `NSKeyedArchiver` when app is backgrounded
+* Added queue hydration via `NSKeyedArchiver` when app is brought to foreground
+
+#### Group metrics
+
+* Added `groupNamed:valued:` to convert an `NSDictionary` into an array of `LibratoMetric`s (https://github.com/amco/librato-iOS/commit/fa4a9a5cf525e6ed04192e41b8bb709e57612a57)
+* Added `groupNamed:context:` to automatically prefix any metrics created in the context with the group name
+
+#### Notification subscription
+
+* Added ability of `Librato` to subscribe to notifications with `listenForNotification:context:` and perform given `context` when notification is caught (https://github.com/amco/librato-iOS/commit/4a7b5a974263b596bdaa1e74943c36d586b93f51)
+* Added queue specific to Librato subscriptions for `dispatch_async`ing execution of assigned `context`
+
+#### User agent
+
+* Added custom user agent setting available in `Librato` (https://github.com/amco/librato-iOS/commit/24e9edbc8dc03546fb8976239503a4c3ce3aab52)
+* Removed `agentIdentifier` from `LibratoClient`
+
+#### Descriptions
+
+* Added custom descriptions for Librato, LibratoClient, LibratoMetric, LibratoMetricCollection and LibratoQueue to aid debugging (https://github.com/amco/librato-iOS/commit/704c245a1710ac6989d13d8b54d50d24206d8c53)
+
+#### Miscellaneous
+
+* Removed numerous `NSLog`s. Sorry about the extra noise. (https://github.com/amco/librato-iOS/commit/474fe9a115ffe308eb2e858a93af0453568e76ad, https://github.com/amco/librato-iOS/commit/7433254602cdc3d3b6d9b755766a929b82d73805)
+
 ### Version 0.1.0
 
-* Initial commit and functionality
+Initial commit and functionality
+
+* Code available via CocoaPods
+
+#### Metrics
+
+* Create counter metric
+* Create group metric, statistics automatically computed
+* Name and source fields automatically cleaned and trimmed
+* Custom prefix available to be applied to all metric names
+* Values for all fields can be manipulated after initialization
+
+#### Submission
+
+* Metric types offered but `NSDictionary` data automatically parsed into appropriate Metric type and queued
+* Metrics only queued until manual submission
+* Only available parser is direct JSON parsing
+
+#### Queue
+
+* Add-only, no management
+* Manual submission
+
+#### Localization
+
+* Error messages localized for English

Demo/librato-iOS Demo.xcodeproj/project.pbxproj

@@ -334,7 +334,7 @@
 			isa = XCBuildConfiguration;
 			buildSettings = {
 				ALWAYS_SEARCH_USER_PATHS = NO;
-				ARCHS = "$(ARCHS_STANDARD_INCLUDING_64_BIT)";
+				ARCHS = "$(ARCHS_STANDARD)";
 				CLANG_CXX_LANGUAGE_STANDARD = "gnu++0x";
 				CLANG_CXX_LIBRARY = "libc++";
 				CLANG_ENABLE_MODULES = YES;
@@ -363,7 +363,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 7.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 6.1;
 				ONLY_ACTIVE_ARCH = YES;
 				SDKROOT = iphoneos;
 				TARGETED_DEVICE_FAMILY = "1,2";
@@ -374,7 +374,7 @@
 			isa = XCBuildConfiguration;
 			buildSettings = {
 				ALWAYS_SEARCH_USER_PATHS = NO;
-				ARCHS = "$(ARCHS_STANDARD_INCLUDING_64_BIT)";
+				ARCHS = "$(ARCHS_STANDARD)";
 				CLANG_CXX_LANGUAGE_STANDARD = "gnu++0x";
 				CLANG_CXX_LIBRARY = "libc++";
 				CLANG_ENABLE_MODULES = YES;
@@ -397,7 +397,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				IPHONEOS_DEPLOYMENT_TARGET = 7.0;
+				IPHONEOS_DEPLOYMENT_TARGET = 6.1;
 				SDKROOT = iphoneos;
 				TARGETED_DEVICE_FAMILY = "1,2";
 				VALIDATE_PRODUCT = YES;

Demo/librato-iOS Demo/LibratoDemoAppDelegate.m

@@ -25,6 +25,10 @@ - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(
     [eventTracker groupDictionaryExample];
     [eventTracker groupContextExample];
     [eventTracker gaugeMetricExample];
+    [eventTracker notificationExample];
+    [eventTracker metricCreationHelpersExample];
+    [eventTracker customUAExample];
+    [eventTracker submissionBlocksExample];
 
     return YES;
 }

Demo/librato-iOS Demo/LibratoDemoEventTracker.h

@@ -22,5 +22,9 @@
 - (void)groupDictionaryExample;
 - (void)groupContextExample;
 - (void)gaugeMetricExample;
+- (void)notificationExample;
+- (void)customUAExample;
+- (void)metricCreationHelpersExample;
+- (void)submissionBlocksExample;
 
 @end

Demo/librato-iOS Demo/LibratoDemoEventTracker.m

@@ -49,35 +49,30 @@ + (Librato *)sharedInstance
 - (void)counterMetricExample
 {
     LibratoMetric *simpleMetric = [LibratoMetric metricNamed:@"works" valued:self.randomNumber options:@{@"source": @"demo app"}];
-    simpleMetric.measureTime = [NSDate dateWithTimeIntervalSinceNow:-(3600 * 24)];
+    simpleMetric.measureTime = [NSDate dateWithTimeIntervalSinceNow:-(60*5)];
 
-    NSLog(@"%@", simpleMetric);
-
-    [LibratoDemoEventTracker.sharedInstance submit:simpleMetric];
+    [LibratoDemoEventTracker.sharedInstance add:simpleMetric];
 }
 
 
 /*
- Creates two different metrics but submits them simultaneously
+ Creates two different metrics but adds them simultaneously
 */
 - (void)multipleMetricSubmissionExample
 {
     LibratoMetric *memoryMetric  = [LibratoMetric metricNamed:@"memory.available" valued:self.randomNumber options:nil];
     LibratoMetric *storageMetric = [LibratoMetric metricNamed:@"storage.available" valued:self.randomNumber options:nil];
 
-    NSLog(@"%@", memoryMetric);
-    NSLog(@"%@", storageMetric);
-
-    [LibratoDemoEventTracker.sharedInstance submit:@[memoryMetric, storageMetric]];
+    [LibratoDemoEventTracker.sharedInstance add:@[memoryMetric, storageMetric]];
 }
 
 
 /*
- Creates and auto-submits two counter metrics: "meaning" and "plutonium", the latter using an NSDictionary to set the value and source simultaneously
+ Creates two counter metrics: "meaning" and "plutonium", the latter using an NSDictionary to set the value and source simultaneously
 */
 - (void)dictionaryCreationExample
 {
-    [LibratoDemoEventTracker.sharedInstance submit:@{@"meaning": self.randomNumber, @"plutonium": @{@"value": @238, @"source": @"Russia, with love"}}];
+    [LibratoDemoEventTracker.sharedInstance add:@{@"meaning": self.randomNumber, @"plutonium": @{@"value": @238, @"source": @"Russia, with love"}}];
 }
 
 
@@ -89,7 +84,7 @@ - (void)dictionaryCreationExample
  The group prefix is the first argument and is joined to each metric named with a period.
  The dictionary's key value is the metric name as an NSString and the value is an NSNumber value.
  
- If the group is named "foo" and the first metric is named "bar" it will be submitted with the name "foo.bar"
+ If the group is named "foo" and the first metric is named "bar" it metric's submitted name will be "foo.bar"
 */
 - (void)groupDictionaryExample
 {
@@ -99,7 +94,7 @@ - (void)groupDictionaryExample
                                 @"friends": @172
                                 };
     NSArray *metrics = [LibratoDemoEventTracker.sharedInstance groupNamed:@"user" valued:valueDict];
-    [LibratoDemoEventTracker.sharedInstance submit:metrics];
+    [LibratoDemoEventTracker.sharedInstance add:metrics];
 }
 
 
@@ -112,13 +107,38 @@ - (void)groupContextExample
         LibratoMetric *logins = [LibratoMetric metricNamed:@"logins" valued:@12 options:nil];
         LibratoMetric *logouts = [LibratoMetric metricNamed:@"logouts" valued:@7 options:nil];
         LibratoMetric *timeouts = [LibratoMetric metricNamed:@"timeouts" valued:@5 options:nil];
-        [l submit:@[logins, logouts, timeouts]];
+        [l add:@[logins, logouts, timeouts]];
     }];
 }
 
 
 /*
- Creates a series of counter measurements and submits them as a gague metric
+ Provide the name of a notification and that notification will come into the block's context when it's caught.
+ Contexts are executed asynchronously in a Librato-specific serial queue.
+ A subscription with block is used and returned so you're responsible for unsubscribing when appropriate!
+*/
+- (void)notificationExample
+{
+    __weak Librato *weakDemo = LibratoDemoEventTracker.sharedInstance;
+    id subscription = [LibratoDemoEventTracker.sharedInstance listenForNotification:@"state.sleeping" context:^(NSNotification *notification) {
+        LibratoMetric *useName = [LibratoMetric metricNamed:notification.name valued:@100 options:nil];
+        LibratoMetric *useInfo = [LibratoMetric metricNamed:notification.userInfo[@"name"] valued:notification.userInfo[@"value"] options:notification.userInfo];
+
+        [weakDemo add:@[useName, useInfo]];
+    }];
+
+    [NSNotificationCenter.defaultCenter postNotificationName:@"state.sleeping" object:nil userInfo:@{
+                                                                                                     @"name": @"infoName",
+                                                                                                     @"value": @42
+                                                                                                     }];
+
+    // Don't forget to remove your subscriptions when you're done lest they hang around and point to a nil object!
+    [NSNotificationCenter.defaultCenter removeObserver:subscription];
+}
+
+
+/*
+ Creates a series of counter measurements and adds them as a gague metric
 */
 - (void)gaugeMetricExample
 {
@@ -132,10 +152,54 @@ - (void)gaugeMetricExample
     LibratoMetric *metric8 = [LibratoMetric metricNamed:@"bagels" valued:@0 options:nil];
 
     NSArray *bagels = @[metric1, metric2, metric3, metric4, metric5, metric6, metric7, metric8];
-    NSLog(@"%@", bagels);
     LibratoGaugeMetric *bagelGuage = [LibratoGaugeMetric metricNamed:@"bagel_guage" measurements:bagels];
 
-    [LibratoDemoEventTracker.sharedInstance submit:bagelGuage];
+    [LibratoDemoEventTracker.sharedInstance add:bagelGuage];
+}
+
+
+/*
+ You can add a custom string the User Agent sent with all of the Librato requests
+ WARNING: Setting a custom UA will reset your client's connection so do not do this arbitrarily
+*/
+- (void)customUAExample
+{
+    Librato *l = LibratoDemoEventTracker.sharedInstance;
+    l.customUserAgent = @"Demo UA";
+
+    [l add:@{@"ua.custom.instances": @1}];
+}
+
+
+/*
+ Metrics can be created with increasing levels of specificity
+ There are helpers for simple name & value metrics all the way up to all arguments specified
+*/
+- (void)metricCreationHelpersExample
+{
+    LibratoMetric *basic = [LibratoMetric metricNamed:@"basic" valued:@1];
+    LibratoMetric *explicit = [LibratoMetric metricNamed:@"explicit" valued:@100 source:@"demo" measureTime:NSDate.date];
+    LibratoMetric *custom = [LibratoMetric metricNamed:@"custom" valued:@50 options:@{@"source": @"demo"}];
+
+    [LibratoDemoEventTracker.sharedInstance add:@[basic, explicit, custom]];
+}
+
+
+- (void)submissionBlocksExample
+{
+    Librato *libratoInstance = LibratoDemoEventTracker.sharedInstance;
+
+    [libratoInstance setSubmitSuccessBlock:^(NSDictionary *JSON, NSUInteger code) {
+        if (code == 200) {
+            NSLog(@"Successful submission. Response JSON is: %@", JSON);
+        }
+    }];
+
+    [libratoInstance setSubmitFailureBlock:^(NSError *error, NSDictionary *JSON) {
+        NSLog(@"Error submitting metric: %@", error);
+    }];
+
+    [libratoInstance add:[LibratoMetric metricNamed:@"callbacks.test" valued:@123]];
 }
 
 

Demo/librato-iOS Demo/librato-iOS Demo-Info.plist

@@ -17,7 +17,7 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>1.0</string>
+	<string>1.0.0</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleVersion</key>