diff --git a/docs/Add-HttpClientInstrumentation.md b/docs/Add-HttpClientInstrumentation.md index 57fb6a1..e59ebb6 100644 --- a/docs/Add-HttpClientInstrumentation.md +++ b/docs/Add-HttpClientInstrumentation.md @@ -1,28 +1,44 @@ # Add-HttpClientInstrumentation -Adds Http Client Instrumentation +Adds Http Client Instrumentation. ## Parameters ### Parameter Set 1 - `[TracerProviderBuilderBase]` **TracerProvider** _Instance of TracerProviderBuilderBase._ Mandatory, ValueFromPipeline -- `[Action[OpenTelemetry.Instrumentation.Http.HttpClientTraceInstrumentationOptions]]` **Options** _Parameter help description_ +- `[ScriptBlock]` **RequestFilter** _A filter function that determines whether or not to collect telemetry on a per request basis. Must return a bool._ +- `[Switch]` **RecordException** _Indicating whether exception will be recorded ActivityEvent or not. This instrumentation automatically sets Activity Status to Error if the Http StatusCode is >= 400. Additionally, `RecordException` feature may be turned on, to store the exception to the Activity itself as ActivityEvent._ ## Examples ### Example 1 - +Enabled the zero-code instrumentation of System.Net.Http.HttpClient methods. ```powershell New-TracerProviderBuilder | Add-HttpClientInstrumentation ``` +### Example 2 + +Only collect web requests with a `Method` of `Get`. + +```powershell +New-TracerProviderBuilder | Add-HttpClientInstrumentation { $_.Method -eq 'Get' } +``` +### Example 3 + +Only collect web requests sent to the "google.com" domain. + +```powershell +New-TracerProviderBuilder | Add-HttpClientInstrumentation { $_.RequestUri -like '*google.com*' } +``` ## Links - [New-TracerProviderBuilder](New-TracerProviderBuilder.md) - [https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.Http/README.md](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.Http/README.md) +- [https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httprequestmessage?view=netstandard-2.1#properties](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httprequestmessage?view=netstandard-2.1#properties) ## Outputs diff --git a/docs/New-HttpClientTraceInstrumentationOption.md b/docs/New-HttpClientTraceInstrumentationOption.md deleted file mode 100644 index 8445428..0000000 --- a/docs/New-HttpClientTraceInstrumentationOption.md +++ /dev/null @@ -1,42 +0,0 @@ -# New-HttpClientTraceInstrumentationOption - -Initializes a new instance of the HttpClientTraceInstrumentationOptions class for HttpClient instrumentation. - -## Parameters - -### Parameter Set 1 - -- `[Func[Net.Http.HttpRequestMessage, bool]]` **RequestFilter** _A filter function that determines whether or not to collect telemetry on a per request basis._ -- `[Switch]` **RecordException** _Indicating whether exception will be recorded ActivityEvent or not. This instrumentation automatically sets Activity Status to Error if the Http StatusCode is >= 400. Additionally, `RecordException` feature may be turned on, to store the exception to the Activity itself as ActivityEvent._ - -## Examples - -### Example 1 - -Collect only web requests with a `Method` of `Get`. - -```powershell -$options = New-HttpClientTraceInstrumentationOption -RequestFilter {param([Net.Http.HttpRequestMessage]$request) $request.Method -eq 'Get' } -New-TracerProviderBuilder | Add-HttpClientInstrumentation -Options $options -``` - -### Example 2 - -Collect only web requests send to the "google.com" domain. - -```powershell -$options = New-HttpClientTraceInstrumentationOption -RequestFilter {param([Net.Http.HttpRequestMessage]$request) $request.RequestUri -like '*google.com*' } -New-TracerProviderBuilder | Add-HttpClientInstrumentation -Options $options -``` - -## Links - -- [https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httprequestmessage?view=netstandard-2.1#properties](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httprequestmessage?view=netstandard-2.1#properties) - -## Notes - -Filter scriptblock must return a bool. `[Func[Net.Http.HttpRequestMessage, bool]]` - -## Outputs - -- `OpenTelemetry.Instrumentation.Http.HttpClientTraceInstrumentationOptions` diff --git a/docs/README.md b/docs/README.md index fbf79f4..d78a4bf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,14 +8,13 @@ PowerShell module for collecting and sending Open Telemetry - [Add-ActivityTag](Add-ActivityTag.md) _Add key-value data called Tags to an Activity._ - [Add-ExporterConsole](Add-ExporterConsole.md) _Adds a Console Exporter_ - [Add-ExporterOtlpTrace](Add-ExporterOtlpTrace.md) _Adds an OTLP Exporter_ -- [Add-HttpClientInstrumentation](Add-HttpClientInstrumentation.md) _Adds Http Client Instrumentation_ +- [Add-HttpClientInstrumentation](Add-HttpClientInstrumentation.md) _Adds Http Client Instrumentation._ - [Add-ResourceConfiguration](Add-ResourceConfiguration.md) _Adds a Resource Configuration to a Tracer_ - [Add-TracerSource](Add-TracerSource.md) _Adds and ActivitySource to a TracerProviderBuilder_ - [Disable-OtelDiagnosticLog](Disable-OtelDiagnosticLog.md) _Disable the internal logs generated by all OpenTelemetry components._ - [Enable-OtelDiagnosticLog](Enable-OtelDiagnosticLog.md) _Enable the internal logs generated by all OpenTelemetry components._ - [Get-OtelDiagnosticLog](Get-OtelDiagnosticLog.md) _Get the contents of the diagnostic log._ - [New-ActivitySource](New-ActivitySource.md) _Create an instance of ActivitySource._ -- [New-HttpClientTraceInstrumentationOption](New-HttpClientTraceInstrumentationOption.md) _Options for HttpClient instrumentation._ - [New-TracerProviderBuilder](New-TracerProviderBuilder.md) _Creates new Tracer Provider Builder_ - [Set-ActivityStatus](Set-ActivityStatus.md) _Set the Activity Status._ - [Start-Activity](Start-Activity.md) _Start an Activity._ diff --git a/samples/README.md b/samples/README.md index 0fed129..eca93ae 100644 --- a/samples/README.md +++ b/samples/README.md @@ -48,7 +48,7 @@ The Sample module creates a Tracer in manifest using the Service Name `potel-sam We attach two Exporters - OtlpTrace and Console. All activities will be sent to both Exporters. The OtlpTrace exporter will send data to Jaeger in this instance and the Console exporter will write output to StdOut. -This sample also uses the [Zero-code instrumentation](https://opentelemetry.io/docs/concepts/instrumentation/zero-code/) for `System.Net.Http.HttPClient` which will automatically create Activities when methods of `HttPClient` are invoked. +This sample also uses the [Zero-code instrumentation](https://opentelemetry.io/docs/concepts/instrumentation/zero-code/) for `System.Net.Http.HttPClient` which will automatically create Activities when methods of `HttPClient` are invoked. In this case we pass a filter script to only collect requests made to any google.com address. The Tracer exists globally in the PowerShell session in the current version of **potel**. This brings with it some considerations. The `HttPClient` instrumentation will record every instance of `HttPClient` for any process within PowerShell. Filtering has not yet been implemented. It will also continue to generate new Activities/Spans until `Stop-Tracer` is called or the PowerShell process is stopped. diff --git a/samples/sample.psm1 b/samples/sample.psm1 index 7b46854..2d4721d 100644 --- a/samples/sample.psm1 +++ b/samples/sample.psm1 @@ -1,17 +1,12 @@ # The Activity Source binds Activities (Spans) to a Tracer. $activitySource = New-ActivitySource -Name potel-sample -# Only collect HttpClient requests to the google.com domain -$options = New-HttpClientTraceInstrumentationOption -RequestFilter { - param([Net.Http.HttpRequestMessage]$request) $request.RequestUri -like '*google.com*' -} - # A Tracer provides the configuration and lifecycle of your instrumentation. # The Tracer does nothing itself, but binds inputs and outputs. New-TracerProviderBuilder | Add-TracerSource -ActivitySource $activitySource | Add-ResourceConfiguration -ServiceName potel-sample -Attribute @{"host.name" = $(hostname) } | -Add-HttpClientInstrumentation -Options $options | +Add-HttpClientInstrumentation { $_.RequestUri -like '*google.com*' } | Add-ExporterOtlpTrace -Endpoint http://localhost:4317 | Add-ExporterConsole | Start-Tracer diff --git a/src/public/Add-HttpClientInstrumentation.ps1 b/src/public/Add-HttpClientInstrumentation.ps1 index b545e37..7122e0d 100644 --- a/src/public/Add-HttpClientInstrumentation.ps1 +++ b/src/public/Add-HttpClientInstrumentation.ps1 @@ -1,22 +1,36 @@ <# .SYNOPSIS - Adds Http Client Instrumentation + Adds Http Client Instrumentation. .DESCRIPTION - Adds Http Client Instrumentation + Adds Http Client Instrumentation. .PARAMETER TracerProvider Instance of TracerProviderBuilderBase. +.PARAMETER RequestFilter + A filter function that determines whether or not to collect telemetry on a per request basis. Must return a bool. +.PARAMETER RecordException + Indicating whether exception will be recorded ActivityEvent or not. This instrumentation automatically sets Activity Status to Error if the Http StatusCode is >= 400. Additionally, `RecordException` feature may be turned on, to store the exception to the Activity itself as ActivityEvent. .INPUTS Instance of TracerProviderBuilderBase .OUTPUTS TracerProviderBuilderBase .EXAMPLE New-TracerProviderBuilder | Add-HttpClientInstrumentation + + Enabled the zero-code instrumentation of System.Net.Http.HttpClient methods. +.EXAMPLE + New-TracerProviderBuilder | Add-HttpClientInstrumentation { $_.Method -eq 'Get' } + + Only collect web requests with a `Method` of `Get`. +.EXAMPLE + New-TracerProviderBuilder | Add-HttpClientInstrumentation { $_.RequestUri -like '*google.com*' } + + Only collect web requests sent to the "google.com" domain. .LINK New-TracerProviderBuilder -.LINK - New-HttpClientTraceInstrumentationOption .LINK https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.Http/README.md +.LINK + https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httprequestmessage?view=netstandard-2.1#properties #> function Add-HttpClientInstrumentation { [CmdletBinding()] @@ -26,10 +40,25 @@ function Add-HttpClientInstrumentation { $TracerProvider, [Parameter(Position = 0)] - [Action[OpenTelemetry.Instrumentation.Http.HttpClientTraceInstrumentationOptions]] - $Options + [scriptblock] + $RequestFilter = { $true }, + + [Parameter()] + [switch] + $RecordException ) - [OpenTelemetry.Trace.HttpClientInstrumentationTracerProviderBuilderExtensions]::AddHttpClientInstrumentation($TracerProvider, $null, $Options) + $options = { + param([OpenTelemetry.Instrumentation.Http.HttpClientTraceInstrumentationOptions]$o) + + $o.FilterHttpRequestMessage = { param([Net.Http.HttpRequestMessage]$request) + $RequestFilter.InvokeWithContext($null, [PSVariable]::new('_', $request)) + } + + $o.RecordException = $RecordException + + }.GetNewClosure() + + [OpenTelemetry.Trace.HttpClientInstrumentationTracerProviderBuilderExtensions]::AddHttpClientInstrumentation($TracerProvider, $null, $options) } \ No newline at end of file diff --git a/src/public/New-HttpClientTraceInstrumentationOption.ps1 b/src/public/New-HttpClientTraceInstrumentationOption.ps1 deleted file mode 100644 index 2884f6e..0000000 --- a/src/public/New-HttpClientTraceInstrumentationOption.ps1 +++ /dev/null @@ -1,45 +0,0 @@ -<# -.SYNOPSIS - Options for HttpClient instrumentation. -.DESCRIPTION - Initializes a new instance of the HttpClientTraceInstrumentationOptions class for HttpClient instrumentation. -.PARAMETER RequestFilter - A filter function that determines whether or not to collect telemetry on a per request basis. -.PARAMETER RecordException - Indicating whether exception will be recorded ActivityEvent or not. This instrumentation automatically sets Activity Status to Error if the Http StatusCode is >= 400. Additionally, `RecordException` feature may be turned on, to store the exception to the Activity itself as ActivityEvent. -.NOTES - Filter scriptblock must return a bool. `[Func[Net.Http.HttpRequestMessage, bool]]` -.LINK - https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httprequestmessage?view=netstandard-2.1#properties -.EXAMPLE - $options = New-HttpClientTraceInstrumentationOption -RequestFilter {param([Net.Http.HttpRequestMessage]$request) $request.Method -eq 'Get' } - New-TracerProviderBuilder | Add-HttpClientInstrumentation -Options $options - - Collect only web requests with a `Method` of `Get`. -.EXAMPLE - $options = New-HttpClientTraceInstrumentationOption -RequestFilter {param([Net.Http.HttpRequestMessage]$request) $request.RequestUri -like '*google.com*' } - New-TracerProviderBuilder | Add-HttpClientInstrumentation -Options $options - - Collect only web requests send to the "google.com" domain. -#> -function New-HttpClientTraceInstrumentationOption { - [CmdletBinding()] - [OutputType('OpenTelemetry.Instrumentation.Http.HttpClientTraceInstrumentationOptions')] - param ( - [Parameter(Position = 0)] - [Func[Net.Http.HttpRequestMessage, bool]] - $RequestFilter, - - [Parameter()] - [switch] - $RecordException - ) - - $options = { - param([OpenTelemetry.Instrumentation.Http.HttpClientTraceInstrumentationOptions]$o) - $o.FilterHttpRequestMessage = $RequestFilter - $o.RecordException = $RecordException - } - - $options.GetNewClosure() | Write-Output -} \ No newline at end of file