2 * Copyright (c) 2017 Apple Inc. All Rights Reserved.
4 * @APPLE_LICENSE_HEADER_START@
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
21 * @APPLE_LICENSE_HEADER_END@
28 #import <Foundation/Foundation.h>
29 #import <Security/SFAnalyticsSampler.h>
30 #import <Security/SFAnalyticsMultiSampler.h>
31 #import <Security/SFAnalyticsActivityTracker.h>
33 NS_ASSUME_NONNULL_BEGIN
35 // this sampling interval will cause the sampler to run only at data reporting time
36 extern const NSTimeInterval SFAnalyticsSamplerIntervalOncePerReport
;
38 typedef NS_ENUM(uint32_t, SFAnalyticsTimestampBucket
) {
39 SFAnalyticsTimestampBucketSecond
= 0,
40 SFAnalyticsTimestampBucketMinute
= 1,
41 SFAnalyticsTimestampBucketHour
= 2,
44 @protocol SFAnalyticsProtocol
<NSObject
>
45 + (id
<SFAnalyticsProtocol
> _Nullable
)logger
;
47 - (void)logResultForEvent
:(NSString
*)eventName
48 hardFailure
:(bool)hardFailure
49 result
:(NSError
* _Nullable
)eventResultError
;
50 - (void)logResultForEvent
:(NSString
*)eventName
51 hardFailure
:(bool)hardFailure
52 result
:(NSError
* _Nullable
)eventResultError
53 withAttributes
:(NSDictionary
* _Nullable
)attributes
;
55 - (SFAnalyticsMultiSampler
* _Nullable
)AddMultiSamplerForName
:(NSString
*)samplerName
56 withTimeInterval
:(NSTimeInterval
)timeInterval
57 block
:(NSDictionary
<NSString
*,NSNumber
*> *(^)(void))block
;
59 - (SFAnalyticsActivityTracker
* _Nullable
)logSystemMetricsForActivityNamed
:(NSString
*)eventName
60 withAction
:(void (^ _Nullable
)(void))action
;
61 - (SFAnalyticsActivityTracker
* _Nullable
)startLogSystemMetricsForActivityNamed
:(NSString
*)eventName
;
64 @interface SFAnalytics
: NSObject
<SFAnalyticsProtocol
>
66 + (instancetype _Nullable
)logger
;
68 + (NSInteger
)fuzzyDaysSinceDate
:(NSDate
*)date
;
69 + (void)addOSVersionToEvent
:(NSMutableDictionary
*)event
;
70 // Help for the subclass to pick a prefered location
71 + (NSString
*)defaultAnalyticsDatabasePath
:(NSString
*)basename
;
73 + (NSString
*)defaultProtectedAnalyticsDatabasePath
:(NSString
*)basename uuid
:(NSUUID
* __nullable
)userUuid
;
74 + (NSString
*)defaultProtectedAnalyticsDatabasePath
:(NSString
*)basename
; // uses current user UUID for path
76 - (void)dailyCoreAnalyticsMetrics
:(NSString
*)eventName
;
78 // Log event-based metrics: create an event corresponding to some event in your feature
79 // and call the appropriate method based on the successfulness of that event
80 - (void)logSuccessForEventNamed
:(NSString
*)eventName
;
81 - (void)logSuccessForEventNamed
:(NSString
*)eventName timestampBucket
:(SFAnalyticsTimestampBucket
)timestampBucket
;
83 - (void)logHardFailureForEventNamed
:(NSString
*)eventName withAttributes
:(NSDictionary
* _Nullable
)attributes
;
84 - (void)logHardFailureForEventNamed
:(NSString
*)eventName withAttributes
:(NSDictionary
* _Nullable
)attributes timestampBucket
:(SFAnalyticsTimestampBucket
)timestampBucket
;
86 - (void)logSoftFailureForEventNamed
:(NSString
*)eventName withAttributes
:(NSDictionary
* _Nullable
)attributes
;
87 - (void)logSoftFailureForEventNamed
:(NSString
*)eventName withAttributes
:(NSDictionary
* _Nullable
)attributes timestampBucket
:(SFAnalyticsTimestampBucket
)timestampBucket
;
89 // or just log an event if it is not failable
90 - (void)noteEventNamed
:(NSString
*)eventName
;
91 - (void)noteEventNamed
:(NSString
*)eventName timestampBucket
:(SFAnalyticsTimestampBucket
)timestampBucket
;
93 - (void)logResultForEvent
:(NSString
*)eventName
94 hardFailure
:(bool)hardFailure
95 result
:(NSError
* _Nullable
)eventResultError
;
96 - (void)logResultForEvent
:(NSString
*)eventName
97 hardFailure
:(bool)hardFailure
98 result
:(NSError
* _Nullable
)eventResultError
99 timestampBucket
:(SFAnalyticsTimestampBucket
)timestampBucket
;
100 - (void)logResultForEvent
:(NSString
*)eventName
101 hardFailure
:(bool)hardFailure
102 result
:(NSError
* _Nullable
)eventResultError
103 withAttributes
:(NSDictionary
* _Nullable
)attributes
;
104 - (void)logResultForEvent
:(NSString
*)eventName
105 hardFailure
:(bool)hardFailure
106 result
:(NSError
* _Nullable
)eventResultError
107 withAttributes
:(NSDictionary
* _Nullable
)attributes
108 timestampBucket
:(SFAnalyticsTimestampBucket
)timestampBucket
;
110 // Track the state of a named value over time
111 - (SFAnalyticsSampler
* _Nullable
)addMetricSamplerForName
:(NSString
*)samplerName
112 withTimeInterval
:(NSTimeInterval
)timeInterval
113 block
:(NSNumber
* (^)(void))block
;
114 - (SFAnalyticsSampler
* _Nullable
)existingMetricSamplerForName
:(NSString
*)samplerName
;
115 - (void)removeMetricSamplerForName
:(NSString
*)samplerName
;
116 // Same idea, but log multiple named values in a single block
117 - (SFAnalyticsMultiSampler
* _Nullable
)AddMultiSamplerForName
:(NSString
*)samplerName
118 withTimeInterval
:(NSTimeInterval
)timeInterval
119 block
:(NSDictionary
<NSString
*, NSNumber
*>* (^)(void))block
;
120 - (SFAnalyticsMultiSampler
*)existingMultiSamplerForName
:(NSString
*)samplerName
;
121 - (void)removeMultiSamplerForName
:(NSString
*)samplerName
;
123 // Log measurements of arbitrary things
124 // System metrics measures how much time it takes to complete the action - possibly more in the future. The return value can be ignored if you only need to execute 1 block for your activity
125 - (SFAnalyticsActivityTracker
* _Nullable
)logSystemMetricsForActivityNamed
:(NSString
*)eventName
126 withAction
:(void (^ _Nullable
)(void))action
;
128 // Same as above, but automatically starts the tracker, since you haven't given it any action to perform
129 - (SFAnalyticsActivityTracker
* _Nullable
)startLogSystemMetricsForActivityNamed
:(NSString
*)eventName
;
131 - (void)logMetric
:(NSNumber
*)metric withName
:(NSString
*)metricName
;
134 // --------------------------------
135 // Things below are for subclasses
137 // Override to create a concrete logger instance
138 @
property (readonly
, class, nullable
) NSString
* databasePath
;
141 - (void)setDateProperty
:(NSDate
* _Nullable
)date forKey
:(NSString
*)key
;
142 - (NSDate
* _Nullable
)datePropertyForKey
:(NSString
*)key
;
144 - (void)incrementIntegerPropertyForKey
:(NSString
*)key
;
145 - (void)setNumberProperty
:(NSNumber
* _Nullable
)number forKey
:(NSString
*)key
;
146 - (NSNumber
* _Nullable
)numberPropertyForKey
:(NSString
*)key
;
149 // --------------------------------
150 // Things below are for unit testing
152 - (void)removeState
; // removes DB object and any samplers
156 NS_ASSUME_NONNULL_END