Make configuration a little less dependant on Sentry being set up (#104)

* move sentry config options into their own struct
make sentry integration more optional

* move sentry config outside of other config object

* missed removing sentryconfig from config constructor

* add attach function to add custom log destinations

* add trace sample rate to sentry config

* add readme info for traces sample rate

Author: brendanlensink

CHANGELOG.md

@@ -4,7 +4,8 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Un-released
+## [2.0.0]
+- Split Sentry configuration into a separate, optional struct to make not using Sentry a little easier
 - Updated LogLevelPreset names and mapped LogLevels (#91)
 
 ## [0.5.4]

README.md

@@ -50,28 +50,52 @@ _Firebase Crashlytics is no longer a supported destination for crash reporting_
 
 SteamcLog has a number of configuration options
 
-### logLevel: LogLevelPreset
+#### logLevel: LogLevelPreset
 Destination logging levels; it is recommended to use the defaults set by Steamclog instead of initializing these manually. In special cases where more data is desired, update this property. See technical documentation for more details on the available presets.
 
-### requireRedacted: Bool
+#### requireRedacted: Bool
 Default value is `false`.
 Require that all logged objects conform to Redacted or are all redacted by default.
 
-### autoRotateConfig: AutoRotateConfig
+#### autoRotateConfig: AutoRotateConfig
 By default, logs will rotate every 10 minutes, and store 10 archived log files.
 `AutoRotateConfig` allows customization for the auto-rotating behaviour. 
 
 `AutoRotateConfig` has the following fields:
 **fileRotationTime: TimeInterval**: The number of seconds before the log file is rotated and archived.
 
-### sentryFilter: SentryFilter
+Additionally, SteamcLog comes with support to log to Sentry:
+
+### Sentry configuration options
+
+#### key: String
+Your Sentry key
+
+#### attachStackTrace: Bool
+Default value is `true`.
+Toggles Sentry automatically attaching stack traces to error reports.
+
+#### autoSessionTracking: Bool
+Default value is `true`.
+Toggle's Sentry's auto session tracking. More info [here](https://docs.sentry.io/platforms/cocoa/?platform=swift#release-health).
+
+#### debug: Bool
+Default value is `false`.
+Sets Sentry to debug mode. More info [here](https://docs.sentry.io/error-reporting/configuration/?platform=swift#debug)
+
+#### tracesSampleRate: NSNumber
+Default value is 0.0.
+Sets the percentage of the tracing data that is collected by Sentry. Values must be between 0 and 1, and values larger than 1 will be set to 1.
+Note that setting this to anything greater than 0 can cause projects to blow past their usage quotas by generating far more events than normal.
+
+#### filter: SentryFilter
 By default, all error objects will be sent to Sentry when submitted via the `error` call. 
-`SentryFilter` allows you to change this behaviour at the SteamcLog Config-level.
+This allows you to change this behaviour at the SteamcLog Config-level, by passing in a function that filters errors from being logged.
 
 ```swift
-Config(
+SentryConfig(
     // other fields
-    sentryFilter: { error in
+    filter: { error in
         if let error = error as? CustomError {
             return true // CustomError errors will no longer be submitted to Sentry
         }
@@ -125,6 +149,10 @@ And the log will output:
 
 `User(name: "Name", uuid: <redacted>, email: "hi@steamclock.com", created: <redacted>)`
 
+## Custom Log Destinations
+
+In addition to the Sentry log destination that comes packaged with SteamcLog, you can create your own log destination and attach it to your SteamcLog instance using `attach`.
+
 ## Using SteamcLog with Netable
 
 If you're also using [Netable](https://github.com/steamclock/netable), you can pipe your logs directly from Netable into SteamcLog.

SteamcLog.podspec

@@ -8,7 +8,7 @@
 
 Pod::Spec.new do |s|
   s.name             = 'SteamcLog'
-  s.version          = '1.0.1'
+  s.version          = '2.0.0'
   s.summary          = 'A short description of SteamcLog.'
 
 # This description is used to generate tags and improve search results.

SteamcLog/Classes/Helper/Config.swift

@@ -21,54 +21,23 @@ public struct Config {
     /// Require that all logged objects conform to Redacted or are all redacted by default.
     @usableFromInline internal let requireRedacted: Bool
 
-    /// Sentry project specific key. Found here: https://docs.sentry.io/platforms/cocoa/?platform=swift
-    /// Set this key to an empty string to not report logs to Sentry.
-    internal let sentryKey: String
-
-    /// Debug mode for Sentry SDK. Default is false.
-    /// More info here: https://docs.sentry.io/error-reporting/configuration/?platform=swift#debug
-    internal let sentryDebug: Bool
-
-    /// Toggles Sentry auto session tracking. Default is false.
-    /// More info here: https://docs.sentry.io/platforms/cocoa/?platform=swift#release-health
-    internal let sentryAutoSessionTracking: Bool
-
-    /// Toggles Sentry attaching stack traces  to errors. Default is true.
-    internal let sentryAttachStacktrace: Bool
-
-    /// Toggles the ability to filter out errors from being reported to Sentry
-    internal let sentryFilter: SentryFilter
-
     /*
      * Create a new SteamcLog configuration to use.
      *
      * - Parameters:
-     *   - sentryKey: Sentry project key, needed to initialize SentrySDK.
      *   - logLevel: The log level presets for each destination. Default is `.develop`.
      *   - requireRedacted: If true, all logged objects must conform to `Redacted` or be redacted by default. Default is false.
      *   - identifier: The indentifier to note logs under. Default is "steamclog".
      *   - autoRotateConfig: Customize when logs are rotated. Defaults to 600 seconds.
-     *   - sentryDebug: Enable debug mode for SentrySDK. Default is false.
-     *   - sentryAutoSessionTracking: Enably SentrySDK auto session tracking. Default is false.
      */
     public init(
-            sentryKey: String,
             logLevel: LogLevelPreset = .debug,
             requireRedacted: Bool = false,
             identifier: String = "steamclog",
-            autoRotateConfig: AutoRotateConfig = AutoRotateConfig(),
-            sentryDebug: Bool = false,
-            sentryAutoSessionTracking: Bool = true,
-            sentryAttachStacktrace: Bool = true,
-            sentryFilter: @escaping SentryFilter = { error in false }) {
+            autoRotateConfig: AutoRotateConfig = AutoRotateConfig()) {
         self.requireRedacted = requireRedacted
         self.logLevel = logLevel
         self.identifier = identifier
         self.autoRotateConfig = autoRotateConfig
-        self.sentryKey = sentryKey
-        self.sentryDebug = sentryDebug
-        self.sentryAutoSessionTracking = sentryAutoSessionTracking
-        self.sentryAttachStacktrace = sentryAttachStacktrace
-        self.sentryFilter = sentryFilter
     }
 }

SteamcLog/Classes/Helper/SentryConfig.swift

@@ -0,0 +1,57 @@
+//
+//  SentryConfig.swift
+//  
+//
+//  Created by Brendan on 2022-03-21.
+//
+
+import Foundation
+
+public struct SentryConfig {
+    /// Sentry project specific key. Found here: https://docs.sentry.io/platforms/cocoa/?platform=swift
+    /// Set this key to an empty string to not report logs to Sentry.
+    let key: String
+
+    /// Toggles Sentry attaching stack traces to errors. Default is true.
+    let attachStackTrace: Bool
+
+    /// Toggles Sentry auto session tracking. Default is false.
+    /// More info here: https://docs.sentry.io/platforms/cocoa/?platform=swift#release-health
+    let autoSessionTracking: Bool
+
+    /// Debug mode for Sentry SDK. Default is false.
+    /// More info here: https://docs.sentry.io/error-reporting/configuration/?platform=swift#debug
+    let debug: Bool
+
+    /// Sets the percentage of the tracing data that is collected by Sentry. Default is 0.
+    let tracesSampleRate: NSNumber
+
+    /// Toggles the ability to filter out errors from being reported to Sentry
+    let filter: SentryFilter
+
+    /*
+     * Create a new Sentry Configuration to use.
+     *
+     * - Parameters:
+     *   - key: Sentry project key, needed to initialize SentrySDK.
+     *   - attachStackTrace: Toggles Sentry attaching stack traces to errors. Default is true.
+     *   - autoSessionTracking: Enable SentrySDK auto session tracking. Default is false.
+     *   - debug: Enable debug mode for SentrySDK. Default is false.
+     *   - tracesSampleRate: Sets the percentage of the tracing data that is collected by Sentry.
+     *   - filter: Toggles the ability to filter out errors from being reported to Sentry
+     */
+    public init(
+            key: String,
+            attachStacktrace: Bool = true,
+            autoSessionTracking: Bool = true,
+            debug: Bool = false,
+            tracesSampleRate: NSNumber = 0.0,
+            filter: @escaping SentryFilter = { error in false }) {
+        self.key = key
+        self.attachStackTrace = attachStacktrace
+        self.autoSessionTracking = autoSessionTracking
+        self.debug = debug
+        self.tracesSampleRate = tracesSampleRate
+        self.filter = filter
+    }
+}

SteamcLog/Classes/SteamcLog.swift

@@ -13,46 +13,59 @@ import XCGLogger
 public struct SteamcLog {
     public var config: Config! {
         didSet {
-            sentryDestination.outputLevel = config.logLevel.remote.xcgLevel
+            sentryDestination?.outputLevel = config.logLevel.remote.xcgLevel
             fileDestination.outputLevel = config.logLevel.disk.xcgLevel
             systemDestination.outputLevel = config.logLevel.console.xcgLevel
         }
     }
 
+    // Sentry configuration options. If this is not set (or set to nil during creation), Sentry will not be used.
+    public var sentryConfig: SentryConfig?
+
     @usableFromInline internal var xcgLogger: XCGLogger!
     @usableFromInline internal let encoder = JSONEncoder()
 
     private var fileDestination: FileDestination!
-    private var sentryDestination: SentryDestination!
+    private var sentryDestination: SentryDestination?
     private var systemDestination: SteamcLogSystemLogDestination!
 
-    public init(_ config: Config) {
+    /*
+     * Create your SteamcLog object.
+     * We recommend setting up a global instance of SteamcLog, probably in your AppDelegate file.
+     *
+     * - Parameters:
+     *   - config: General configuration options. See Config.swift for details.
+     *   - sentryConfig: Sentry configuration options. If this is `nil`, Sentry will not be used.
+     */
+    public init(_ config: Config, sentryConfig: SentryConfig?) {
         self.config = config
         xcgLogger = XCGLogger(identifier: config.identifier, includeDefaultDestinations: false)
 
         xcgLogger.setup(
             level: config.logLevel.global.xcgLevel
         )
 
-        SentrySDK.configureScope { scope in
-            #if DEBUG
-            scope.setTag(value: "debug", key: "environment")
-            #else
-            scope.setTag(value: "prod", key: "environment")
-            #endif
-        }
+        if let sentry = sentryConfig {
+            SentrySDK.configureScope { scope in
+                #if DEBUG
+                scope.setTag(value: "debug", key: "environment")
+                #else
+                scope.setTag(value: "prod", key: "environment")
+                #endif
+            }
 
-        SentrySDK.start { options in
-            options.dsn = config.sentryKey
-            options.debug = config.sentryDebug
-            options.attachStacktrace = config.sentryAttachStacktrace
-            options.enableAutoSessionTracking = config.sentryAutoSessionTracking
-            options.tracesSampleRate = 0.0
-        }
+            SentrySDK.start { options in
+                options.dsn = sentry.key
+                options.debug = sentry.debug
+                options.attachStacktrace = sentry.attachStackTrace
+                options.enableAutoSessionTracking = sentry.autoSessionTracking
+                options.tracesSampleRate = sentry.tracesSampleRate
+            }
 
-        sentryDestination = SentryDestination(identifier: "steamclog.sentryDestination")
-        setLoggingDetails(destination: &sentryDestination, outputLevel: config.logLevel.remote)
-        xcgLogger.add(destination: sentryDestination)
+            sentryDestination = SentryDestination(identifier: "steamclog.sentryDestination")
+            setLoggingDetails(destination: &sentryDestination!, outputLevel: config.logLevel.remote)
+            xcgLogger.add(destination: sentryDestination! )
+        }
 
         fileDestination = AutoRotatingFileDestination(writeToFile: logFilePath,
                                                       identifier: "steamclog.fileDestination",
@@ -91,6 +104,19 @@ public struct SteamcLog {
 
     // MARK: - Public Methods
 
+    /*
+     * Attach a new custom log destination to the current logger
+     *
+     * - Parameters:
+     *   - destination: The new destination to attach to the logger.
+     *   - outputLevel: The minimum log level that will be sent to the destination.
+     */
+    public func attach(destination: BaseQueuedDestination, outputLevel: LogLevel) {
+        var newDest = destination
+        setLoggingDetails(destination: &newDest, outputLevel: outputLevel)
+        xcgLogger.add(destination: newDest)
+    }
+
     // MARK: All Log Level
 
     private func internalVerbose(_ message: String, functionName: StaticString, fileName: StaticString, lineNumber: Int) {
@@ -272,7 +298,7 @@ public struct SteamcLog {
 
     public func error<T>(_ message: StaticString, _ object: T, functionName: StaticString = #function, fileName: StaticString = #file, lineNumber: Int = #line) where T: Encodable {
 
-        if let error = object as? Error, config.sentryFilter(error) {
+        if let error = object as? Error, let sentry = sentryConfig, sentry.filter(error) {
             info("\(error) included in sentryFilter and has been blocked from being captured as an error: \(error.localizedDescription)",
                  functionName: functionName,
                  fileName: fileName,