diff --git a/src/content/docs/dotnet/opentelemetry-tracing.md b/src/content/docs/dotnet/opentelemetry-tracing.md new file mode 100644 index 00000000..d0761293 --- /dev/null +++ b/src/content/docs/dotnet/opentelemetry-tracing.md @@ -0,0 +1,132 @@ +--- +title: OpenTelemetry Tracing +--- + +WireMock.Net supports distributed tracing via `System.Diagnostics.Activity` and can export traces using OpenTelemetry. + +## Activity Tracing + +WireMock.Net creates `System.Diagnostics.Activity` objects for request tracing when `ActivityTracingOptions` is configured. This uses the built-in .NET distributed tracing infrastructure. + +### Basic Configuration + +``` c# +var settings = new WireMockServerSettings +{ + ActivityTracingOptions = new ActivityTracingOptions + { + ExcludeAdminRequests = true, + RecordRequestBody = false, + RecordResponseBody = false, + RecordMatchDetails = true + } +}; + +var server = WireMockServer.Start(settings); +``` + +### ActivityTracingOptions Properties + +| Property | Description | Default | +|----------|-------------|---------| +| `ExcludeAdminRequests` | Exclude `/__admin/*` from tracing | `true` | +| `RecordRequestBody` | Include request body in trace attributes | `false` | +| `RecordResponseBody` | Include response body in trace attributes | `false` | +| `RecordMatchDetails` | Include mapping match details in trace attributes | `true` | + +## OpenTelemetry Export + +To export traces to an OpenTelemetry collector, install the `WireMock.Net.OpenTelemetry` package: + +```bash +dotnet add package WireMock.Net.OpenTelemetry +``` + +### Using AdditionalServiceRegistration + +``` c# +using WireMock.OpenTelemetry; +using WireMock.Server; +using WireMock.Settings; + +var settings = new WireMockServerSettings +{ + ActivityTracingOptions = new ActivityTracingOptions + { + ExcludeAdminRequests = true, + RecordMatchDetails = true + }, + AdditionalServiceRegistration = services => + { + services.AddWireMockOpenTelemetry(new OpenTelemetryOptions + { + ExcludeAdminRequests = true, + OtlpExporterEndpoint = "http://localhost:4317" + }); + } +}; + +var server = WireMockServer.Start(settings); +``` + +### Custom TracerProvider Configuration + +``` c# +using OpenTelemetry; +using OpenTelemetry.Trace; +using WireMock.OpenTelemetry; + +using var tracerProvider = Sdk.CreateTracerProviderBuilder() + .AddWireMockInstrumentation(new OpenTelemetryOptions()) + .AddOtlpExporter(options => + { + options.Endpoint = new Uri("http://localhost:4317"); + }) + .Build(); +``` + +### OpenTelemetryOptions Properties + +| Property | Description | Default | +|----------|-------------|---------| +| `ExcludeAdminRequests` | Exclude `/__admin/*` from ASP.NET Core instrumentation | `true` | +| `OtlpExporterEndpoint` | OTLP collector endpoint URL | Uses `OTEL_EXPORTER_OTLP_ENDPOINT` env var | + +## Trace Attributes + +WireMock traces include standard HTTP attributes and WireMock-specific attributes: + +**HTTP attributes:** +- `http.request.method` +- `url.full` +- `url.path` +- `server.address` +- `http.response.status_code` +- `client.address` + +**WireMock attributes:** +- `wiremock.mapping.matched` - Whether a mapping was found +- `wiremock.mapping.guid` - GUID of the matched mapping +- `wiremock.mapping.title` - Title of the matched mapping +- `wiremock.match.score` - Match score +- `wiremock.request.guid` - GUID of the request + +## CLI Arguments + +When using WireMock.Net.StandAlone or Docker, configure tracing via command-line arguments: + +**Activity Tracing:** +```bash +--ActivityTracingEnabled true +--ActivityTracingExcludeAdminRequests true +--ActivityTracingRecordRequestBody false +--ActivityTracingRecordResponseBody false +--ActivityTracingRecordMatchDetails true +``` + +**OpenTelemetry Export:** +```bash +--OpenTelemetryEnabled true +--OpenTelemetryOtlpExporterEndpoint http://localhost:4317 +--OpenTelemetryExcludeAdminRequests true +``` diff --git a/src/content/docs/dotnet/settings.md b/src/content/docs/dotnet/settings.md index 6fee4c59..c0177f69 100644 --- a/src/content/docs/dotnet/settings.md +++ b/src/content/docs/dotnet/settings.md @@ -254,6 +254,30 @@ This is a Enum Flag with these values: - AllowAnyOrigin - AllowAll +### ActivityTracingOptions +Configure distributed tracing via `System.Diagnostics.Activity`. When set to a non-null value, WireMock.Net creates activity spans for each request. + +``` c# +var server = WireMockServer.Start(new WireMockServerSettings +{ + ActivityTracingOptions = new ActivityTracingOptions + { + ExcludeAdminRequests = true, + RecordRequestBody = false, + RecordResponseBody = false, + RecordMatchDetails = true + } +}); +``` + +Where +* `ExcludeAdminRequests` = Exclude `/__admin/*` requests from tracing (default: true). +* `RecordRequestBody` = Include request body in trace attributes (default: false). +* `RecordResponseBody` = Include response body in trace attributes (default: false). +* `RecordMatchDetails` = Include mapping match details in trace attributes (default: true). + +To export traces via OpenTelemetry, see [OpenTelemetry Tracing](opentelemetry-tracing/). + diff --git a/src/content/docs/dotnet/wiremock-commandline-parameters.md b/src/content/docs/dotnet/wiremock-commandline-parameters.md index 52a75a59..7e9552cc 100644 --- a/src/content/docs/dotnet/wiremock-commandline-parameters.md +++ b/src/content/docs/dotnet/wiremock-commandline-parameters.md @@ -31,4 +31,20 @@ See also [Proxy and Record Settings](https://github.com/WireMock-Net/WireMock.Ne | Argument Name| Value Type | Default | Description | | - | - | - | - | | `--ProxyUrl` | string | | The URL to use for proxying. -| `--SaveMapping` | boolean| | Save the mapping for each request/response to the internal Mappings.. \ No newline at end of file +| `--SaveMapping` | boolean| | Save the mapping for each request/response to the internal Mappings.. + +### Activity Tracing Settings [Optional] +| Argument Name| Value Type | Default | Description | +| - | - | - | - | +| `--ActivityTracingEnabled` | boolean | false | Enable activity tracing for requests. | +| `--ActivityTracingExcludeAdminRequests` | boolean | true | Exclude `/__admin/*` requests from tracing. | +| `--ActivityTracingRecordRequestBody` | boolean | false | Include request body in trace attributes. | +| `--ActivityTracingRecordResponseBody` | boolean | false | Include response body in trace attributes. | +| `--ActivityTracingRecordMatchDetails` | boolean | true | Include mapping match details in trace attributes. | + +### OpenTelemetry Settings [Optional] +| Argument Name| Value Type | Default | Description | +| - | - | - | - | +| `--OpenTelemetryEnabled` | boolean | false | Enable OpenTelemetry export. | +| `--OpenTelemetryOtlpExporterEndpoint` | string | | OTLP collector endpoint URL. Uses `OTEL_EXPORTER_OTLP_ENDPOINT` env var if not set. | +| `--OpenTelemetryExcludeAdminRequests` | boolean | true | Exclude `/__admin/*` from ASP.NET Core instrumentation. | \ No newline at end of file