fix #36 - refactor options class (#43)

* fix #36 - refactor options class

* update changelog/readme

* remove some unneccessary whitespace

Author: austinlparker

CHANGELOG.md

@@ -1,6 +1,9 @@
 # Changelog
 
 _vNext_
+- The `Options` class has been refactored to support a more fluent style of configuration. **Breaking Change**
+  - By default, `SatelliteOptions` are now created when `Options` is created that points to the LightStep public satellite pool.
+  - Please see the readme for more information on configuring the tracer.
 - Tags which are passed with an empty value will now set the string value "null" when reporting to LightStep.
 
 _v0.0.8_

README.md

@@ -17,16 +17,9 @@ Install the package via NuGet into your solution, or use `Install-Package LightS
 # Basic Usage
 It's recommended to initialize the tracer once at the beginning of your application and assign it as the global tracer, as follows:
 ```c#
-// substitute your own LS API Key here
-var lsKey = "TEST_TOKEN";
-
-// substitute your satellite endpoint (host, port) here.
-var lsSettings = new SatelliteOptions("localhost", 9996, false);
-
-// create a new tracer and register it
-var tracer = new Tracer(new Options(lsKey, lsSettings));
+var tracerOptions = new Options("PROJECT_ACCESS_TOKEN");
+var tracer = new Tracer(tracerOptions);
 GlobalTracer.Register(tracer);
-...
 ```
 
 Once you've initialized a tracer, you can begin to create and emit spans.
@@ -40,15 +33,15 @@ You can also refer to the `examples` folder for sample code and projects.
 There's several options that can be adjusted when instantiating a `LightStepTracer`.
 
 ## `Options`
-| Property | Description |
+| Method | Description |
 | -------- | ----------- |
-| Tags   | Default tags to apply to all spans created by the tracer.  |
-| ReportPeriod  | How frequently the Tracer should batch and send Spans to LightStep (30s default) |
-| ReportTimeout  | Timeout for sending spans to the Satellite  |
-| AccessToken | The LightStep Project Access Key |
-| Tags | Tags that are applied to each span generated by the tracer. Override or add new tags via the constructor. |
-| Satellite | A SatelliteOptions object that specifies the host, port, and if we should use HTTPS |
-| UseHttp2 | If this is true, we use HTTP/2 to communicate with the Satellite |
+| WithTags(IDictionary<string, object>)   | Default tags to apply to all spans created by the tracer.  |
+| WithReportPeriod(TimeSpan)  | How frequently the Tracer should batch and send Spans to LightStep (30s default) |
+| WithReportTimeout(TimeSpan)  | Timeout for sending spans to the Satellite  |
+| WithToken(string) | The LightStep Project Access Token |
+| WithSatellite(SatelliteOptions) | A SatelliteOptions object that specifies the host, port, and if we should use HTTPS |
+| WithHttp2(bool) | If this is true, we use HTTP/2 to communicate with the Satellite |
+| WithAutomaticReporting(bool) | If false, disables the automatic flushing of buffered spans. |
 
 ## `SatelliteOptions`
 | Property | Description |
@@ -64,12 +57,12 @@ The C# Tracer will prefer TLS 1.2 when available on all .NET Runtime versions, b
 The following is an example of overriding the LightStep Component Name and adding a new custom tag for all spans -
 
 ```csharp
-var satelliteOptions = newSatelliteOptions("satellite.mydomain.com");
+var satelliteOptions = new SatelliteOptions("satellite.mydomain.com");
 var overrideTags = new Dictionary<string, object> 
 {
     {LightStepConstants.ComponentNameKey, "test_component"},
     {"my_tag", "foobar"}
 };
-var tracerOptions = new Options("TEST_TOKEN", overrideTags, satelliteOptions);
-var tracer = new Tracer(tracerOptions, satelliteOptions);
+var tracerOptions = new Options("TEST_TOKEN").WithSatellite(satelliteOptions).WithTags(overrideTags);
+var tracer = new Tracer(tracerOptions);
 ```

examples/LightStep.CSharpAspectTestApp/Program.cs

@@ -17,8 +17,7 @@ static void Main(string[] args)
             // create your tracer options, initialize it, assign it to the GlobalTracer
             var lsKey = Environment.GetEnvironmentVariable("LS_KEY");
             var lsSettings = new SatelliteOptions("collector.lightstep.com");
-            var lsOptions = new Options(lsKey, lsSettings);
-            lsOptions.UseHttp2 = false;
+            var lsOptions = new Options(lsKey).WithStatellite(lsSettings);
             var tracer = new Tracer(lsOptions);
 
             GlobalTracer.Register(tracer);

examples/LightStep.CSharpDITestApp/Program.cs

@@ -12,7 +12,7 @@ internal class Program
         public static void Main(string[] args)
         {
             // replace these options with your satellite and api key
-            var tracerOptions = new Options("TEST_TOKEN", new SatelliteOptions("localhost", 9996, true));
+            var tracerOptions = new Options("TEST_TOKEN").WithStatellite(new SatelliteOptions("localhost", 9996, true));
             var container = new WindsorContainer();
             // during registration, pass your options to the concrete LightStep Tracer implementation
             container.Register(Component.For<ITracer>().ImplementedBy<Tracer>().DependsOn(Dependency.OnValue("options", tracerOptions)));            

examples/LightStep.CSharpTestApp/Program.cs

@@ -1,18 +1,19 @@
 using System;
 using System.IO;
 using System.Threading;
+using Google.Protobuf.WellKnownTypes;
 using OpenTracing.Util;
 
-namespace LightStep.TestApp
+namespace LightStep.CSharpTestApp
 {
     internal class Program
     {
         private static void Main(string[] args)
         {
             // substitute your own LS API Key here
-            var lsKey = "TEST_TOKEN";
-            var lsSettings = new SatelliteOptions("localhost", 9996, true);
-            var tracer = new Tracer(new Options(lsKey, lsSettings));
+            var lightStepSatellite = new SatelliteOptions("localhost", 9996, true);
+            var lightStepOptions = new Options("TEST_TOKEN").WithStatellite(lightStepSatellite);
+            var tracer = new Tracer(lightStepOptions);
             GlobalTracer.Register(tracer);
 
             for (var i = 0; i < 500; i++)

src/LightStep/Options.cs

@@ -17,71 +17,101 @@ public class Options
         /// </summary>
         public readonly ulong TracerGuid = new Random().NextUInt64();
 
-        /// <summary>
-        /// Creates a new set of options for the LightStep tracer.
-        /// </summary>
-        /// <param name="token">Project API Key.</param>
-        /// <param name="satelliteOptions">Satellite endpoint configuration.</param>
-        public Options(string token, SatelliteOptions satelliteOptions) : this(token, new Dictionary<string, object>(), satelliteOptions)
-        {
-            
-        }
-        
-        /// <summary>
-        ///     Creates a new set of options for the LightStep tracer.
-        /// </summary>
-        /// <param name="token">Project API key.</param>
-        /// <param name="tags">Tags to add to every span emitted from this tracer.</param>
-        /// <param name="satelliteOptions">Satellite endpoint configuration.</param>
-        /// <exception cref="ArgumentNullException">An API key is required.</exception>
-        public Options(string token, IDictionary<string, object> tags, SatelliteOptions satelliteOptions)
-        {
-            if (string.IsNullOrWhiteSpace(token)) throw new ArgumentNullException(nameof(token));
-
-            Tags = tags.Count > 0 ? MergeTags(tags) : InitializeDefaultTags();
-            ReportPeriod = TimeSpan.FromMilliseconds(5000);
-            ReportTimeout = TimeSpan.FromSeconds(30);
-            AccessToken = token;
-            Satellite = satelliteOptions;
-            UseHttp2 = false;
-            Run = true;
-        }
-
         /// <summary>
         ///     API key for a LightStep project.
         /// </summary>
-        public string AccessToken { get; set; }
+        public string AccessToken { get; private set; }
 
         /// <summary>
         /// If true, tracer will start reporting
         /// </summary>
         /// 
-        public bool Run { get; set; }
+        public bool Run { get; private set; }
         /// <summary>
         ///     True if the satellite connection should use HTTP/2, false otherwise.
         /// </summary>
-        public bool UseHttp2;
+        public bool UseHttp2 { get; private set; }
 
         /// <summary>
         ///     LightStep Satellite endpoint configuration.
         /// </summary>
-        public SatelliteOptions Satellite { get; set; }
+        public SatelliteOptions Satellite { get; private set; }
 
         /// <summary>
         ///     How often the reporter will send spans to a LightStep Satellite.
         /// </summary>
-        public TimeSpan ReportPeriod { get; set; }
+        public TimeSpan ReportPeriod { get; private set; }
 
         /// <summary>
         ///     Timeout for sending spans to a LightStep Satellite.
         /// </summary>
-        public TimeSpan ReportTimeout { get; set; }
+        public TimeSpan ReportTimeout { get; private set; }
 
         /// <summary>
         ///     Tags that should be applied to each span generated by this tracer.
         /// </summary>
-        public IDictionary<string, object> Tags { get; set; }
+        public IDictionary<string, object> Tags { get; private set; }
+
+        public Options WithToken(string token)
+        {
+            AccessToken = token;
+            return this;
+        }
 
+        public Options WithHttp2()
+        {
+            UseHttp2 = true;
+            return this;
+        }
+
+        public Options WithStatellite(SatelliteOptions options)
+        {
+            Satellite = options;
+            return this;
+        }
+
+        public Options WithReportPeriod(TimeSpan period)
+        {
+            ReportPeriod = period;
+            return this;
+        }
+
+        public Options WithReportTimeout(TimeSpan timeout)
+        {
+            ReportTimeout = timeout;
+            return this;
+        }
+
+        public Options WithTags(IDictionary<string, object> tags)
+        {
+            Tags = MergeTags(tags);
+            return this;
+        }
+
+        public Options WithAutomaticReporting(bool shouldRun)
+        {
+            Run = shouldRun;
+            return this;
+        }
+        
+        /// <summary>
+        ///     Creates a new set of options for the LightStep tracer.
+        /// </summary>
+        /// <param name="token">Project API key.</param>
+        /// <exception cref="ArgumentNullException">An API key is required.</exception>
+        public Options(string token)
+        {
+            if (string.IsNullOrWhiteSpace(token)) throw new ArgumentNullException(nameof(token));
+
+            Tags = InitializeDefaultTags();
+            ReportPeriod = TimeSpan.FromMilliseconds(5000);
+            ReportTimeout = TimeSpan.FromSeconds(30);
+            AccessToken = token;
+            Satellite = new SatelliteOptions("collector.lightstep.com");
+            UseHttp2 = false;
+            Run = true;
+        }
+        
         private IDictionary<string, object> MergeTags(IDictionary<string, object> input)
         {
             var attributes = InitializeDefaultTags();

src/LightStep/SatelliteOptions.cs

@@ -1,7 +1,7 @@
 namespace LightStep
 {
     /// <summary>
-    ///     Contains information on a LightStep Satellite Endpoint.
+    /// Options to configure a LightStep satellite.
     /// </summary>
     public class SatelliteOptions
     {

test/LightStep.Tests/LightStepProtoTests.cs

@@ -13,17 +13,14 @@ private Tracer GetTracer(ISpanRecorder recorder = null)
         {
             var spanRecorder = recorder ?? new SimpleMockRecorder();
             var satelliteOptions = new SatelliteOptions("localhost", 80, true);
-            var tracerOptions = new Options("TEST", satelliteOptions);
-            tracerOptions.Run = false;
-
+            var tracerOptions = new Options("TEST").WithStatellite(satelliteOptions).WithAutomaticReporting(false);
             return new Tracer(tracerOptions, spanRecorder);
         }
 
         private LightStepHttpClient GetClient()
         {
             var satelliteOptions = new SatelliteOptions("localhost", 80, true);
-            var tracerOptions = new Options("TEST", satelliteOptions);
-            tracerOptions.Run = false;
+            var tracerOptions = new Options("TEST").WithStatellite(satelliteOptions).WithAutomaticReporting(false);
             return new LightStepHttpClient("http://localhost:80", tracerOptions);
         }
 

test/LightStep.Tests/PropagatorTests.cs

@@ -18,8 +18,7 @@ public void PropagatorStackInTracerShouldInjectAndExtract()
 
             var sr = new SimpleMockRecorder();
             var satOpts = new SatelliteOptions("localhost", 80, true);
-            var tracerOpts = new Options("TEST", satOpts);
-            tracerOpts.Run = false;
+            var tracerOpts = new Options("TEST").WithStatellite(satOpts).WithAutomaticReporting(false);
 
             var tracer = new Tracer(tracerOpts, sr, ps);
 

test/LightStep.Tests/SpanTests.cs

@@ -13,8 +13,7 @@ private Tracer GetTracer(ISpanRecorder recorder = null)
         {
             var spanRecorder = recorder ?? new SimpleMockRecorder();
             var satelliteOptions = new SatelliteOptions("localhost", 80, true);
-            var tracerOptions = new Options("TEST", satelliteOptions);
-            tracerOptions.Run = false;
+            var tracerOptions = new Options("TEST").WithStatellite(satelliteOptions).WithAutomaticReporting(false);
             return new Tracer(tracerOptions, spanRecorder);
         }