Add main readme for traces with best practices

docs/trace/README.md

@@ -0,0 +1,49 @@
+# OpenTelemetry .NET Traces
+
+## Best Practices
+
+### ActivitySource singleton
+
+`ActivitySource` SHOULD only be created once and reused throughout the
+application lifetime. This
+[example](./getting-started-console/Program.cs) shows how
+`ActivitySource` is created as a `static` field and then used in the
+application. You could also look at this ASP.NET Core
+[example](../../examples/AspNetCore/Program.cs) which shows a more Dependency
+Injection friendly way of doing this by extracting the `ActivitySource` into a
+dedicated class called
+[Instrumentation](../../examples/AspNetCore/Instrumentation.cs) which is then
+added as a `Singleton` service.
+
+### Manually creating Activities
+
+As shown in the [getting started](getting-started-console/README.md) guide, it
+is very easy to manually create `Activity`. Due to this, it can be tempting to
+create too many activities (eg: for each method call). In addition to being
+expensive, excessive activities can also make trace visualization harder.
+Instead of manually creating `Activity`, check if you can leverage
+instrumentation libraries, such as [ASP.NET
+Core](../../src/OpenTelemetry.Instrumentation.AspNetCore/README.md),
+[HttpClient](../../src/OpenTelemetry.Instrumentation.Http/README.md) which will
+not only create and populate `Activity` with tags(attributes), but also takes
+care of propagating/restoring the context across process boundaries. If the
+`Activity` produced by the instrumentation library is missing some information
+you need, it is generally recommend to enrich the existing Activity with that
+information, as opposed to creating a new one.
+
+## Common issues that lead to missing traces
+
+- The `ActivitySource` used to create the `Activity` is not added to the
+  `TracerProvider`. Use `AddSource` method to enable the activity from a given
+  `ActivitySource`.
+- `TracerProvider` is disposed too early. You need to ensure that the
+  `TracerProvider` instance is kept active for traces to be collected. In a
+  typical application, a single TracerProvider is built at application startup,
+  and is disposed of at application shutdown. For an ASP.NET Core application,
+  use `AddOpenTelemetry` and `WithTraces` methods from the
+  `OpenTelemetry.Extensions.Hosting` package to correctly setup
+  `TracerProvider`. Here's a [sample ASP.NET Core
+  app](../../examples/AspNetCore/Program.cs) for reference. For simpler
+  applications such as Console apps, refer to this
+  [example](../../docs/trace/getting-started-console/Program.cs).
+- TODO: Sampling

examples/AspNetCore/Controllers/WeatherForecastController.cs

@@ -49,7 +49,7 @@ public IEnumerable<WeatherForecast> Get()
         // that calculating the forecast is an expensive operation and therefore
         // something to be distinguished from the overall request.
         // Note: Tags can be added to the current activity without the need for
-        // a manual activity using Acitivty.Current?.SetTag()
+        // a manual activity using Activity.Current?.SetTag()
         using var activity = this.activitySource.StartActivity("calculate forecast");
 
         var rng = new Random();