From 0742779485948e54cccd6aaaa9843fde0362ea73 Mon Sep 17 00:00:00 2001 From: David Hayden Date: Thu, 20 Jan 2022 18:32:53 +0000 Subject: [PATCH 1/4] Add documentation for enriching activities --- conceptual/Npgsql/diagnostics/tracing.md | 38 ++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/conceptual/Npgsql/diagnostics/tracing.md b/conceptual/Npgsql/diagnostics/tracing.md index 9a16f49c2..a3a8623ab 100644 --- a/conceptual/Npgsql/diagnostics/tracing.md +++ b/conceptual/Npgsql/diagnostics/tracing.md @@ -29,3 +29,41 @@ 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 + +This option allows one to enrich the activity with additional information from the `NpgsqlCommand`, or on any exception. +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 either the `NpgsqlCommand` or an exception, depending on the event name: + +For event name "OnStartActivity", 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 `Exception`. + +Example: + +```csharp +using System; +using Npgsql; +using OpenTelemetry; + +var tracerProvider = Sdk.CreateTracerProviderBuilder() + .AddNpgsql(options => options.Enrich + = (activity, eventName, rawObject) => + { + switch (eventName, rawObject) + { + case ("OnStartActivity", NpgsqlCommand command): + activity.SetTag("command.type", command.CommandType); + break; + case ("OnStopActivity", NpgsqlCommand command): + activity.SetTag("command.type", command.CommandType); + break; + case ("OnException", Exception exception): + activity.SetTag("stackTrace", exception.StackTrace); + break; + } + }).Build(); +``` \ No newline at end of file From 5218e02d04a1d21793f46b7299796fbc5568b9ec Mon Sep 17 00:00:00 2001 From: David Hayden Date: Thu, 20 Jan 2022 18:56:56 +0000 Subject: [PATCH 2/4] Rename Enrich -> EnrichCommandExecution --- conceptual/Npgsql/diagnostics/tracing.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/conceptual/Npgsql/diagnostics/tracing.md b/conceptual/Npgsql/diagnostics/tracing.md index a3a8623ab..ed05021e7 100644 --- a/conceptual/Npgsql/diagnostics/tracing.md +++ b/conceptual/Npgsql/diagnostics/tracing.md @@ -32,9 +32,12 @@ In this trace, the Npgsql query (to database testdb) took around 800ms, and was ### Enrich -This option allows one to enrich the activity with additional information from the `NpgsqlCommand`, or on any exception. -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 either the `NpgsqlCommand` or an exception, depending on the event name: +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 an exception, depending on the event name: For event name "OnStartActivity", the actual object will be `NpgsqlCommand`. @@ -48,9 +51,10 @@ Example: using System; using Npgsql; using OpenTelemetry; +using OpenTelemetry.Trace; var tracerProvider = Sdk.CreateTracerProviderBuilder() - .AddNpgsql(options => options.Enrich + .AddNpgsql(options => options.EnrichCommandExecution = (activity, eventName, rawObject) => { switch (eventName, rawObject) From 37a0ca9c1c06d15452318335a9c9b1283908948f Mon Sep 17 00:00:00 2001 From: David Hayden Date: Mon, 7 Mar 2022 19:24:52 +0000 Subject: [PATCH 3/4] Pass command + exception to enrich for OnException event --- conceptual/Npgsql/diagnostics/tracing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/conceptual/Npgsql/diagnostics/tracing.md b/conceptual/Npgsql/diagnostics/tracing.md index ed05021e7..2cdd4701d 100644 --- a/conceptual/Npgsql/diagnostics/tracing.md +++ b/conceptual/Npgsql/diagnostics/tracing.md @@ -37,13 +37,13 @@ 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 an exception, depending on the event name: +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 "OnStopActivity", the actual object will be `NpgsqlCommand`. -For event name "OnException", the actual object will be `Exception`. +For event name "OnException", the actual object will be `ValueTuple`. Example: @@ -65,7 +65,7 @@ var tracerProvider = Sdk.CreateTracerProviderBuilder() case ("OnStopActivity", NpgsqlCommand command): activity.SetTag("command.type", command.CommandType); break; - case ("OnException", Exception exception): + case ("OnException", (NpgsqlCommand command, Exception exception)): activity.SetTag("stackTrace", exception.StackTrace); break; } From 5b351e7446218c072c8e8037e4c2293a4a17e03e Mon Sep 17 00:00:00 2001 From: David Hayden Date: Tue, 19 Apr 2022 20:15:15 +0100 Subject: [PATCH 4/4] Add documentation for disabling activity events --- conceptual/Npgsql/diagnostics/tracing.md | 28 +++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/conceptual/Npgsql/diagnostics/tracing.md b/conceptual/Npgsql/diagnostics/tracing.md index 2cdd4701d..ef6032436 100644 --- a/conceptual/Npgsql/diagnostics/tracing.md +++ b/conceptual/Npgsql/diagnostics/tracing.md @@ -30,7 +30,7 @@ For example, Zipkin visualizes traces in the following way: 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 +### 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`. @@ -41,6 +41,8 @@ This action's parameters contain the activity itself (which can be enriched), th 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`. @@ -62,6 +64,9 @@ var tracerProvider = Sdk.CreateTracerProviderBuilder() 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; @@ -70,4 +75,25 @@ var tracerProvider = Sdk.CreateTracerProviderBuilder() 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