{"id":20980690,"url":"https://github.com/statful/statful-client-objc","last_synced_at":"2025-05-14T15:30:50.723Z","repository":{"id":56922208,"uuid":"63605283","full_name":"statful/statful-client-objc","owner":"statful","description":"Statful client to send metrics from macOS and iOS.","archived":false,"fork":false,"pushed_at":"2016-10-03T20:15:08.000Z","size":522,"stargazers_count":4,"open_issues_count":1,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-19T19:36:27.735Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/statful.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-18T13:28:09.000Z","updated_at":"2016-09-30T09:15:59.000Z","dependencies_parsed_at":"2022-08-21T04:50:22.236Z","dependency_job_id":null,"html_url":"https://github.com/statful/statful-client-objc","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-objc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-objc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-objc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-objc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statful","download_url":"https://codeload.github.com/statful/statful-client-objc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254171599,"owners_count":22026470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T05:29:38.771Z","updated_at":"2025-05-14T15:30:49.320Z","avatar_url":"https://github.com/statful.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Statful Client Objective-C\n\n[![Build Status](https://travis-ci.org/statful/statful-client-objc.svg?branch=master)](https://travis-ci.org/statful/statful-client-objc)\n\nStatful client for macOS and iOS written in Objective-C.\nThis client is intended to gather metrics and send them to the Statful service.\n\n[//]: # (Please check out our [website](http://statful.com) or our extended [documentation](http://statful.com/docs) for a comprehensive look at all features available on Statful.)\n\n## Table of Contents\n\n* [Supported Platforms](#supported-platforms)\n* [Installation](#installation)\n* [Quick Start](#quick-start)\n* [Examples](#examples)\n* [Reference](#reference)\n* [Still Need Help?](#still-need-help)\n* [Authors](#authors)\n* [License](#license)\n\n## Supported Platforms\n\n| Statful Client Version | Minimum iOS Target  | Minimum macOS Target  | Minimum watchOS Target  | Minimum tvOS Target  | Notes |\n|:---|:---|:---|:---|:---|:---|\n| 1.0.x | 8.0 | 10.8 | n/a | n/a | Xcode 7+ is required |\n\n\u003e **IMPORTANT:** Your project must support [64-bit with modern Cocoa runtime](https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ObjCRuntimeGuide/Articles/ocrtVersionsPlatforms.html).\n\n## Installation\nCurrently Statful Client Objective-C can only be installed with CocoaPods.\n\n### CocoaPods\n\nTo install it using [CocoaPods](http://cocoapods.org), a dependency manager for Objective-C, ensure you have CocoaPods installed and configured on your project. \nIf don't have it installed or configured in your project please check out [CocoaPods Documentation](https://guides.cocoapods.org).\n\n#### Podfile\n\nTo integrate Statful Client into your Xcode project using CocoaPods, add this line to your `Podfile`:\n\n```ruby\npod 'StatfulClientObjc', '~\u003e 1.0.0'\n```\n\nAnd then run the following command:\n\n```bash\n$ pod install\n```\n\n#### Including Statful Client\nAt this point you only need to include Statful Client into your project to start using it. \n\n```objc\n#import \u003cStatfulClient/SFClient.h\u003e\n```\n\n## Quick Start\nAfter installing Statful Client you are ready to use it. The quickest way is to do the following:\n\n```objc\n#import \u003cStatfulClient/SFClient.h\u003e\n\n// Creates a NSDictionary with configuration and pass it to the client\nNSDictionary *clientConfig = @{@\"transport\":@(SFClientTransportAPI), @\"token\": @\"YOUR_TOKEN_FOR_STATFUL_API\"};\nSFClient *statfulClient = [SFClient clientWithConfig:clientConfig];\n\n// Starts the client to begin buffering and send metrics\n// Any metric sent before the client start is ignored\n[statfulClient start];\n\n// Send a metric\n[statfulClient counterWithName:@\"testCounter\" value:@0];\n\n// Stop the client before exit your application to ensure you'll not loose metrics\n// Every metric in the buffer is sent when client stop is called\n[statfulClient stop];\n```\n\u003e **IMPORTANT:** This configuration uses the default **host** and **port**. You can learn more about configuration in [Reference](#api-reference).\n\n## Examples\nYou 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.\n\n### UDP Configuration\n\nCreates a simple UDP configuration for the client.\n\n```objc\nNSDictionary *clientConfig = @{ @\"app\": @\"AccountService\",\n                                @\"host\": @\"statful-relay.yourcompany.com\",\n                                @\"tags\": @{\n                                    @\"cluster\": @\"production\"\n                                },\n                                @\"transport\":@(SFClientTransportUDP)\n                             };\nSFClient *statfulClient = [SFClient clientWithConfig:clientConfig];\n```\n\n### HTTP Configuration\n\nCreates a simple HTTP API configuration for the client.\n\n```objc\nNSDictionary *clientConfig = @{ @\"app\": @\"AccountService\",\n                                @\"host\": @\"statful-relay.yourcompany.com\",\n                                @\"tags\": @{\n                                    @\"cluster\": @\"production\"\n                                },\n                                @\"token\": @\"YOUR_TOKEN_FOR_STATFUL_API\",\n                                @\"transport\":@(SFClientTransportAPI)\n                             };\nSFClient *statfulClient = [SFClient clientWithConfig:clientConfig];\n```\n\n### Logger Configuration\n\nCreates a simple client configuration and change some logger's definitions.\n\n```objc\nNSDictionary *clientConfig = @{ @\"host\": @\"statful-relay.yourcompany.com\",\n                                @\"logger\": [DDTTYLogger sharedInstance],\n                                @\"token\": @\"YOUR_TOKEN_FOR_STATFUL_API\",\n                                @\"transport\":@(SFClientTransportAPI)\n                             };\n                             \nSFClient *statfulClient = [SFClient clientWithConfig:clientConfig];\n                             \n// Logger was instantiated with DDTTYLogger, a default implementation of Xcode Console Logger already provided by CocoaLumberjack. \n// Also is always instantiated with lower available logger level: SFLoggerLogLevelError.\n// However you're able to change logger\nstatfulClient.logger.loggerLevel = SFLoggerLogLevelDebug;\n                             \n// You can also change the logger used by the client.\n// For doing that you have to provide a logger that inherits from DDAbstractLogger \u003cDDLogger\u003e\n// For example: \nstatfulClient.logger.logger = [DDTTYLogger sharedInstance];\n\n// Or \nDDFileLogger *fileLogger = [[DDFileLogger alloc] init];\nfileLogger.rollingFrequency = 60 * 60 * 24;\nfileLogger.logFileManager.maximumNumberOfLogFiles = 7;\nstatfulClient.logger.logger = fileLogger\n\n```\n\n### Defaults Configuration Per Method\n\nCreates a configuration for the client with custom default options per method.\n\n```objc\nNSDictionary *clientConfig = @{ @\"app\": @\"AccountService\",\n                                @\"defaults\": @{\n                                    @\"counter\": @{\n                                        @\"agg\": @[@\"avg\"],\n                                        @\"agg_freq\": @180\n                                    },\n                                    @\"gauge\": @{\n                                        @\"agg\": @[@\"first\"],\n                                        @\"agg_freq\": @180\n                                    },\n                                    @\"timer\": @{\n                                        @tags: @{\n                                            @\"cluster\": @\"qa\"\n                                        },\n                                        @\"agg\": @[@\"count\"],\n                                        @\"agg_freq\": @180\n                                    }\n                                },\n                                @\"host\": @\"statful-relay.yourcompany.com\",\n                                @\"tags\": @{\n                                    @\"cluster\": @\"production\"\n                                },\n                                @\"token\": @\"YOUR_TOKEN_FOR_STATFUL_API\",\n                                @\"transport\":@(SFClientTransportAPI)\n                             };\nSFClient *statfulClient = [SFClient clientWithConfig:clientConfig];\n```\n\n### Mixed Complete Configuration\n\nCreates a configuration defining a value for every available option.\n\n```objc\nNSDictionary *clientConfig = @{ @\"app\": @\"AccountService\",\n                                @\"defaults\": @{\n                                    @\"timer\": @{\n                                        @tags: @{\n                                            @\"cluster\": @\"qa\"\n                                        },\n                                        @\"agg\": @[@\"count\"],\n                                        @\"agg_freq\": @180\n                                    }\n                                },\n                                @\"dryrun\": @YES,\n                                @\"flush_interval\": @5000,\n                                @\"flush_size\": @50,\n                                @\"host\": @\"statful-relay.yourcompany.com\",\n                                @\"logger\": [DDTTYLogger sharedInstance],\n                                @\"namespace\": @\"application\",\n                                @\"port\": @\"123\",\n                                @\"sample_rate\": @95,\n                                @\"secure\": @NO,\n                                @\"tags\": @{\n                                    @\"cluster\": @\"production\"\n                                },\n                                @\"timeout\": @300,\n                                @\"token\": @\"YOUR_TOKEN_FOR_STATFUL_API\",\n                                @\"transport\": @(SFClientTransportAPI)\n                             };\nSFClient *statfulClient = [SFClient clientWithConfig:clientConfig];\n```\n\n### Add Metrics\n\nCreates a simple client configuration and use it to send some metrics.\n\n```objc\nNSDictionary *clientConfig = @{ @\"host\": @\"statful-relay.yourcompany.com\",\n                                @\"token\": @\"YOUR_TOKEN_FOR_STATFUL_API\",\n                                @\"transport\":@(SFClientTransportAPI)\n                             };\nSFClient *statfulClient = [SFClient clientWithConfig:clientConfig];\n\n// Ignored metric\n[statfulClient gaugeWithName:@\"testTimer\" value:@0];\n\n[statfulClient start];\n\n// Send three different metrics (gauge, timer and a counter)\n// Attention: calling method gaugeWithName:value is equal to \n// calling gaugeWithName:value:options with null options\n[statfulClient gaugeWithName:@\"testTimer\" value:@0];\n[statfulClient timerWithName:@\"testTimer\" value:@0 options:nil];\n[statfulClient timerWithName:@\"testTimer\" value:@0 options:@{@\"agg\": @[@\"first\"],\n                                                             @\"agg_freq\": @60\n                                                            }];\n                                                            \n// Metric to be sent with more custom options like timestamp instead of current timestamp\n[statfulClient timerWithName:@\"testTimer\" value:@0 options:@{@\"tags\": @{\n                                                                @\"cluster\": @\"sandbox\"\n                                                             },\n                                                             @\"agg\": @[@\"last\"],\n                                                             @\"agg_freq\": @60\n                                                             @\"namespace\": @\"sandbox\"\n                                                             @\"timestamp\": @\"1469714440\"\n                                                            }];\n                                                            \n[statfulClient stop];\n\n// Ignored metric\n[statfulClient gaugeWithName:@\"testTimer\" value:@0];\n\n```\n\n## Reference \n\nOur Statful Client API it's very simple. You can browse the full reference below.\n\n### Client\n\nThe Client used to send metrics for the system.\n\n#### Class \n`SFClient`\n\n#### Enumerated Types\n\n##### SFClientTransport\n\n| Type | Description |\n|:---|:---|\n| `SFClientTransportAPI` | An enumerated type that defines API transport. It makes the client send the metrics through a HTTP API. |\n| `SFClientTransportUDP` | An enumerated type that defines UDP transport. It makes the client send the metrics through an UDP socket. |\n\n#### Methods\n\n```objc\n+ (instancetype)clientWithConfig:(NSDictionary*)config\n```\n\nThis is a class method that receives a `NSDictionary *` with configuration  and returns a new `SFClient`.\nThe custom options that can be set on config param are detailed below.\n\n| Option | Description | Type | Default | Required |\n|:---|:---|:---|:---|:---|\n| _app_ | Defines the application global option. If specified sets a global tag `app=settedValue`. | `NSString*` | **none** | **NO** |\n| _defaults_ | Defines the global default options per method. | `NSDictionary*` | `@{}` | **NO** |\n| _dryrun_ | Defines if metrics should be outputed to the logger instead of being sent. | `NSNumber*` | `@NO` | **NO** |\n| _flush_interval_ | Defines the periodicity of buffer flush in **miliseconds**. | `NSNumber*` | `@10000` | **NO** |\n| _flush_size_ | Defines the number of metrics that the buffer should have to make a flush. | `NSNumber*` | `@10` | **NO** |\n| _host_ | Defines the host for which metrics should be sent. | `NSString*` | `@\"127.0.0.1\"` | **NO** |\n| _logger_ | Defines the internal logger instance according to `DDLogger` protocol from [CocoaLumberjack](https://github.com/CocoaLumberjack/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 \u003cDDLogger\u003e` from CocoaLumberjack. | `DDAbstractLogger \u003cDDLogger\u003e *` | **none** | **NO** |\n| _namespace_ | Defines the global namespace. | `NSString*` | `@\"application\"` | **NO** |\n| _port_ | Defines the host por for which metrics should be sent. | `NSString*` | `@\"2013\"` | **NO** |\n| _sample_rate_ | Defines the rate sampling. **Should be a number between [1, 100]**. | `NSNumber*` | `@100` | **NO** |\n| _secure_ | Enable or disable https protocol. | `NSNumber*` | `@\"true\"` | **NO** |\n| _tags_ | Defines the global tags. | `NSDictionary*` | `@{}` | **NO** |\n| _timeout_ | Defines the timeout for the transport layers in **miliseconds**. | `NSNumber*` | `@2000` | **NO** |\n| _token_ | Defines the token to be used  `SFClientTransportAPI`.  | `NSString*` | **none** | **NO** |\n| _transport_ | Defines the transport layer to be used to send metrics.\u003cbr\u003e\u003cbr\u003e **Valid Transports:** `SFClientTransportAPI, SFClientTransportUDP` | `NSNumber*` | **none** | **YES** |\n\n```objc\n- (BOOL)start\n```\n\nThis method tries to start the client and returns a boolean. If it succeeds it becomes possible send metrics. \n\n```objc\n- (BOOL)stop\n```\n\nThis 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. \n\n```objc\n- (void)counterWithName:(NSString*)name value:(NSNumber*)value\n- (void)gaugeWithName:(NSString*)name value:(NSNumber*)value\n- (void)timerWithName:(NSString*)name value:(NSNumber*)value\n```\n\nThese method receives a string name and a number value and sends a simple counter/gauge/timer metric (with default method options).\nRead the reference of methods with options params to know the defaults.\n\n```objc\n- (void)counterWithName:(NSString*)name value:(NSNumber*)value options:(NSDictionary*)options\n- (void)gaugeWithName:(NSString*)name value:(NSNumber*)value options:(NSDictionary*)options\n- (void)timerWithName:(NSString*)name value:(NSNumber*)value options:(NSDictionary*)options\n```\n\nThese method receives a string name, a number value, a dictionary with options and sends a counter/gauge/timer metric with custom options.\nThe custom options that can be set on options param are detailed below.\n\n| Option | Description | Type | Default for Counter | Default for Gauge | Default for Timer |\n|:---|:---|:---|:---|:---|:---|\n| _agg_ | Defines the aggregations to send with metric. It merges with priority with previous defined default per method aggregations on client configuration.\u003cbr\u003e\u003cbr\u003e **Valid Aggregations:** `@\"avg\", @\"count\", @\"sum\", @\"first\", @\"last\", @\"p90\", @\"p95\", @\"min\", @\"max\"` | `NSArray*` | `@[@\"avg\", @\"p90\"]` | `@[@\"last\"]` | `@[@\"avg\", @\"p90\", @\"count\"]` |\n| _agg_freq_ | Defines the aggregation frequency in **seconds** of the metric. It replaces the previous defined default per method aggregation frequency on client configuration.\u003cbr\u003e\u003cbr\u003e **Valid Aggregation Frequencies:** `@10, @30, @60 ,@120, @180, @300` | `NSNumber*` | `@10` | `@10` | `@10` |\n| _namespace_ | Defines the namespace to send with metric. It replaces the previous defined global namespace on client configuration. | `NSString*` | `@\"application\"` | `@\"application\"` | `@\"application\"` |\n| _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\"}` |\n| _timestamp_ | Defines the timestamp of the metric. This timestamp is a **POSIX/Epoch** time in **seconds**. | `NSString*` | `current timestamp` | `current timestamp` | `current timestamp` |\n\n#### Properties\n\n| Property | Type | Description | Access  |\n|:---|:---|:---|:---|\n| _logger_ | `SFLogger*` | The logger object used by client. | **readonly** |\n| _isConfigValid_ | `BOOL` | A boolean value indicating whether the setted config is valid. | **readonly** |\n| _isStarted_ | `BOOL` | A boolean value indicating whether the client is started. | **readonly** |\n\n### Logger\n\nThe Logger used by Statful Client Objective-c is a simple encapsulation for the [CocoaLumberjack](https://github.com/CocoaLumberjack/CocoaLumberjack) logger. \n\n#### Class \n`SFLogger`\n\n#### Enumerated Types\n\n##### SFLoggerLogLevel\n\n| Type | Description |\n|:---|:---|\n| `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. |\n| `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. |\n| `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. |\n\n#### Methods\n\n```objc\n+ (instancetype)loggerWithDDLoggerInstance:(DDAbstractLogger \u003cDDLogger\u003e *)logger loggerLevel:(SFLoggerLogLevel)loggerLevel\n```\n\nThis is a class method that receives a `DDAbstractLogger \u003cDDLogger\u003e *` and a `SFLoggerLogLevel` and returns a new `SFLogger`.\n\n```objc\n- (void)logDebug:(id)format, ...\n```\n\nThis method receives a string format followed by the format params (seperated by commas) and sends a new **debug** message to be logged.\n\n```objc\n- (void)logError:(id)format, ...\n```\n\nThis method receives a string format followed by the format params (seperated by commas) and sends a new **error** message to be logged.\n\n```objc\n- (void)logVerbose:(id)format, ...\n```\n\nThis method receives a string format followed by the format params (seperated by commas) and sends a new **verbose** message to be logged.\n\n#### Properties\n\n| Property | Type | Description | Access  |\n|:---|:---|:---|:---|\n| _logger_ | `DDAbstractLogger \u003cDDLogger\u003e *` | The internal logger instance according DDLogger protocol from [CocoaLumberjack](https://github.com/CocoaLumberjack/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 \u003cDDLogger\u003e` from CocoaLumberjack. | **readwrite** |\n| _loggerLevel_ | `SFLoggerLogLevel ` | The logger level used to select which messages should be outputed. It can be  | **readwrite** |\n\n\n## Still Need Help?\n[//]: # (If you are feeling that you're still needing help, please visit our oficial full [Statful Documentation](http://statful.com/docs) page.)\n\nIf you are feeling that you're still needing help, please visit our oficial full Statful Documentation page.\n\n## Authors\n\n[Mindera - Software Craft](https://github.com/Mindera)\n\n## License\n\nStatful Obj-C Client is available under the MIT license. See the [LICENSE](https://raw.githubusercontent.com/statful/statful-client-objc/master/LICENSE) file for more info.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatful%2Fstatful-client-objc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatful%2Fstatful-client-objc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatful%2Fstatful-client-objc/lists"}