Merge pull request #11 from bmermet/codedocumentation

Add documentation on public members and code examples

Author: bmermet

README.md

@@ -7,10 +7,10 @@ Datadog APM traces the path of each request through your application stack, reco
 This repository contains what you need to trace C# applications. Some quick notes up front:
 
 - **Datadog C# APM is currently in Alpha**
-- It supports .Net Framework version above 4.5 and .Net Core 2.0
-- It does not support out of process propagation
-- It does not provide automatic framework instrumentation, all instrumentation is [manual](#manual-instrumentation)
-- Multiple AppDomains are not supported (but it could work).
+- It supports .Net Framework version above 4.5 and .Net Core 2.0.
+- It does not support out of process propagation.
+- It does not provide automatic framework instrumentation, all instrumentation is [manual](#manual-instrumentation).
+- Multiple AppDomains are not supported.
 - Our tracer is based on the current OpenTracing standard, however we do not yet support the following features: `FollowsFrom` references, `Baggage` or `Log`.
 
 ## The Components
@@ -26,10 +26,104 @@ Before instrumenting your code, [install the Datadog Agent](https://app.datadogh
 
 ### Manual Instrumentation
 
+#### Introduction
+
+Before instrumenting your application, have a look at the [Datadog APM Terminology](https://docs.datadoghq.com/tracing/terminology/) to get familiar with the core concepts of Datadog APM.
+
 #### Setup
 
+In order to instrument you code you need to add the `Datadog.Trace` NuGet package to your project.
+
+Your tracing adventure starts with the `ITracer` object, you should typically instantiate only one `ITracer` for the lifetime of your app and use it in all places of your code where you want to add tracing. Instantiating the `ITracer` is done with the `TracerFactory.GetTracer` method.
+
+To get a tracer with default parameters (i.e. the agent endpoint set to `http://localhost:8126`, and the default service name set to the name of the AppDomain):
+
+```csharp
+ITracer tracer = TracerFactory.GetTracer();
+```
+
+Customize your tracer object by adding optional parameters to the `TracerFactory.GetTracer` call:
+
+By default the service name is set to the name of the AppDomain, choose a custom name with the defaultServiceName parameter:
+
+```csharp
+ITracer tracer = TracerFactory.GetTracer(defaultServiceName: "YourServiceName")
+```
+
+By default, the trace endpoint is set to http://localhost:8126, send traces to a different endpoint with the agentEndpoint parameter:
+
+```csharp
+ITracer tracer = TracerFactory.GetTracer(agentEndpoint: new Url("http://myendpoint:port"));
+```
+
 #### Examples
 
+Use the shared `ITracer` object you created to create spans, instrument any section of your code, and get detailed metrics on it.
+
+Set the ServiceName to recognize which service this trace belongs to; if you don't, the parent span's service name or in case of a root span the defaultServiceName stated above is used.
+
+Set the ResourceName to scope this trace to a specific endpoint or SQL Query; For instance:
+- "GET /users/:id"
+- "SELECT * FROM ..."
+if you don't the OperationName will be used.
+
+A minimal examples is:
+
+```csharp
+using (ISpan span = tracer.BuildSpan("OperationName").WithTag(DDTags.ServiceName, "ServiceName").Start())
+{
+    span.SetTag(DDTags.ResourceName, "ResourceName");
+
+    // Instrumented code
+    Thread.Sleep(1000);
+}
+```
+
+You may also choose, not to use the `using` construct and close the `ISpan` object explictly:
+
+```csharp
+ISpan span = tracer.BuildSpan("OperationName").WithTag(DDTags.ServiceName, "ServiceName").Start();
+span.SetTag(DDTags.ResourceName, "ResourceName");
+
+// Instrumented code
+Thread.Sleep(1000);
+
+
+// Finish sets the span duration and sends it to the agent (if you don't call finish the data will never be sent to Datadog)
+span.Finish();
+```
+
+You may add custom tags by calling `ISpan.SetTag`:
+
+```csharp
+ISpan span = tracer.BuildSpan("SqlQuery").Start();
+span.SetTag("db.rows", 10);
+```
+
+You should not have to explicitly declare parent/children relationship between your spans, but to override the default behavior - a new span is considered a child of the innermost open span in its logical context- use:
+
+```csharp
+ISpan parent = tracer.BuildSpan("Parent").Start();
+ISpan child = tracer.BuildSpan("Child").AsChildOf(parent).Start();
+```
+
+#### Advanced Usage
+
+When creating a tracer, add some metadata to your services to customize how they will appear in your Datadog application:
+
+```csharp
+var serviceInfoList = new List<ServiceInfo>
+{
+    new ServiceInfo
+    {
+        App = "MyAppName",
+        AppType = "web",
+        ServiceName = "MyServiceName"
+    }
+};
+ITracer tracer = TracerFactory.GetTracer(serviceInfoList: serviceInfoList);
+```
+
 ## Further Reading
 
 - [OpenTracing's documentation](https://github.com/opentracing/opentracing-csharp); feel free to use the Trace C# API to customize your instrumentation.

src/Datadog.Trace.IntegrationTests/SendTracesToAgent.cs

@@ -70,8 +70,8 @@ public async void CustomServiceName()
             _tracer = TracerFactory.GetTracer(new Uri("http://localhost:8126"), serviceList, null, _httpRecorder);
 
             var span = (Span)_tracer.BuildSpan("Operation")
-                .WithTag(Tags.ResourceName, "This is a resource")
-                .WithTag(Tags.ServiceName, ServiceName)
+                .WithTag(DDTags.ResourceName, "This is a resource")
+                .WithTag(DDTags.ServiceName, ServiceName)
                 .Start();
             span.Finish();
 
@@ -94,8 +94,8 @@ public async void CustomServiceName()
         public async void Utf8Everywhere()
         {
             var span = (Span)_tracer.BuildSpan("Aᛗᚪᚾᚾᚪ")
-                .WithTag(Tags.ResourceName, "η γλώσσα μου έδωσαν ελληνική")
-                .WithTag(Tags.ServiceName, "На берегу пустынных волн")
+                .WithTag(DDTags.ResourceName, "η γλώσσα μου έδωσαν ελληνική")
+                .WithTag(DDTags.ServiceName, "На берегу пустынных волн")
                 .WithTag("யாமறிந்த", "ნუთუ კვლა")
                 .Start();
             span.Finish();

src/Datadog.Trace.Tests/TracerTests.cs

@@ -17,8 +17,11 @@ public void BuildSpan_NoParameter_DefaultParameters()
 
             var builder = tracer.BuildSpan("Op1");
             var span = (Span)builder.Start();
-
-            Assert.Equal("Datadog.Trace", span.ServiceName);
+#if NETCOREAPP2_0
+            Assert.Equal("testhost", span.ServiceName);
+#else
+            Assert.Equal("Datadog.Trace.Tests.Net45", span.ServiceName);
+#endif
             Assert.Equal("Op1", span.OperationName);
         }
 

src/Datadog.Trace/MsgPackContent.cs

@@ -7,7 +7,7 @@
 
 namespace Datadog.Trace
 {
-    public class MsgPackContent<T> : HttpContent
+    internal class MsgPackContent<T> : HttpContent
     {
         public T Value { get; private set; }
         private SerializationContext _serializationContext;

src/Datadog.Trace/RandomUtils.cs

@@ -2,7 +2,7 @@
 
 namespace Datadog.Trace
 {
-    public static class RandomUtils
+    internal static class RandomUtils
     {
         public static UInt64 NextUInt63(this Random rnd)
         {

src/Datadog.Trace/Span.cs

@@ -187,13 +187,13 @@ public ISpan SetTag(string key, string value)
                     return this;
                 }
                 switch (key) {
-                    case Datadog.Trace.Tags.ResourceName:
+                    case DDTags.ResourceName:
                         ResourceName = value;
                         return this;
                     case OpenTracing.Tags.Error:
                         Error = value == "True";
                         return this;
-                    case Datadog.Trace.Tags.SpanType:
+                    case DDTags.SpanType:
                         Type = value;
                         return this;
                 }

src/Datadog.Trace/SpanBuilder.cs

@@ -5,7 +5,7 @@
 
 namespace Datadog.Trace
 {
-    public class SpanBuilder : ISpanBuilder
+    internal class SpanBuilder : ISpanBuilder
     {
         private static ILog _log = LogProvider.For<SpanBuilder>();
 
@@ -112,7 +112,7 @@ public ISpanBuilder WithTag(string key, string value)
         {
             lock (_lock)
             {
-                if (key == Tags.ServiceName)
+                if (key == DDTags.ServiceName)
                 {
                     _serviceName = value;
                     return this;

src/Datadog.Trace/Tags.cs

@@ -1,6 +1,6 @@
 namespace Datadog.Trace
 {
-    public static class Tags
+    public static class DDTags
     {
         public const string ServiceName = "service.name";
         public const string ResourceName = "resource.name";

src/Datadog.Trace/Tracer.cs

@@ -21,7 +21,7 @@ internal class Tracer : ITracer, IDatadogTracer
         public Tracer(IAgentWriter agentWriter, List<ServiceInfo> serviceInfo = null, string defaultServiceName = null)
         {
             _agentWriter = agentWriter;
-            _defaultServiceName = GetExecutingAssemblyName() ?? Constants.UnkownService;
+            _defaultServiceName = GetAppDomainFriendlyName() ?? Constants.UnkownService;
             if (serviceInfo != null)
             {
                 foreach(var service in serviceInfo)
@@ -35,12 +35,11 @@ public Tracer(IAgentWriter agentWriter, List<ServiceInfo> serviceInfo = null, st
             }
         }
 
-        private string GetExecutingAssemblyName()
+        private string GetAppDomainFriendlyName()
         {
             try
             {
-                var name = Assembly.GetExecutingAssembly().GetName();
-                return name.Name;
+                return AppDomain.CurrentDomain.FriendlyName;
             }
             catch
             {

src/Datadog.Trace/TracerFactory.cs

@@ -9,17 +9,24 @@ public static class TracerFactory
     {
         private static Uri _defaultUri = new Uri("http://localhost:8126");
 
-        public static ITracer GetTracer(Uri uri = null, List<ServiceInfo> serviceInfos = null, string defaultServiceName = null)
+        /// <summary>
+        /// Create a  new ITracer object  with the given parameters
+        /// </summary>
+        /// <param name="agentEndpoint">The agent endpoint where the traces will be sent (default is http://localhost:8126).</param>
+        /// <param name="serviceInfoList">The service information list.</param>
+        /// <param name="defaultServiceName">Default name of the service (default is the name of the executing assembly).</param>
+        /// <returns></returns>
+        public static ITracer GetTracer(Uri agentEndpoint = null, List<ServiceInfo> serviceInfoList = null, string defaultServiceName = null)
         {
-            uri = uri ?? _defaultUri;
-            return GetTracer(uri, serviceInfos, defaultServiceName, null);
+            agentEndpoint = agentEndpoint ?? _defaultUri;
+            return GetTracer(agentEndpoint, serviceInfoList, defaultServiceName, null);
         }
 
-        internal static Tracer GetTracer(Uri uri, List<ServiceInfo> serviceInfos = null, string defaultServiceName = null, DelegatingHandler delegatingHandler = null)
+        internal static Tracer GetTracer(Uri agentEndpoint, List<ServiceInfo> serviceInfoList = null, string defaultServiceName = null, DelegatingHandler delegatingHandler = null)
         {
-            var api = new Api(uri, delegatingHandler);
+            var api = new Api(agentEndpoint, delegatingHandler);
             var agentWriter = new AgentWriter(api);
-            var tracer = new Tracer(agentWriter, serviceInfos, defaultServiceName);
+            var tracer = new Tracer(agentWriter, serviceInfoList, defaultServiceName);
             return tracer;
         }
     }