Instrumentation

Every integration emits traces and metrics via System.Diagnostics (ActivitySource / Meter). Any OpenTelemetry-compatible pipeline can consume this data directly. The ActivitySource and the Meter share the name in AddressValidationTelemetry.SourceName ("Visus.AddressValidation").

Setup

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService("MyApp"))
    .WithTracing(tracing => tracing.AddSource(AddressValidationTelemetry.SourceName))
    .WithMetrics(metrics => metrics.AddMeter(AddressValidationTelemetry.SourceName));

This requires the OpenTelemetry.Extensions.Hosting package:

dotnet add package OpenTelemetry.Extensions.Hosting

Note

The snippet above only registers the source and meter. It does not send data anywhere; add an exporter to WithTracing / WithMetrics as shown in Exporting to a Backend below.

What Is Measured

Activities

Name	Emitted By	Tags	Description
`address_validation.validate`	`AbstractAddressValidationService<TRequest, TApiResponse>`	`address_validation.request_type`, `address_validation.country`, `address_validation.result`	Wraps a single `ValidateAsync` call, from request validation through response mapping.
`address_validation.validate_many`	`AbstractBatchAddressValidationService<TRequest, TApiResponse>`	`address_validation.request_type`, `address_validation.batch_size`, `address_validation.country`, `address_validation.result`	Wraps a single `ValidateManyAsync` call, from per-item request validation through response mapping. `address_validation.country` is the shared country when every item in the batch has the same country. It falls back to the `batch` sentinel when the batch spans multiple countries.
`address_validation.token_fetch`	`AbstractAuthenticationService<TClient>`	`address_validation.client_type`, `address_validation.result`	Wraps a single access token fetch on a cache miss. Not started on a cache hit.

All activities are marked with ActivityStatusCode.Error and record the exception when the underlying operation throws.

Metrics

Name	Kind	Unit	Tags	Description
`visus.address_validation.validate.duration`	Histogram<double>	s	`address_validation.request_type`, `address_validation.result`, `address_validation.country`	Duration of a `ValidateAsync` or `ValidateManyAsync` call. For a batch call, `address_validation.country` is the shared country, or the `batch` sentinel when the batch spans multiple countries.
`visus.address_validation.validate.response_warning_count`	Histogram<long>	—	`address_validation.request_type`, `address_validation.result`, `address_validation.country`	Number of warnings on the produced response. Not recorded when the API returns no response. For a batch call, one recording is made per item.
`visus.address_validation.validate.response_suggestion_count`	Histogram<long>	—	`address_validation.request_type`, `address_validation.result`, `address_validation.country`	Number of suggestions on the produced response. Not recorded when the API returns no response. For a batch call, one recording is made per item.
`visus.address_validation.token_fetch.duration`	Histogram<double>	s	`address_validation.client_type`, `address_validation.result`	Duration of a token fetch (cache miss only).
`visus.address_validation.token_fetch.cache_result`	Counter<long>	—	`address_validation.client_type`, `address_validation.cache_result`	Incremented on every token cache lookup, whether it hits or misses.

Tag Values

Tag	Values
`address_validation.result` (validate)	`success`, `invalid_request`, `no_response`, `invalid_response`, `error`
`address_validation.result` (validate_many)	`success`, `partial`, `invalid_request`, `no_response`, `error` for the overall call; `success`, `invalid_request`, `invalid_response` per item
`address_validation.result` (token_fetch)	`success`, `empty_token`, `error`
`address_validation.cache_result`	`hit`, `miss`
`address_validation.request_type`	The `TRequest` type name (e.g., `FedExAddressValidationRequest`)
`address_validation.batch_size`	The number of requests passed to `ValidateManyAsync`
`address_validation.client_type`	The `TClient` type name of the provider's authentication client
`address_validation.country`	The `CountryCode` of the request, or `unknown` when absent. For the overall `validate_many` activity and its duration metric, this tag is the shared country when every item in the batch has the same country. Otherwise, this tag is `batch`.

Exporting to a Backend

The tabs below each extend the Setup snippet with an exporter. Pick the one that matches your observability stack.

For local development and debugging. Writes traces and metrics to standard output.

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService("MyApp"))
    .WithTracing(tracing => tracing
        .AddSource(AddressValidationTelemetry.SourceName)
        .AddConsoleExporter())
    .WithMetrics(metrics => metrics
        .AddMeter(AddressValidationTelemetry.SourceName)
        .AddConsoleExporter());

dotnet add package OpenTelemetry.Exporter.Console

Sends data to any collector that accepts the OpenTelemetry Protocol (including Jaeger and Grafana Tempo) via a local OpenTelemetry Collector.

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService("MyApp"))
    .WithTracing(tracing => tracing
        .AddSource(AddressValidationTelemetry.SourceName)
        .AddOtlpExporter(otlp => otlp.Endpoint = new Uri("http://localhost:4317")))
    .WithMetrics(metrics => metrics
        .AddMeter(AddressValidationTelemetry.SourceName)
        .AddOtlpExporter(otlp => otlp.Endpoint = new Uri("http://localhost:4317")));

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

Sends data directly to Azure Monitor Application Insights using its connection string. No collector required.

string connectionString = builder.Configuration["ApplicationInsights:ConnectionString"]!;

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService("MyApp"))
    .WithTracing(tracing => tracing
        .AddSource(AddressValidationTelemetry.SourceName)
        .AddAzureMonitorTraceExporter(azure => azure.ConnectionString = connectionString))
    .WithMetrics(metrics => metrics
        .AddMeter(AddressValidationTelemetry.SourceName)
        .AddAzureMonitorMetricExporter(azure => azure.ConnectionString = connectionString));

dotnet add package Azure.Monitor.OpenTelemetry.Exporter

The Datadog Agent accepts OTLP directly, so this reuses the standard OTLP exporter pointed at the agent's OTLP intake port.

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService("MyApp"))
    .WithTracing(tracing => tracing
        .AddSource(AddressValidationTelemetry.SourceName)
        .AddOtlpExporter(otlp => otlp.Endpoint = new Uri("http://localhost:4318")))
    .WithMetrics(metrics => metrics
        .AddMeter(AddressValidationTelemetry.SourceName)
        .AddOtlpExporter(otlp => otlp.Endpoint = new Uri("http://localhost:4318")));

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

Note

The Datadog Agent must have OTLP ingestion enabled (otlp_config.receiver.protocols.grpc in datadog.yaml, or the DD_OTLP_CONFIG_RECEIVER_PROTOCOLS_GRPC_ENDPOINT environment variable). See the Datadog OTLP ingestion docs for details.

New Relic accepts OTLP directly. No collector required. Authenticate with a license key sent as the api-key header.

string licenseKey = builder.Configuration["NewRelic:LicenseKey"]!;

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService("MyApp"))
    .WithTracing(tracing => tracing
        .AddSource(AddressValidationTelemetry.SourceName)
        .AddOtlpExporter(otlp =>
        {
            otlp.Endpoint = new Uri("https://otlp.nr-data.net:4317");
            otlp.Headers = $"api-key={licenseKey}";
        }))
    .WithMetrics(metrics => metrics
        .AddMeter(AddressValidationTelemetry.SourceName)
        .AddOtlpExporter(otlp =>
        {
            otlp.Endpoint = new Uri("https://otlp.nr-data.net:4317");
            otlp.Headers = $"api-key={licenseKey}";
        }));

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

Note

Use https://otlp.eu01.nr-data.net:4317 instead if your account is hosted in the EU data center. See the New Relic OTLP endpoint docs for details.

Sends data to a local AWS Distro for OpenTelemetry (ADOT) Collector, which forwards traces to X-Ray and metrics to CloudWatch.

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService("MyApp"))
    .WithTracing(tracing => tracing
        .AddSource(AddressValidationTelemetry.SourceName)
        .AddOtlpExporter(otlp => otlp.Endpoint = new Uri("http://localhost:4317")))
    .WithMetrics(metrics => metrics
        .AddMeter(AddressValidationTelemetry.SourceName)
        .AddOtlpExporter(otlp => otlp.Endpoint = new Uri("http://localhost:4317")));

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

Note

Configuring the ADOT Collector itself (X-Ray and CloudWatch exporters, IAM permissions) is outside the scope of this library. See the ADOT Collector documentation for setup instructions.

Exposes metrics on a scrape endpoint for Prometheus to pull, visualized in Grafana. Traces still need an OTLP target such as Tempo; see the OTLP Collector tab above.

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService("MyApp"))
    .WithMetrics(metrics => metrics
        .AddMeter(AddressValidationTelemetry.SourceName)
        .AddPrometheusExporter());

// After building the app:
app.MapPrometheusScrapingEndpoint();

dotnet add package OpenTelemetry.Exporter.Prometheus.AspNetCore

Table of Contents

Instrumentation

Setup

Note

What Is Measured

Activities

Metrics

Tag Values

Exporting to a Backend