Provide documentation for writing dependencies (#45)

* Provide documentation for writing dependencies Signed-off-by: Tom Kerkhove <[email protected]> * Align with other docs * Remove local test
arcus-azure · Mar 23, 2020 · f6b8ff5 · f6b8ff5
1 parent 4713e7c
commit f6b8ff5
Show file tree

Hide file tree

Showing 3 changed files with 60 additions and 5 deletions.
diff --git a/docs/features/writing-different-telemetry-types.md b/docs/features/writing-different-telemetry-types.md
@@ -9,7 +9,7 @@ Logs are a great way to gain insights, but sometimes they are not the best appro
 
 We provide the capability to track the following telemetry types on top of ILogger with good support on Serilog:
 
-- Dependencies
+- [Dependencies](#dependencies)
 - [Events](#events)
 - [Metrics](#metrics)
 - Requests
@@ -24,6 +24,64 @@ This feature requires to install our NuGet package
 PM > Install-Package Arcus.Observability.Telemetry.Core
 ```
 
+## Dependencies
+
+Dependencies allow you to track how your external dependencies are doing to give you insights on performance and error rate.
+
+We provide support for the following dependencies:
+
+- [HTTP](#measuring-http-dependencies)
+- [SQL](#measuring-sql-dependencies)
+
+### Measuring HTTP dependencies
+
+Here is how you can report a HTTP dependency:
+
+```csharp
+var telemetryContext = new Dictionary<string, object>
+{
+    { "Tenant", "Contoso"},
+};
+
+// Create request
+var request = new HttpRequestMessage(HttpMethod.Post, "http://requestbin.net/r/ujxglouj")
+{
+    Content = new StringContent("{\"message\":\"Hello World!\"")
+};
+
+// Start measuring
+var startTime = DateTimeOffset.UtcNow;
+durationMeasurement.Start();
+
+// Send request to dependant service
+var response = await httpClient.SendAsync(request);
+
+_logger.LogHttpDependency(request, response.StatusCode, startTime, durationMeasurement.Elapsed, telemetryContext);
+// Output: "HTTP Dependency requestbin.net for POST /r/ujxglouj completed with 200 in 00:00:00.2521801 at 03/23/2020 09:56:31 +00:00 (Successful: True - Context: [Tenant, Contoso])"
+```
+
+### Measuring SQL dependencies
+
+Here is how you can report a SQL dependency:
+
+```csharp
+var telemetryContext = new Dictionary<string, object>
+{
+    { "Catalog", "Products"},
+    { "Tenant", "Contoso"},
+};
+
+// Start measuring
+var startTime = DateTimeOffset.UtcNow;
+durationMeasurement.Start();
+
+// Interact with database
+var products = await _repository.GetProducts();
+
+_logger.LogSqlDependency("sample-server", "sample-database", "my-table", "get-products", isSuccessful: true, startTime: startTime, duration: durationMeasurement.Elapsed, context: telemetryContext);
+// Output: "SQL Dependency sample-server for sample-database/my-table for operation get-products in 00:00:01.2396312 at 03/23/2020 09:32:02 +00:00 (Successful: True - Context: [Catalog, Products], [Tenant, Contoso])"
+```
+
 ## Events
 
 Events allow you to report custom events which are a great way to track business-related events.

diff --git a/src/Arcus.Observability.Telemetry.Core/Extensions/ILoggerExtensions.cs b/src/Arcus.Observability.Telemetry.Core/Extensions/ILoggerExtensions.cs
@@ -1,9 +1,7 @@
 using System;
 using System.Collections.Generic;
-using System.Linq;
 using System.Net;
 using System.Net.Http;
-using System.Text;
 using Arcus.Observability.Telemetry.Core;
 using GuardNet;
 using Microsoft.AspNetCore.Http;
@@ -24,7 +22,7 @@ public static class ILoggerExtensions
             + ContextProperties.EventTracking.EventContext + "})";
 
         private const string HttpDependencyFormat =
-            MessagePrefixes.DependencyViaHttp + "{"
+            MessagePrefixes.DependencyViaHttp + " {"
             + ContextProperties.DependencyTracking.TargetName + "} for {"
             + ContextProperties.DependencyTracking.DependencyName + "} completed with {"
             + ContextProperties.DependencyTracking.ResultCode + "} in {"

diff --git a/src/Arcus.Observability.Telemetry.Core/MessagePrefixes.cs b/src/Arcus.Observability.Telemetry.Core/MessagePrefixes.cs
@@ -7,6 +7,5 @@ public static class MessagePrefixes
         public const string Event = "Events";
         public const string Metric = "Metric";
         public const string RequestViaHttp = "HTTP Request";
-        public const string SecurityEvent = "Security";
     }
 }