Statful client for macOS and iOS written in Objective-C. This client is intended to gather metrics and send them to the Statful service.
[//]: # (Please check out our website or our extended documentation for a comprehensive look at all features available on Statful.)
| Statful Client Version | Minimum iOS Target | Minimum macOS Target | Minimum watchOS Target | Minimum tvOS Target | Notes |
|---|---|---|---|---|---|
| 1.0.x | 8.0 | 10.8 | n/a | n/a | Xcode 7+ is required |
IMPORTANT: Your project must support 64-bit with modern Cocoa runtime.
Currently Statful Client Objective-C can only be installed with CocoaPods.
To install it using CocoaPods, a dependency manager for Objective-C, ensure you have CocoaPods installed and configured on your project. If don't have it installed or configured in your project please check out CocoaPods Documentation.
To integrate Statful Client into your Xcode project using CocoaPods, add this line to your Podfile:
pod 'StatfulClientObjc', '~> 1.0.0'And then run the following command:
$ pod installAt this point you only need to include Statful Client into your project to start using it.
#import <StatfulClient/SFClient.h>After installing Statful Client you are ready to use it. The quickest way is to do the following:
#import <StatfulClient/SFClient.h>
// Creates a NSDictionary with configuration and pass it to the client
NSDictionary *clientConfig = @{@"transport":@(SFClientTransportAPI), @"token": @"YOUR_TOKEN_FOR_STATFUL_API"};
SFClient *statfulClient = [SFClient clientWithConfig:clientConfig];
// Starts the client to begin buffering and send metrics
// Any metric sent before the client start is ignored
[statfulClient start];
// Send a metric
[statfulClient counterWithName:@"testCounter" value:@0];
// Stop the client before exit your application to ensure you'll not loose metrics
// Every metric in the buffer is sent when client stop is called
[statfulClient stop];IMPORTANT: This configuration uses the default host and port. You can learn more about configuration in Reference.
You can find here some useful usage examples of the Statful Client. In the following examples is assumed you have already installed and included Statful Client in your project.
Creates a simple UDP configuration for the client.
NSDictionary *clientConfig = @{ @"app": @"AccountService",
@"host": @"statful-relay.yourcompany.com",
@"tags": @{
@"cluster": @"production"
},
@"transport":@(SFClientTransportUDP)
};
SFClient *statfulClient = [SFClient clientWithConfig:clientConfig];Creates a simple HTTP API configuration for the client.
NSDictionary *clientConfig = @{ @"app": @"AccountService",
@"host": @"statful-relay.yourcompany.com",
@"tags": @{
@"cluster": @"production"
},
@"token": @"YOUR_TOKEN_FOR_STATFUL_API",
@"transport":@(SFClientTransportAPI)
};
SFClient *statfulClient = [SFClient clientWithConfig:clientConfig];Creates a simple client configuration and change some logger's definitions.
NSDictionary *clientConfig = @{ @"host": @"statful-relay.yourcompany.com",
@"logger": [DDTTYLogger sharedInstance],
@"token": @"YOUR_TOKEN_FOR_STATFUL_API",
@"transport":@(SFClientTransportAPI)
};
SFClient *statfulClient = [SFClient clientWithConfig:clientConfig];
// Logger was instantiated with DDTTYLogger, a default implementation of Xcode Console Logger already provided by CocoaLumberjack.
// Also is always instantiated with lower available logger level: SFLoggerLogLevelError.
// However you're able to change logger
statfulClient.logger.loggerLevel = SFLoggerLogLevelDebug;
// You can also change the logger used by the client.
// For doing that you have to provide a logger that inherits from DDAbstractLogger <DDLogger>
// For example:
statfulClient.logger.logger = [DDTTYLogger sharedInstance];
// Or
DDFileLogger *fileLogger = [[DDFileLogger alloc] init];
fileLogger.rollingFrequency = 60 * 60 * 24;
fileLogger.logFileManager.maximumNumberOfLogFiles = 7;
statfulClient.logger.logger = fileLogger
Creates a configuration for the client with custom default options per method.
NSDictionary *clientConfig = @{ @"app": @"AccountService",
@"defaults": @{
@"counter": @{
@"agg": @[@"avg"],
@"agg_freq": @180
},
@"gauge": @{
@"agg": @[@"first"],
@"agg_freq": @180
},
@"timer": @{
@tags: @{
@"cluster": @"qa"
},
@"agg": @[@"count"],
@"agg_freq": @180
}
},
@"host": @"statful-relay.yourcompany.com",
@"tags": @{
@"cluster": @"production"
},
@"token": @"YOUR_TOKEN_FOR_STATFUL_API",
@"transport":@(SFClientTransportAPI)
};
SFClient *statfulClient = [SFClient clientWithConfig:clientConfig];Creates a configuration defining a value for every available option.
NSDictionary *clientConfig = @{ @"app": @"AccountService",
@"defaults": @{
@"timer": @{
@tags: @{
@"cluster": @"qa"
},
@"agg": @[@"count"],
@"agg_freq": @180
}
},
@"dryrun": @YES,
@"flush_interval": @5000,
@"flush_size": @50,
@"host": @"statful-relay.yourcompany.com",
@"logger": [DDTTYLogger sharedInstance],
@"namespace": @"application",
@"port": @"123",
@"sample_rate": @95,
@"secure": @NO,
@"tags": @{
@"cluster": @"production"
},
@"timeout": @300,
@"token": @"YOUR_TOKEN_FOR_STATFUL_API",
@"transport": @(SFClientTransportAPI)
};
SFClient *statfulClient = [SFClient clientWithConfig:clientConfig];Creates a simple client configuration and use it to send some metrics.
NSDictionary *clientConfig = @{ @"host": @"statful-relay.yourcompany.com",
@"token": @"YOUR_TOKEN_FOR_STATFUL_API",
@"transport":@(SFClientTransportAPI)
};
SFClient *statfulClient = [SFClient clientWithConfig:clientConfig];
// Ignored metric
[statfulClient gaugeWithName:@"testTimer" value:@0];
[statfulClient start];
// Send three different metrics (gauge, timer and a counter)
// Attention: calling method gaugeWithName:value is equal to
// calling gaugeWithName:value:options with null options
[statfulClient gaugeWithName:@"testTimer" value:@0];
[statfulClient timerWithName:@"testTimer" value:@0 options:nil];
[statfulClient timerWithName:@"testTimer" value:@0 options:@{@"agg": @[@"first"],
@"agg_freq": @60
}];
// Metric to be sent with more custom options like timestamp instead of current timestamp
[statfulClient timerWithName:@"testTimer" value:@0 options:@{@"tags": @{
@"cluster": @"sandbox"
},
@"agg": @[@"last"],
@"agg_freq": @60
@"namespace": @"sandbox"
@"timestamp": @"1469714440"
}];
[statfulClient stop];
// Ignored metric
[statfulClient gaugeWithName:@"testTimer" value:@0];
Our Statful Client API it's very simple. You can browse the full reference below.
The Client used to send metrics for the system.
SFClient
| Type | Description |
|---|---|
SFClientTransportAPI |
An enumerated type that defines API transport. It makes the client send the metrics through a HTTP API. |
SFClientTransportUDP |
An enumerated type that defines UDP transport. It makes the client send the metrics through an UDP socket. |
+ (instancetype)clientWithConfig:(NSDictionary*)configThis is a class method that receives a NSDictionary * with configuration and returns a new SFClient.
The custom options that can be set on config param are detailed below.
| Option | Description | Type | Default | Required |
|---|---|---|---|---|
| app | Defines the application global option. If specified sets a global tag app=settedValue. |
NSString* |
none | NO |
| defaults | Defines the global default options per method. | NSDictionary* |
@{} |
NO |
| dryrun | Defines if metrics should be outputed to the logger instead of being sent. | NSNumber* |
@NO |
NO |
| flush_interval | Defines the periodicity of buffer flush in miliseconds. | NSNumber* |
@10000 |
NO |
| flush_size | Defines the number of metrics that the buffer should have to make a flush. | NSNumber* |
@10 |
NO |
| host | Defines the host for which metrics should be sent. | NSString* |
@"127.0.0.1" |
NO |
| logger | Defines the internal logger instance according to DDLogger protocol from CocoaLumberjack used by SFLogger to output the messages. It can be one already defined by CocoaLumberjack like DTTYLogger, DDASLLogger, DDFileLogger or any other custom logger object that complies with DDAbstractLogger <DDLogger> from CocoaLumberjack. |
DDAbstractLogger <DDLogger> * |
none | NO |
| namespace | Defines the global namespace. | NSString* |
@"application" |
NO |
| port | Defines the host por for which metrics should be sent. | NSString* |
@"2013" |
NO |
| sample_rate | Defines the rate sampling. Should be a number between [1, 100]. | NSNumber* |
@100 |
NO |
| secure | Enable or disable https protocol. | NSNumber* |
@"true" |
NO |
| tags | Defines the global tags. | NSDictionary* |
@{} |
NO |
| timeout | Defines the timeout for the transport layers in miliseconds. | NSNumber* |
@2000 |
NO |
| token | Defines the token to be used SFClientTransportAPI. |
NSString* |
none | NO |
| transport | Defines the transport layer to be used to send metrics. Valid Transports: SFClientTransportAPI, SFClientTransportUDP |
NSNumber* |
none | YES |
- (BOOL)startThis method tries to start the client and returns a boolean. If it succeeds it becomes possible send metrics.
- (BOOL)stopThis method tries to stop the client and also send all the metrics still in the buffer returning a boolean. If it succeeds it becomes impossible send metrics.
- (void)counterWithName:(NSString*)name value:(NSNumber*)value
- (void)gaugeWithName:(NSString*)name value:(NSNumber*)value
- (void)timerWithName:(NSString*)name value:(NSNumber*)valueThese method receives a string name and a number value and sends a simple counter/gauge/timer metric (with default method options). Read the reference of methods with options params to know the defaults.
- (void)counterWithName:(NSString*)name value:(NSNumber*)value options:(NSDictionary*)options
- (void)gaugeWithName:(NSString*)name value:(NSNumber*)value options:(NSDictionary*)options
- (void)timerWithName:(NSString*)name value:(NSNumber*)value options:(NSDictionary*)optionsThese method receives a string name, a number value, a dictionary with options and sends a counter/gauge/timer metric with custom options. The custom options that can be set on options param are detailed below.
| Option | Description | Type | Default for Counter | Default for Gauge | Default for Timer |
|---|---|---|---|---|---|
| agg | Defines the aggregations to send with metric. It merges with priority with previous defined default per method aggregations on client configuration. Valid Aggregations: @"avg", @"count", @"sum", @"first", @"last", @"p90", @"p95", @"min", @"max" |
NSArray* |
@[@"avg", @"p90"] |
@[@"last"] |
@[@"avg", @"p90", @"count"] |
| agg_freq | Defines the aggregation frequency in seconds of the metric. It replaces the previous defined default per method aggregation frequency on client configuration. Valid Aggregation Frequencies: @10, @30, @60 ,@120, @180, @300 |
NSNumber* |
@10 |
@10 |
@10 |
| namespace | Defines the namespace to send with metric. It replaces the previous defined global namespace on client configuration. | NSString* |
@"application" |
@"application" |
@"application" |
| tags | Defines the tags to send with metric. It merges with priority with previous defined global tags and default per method tags on client configuration. | NSDictionary* |
@{} |
@{} |
@{@"unit": @"ms"} |
| timestamp | Defines the timestamp of the metric. This timestamp is a POSIX/Epoch time in seconds. | NSString* |
current timestamp |
current timestamp |
current timestamp |
| Property | Type | Description | Access |
|---|---|---|---|
| logger | SFLogger* |
The logger object used by client. | readonly |
| isConfigValid | BOOL |
A boolean value indicating whether the setted config is valid. | readonly |
| isStarted | BOOL |
A boolean value indicating whether the client is started. | readonly |
The Logger used by Statful Client Objective-c is a simple encapsulation for the CocoaLumberjack logger.
SFLogger
| Type | Description |
|---|---|
SFLoggerLogLevelError |
An enumerated type that defines the Error logger's level. This is the most restrict logger level that forces logger to only output error messages. |
SFLoggerLogLevelDebug |
An enumerated type that defines the Debug logger's level. This is the intermediate logger level that forces logger to output debug messages but also error messages. |
SFLoggerLogLevelVerbose |
An enumerated type that defines the Verbose logger's level. This is the least restrict logger level that forces logger to output all kind of messages. |
+ (instancetype)loggerWithDDLoggerInstance:(DDAbstractLogger <DDLogger> *)logger loggerLevel:(SFLoggerLogLevel)loggerLevelThis is a class method that receives a DDAbstractLogger <DDLogger> * and a SFLoggerLogLevel and returns a new SFLogger.
- (void)logDebug:(id)format, ...This method receives a string format followed by the format params (seperated by commas) and sends a new debug message to be logged.
- (void)logError:(id)format, ...This method receives a string format followed by the format params (seperated by commas) and sends a new error message to be logged.
- (void)logVerbose:(id)format, ...This method receives a string format followed by the format params (seperated by commas) and sends a new verbose message to be logged.
| Property | Type | Description | Access |
|---|---|---|---|
| logger | DDAbstractLogger <DDLogger> * |
The internal logger instance according DDLogger protocol from CocoaLumberjack used by SFLogger to output messages. It can be one already defined by CocoaLumberjack like DTTYLogger, DDASLLogger, DDFileLogger or any other custom logger object that complies with DDAbstractLogger <DDLogger> from CocoaLumberjack. |
readwrite |
| loggerLevel | SFLoggerLogLevel |
The logger level used to select which messages should be outputed. It can be | readwrite |
[//]: # (If you are feeling that you're still needing help, please visit our oficial full Statful Documentation page.)
If you are feeling that you're still needing help, please visit our oficial full Statful Documentation page.
Statful Obj-C Client is available under the MIT license. See the LICENSE file for more info.