Merge pull request #32 from amco/doc_updates

Updated docs for 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

README.md

@@ -1,7 +1,7 @@
 librato-iOS
 ===========
 
-`librato-iOS` integrates with your iOS application (via [CocoaPods](http://cocoapods.org/)) to make reporting your metrics to [Librato](http://librato.com/) super easy. Reporting is done asynchronously and is designed to stay out of your way while allowing you to dig into each report's details, if you want.
+`librato-iOS` integrates with your iOS application (via [CocoaPods](http://cocoapods.org/)) to make reporting your metrics to [Librato](http://librato.com/) super easy. Reporting is done asynchronously and is designed to stay out of your way while allowing you to dig into each metric's details, if you want.
 
 Metrics are automatically cached while the network is unavailable and saved if the app closes before they're submitted. Don't worry about submitting metrics, we make sure they don't go missing before they can be handed off to Librato's service.
 
@@ -14,16 +14,16 @@ After installing `librato-iOS` into your workspace with CocoaPods just create a
 ```objective-c
 #import "Librato.h"
 
-...
-// The prefix is optional but recommended as it helps you organize across your different projects
-Librato *librato = [Librato.alloc initWithEmail:@"[email protected]" apiKey:@"abc123..." prefix:@""];
+// The prefix is optional but recommended as it
+// helps you organize across your different projects
+Librato *librato = [Librato.alloc initWithEmail:@"[email protected]"
+                                         apiKey:@"abc123..."
+                                         prefix:@""];
 
-// You can provide an NSDictionary with values for the optional "source" and "measure_time" fields
-LibratoMetric *filesOpened = [LibratoMetric metricNamed:@"files.opened" valued:@42 options:nil];
-// Optional values can be set directly on the metric object as well.
-// NOTE: The maximum age for any submitted metric is fifteen minutes, as dictated by Librato.
-filesOpened.measureTime = [NSDate.date dateByAddingTimeInterval:-10];
+// Create a metric with a specific name and value
+LibratoMetric *filesOpened = [LibratoMetric metricNamed:@"files.opened" valued:@42];
 
+// Add it to the queue to be automatically submitted
 [librato add:filesOpened];
 ```
 
@@ -56,7 +56,7 @@ Two types of measurement are currently available: counts and groups. These act a
 This is the default metric type and requires only an NSString name and NSNumber value.
 
 ```objective-c
-LibratoMetric *metric = [LibratoMetric metricNamed:@"downloads" valued:@42 options:nil];
+LibratoMetric *metric = [LibratoMetric metricNamed:@"downloads" valued:@42];
 ```
 
 Additionally, you can provide optional `source` and `measureTime`. The `source` is useful when reviewing data to determine from where measurements with the same name originate. The `measureTime` is automatically generated if not provided but you can set a unique time if you have events that occurred in the past and want to add them to the stack. Metrics must be marked as happening within the last year's time.
@@ -66,34 +66,46 @@ Additionally, you can provide optional `source` and `measureTime`. The `source`
 These values can be provided in the `options` NSDictionary or stated explicitly after the object has been instantiated.
 
 ```objective-c
-LibratoMetric *metric = [LibratoMetric metricNamed:@"downloads" valued:@42 options:@{@"source": @"the internet", @"measureTime": [NSDate.date dateByAddingTimeInterval:-(3600 * 24)]}];
+NSDate *previousDay = [NSDate.date dateByAddingTimeInterval:-(3600 * 24)];
+LibratoMetric *metric = [LibratoMetric metricNamed:@"downloads"
+                                            valued:@42
+                                           options:@{
+                                              @"source": @"the internet",
+                                              @"measureTime": previousDay
+                                            }];
 
 // or...
 
-LibratoMetric *metric = [LibratoMetric metricNamed:@"downloads" valued:@42 options:nil];
+LibratoMetric *metric = [LibratoMetric metricNamed:@"downloads" valued:@42];
 metric.source = @"the internet";
-metric.measureTime = [NSDate.date dateByAddingTimeInterval:-(3600 * 24)]
+metric.measureTime = previousDay;
 ```
 
 Optionally, you can create one or more counters inline with an NSDictionary when adding.
 
 ```objective-c
-[<some librato instance> add:@{@"downloads": @13, @"plutonium": @{@"value": @238, @"source": @"Russia, with love"}}];
+[<some librato instance> add:@{
+                               @"downloads": @13,
+                               @"plutonium": @{
+                                   @"value": @238,
+                                  @"source": @"Russia, with love"
+                                }
+                              }];
 ```
 
 ### Grouping
 
 Groups are aggregated metrics of multiple data points with related, meaningful data. These are created with an array of counter metrics.
 
 ```objective-c
-LibratoMetric *bagelMetric1 = [LibratoMetric metricNamed:@"bagels" valued:@13 options:nil];
-LibratoMetric *bagelMetric2 = [LibratoMetric metricNamed:@"bagels" valued:@10 options:nil];
-LibratoMetric *bagelMetric3 = [LibratoMetric metricNamed:@"bagels" valued:@9 options:nil];
-LibratoMetric *bagelMetric4 = [LibratoMetric metricNamed:@"bagels" valued:@8 options:nil];
-LibratoMetric *bagelMetric5 = [LibratoMetric metricNamed:@"bagels" valued:@2 options:nil];
-LibratoMetric *bagelMetric6 = [LibratoMetric metricNamed:@"bagels" valued:@1 options:nil];
-LibratoMetric *bagelMetric7 = [LibratoMetric metricNamed:@"bagels" valued:@0 options:nil];
-LibratoMetric *bagelMetric8 = [LibratoMetric metricNamed:@"bagels" valued:@0 options:nil];
+LibratoMetric *bagelMetric1 = [LibratoMetric metricNamed:@"bagels" valued:@13];
+LibratoMetric *bagelMetric2 = [LibratoMetric metricNamed:@"bagels" valued:@10];
+LibratoMetric *bagelMetric3 = [LibratoMetric metricNamed:@"bagels" valued:@9];
+LibratoMetric *bagelMetric4 = [LibratoMetric metricNamed:@"bagels" valued:@8];
+LibratoMetric *bagelMetric5 = [LibratoMetric metricNamed:@"bagels" valued:@2];
+LibratoMetric *bagelMetric6 = [LibratoMetric metricNamed:@"bagels" valued:@1];
+LibratoMetric *bagelMetric7 = [LibratoMetric metricNamed:@"bagels" valued:@0];
+LibratoMetric *bagelMetric8 = [LibratoMetric metricNamed:@"bagels" valued:@0];
 
 NSArray *bagels = @[bagelMetric1, bagelMetric2, bagelMetric3, bagelMetric4, bagelMetric5, bagelMetric6, bagelMetric7, bagelMetric8];
 LibratoGaugeMetric *bagelGuage = [LibratoGaugeMetric metricNamed:@"bagel_guage" measurements:bagels];
@@ -125,12 +137,14 @@ If you have a metrics you'd like to add to the queue and trigger an immediate su
 
 There's an optional but highly-recommended prefix you can set which will automatically be added to all metric names. This is a great way to isolate data or quickly filter metrics.
 
-# Monitoring Submission Success or Failure
+# Submission Success or Failure
 
 You can set a blocks to handle the success and failure cases for metric submission. These are referenced when the submission calls back so sporadically setting or `nil`-ling the blocks may lead to unexpected results.
 
 ```objective-c
-Librato *librato = [Librato.alloc initWithEmail:@"[email protected]" apiKey:@"abc123..." prefix:@""];
+Librato *librato = [Librato.alloc initWithEmail:@"[email protected]"
+                                         apiKey:@"abc123..."
+                                         prefix:@""];
 [libratoInstance setSubmitSuccessBlock:^(NSDictionary *JSON, NSUInteger code) {
     if (code == 200) {
         NSLog(@"Successful submission. Response JSON is: %@", JSON);

librato-iOS.podspec

@@ -1,9 +1,9 @@
 Pod::Spec.new do |s|
     s.name                  = "librato-iOS"
-    s.version               = "0.1.2"
+    s.version               = "1.0.0"
     s.summary               = "Librato library for iOS"
     s.description           = <<-DESC
-    A simple wrapper for the Librato API with some conveniences for common use cases
+    A simple, delightful wrapper for the Librato API with conveniences for common use cases
     DESC
     s.homepage              = "https://github.com/amco/librato-iOS"
     s.license               = { :type => 'MIT', :file => 'LICENSE.md' }