Document SqlClientInstrumentation Enrich behavior (#1604)

Co-authored-by: Cijo Thomas <cithomas@microsoft.com>

src/OpenTelemetry.Instrumentation.SqlClient/README.md

@@ -120,6 +120,41 @@ using Sdk.CreateTracerProviderBuilder()
     .Build();
 ```
 
+### Enrich
+
+This option, available on .NET Core only, allows one to enrich the activity
+with additional information from the raw `SqlCommand` object. The `Enrich`
+action is called only when `activity.IsAllDataRequested` is `true`. It contains
+the activity itself (which can be enriched), the name of the event, and the
+actual raw object.
+
+Currently there is only one event name reported, "OnCustom". The actual object
+is `Microsoft.Data.SqlClient.SqlCommand` for `Microsoft.Data.SqlClient` and
+`System.Data.SqlClient.SqlCommand` for `System.Data.SqlClient`.
+
+The following code snippet shows how to add additional tags using `Enrich`.
+
+```csharp
+using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+    .AddSqlClientInstrumentation(opt => opt.Enrich
+        = (activity, eventName, rawObject) =>
+    {
+        if (eventName.Equals("OnCustom"))
+        {
+            if (rawObject is SqlCommand cmd)
+            {
+                activity.SetTag("db.commandTimeout", cmd.CommandTimeout);
+            }
+        };
+    })
+    .Build();
+```
+
+[Processor](../../docs/trace/extending-the-sdk/README.md#processor),
+is the general extensibility point to add additional properties to any activity.
+The `Enrich` option is specific to this instrumentation, and is provided to
+get access to `SqlCommand` object.
+
 ## References
 
 * [OpenTelemetry Project](https://opentelemetry.io/)

src/OpenTelemetry.Instrumentation.SqlClient/SqlClientInstrumentationOptions.cs

@@ -63,9 +63,26 @@ namespace OpenTelemetry.Instrumentation.SqlClient
         /// <remarks>
         /// <para><see cref="Activity"/>: the activity being enriched.</para>
         /// <para>string: the name of the event.</para>
-        /// <para>object: the raw object from which additional information can be extracted to enrich the activity.
-        /// The type of this object depends on the event, which is given by the above parameter.</para>
+        /// <para>object: the raw <c>SqlCommand</c> object from which additional information can be extracted to enrich the activity.</para>
+        /// <para>See also: <a href="https://github.com/open-telemetry/opentelemetry-dotnet/tree/master/src/OpenTelemetry.Instrumentation.SqlClient#Enrich">example</a>.</para>
         /// </remarks>
+        /// <example>
+        /// <code>
+        /// using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+        ///     .AddSqlClientInstrumentation(opt => opt.Enrich
+        ///         = (activity, eventName, rawObject) =>
+        ///      {
+        ///         if (eventName.Equals("OnCustom"))
+        ///         {
+        ///             if (rawObject is SqlCommand cmd)
+        ///             {
+        ///                 activity.SetTag("db.commandTimeout", cmd.CommandTimeout);
+        ///             }
+        ///         }
+        ///      })
+        ///     .Build();
+        /// </code>
+        /// </example>
         public Action<Activity, string, object> Enrich { get; set; }
 
         internal static SqlConnectionDetails ParseDataSource(string dataSource)