Merge pull request #95 from mdsol/develop

Release of 3.1.0

README.md

@@ -19,26 +19,27 @@ determine whether or not to trace this request. `SampleRate` is the approximate
 zipkin.
 
 ## Configurations
-Please use `ZipkinConig` class to configure the module and verify these values and modify them according to your
+Please use `ZipkinConfig` class to configure the module and verify these values and modify them according to your
 service/environment.
 
 - `Bypass` - Controls whether the requests should be sent through the Zipkin module
   - **false**: Enables the ZipkinMiddleware/ZipkinMessageHandler
   - **true**: Disables the ZipkinMiddleware/ZipkinMessageHandler
 - `ZipkinBaseUri` - is the zipkin scribe/collector server URI with port to send the Spans
 - `Domain` - is a valid public facing base url for your app instance. Zipkin will use to label the trace.
+  - by default this looks at the incoming requests and uses the hostname from them. It's a `Func<IOwinRequest, Uri>` - customise this to your requirements.
 - `SpanProcessorBatchSize` - how many Spans should be sent to the zipkin scribe/collector in one go.
 - `SampleRate` - 1 decimal point float value between 0 and 1. This value will determine randomly if the current request will be traced or not.	 
 - `NotToBeDisplayedDomainList`(optional) - It will be used when logging host name by excluding these strings in service name attribute
 	e.g. domain: ".xyz.com", host: "abc.xyz.com" will be logged as "abc" only    
-- `ExcludedPathList`(optional) - Path list that is not needed for tracing. Each item must start with "/". 
+- `ExcludedPathList`(optional) - Path list that is not needed for tracing. Each item must start with "/".
 
 
-```
+```csharp
 var config = new ZipkinConfig
 {
 	Bypass = request => request.Uri.AbsolutePath.StartsWith("/allowed"),
-	Domain = new Uri("https://yourservice.com"),
+	Domain = request => new Uri("https://yourservice.com"), // or, you might like to derive a value from the request, like r => new Uri($"{r.Scheme}{Uri.SchemeDelimiter}{r.Host}"),
 	ZipkinBaseUri = new Uri("http://zipkin.xyz.net:9411"),
 	SpanProcessorBatchSize = 10,
 	SampleRate = 0.5,
@@ -53,7 +54,7 @@ var config = new ZipkinConfig
 Server Trace relies on OWIN Middleware. Please create OWIN Startup class then call `UseZipkin()`.
 
 
-```
+```csharp
 using Medidata.ZipkinTracer.Core;
 using Medidata.ZipkinTracer.Core.Middlewares;
 
@@ -67,27 +68,33 @@ public class Startup
 			ZipkinBaseUri = new Uri("http://zipkin.xyz.net:9411"),
 			SpanProcessorBatchSize = 10,
 		    SampleRate = 0.5    
-		};
+		});
     }
 }
 
 ```
 
 ### Client trace (Outbound request)
-Client Trace relies on HttpMessageHandler for HttpClient. Please pass a ZipkinMessageHandler instance into HttpClient. 
+Client Trace relies on HttpMessageHandler for HttpClient. Please pass a ZipkinMessageHandler instance into HttpClient.
 
+Note: You will need the `GetOwinContext` extension method. If you host in IIS with `System.Web`, this can be found in `Microsoft.Owin.Host.SystemWeb`.
 
-```
+```csharp
 using Medidata.ZipkinTracer.Core.Handlers;
 
 public class HomeController : AsyncController
 {
-	private ILog logger = LogManager.GetLogger("HomeController");
-
     public async Task<ActionResult> Index()
     {
         var context = System.Web.HttpContext.Current.GetOwinContext();
-		var client = new ZipkinClient(logger, context);
+		var config = new ZipkinConfig // you can use Dependency Injection to get the same config across your app.
+		{
+		    Domain = new Uri("https://yourservice.com"),
+		    ZipkinBaseUri = new Uri("http://zipkin.xyz.net:9411"),
+		    SpanProcessorBatchSize = 10,
+		    SampleRate = 0.5    
+		}
+		var client = new ZipkinClient(config, context);
 
         using (var httpClient = new HttpClient(new ZipkinMessageHandler(client))))
         {
@@ -104,10 +111,19 @@ public class HomeController : AsyncController
 ```
 
 #### Recording arbitrary events and additional information
-Additional annotations can be recorded by using the ZipkinClient's `Record()` and `RecordBinary<T>()` methods:
+**NOTE:This can only be used if you are NOT using ZipkinMessageHandler as described above "Client trace (Outbound request)". ```RecordBinary<T()``` needs to be called before ```EndClientTrace()``` is invoked.**
 
-```
-var zipkinClient = (ITracerClient)HttpContext.Current.Items["zipkinClient"];
+Additional annotations can be recorded by using the ZipkinClient's `Record()` and `RecordBinary<T>()` methods:
+```csharp
+var context = System.Web.HttpContext.Current.GetOwinContext();
+var config = new ZipkinConfig // you can use Dependency Injection to get the same config across your app.
+{
+	Domain = new Uri("https://yourservice.com"),
+	ZipkinBaseUri = new Uri("http://zipkin.xyz.net:9411"),
+	SpanProcessorBatchSize = 10,
+	SampleRate = 0.5    
+}
+var zipkinClient = new ZipkinClient(config, context);
 var url = "https://abc.xyz.com:8000";
 var requestUri = "/object/1";
 HttpResponseMessage result;
@@ -116,17 +132,17 @@ using (var client = new HttpClient())
     client.BaseAddress = new Uri(url);
 
 	// start client trace
-    var span = tracerClient.StartClientTrace(new Uri(client.BaseAddress, requestUri), "GET");
+    var span = zipkinClient.StartClientTrace(new Uri(client.BaseAddress, requestUri), "GET");
 
-    tracerClient.Record(span, "A description which will gets recorded with a timestamp.");
+    zipkinClient.Record(span, "A description which will gets recorded with a timestamp.");
 
     result = await client.GetAsync(requestUri);
 
     // Record the total memory used after the call
-    tracerClient.RecordBinary(span, "client.memory", GC.GetTotalMemory(false));
+    zipkinClient.RecordBinary(span, "client.memory", GC.GetTotalMemory(false));
 
 	// end client trace
-    tracerClient.EndClientTrace(span);	
+    zipkinClient.EndClientTrace(span);
 }
 ...
 ```
@@ -138,6 +154,12 @@ case the caller member name (method, property etc.) will get recorded.
 With the `RecordLocalComponent()` method of the client a local component (or information) can be recorded for the
 current trace. This will result an additional binary annotation with the 'lc' key (LOCAL_COMPONENT) and a custom value.
 
+#### Troubleshooting
+
+##### Logs
+
+Logging internal to the library is provided via the [LibLog abstraction](https://github.com/damianh/LibLog). Caveat: to get logs, you must have initialised your logging framework on application-start ([console app example](https://github.com/damianh/LibLog/blob/master/src/LibLog.Example.Log4Net/Program.cs#L12) - a web-app might do this in OWIN Startup or Global.asax, or the inversion of control container initialisation).
+
 ## Contributors
 ZipkinTracer is (c) Medidata Solutions Worldwide and owned by its major contributors:
 * Tomoko Kwan