diff --git a/conceptual/Npgsql/diagnostics/tracing.md b/conceptual/Npgsql/diagnostics/tracing.md index 9a16f49c2..ef6032436 100644 --- a/conceptual/Npgsql/diagnostics/tracing.md +++ b/conceptual/Npgsql/diagnostics/tracing.md @@ -29,3 +29,71 @@ For example, Zipkin visualizes traces in the following way: ![Zipkin UI Sample](/img/zipkin.png) In this trace, the Npgsql query (to database testdb) took around 800ms, and was nested inside the application's `work1` activity, which also had another unrelated `subtask1`. This allows understanding the relationships between the different activities, and where time is being spent. + +### Enrich Options + +Enrich actions on the tracing options allow activities created by Npgsql to be enriched with additional information from the raw object relating to the activity, or on any exception. +The action is called only when `activity.IsAllDataRequested` is `true`. + +#### `EnrichCommandExecution` + +This action's parameters contain the activity itself (which can be enriched), the name of the event, and either the `NpgsqlCommand` or a tuple also containing an exception, depending on the event name: + +For event name "OnStartActivity", the actual object will be `NpgsqlCommand`. + +For event name "OnFirstResponse", the actual object will be `NpgsqlCommand`. + +For event name "OnStopActivity", the actual object will be `NpgsqlCommand`. + +For event name "OnException", the actual object will be `ValueTuple`. + +Example: + +```csharp +using System; +using Npgsql; +using OpenTelemetry; +using OpenTelemetry.Trace; + +var tracerProvider = Sdk.CreateTracerProviderBuilder() + .AddNpgsql(options => options.EnrichCommandExecution + = (activity, eventName, rawObject) => + { + switch (eventName, rawObject) + { + case ("OnStartActivity", NpgsqlCommand command): + activity.SetTag("command.type", command.CommandType); + break; + case ("OnFirstResponse", NpgsqlCommand command): + activity.SetTag("received-first-response", DateTime.UtcNow); + break; + case ("OnStopActivity", NpgsqlCommand command): + activity.SetTag("command.type", command.CommandType); + break; + case ("OnException", (NpgsqlCommand command, Exception exception)): + activity.SetTag("stackTrace", exception.StackTrace); + break; + } + }).Build(); +``` + +### Record Options + +Recording of an `ActivityEvent` can be disabled for exceptions or the point at which a first response is received, by setting the corresponding flags on the options. +Note that even when disabled, the corresponding Enrich invocations will still occur ("OnException" and "OnFirstResponse" respectively, see above). + +Example: + +```csharp +using System; +using Npgsql; +using OpenTelemetry; +using OpenTelemetry.Trace; + +var tracerProvider = Sdk.CreateTracerProviderBuilder() + .AddNpgsql(options => + { + options.RecordCommandExecutionException = false; // Default = true + options.RecordCommandExecutionFirstResponse = false; // Default = true + }).Build(); +``` \ No newline at end of file