AppSurfaceOtlpExporterMode ExporterMode { get; set; }
Source
Gets or sets when AppSurface should add OTLP exporters.
Observability
IAppSurfaceEnvironmentReader
SourceReads 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.
GetEnvironmentVariable
string? GetEnvironmentVariable(string variable)
Source
Gets the value of an environment variable.
Parameters
variableThe environment variable name to read.
Returns
The configured value, or null when the variable is not present.
AppSurfaceEnvironmentReader
SourceDefault 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.
AppSurfaceObservabilityOptions
SourceConfigures 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.
ExporterMode
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.
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.
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.
AppSurfaceObservabilityModule
SourceAppSurface 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.
ConfigureServices
void ConfigureServices(StartupContext context, IServiceCollection services)
Source
Registers options metadata for service consumers that inspect AppSurfaceObservabilityOptions.
Parameters
contextThe current startup context.servicesThe service collection receiving options registration.
ConfigureHostBeforeServices
void ConfigureHostBeforeServices(StartupContext context, IHostBuilder builder)
Source
Registers OpenTelemetry logging with access to host configuration.
Parameters
contextThe current startup context.builderThe host builder to configure.
ConfigureHostAfterServices
void ConfigureHostAfterServices(StartupContext context, IHostBuilder builder)
Source
Registers OpenTelemetry tracing and metrics with access to host configuration.
Parameters
contextThe current startup context.builderThe host builder to configure.
RegisterDependentModules
void RegisterDependentModules(ModuleDependencyBuilder builder)
Source
Registers dependent modules; no dependencies are required.
Parameters
builderThe dependency builder.
ResourceBuilderFactory
SourceCreate
ResourceBuilder Create(AppSurfaceObservabilityPlan plan)
Source
Creates the shared OpenTelemetry resource builder for AppSurface observability providers.
Parameters
planThe 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.
AppSurfaceObservabilityLoggingBuilderExtensions
SourceProvides logging-builder extensions for AppSurface observability.
AddAppSurfaceObservabilityLogging
2 overloads
ILoggingBuilder AddAppSurfaceObservabilityLogging(this ILoggingBuilder builder, StartupContext context, IConfiguration configuration, Action<AppSurfaceObservabilityOptions>? configure = null)
Source
Adds AppSurface OpenTelemetry logging.
Parameters
builderThe logging builder to configure.contextThe AppSurface startup context that supplies the default service identity.configurationConfiguration used to bindAppSurfaceObservabilityOptions.configureOptional 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
builderThe logging builder receiving OpenTelemetry logging configuration.contextThe startup context used to resolve default service identity metadata.configurationConfiguration used to bind and resolve observability options.configureOptional code configuration applied after bound configuration values.registerOptionstrueto bind and validate options in DI;falsewhen 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.
ConfigureLogging
void ConfigureLogging(OpenTelemetryLoggerOptions options, AppSurfaceObservabilityPlan plan)
Source
Applies AppSurface OpenTelemetry logging defaults to logger options.
Parameters
optionsThe logger options captured by OpenTelemetry logging.planThe 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.
AppSurfaceObservabilityServiceCollectionExtensions
SourceProvides service-registration extensions for AppSurface observability.
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
servicesThe service collection to configure.contextThe AppSurface startup context that supplies the default service identity.configurationConfiguration used to bindAppSurfaceObservabilityOptions.configureOptional 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
servicesThe service collection receiving OpenTelemetry services.contextThe startup context used to resolve default service identity metadata.configurationConfiguration used to bind and resolve observability options.configureOptional code configuration applied after bound configuration values.registerOptionstrueto bind and validate options in DI;falsewhen 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.
ConfigureAppSurfaceObservability
2 overloads
IServiceCollection ConfigureAppSurfaceObservability(this IServiceCollection services, Action<AppSurfaceObservabilityOptions>? configure = null)
Source
Registers and validates AppSurfaceObservabilityOptions without adding OpenTelemetry providers.
Parameters
servicesThe service collection receiving the options registration.configureOptional 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
servicesThe service collection receiving the options registration.configurationThe configuration source to bind from.configureOptional 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.
AddOptionsBuilder
OptionsBuilder<AppSurfaceObservabilityOptions> AddOptionsBuilder(IServiceCollection services)
Source
Creates the shared options builder and validation rules.
Parameters
servicesThe 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.
ConfigureOptionsBuilder
void ConfigureOptionsBuilder(OptionsBuilder<AppSurfaceObservabilityOptions> builder, Action<AppSurfaceObservabilityOptions>? configure)
Source
Applies optional code configuration to the shared options builder.
Parameters
builderThe options builder to configure.configureOptional 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.
ConfigureTracing
2 overloads
void ConfigureTracing(TracerProviderBuilder tracing, AppSurfaceObservabilityPlan plan)
Source
Adds AppSurface tracing sources and the optional OTLP trace exporter.
Parameters
tracingThe tracing builder to configure.planThe 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
tracingThe tracing builder to configure.planThe resolved plan that controls exporter setup.addExporterCallback 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.
ConfigureMetrics
2 overloads
void ConfigureMetrics(MeterProviderBuilder metrics, AppSurfaceObservabilityPlan plan)
Source
Adds AppSurface metric meters and the optional OTLP metric exporter.
Parameters
metricsThe metrics builder to configure.planThe 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
metricsThe metrics builder to configure.planThe resolved plan that controls exporter setup.addExporterCallback 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.
ConfigureExporter
void ConfigureExporter(OtlpExporterOptions options, AppSurfaceObservabilityPlan plan)
Source
Applies AppSurface endpoint configuration to an OTLP exporter.
Parameters
optionsThe exporter options supplied by OpenTelemetry.planThe 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.
ConfigureResource
void ConfigureResource(ResourceBuilder resource, AppSurfaceObservabilityPlan plan)
Source
Adds AppSurface service identity metadata to an OpenTelemetry resource builder.
Parameters
resourceThe resource builder captured by OpenTelemetry providers.planThe 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.
AppSurfaceObservabilityPlan
SourceCaptures the immutable observability registration plan resolved from AppSurface configuration.
Parameters
ExporterModeThe validated exporter registration mode.EndpointThe resolved OTLP endpoint, ornullwhen the host should use OpenTelemetry defaults or skip export.ServiceNameThe OpenTelemetry resource service name that tracing, metrics, and logging should share.ServiceVersionThe optional OpenTelemetry resource service version.ShouldRegisterExporterWhether AppSurface should add OTLP exporters to the OpenTelemetry builders.ShouldLogSkippedExporterDiagnosticWhether 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.
Resolve
AppSurfaceObservabilityPlan Resolve(StartupContext context, IConfiguration configuration, Action<AppSurfaceObservabilityOptions>? configure = null, IAppSurfaceEnvironmentReader? environment = null)
Source
Resolves the effective OpenTelemetry registration plan.
Parameters
contextThe AppSurface startup context that supplies the default service name.configurationConfiguration used to bind AppSurface observability options and optional OTEL keys.configureOptional code configuration applied after bound configuration values.environmentOptional 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
ArgumentNullExceptionThrown whencontextorconfigurationisnull.InvalidOperationExceptionThrown whenAppSurfaceObservabilityOptions.ExporterModeis 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.
ResolveUri
Uri? ResolveUri(string? value, string settingName = AppSurfaceObservabilityOptions.OtlpEndpointEnvironmentVariable)
Source
Resolves an optional absolute URI from configuration or environment input.
Parameters
valueThe configured value to parse.settingNameThe setting name used in validation failures.
Returns
The parsed absolute URI, or null when value is blank.
Exceptions
InvalidOperationExceptionThrown whenvalueis 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.
AppSurfaceOtlpExporterMode
SourceControls 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.
AppSurfaceObservabilityServicesRegistrationMarker
SourceMarks 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.
AppSurfaceObservabilityLoggingRegistrationMarker
SourceMarks 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.
AppSurfaceObservabilityHostBuilderExtensions
SourceProvides host-builder extensions for enabling AppSurface observability outside module discovery.
ConfigureAppSurfaceObservability
IHostBuilder ConfigureAppSurfaceObservability(this IHostBuilder builder, StartupContext context, Action<AppSurfaceObservabilityOptions>? configure = null)
Source
Configures OpenTelemetry logging, tracing, and metrics for an AppSurface host.
Parameters
builderThe host builder to configure.contextThe AppSurface startup context that supplies the default service identity.configureOptional 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.
AppSurfaceTelemetrySources
SourceNames the OpenTelemetry sources and meters that AppSurface-owned instrumentation should use.
Remarks
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.
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.
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.