AppSurface Search
Section API Reference
API Reference Language: C# Component: Observability Audience: developer

Observability

Type

AppSurfaceObservabilityHostBuilderExtensions

Source

Provides host-builder extensions for enabling AppSurface observability outside module discovery.

Method

ConfigureAppSurfaceObservability

IHostBuilder ConfigureAppSurfaceObservability(this IHostBuilder builder, StartupContext context, Action<AppSurfaceObservabilityOptions>? configure = null)
Source

Configures OpenTelemetry logging, tracing, and metrics for an AppSurface host.

Parameters

  • builder
    The host builder to configure.
  • context
    The AppSurface startup context that supplies the default service identity.
  • configure
    Optional code configuration that composes after bound configuration values.

Returns

The supplied builder .

Remarks

Use this extension when a custom host does not activate AppSurfaceObservabilityModule through the module dependency graph. Multiple calls are safe and first registration wins, which keeps configured options aligned with the OpenTelemetry providers and exporters captured during registration.

Type

ResourceBuilderFactory

Source
Method

Create

ResourceBuilder Create(AppSurfaceObservabilityPlan plan)
Source

Creates the shared OpenTelemetry resource builder for AppSurface observability providers.

Parameters

  • plan
    The resolved plan that supplies the service identity metadata.

Returns

A resource builder containing OpenTelemetry defaults plus AppSurface service identity values.

Remarks

Use this factory when logging, tracing, or metrics registration must share the same resource identity. It starts from ResourceBuilder.CreateDefault so OpenTelemetry's standard SDK, process, and host defaults remain available, then applies the AppSurface service name and optional version. Hosts that need additional attributes can still add them through their own OpenTelemetry configuration after AppSurface registration.

Type

IAppSurfaceEnvironmentReader

Source

Reads environment variables for observability plan resolution.

Remarks

This internal seam keeps endpoint precedence tests deterministic without mutating process-wide environment state. Implementations should preserve the platform behavior of returning null when a variable is not set; callers normalize blank values separately so empty environment variables do not become configured endpoints.

Method

GetEnvironmentVariable

string? GetEnvironmentVariable(string variable)
Source

Gets the value of an environment variable.

Parameters

  • variable
    The environment variable name to read.

Returns

The configured value, or null when the variable is not present.

Type

AppSurfaceEnvironmentReader

Source

Default process environment reader used by AppSurface observability.

Remarks

The singleton Instance avoids repeated allocation while keeping the production path explicit. Tests should use IAppSurfaceEnvironmentReader rather than changing real environment variables.

Type

AppSurfaceObservabilityOptions

Source

Configures AppSurface's application-side OpenTelemetry registration.

Remarks

These options live under the AppSurfaceObservability configuration section. The default exporter mode keeps local and test runs quiet unless Aspire or another host supplies an OTLP endpoint. The service identity values are written to OpenTelemetry resource metadata; they do not change the .NET Generic Host application identity used for static web assets or framework hosting behavior.

Property

ExporterMode

AppSurfaceOtlpExporterMode ExporterMode { get; set; } Source

Gets or sets when AppSurface should add OTLP exporters.

Property

OtlpEndpoint

Uri? OtlpEndpoint { get; set; } Source

Gets or sets the AppSurface-owned OTLP endpoint.

Remarks

When set, this endpoint takes precedence over OTEL_EXPORTER_OTLP_ENDPOINT . Use AppSurfaceObservability:OtlpEndpoint in JSON-style configuration or AppSurfaceOtlpEndpointEnvironmentVariable in environment-variable configuration.

Property

ServiceName

string? ServiceName { get; set; } Source

Gets or sets the OpenTelemetry resource service name.

Remarks

When omitted, AppSurface uses Core.StartupContext.ApplicationName and then the root module assembly name fallback.

Property

ServiceVersion

string? ServiceVersion { get; set; } Source

Gets or sets the OpenTelemetry resource service version.

Remarks

AppSurface emits service.version only when this value is configured.

Type

AppSurfaceObservabilityServicesRegistrationMarker

Source

Marks that AppSurface tracing, metrics, resource, and startup-diagnostic services have already been registered.

Remarks

The service-collection extension uses this marker to make provider registration idempotent. First registration wins because OpenTelemetry captures resource and exporter setup when providers are configured; later calls should not silently replace the plan or create duplicate providers.

Type

AppSurfaceObservabilityLoggingRegistrationMarker

Source

Marks that AppSurface OpenTelemetry logging has already been registered.

Remarks

The logging extension uses this marker to preserve first-registration-wins behavior for log exporter setup. Keep this marker separate from AppSurfaceObservabilityServicesRegistrationMarker because logging is registered through ILoggingBuilder before the tracing and metrics service path in module-based hosts.

Type

AppSurfaceObservabilityServiceCollectionExtensions

Source

Provides service-registration extensions for AppSurface observability.

Method

AddAppSurfaceObservability

2 overloads
IServiceCollection AddAppSurfaceObservability(this IServiceCollection services, StartupContext context, IConfiguration configuration, Action<AppSurfaceObservabilityOptions>? configure = null)
Source

Adds AppSurface OpenTelemetry tracing and metrics to the service collection.

Parameters

  • services
    The service collection to configure.
  • context
    The AppSurface startup context that supplies the default service identity.
  • configuration
    Configuration used to bind AppSurfaceObservabilityOptions .
  • configure
    Optional code configuration that composes after bound configuration values.

Returns

The supplied services .

Remarks

This extension is the app-runtime side of Aspire observability: it never references Aspire hosting packages and it registers OTLP exporters only according to AppSurfaceObservabilityOptions.ExporterMode . Repeated calls are idempotent and first registration wins, which keeps configured options aligned with the captured OpenTelemetry resource, tracing, and metrics setup.

IServiceCollection AddAppSurfaceObservability(this IServiceCollection services, StartupContext context, IConfiguration configuration, Action<AppSurfaceObservabilityOptions>? configure, bool registerOptions)
Source

Adds AppSurface tracing and metrics with explicit control over options registration.

Parameters

  • services
    The service collection receiving OpenTelemetry services.
  • context
    The startup context used to resolve default service identity metadata.
  • configuration
    Configuration used to bind and resolve observability options.
  • configure
    Optional code configuration applied after bound configuration values.
  • registerOptions
    true to bind and validate options in DI; false when logging or a host hook has already registered them.

Returns

The supplied services .

Remarks

The registration marker makes this path idempotent. First registration wins because OpenTelemetry captures resource, tracing, metrics, and exporter setup when providers are registered.

Method

ConfigureAppSurfaceObservability

2 overloads
IServiceCollection ConfigureAppSurfaceObservability(this IServiceCollection services, Action<AppSurfaceObservabilityOptions>? configure = null)
Source

Registers and validates AppSurfaceObservabilityOptions without adding OpenTelemetry providers.

Parameters

  • services
    The service collection receiving the options registration.
  • configure
    Optional code configuration that composes after bound configuration values.

Returns

The supplied services .

Remarks

Use this extension for consumers that read IOptions{TOptions} directly. Values that should affect AppSurface-owned OpenTelemetry resource or exporter setup must be supplied through the first provider-registration call, because OpenTelemetry captures that setup when providers are registered.

IServiceCollection ConfigureAppSurfaceObservability(this IServiceCollection services, IConfiguration configuration, Action<AppSurfaceObservabilityOptions>? configure = null)
Source

Registers and validates AppSurface observability options from a supplied configuration instance.

Parameters

  • services
    The service collection receiving the options registration.
  • configuration
    The configuration source to bind from.
  • configure
    Optional code configuration applied after bound configuration values.

Returns

The supplied services .

Remarks

This overload avoids DI configuration split-brain for hosts that pass a specific configuration object into registration. Provider setup must use the same configuration instance that options binding uses.

Method

AddOptionsBuilder

OptionsBuilder<AppSurfaceObservabilityOptions> AddOptionsBuilder(IServiceCollection services)
Source

Creates the shared options builder and validation rules.

Parameters

  • services
    The service collection receiving options services.

Returns

The configured options builder.

Remarks

Validation fails closed for undefined exporter modes and relative OTLP endpoints so invalid telemetry configuration is surfaced during options validation or plan resolution rather than producing partial provider setup.

Method

ConfigureOptionsBuilder

void ConfigureOptionsBuilder(OptionsBuilder<AppSurfaceObservabilityOptions> builder, Action<AppSurfaceObservabilityOptions>? configure)
Source

Applies optional code configuration to the shared options builder.

Parameters

  • builder
    The options builder to configure.
  • configure
    Optional code configuration applied after configuration binding.

Remarks

Code configuration composes after bound values so applications can set environment-specific defaults in configuration and still make last-mile adjustments in startup code.

Method

ConfigureTracing

2 overloads
void ConfigureTracing(TracerProviderBuilder tracing, AppSurfaceObservabilityPlan plan)
Source

Adds AppSurface tracing sources and the optional OTLP trace exporter.

Parameters

  • tracing
    The tracing builder to configure.
  • plan
    The resolved plan that controls exporter setup.

Remarks

This method always registers AppSurface's standard activity sources. It adds an OTLP exporter only when plan requires AppSurface-owned export; otherwise hosts may add their own exporters.

void ConfigureTracing(TracerProviderBuilder tracing, AppSurfaceObservabilityPlan plan, Action<TracerProviderBuilder, AppSurfaceObservabilityPlan> addExporter)
Source

Adds AppSurface tracing sources and delegates optional exporter registration.

Parameters

  • tracing
    The tracing builder to configure.
  • plan
    The resolved plan that controls exporter setup.
  • addExporter
    Callback used to register the trace exporter when the plan requires export.

Remarks

The callback is an internal test seam. Production passes the OpenTelemetry OTLP exporter registration callback, and tests can assert that exporter registration was requested without depending on OpenTelemetry internals.

Method

ConfigureMetrics

2 overloads
void ConfigureMetrics(MeterProviderBuilder metrics, AppSurfaceObservabilityPlan plan)
Source

Adds AppSurface metric meters and the optional OTLP metric exporter.

Parameters

  • metrics
    The metrics builder to configure.
  • plan
    The resolved plan that controls exporter setup.

Remarks

This method always registers AppSurface's standard meter names. It adds an OTLP exporter only when plan requires AppSurface-owned export; otherwise hosts may add their own exporters.

void ConfigureMetrics(MeterProviderBuilder metrics, AppSurfaceObservabilityPlan plan, Action<MeterProviderBuilder, AppSurfaceObservabilityPlan> addExporter)
Source

Adds AppSurface metric meters and delegates optional exporter registration.

Parameters

  • metrics
    The metrics builder to configure.
  • plan
    The resolved plan that controls exporter setup.
  • addExporter
    Callback used to register the metric exporter when the plan requires export.

Remarks

The callback is an internal test seam. Production passes the OpenTelemetry OTLP exporter registration callback, and tests can assert that exporter registration was requested without depending on OpenTelemetry internals.

Method

ConfigureExporter

void ConfigureExporter(OtlpExporterOptions options, AppSurfaceObservabilityPlan plan)
Source

Applies AppSurface endpoint configuration to an OTLP exporter.

Parameters

  • options
    The exporter options supplied by OpenTelemetry.
  • plan
    The resolved plan that may contain an endpoint override.

Remarks

When no endpoint is present, this method intentionally leaves OpenTelemetry defaults untouched so hosts can rely on standard OTEL environment variables or SDK defaults in AppSurfaceOtlpExporterMode.Always mode.

Method

ConfigureResource

void ConfigureResource(ResourceBuilder resource, AppSurfaceObservabilityPlan plan)
Source

Adds AppSurface service identity metadata to an OpenTelemetry resource builder.

Parameters

  • resource
    The resource builder captured by OpenTelemetry providers.
  • plan
    The resolved plan that supplies service name and version.

Remarks

AppSurface does not set a service instance id. Hosts that need per-instance identity should add it in their own OpenTelemetry resource configuration after AppSurface registration.

Type

AppSurfaceObservabilityModule

Source

AppSurface host module that registers application-side OpenTelemetry logging, tracing, and metrics.

Remarks

Add this module to an AppSurface application's dependency graph when the app should publish operational telemetry to Aspire or another OTLP collector. The module reads AppSurfaceObservabilityOptions from configuration, uses StartupContext.ApplicationName as the default service name, and skips exporter registration when AppSurfaceOtlpExporterMode.WhenEndpointConfigured is active without an endpoint. It does not define Aspire resources, dashboards, product analytics, request-body capture, or package-specific AppSurface spans.

Method

ConfigureServices

void ConfigureServices(StartupContext context, IServiceCollection services)
Source

Registers options metadata for service consumers that inspect AppSurfaceObservabilityOptions .

Parameters

  • context
    The current startup context.
  • services
    The service collection receiving options registration.
Method

ConfigureHostBeforeServices

void ConfigureHostBeforeServices(StartupContext context, IHostBuilder builder)
Source

Registers OpenTelemetry logging with access to host configuration.

Parameters

  • context
    The current startup context.
  • builder
    The host builder to configure.
Method

ConfigureHostAfterServices

void ConfigureHostAfterServices(StartupContext context, IHostBuilder builder)
Source

Registers OpenTelemetry tracing and metrics with access to host configuration.

Parameters

  • context
    The current startup context.
  • builder
    The host builder to configure.
Method

RegisterDependentModules

void RegisterDependentModules(ModuleDependencyBuilder builder)
Source

Registers dependent modules; no dependencies are required.

Parameters

  • builder
    The dependency builder.
Type

AppSurfaceTelemetrySources

Source

Provides compatible OpenTelemetry source and meter name surfaces for AppSurface-owned instrumentation.

Remarks

This type keeps the existing v1 public shape for telemetry names while delegating the canonical AppSurface source name to AppSurfaceActivitySources to avoid a hard dependency on this package from framework code.

The v1 observability package registers these names so future AppSurface packages can add spans and metrics without forcing each application to rediscover source names. This package does not add Flow, Auth, Docs, Intelligence, or other package-specific telemetry yet.

Property

StandardActivitySourceNames

IReadOnlyList<string> StandardActivitySourceNames { get; } Source

Gets common .NET activity source names that AppSurface opts into when they are emitted by the host runtime.

Remarks

The returned list is read-only so callers cannot mutate global source registration for the current process. Copy the values into a new collection before adding application-specific sources.

Property

StandardMeterNames

IReadOnlyList<string> StandardMeterNames { get; } Source

Gets common .NET meter names that AppSurface opts into when they are emitted by the host runtime.

Remarks

The returned list is read-only so callers cannot mutate global meter registration for the current process. Copy the values into a new collection before adding application-specific meters.

Type

AppSurfaceObservabilityLoggingBuilderExtensions

Source

Provides logging-builder extensions for AppSurface observability.

Method

AddAppSurfaceObservabilityLogging

2 overloads
ILoggingBuilder AddAppSurfaceObservabilityLogging(this ILoggingBuilder builder, StartupContext context, IConfiguration configuration, Action<AppSurfaceObservabilityOptions>? configure = null)
Source

Adds AppSurface OpenTelemetry logging.

Parameters

  • builder
    The logging builder to configure.
  • context
    The AppSurface startup context that supplies the default service identity.
  • configuration
    Configuration used to bind AppSurfaceObservabilityOptions .
  • configure
    Optional code configuration that composes after bound configuration values.

Returns

The supplied builder .

Remarks

Repeated calls are safe and first registration wins, which keeps configured options aligned with the captured OpenTelemetry logger setup.

ILoggingBuilder AddAppSurfaceObservabilityLogging(this ILoggingBuilder builder, StartupContext context, IConfiguration configuration, Action<AppSurfaceObservabilityOptions>? configure, bool registerOptions)
Source

Adds AppSurface OpenTelemetry logging with explicit control over options registration.

Parameters

  • builder
    The logging builder receiving OpenTelemetry logging configuration.
  • context
    The startup context used to resolve default service identity metadata.
  • configuration
    Configuration used to bind and resolve observability options.
  • configure
    Optional code configuration applied after bound configuration values.
  • registerOptions
    true to bind and validate options in DI; false when another AppSurface registration path has already registered the same options.

Returns

The supplied builder .

Remarks

This overload is used by the host module so logging can be configured before service-provider OpenTelemetry. Registration is idempotent and first registration wins. The resolved plan is captured by the logging options callback, so callers should supply their intended endpoint and service identity on the first call.

Method

ConfigureLogging

void ConfigureLogging(OpenTelemetryLoggerOptions options, AppSurfaceObservabilityPlan plan)
Source

Applies AppSurface OpenTelemetry logging defaults to logger options.

Parameters

  • options
    The logger options captured by OpenTelemetry logging.
  • plan
    The resolved plan that controls resource identity and exporter registration.

Remarks

AppSurface opts into formatted messages, scopes, and parsed state values so structured log attributes remain useful when exported through OTLP. Exporter registration follows plan : when the plan skips export, the host can still add its own logging exporter later.

Type

AppSurfaceObservabilityPlan

Source

Captures the immutable observability registration plan resolved from AppSurface configuration.

Parameters

  • ExporterMode
    The validated exporter registration mode.
  • Endpoint
    The resolved OTLP endpoint, or null when the host should use OpenTelemetry defaults or skip export.
  • ServiceName
    The OpenTelemetry resource service name that tracing, metrics, and logging should share.
  • ServiceVersion
    The optional OpenTelemetry resource service version.
  • ShouldRegisterExporter
    Whether AppSurface should add OTLP exporters to the OpenTelemetry builders.
  • ShouldLogSkippedExporterDiagnostic
    Whether startup should explain that endpoint-driven export was skipped.

Remarks

The plan is resolved once per first registration path. Later option registrations do not rewrite providers because OpenTelemetry captures resource and exporter setup when providers are built.

Method

Resolve

AppSurfaceObservabilityPlan Resolve(StartupContext context, IConfiguration configuration, Action<AppSurfaceObservabilityOptions>? configure = null, IAppSurfaceEnvironmentReader? environment = null)
Source

Resolves the effective OpenTelemetry registration plan.

Parameters

  • context
    The AppSurface startup context that supplies the default service name.
  • configuration
    Configuration used to bind AppSurface observability options and optional OTEL keys.
  • configure
    Optional code configuration applied after bound configuration values.
  • environment
    Optional environment reader used for deterministic tests; production uses process environment variables.

Returns

The resolved immutable plan used by logging, tracing, metrics, and resource registration.

Exceptions

  • ArgumentNullException
    Thrown when context or configuration is null .
  • InvalidOperationException
    Thrown when AppSurfaceObservabilityOptions.ExporterMode is undefined or an endpoint value is not an absolute URI.

Remarks

Endpoint precedence is AppSurface options first, then the raw AppSurfaceObservabilityOptions.AppSurfaceOtlpEndpointEnvironmentVariable environment variable for hosts that did not add environment variables to configuration, then the standard AppSurfaceObservabilityOptions.OtlpEndpointEnvironmentVariable value from configuration, then the same standard variable from the process environment. This keeps AppSurface-owned endpoint configuration more specific than generic OTEL defaults while still honoring collector settings supplied by Aspire.

Method

ResolveUri

Uri? ResolveUri(string? value, string settingName = AppSurfaceObservabilityOptions.OtlpEndpointEnvironmentVariable)
Source

Resolves an optional absolute URI from configuration or environment input.

Parameters

  • value
    The configured value to parse.
  • settingName
    The setting name used in validation failures.

Returns

The parsed absolute URI, or null when value is blank.

Exceptions

  • InvalidOperationException
    Thrown when value is present but is not an absolute URI.

Remarks

Blank values are treated as absent so an empty environment variable does not accidentally enable export. Relative URI values fail closed because OTLP exporters need a concrete collector endpoint.

Enum

AppSurfaceOtlpExporterMode

Source

Controls when AppSurface configures OpenTelemetry Protocol exporters.

Remarks

The default, WhenEndpointConfigured , is designed for Aspire and other collector-backed development environments: export is enabled only when an OTLP endpoint is present in AppSurface configuration or the standard OTEL_EXPORTER_OTLP_ENDPOINT environment variable. Use Always only when the host intentionally wants OpenTelemetry's exporter defaults or host-owned OTLP configuration to apply. Use Never for tests and hosts that install their own exporters.