diff --git a/README.md b/README.md index 0367764..7d7f208 100644 --- a/README.md +++ b/README.md @@ -28,3 +28,5 @@ New-TracerProviderBuilder | Add-ExporterConsole | Start-Tracer ``` + +See the [sample](samples/) module for a walkthrough of how to instrument your own module. diff --git a/docs/Add-HttpClientInstrumentation.md b/docs/Add-HttpClientInstrumentation.md index d7ae5b5..45329dd 100644 --- a/docs/Add-HttpClientInstrumentation.md +++ b/docs/Add-HttpClientInstrumentation.md @@ -1,27 +1,44 @@ # Add-HttpClientInstrumentation -Adds Http Client Instrumentation +Adds Http Client Instrumentation. ## Parameters ### Parameter Set 1 - `[TracerProviderBuilderBase]` **TracerProvider** _Instance of TracerProviderBuilderBase._ Mandatory, ValueFromPipeline +- `[ScriptBlock]` **RequestFilter** _A filter function that determines whether or not to collect telemetry on a per request basis. Must return a `[bool]` and act on an instance of `[Net.Http.HttpRequestMessage]`._ +- `[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 { $this.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/README.md b/docs/README.md index 9a30a89..d78a4bf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,7 @@ 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._ 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 4b583ee..2d4721d 100644 --- a/samples/sample.psm1 +++ b/samples/sample.psm1 @@ -6,7 +6,7 @@ $activitySource = New-ActivitySource -Name potel-sample New-TracerProviderBuilder | Add-TracerSource -ActivitySource $activitySource | Add-ResourceConfiguration -ServiceName potel-sample -Attribute @{"host.name" = $(hostname) } | -Add-HttpClientInstrumentation | +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 1b9c8e5..f41f0db 100644 --- a/src/public/Add-HttpClientInstrumentation.ps1 +++ b/src/public/Add-HttpClientInstrumentation.ps1 @@ -1,29 +1,68 @@ +<# +.SYNOPSIS + Adds Http Client Instrumentation. +.DESCRIPTION + 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]` and act on an instance of `[Net.Http.HttpRequestMessage]`. +.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 { $this.RequestUri -like '*google.com*' } + + Only collect web requests sent to the "google.com" domain. +.LINK + New-TracerProviderBuilder +.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 { - <# - .SYNOPSIS - Adds Http Client Instrumentation - .DESCRIPTION - Adds Http Client Instrumentation - .PARAMETER TracerProvider - Instance of TracerProviderBuilderBase. - .INPUTS - Instance of TracerProviderBuilderBase - .OUTPUTS - TracerProviderBuilderBase - .EXAMPLE - New-TracerProviderBuilder | Add-HttpClientInstrumentation - .LINK - New-TracerProviderBuilder - #> [CmdletBinding()] param ( - # Parameter help description - [Parameter(Mandatory, Position = 0, ValueFromPipeline)] + [Parameter(Mandatory, Position = 1, ValueFromPipeline)] [OpenTelemetry.Trace.TracerProviderBuilderBase] - $TracerProvider + $TracerProvider, + + [Parameter(Position = 0)] + [scriptblock] + $RequestFilter = { $true }, + + [Parameter()] + [switch] + $RecordException ) - $type = [System.AppDomain]::CurrentDomain.GetAssemblies() | Where-Object Location -like "*potel*lib*OpenTelemetry.Instrumentation.Http.dll" | Select-Object -Last 1 + $options = { + param([OpenTelemetry.Instrumentation.Http.HttpClientTraceInstrumentationOptions]$o) + + $o.FilterHttpRequestMessage = { param([Net.Http.HttpRequestMessage]$request) + $context = [system.Collections.Generic.List[PSVariable]]::new() + $context.Add([PSVariable]::new('_', $request)) + $context.Add([PSVariable]::new('this', $request)) + $context.Add([PSVariable]::new('PSItem', $request)) + $RequestFilter.InvokeWithContext($null, $context) + } + + $o.RecordException = $RecordException + + }.GetNewClosure() + + [OpenTelemetry.Trace.HttpClientInstrumentationTracerProviderBuilderExtensions]::AddHttpClientInstrumentation($TracerProvider, $null, $options) - $type.GetType('OpenTelemetry.Trace.HttpClientInstrumentationTracerProviderBuilderExtensions').GetMethod('AddHttpClientInstrumentation', ([System.Reflection.BindingFlags]::Public -bor [System.Reflection.BindingFlags]::Static), [OpenTelemetry.Trace.TracerProviderBuilder]).Invoke($null, @($TracerProvider)) } \ No newline at end of file diff --git a/version.json b/version.json index b6d60d5..a15ae31 100644 --- a/version.json +++ b/version.json @@ -1,6 +1,6 @@ { "$schema": "https://raw.githubusercontent.com/dotnet/Nerdbank.GitVersioning/main/src/NerdBank.GitVersioning/version.schema.json", - "version": "0.2", + "version": "0.3", "cloudBuild": { "buildNumber": { "enabled": true