Releases: open-telemetry/opentelemetry-dotnet
1.6.0 of AspNetCore and Http instrumentation libraries
This is the first stable release of both AspNetCore and Http instrumentation libraries. If you're interested in knowing all of the changes that went into 1.6.0 release, please go through the Release notes of all the previous pre-release versions for 1.6.0 for these two packages.
OpenTelemetry.Instrumentation.AspNetCore
- Re-introduced support for gRPC instrumentation as an opt-in experimental feature. From now onwards, gRPC can be enabled by setting
OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_ENABLE_GRPC_INSTRUMENTATION
flag toTrue
.OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_ENABLE_GRPC_INSTRUMENTATION
can be set as an environment variable or via IConfiguration. The change is introduced in order to support stable release ofhttp
instrumentation. Semantic conventions for RPC is still experimental and hence the package will only support it as an opt-in experimental feature. Note that the support was removed in1.6.0-rc.1
version of the package and versions released before1.6.0-rc.1
had gRPC instrumentation enabled by default. (#5130)
1.7.0 / 1.7.0-beta.1
1.7.0 release for core components
If you're interested in knowing all of the changes that went into 1.7.0
release, please go through the Release notes of all the previous pre-release versions for 1.7.0
.
1.7.0-beta.1 release for non-core components
Note: Instrumentation libraries were not included for 1.7.0-beta.1
.
OpenTelemetry.Shims.OpenTracing
- Remove obsolete
TracerShim(Tracer, TextMapPropagator)
constructor. UseTracerShim(TracerProvider)
orTracerShim(TracerProvider, TextMapPropagator)
constructors. (#4862)
1.6.0-rc.1 of AspNetCore and HttpClient instrumentation libraries
OpenTelemetry.Instrumentation.AspNetCore
-
Removed support for
OTEL_SEMCONV_STABILITY_OPT_IN
environment variable. The library will now emit only the stable
semantic conventions. (#5066) -
Removed
netstandard2.1
target. (#5094) -
Removed support for grpc instrumentation to unblock stable release of http instrumentation. For details, see issue #5098 (#5097)
-
Breaking Change : Renamed
AspNetCoreInstrumentationOptions
toAspNetCoreTraceInstrumentationOptions
. (#5108)
OpenTelemetry.Instrumentation.Http
-
Removed support for
OTEL_SEMCONV_STABILITY_OPT_IN
environment variable. The library will now emit only the stable
semantic conventions. (#5068) -
Update activity DisplayName as per the specification. (#5078)
-
Removed reference to
OpenTelemetry
package. This is a breaking change for users relying on SuppressDownstreamInstrumentation option inOpenTelemetry.Instrumentation.GrpcNetClient
. For details, check out this issue. (#5077) -
Breaking Change: Renamed
HttpClientInstrumentationOptions
toHttpClientTraceInstrumentationOptions
. (#5109) -
Breaking Change: Removed
http.user_agent
tag from HttpClient activity. (#5110) -
HttpWebRequest
: Introduced additional values forerror.type
tag on activity andhttp.client.request.duration
metric. (#5111)
core-1.7.0-rc.1
OpenTelemetry
-
The
AddService
ResourceBuilder
extension method will now generate the sameservice.instance.id
for the lifetime of a process whenautoGenerateServiceInstanceId
istrue
. (#4988) -
Fixed a Metrics SDK bug which led to
ExemplarReservoir.Offer
always being called regardless of whether or not theExemplarFilter
sampled the measurement. (#5004) (#5016) -
Update Metrics SDK to override the default histogram buckets for the followingmetrics from ASP.NET Core and HttpClient runtime:
signalr.server.connection.duration
kestrel.connection.duration
http.client.connection.duration
These histogram metrics which have their
Unit
ass
(second) will have their default histogram buckets as[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]
. (#5008) (#5021) -
Remove the bucket with value
0
for histogram buckets for all metrics from ASP.NET Core and HttpClient. (#5021) -
Updated
Microsoft.Extensions.Logging.Configuration
package version to8.0.0
. (#5051) -
Updated
Microsoft.Extensions.Logging
package version to8.0.0
. (#5051) -
Revert the default behavior of Metrics SDK for Delta aggregation. It would not reclaim unused Metric Points by default. You can enable the SDK to reclaim unused Metric Points by setting the environment variable
OTEL_DOTNET_EXPERIMENTAL_METRICS_RECLAIM_UNUSED_METRIC_POINTS
totrue
before setting up theMeterProvider
. (#5052) -
Update Metrics SDK to override the default histogram buckets for ASP.NET (.NET Framework).
Histogram metrics for the meter name
OpenTelemetry.Instrumentation.AspNet
and instrument namehttp.request.server.duration
which have theirUnit
ass
(second) will have their default histogram buckets as[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]
. (#5063) -
Added
AddProcessor
overload onOpenTelemetryLoggerOptions
which exposes the factory pattern(Func<IServiceProvider, BaseProcessor<LogRecord>> implementationFactory)
. (#4916) -
Add support for Instrumentation Scope Attributes (i.e Meter Tags), fixing issue #4563. (#5089)
-
Added the
ILoggingBuilder.UseOpenTelemetry
experimental API extension for registering OpenTelemetryILogger
integration usingLoggerProviderBuilder
which supports the full DI (IServiceCollection
\IServiceProvider
) API surface (mirrors tracing & metrics). (#5072) -
Changed the
ILoggingBuilder
registration extensions (AddOpenTelemetry
&UseOpenTelemetry
) to fire the optionalOpenTelemetryLoggerOptions
configuration delegate AFTER the "Logging:OpenTelemetry"IConfiguration
section has been applied. (#5072)
OpenTelemetry.Api
- Updated
System.Diagnostics.DiagnosticSource
package version to8.0.0
. (#5051)
OpenTelemetry.Api.ProviderBuilderExtensions
- Updated
Microsoft.Extensions.DependencyInjection.Abstractions
package version to8.0.0
. (#5051)
OpenTelemetry.Exporter.Console
- Add support for Instrumentation Scope Attributes (i.e Meter Tags), fixing issue #4563. (#5089)
OpenTelemetry.Exporter.OpenTelemetryProtocol
-
Made
OpenTelemetry.Exporter.OtlpLogExporter
public. (#4979) -
Updated the
OpenTelemetryLoggerOptions.AddOtlpExporter
extension to retrieveOtlpExporterOptions
andLogRecordExportProcessorOptions
using theIServiceProvider
/ Options API so that they can be controlled viaIConfiguration
(similar to metrics and traces). (#4916) -
Added an
OpenTelemetryLoggerOptions.AddOtlpExporter
extension overload which accepts aname
parameter to support named options. (#4916) -
Add support for Instrumentation Scope Attributes (i.e Meter Tags),
fixing issue #4563. (#5089)
OpenTelemetry.Extensions.Hosting
-
Updated
Microsoft.Extensions.Hosting.Abstractions
package version to8.0.0
. (#5051) -
The
OpenTelemetryBuilder.WithMetrics
method will now register anIMetricsListener
named 'OpenTelemetry' into theIServiceCollection
to enable metric management via the newMicrosoft.Extensions.Diagnostics
.NET 8 APIs. (#4958) -
The
OpenTelemetryBuilder.WithLogging
experimental API method will now register anILoggerProvider
named 'OpenTelemetry' into theIServiceCollection
to enableILoggerFactory
integration. (#5072)
1.6.0-beta.3 of instrumentation libraries
OpenTelemetry.Instrumentation.AspNetCore
-
Removed the Activity Status Description that was being set during exceptions. Activity Status will continue to be reported as
Error
. This is a breaking change.EnrichWithException
can be leveraged
to restore this behavior. (#5025) -
Updated
http.request.method
to match specification guidelines.- For activity, if the method does not belong to one of the known values then the request method will be set on an additional tag
http.request.method.original
andhttp.request.method
will be set to_OTHER
. - For metrics, if the original method does not belong to one of the known values then
http.request.method
onhttp.server.request.duration
metric will be set to_OTHER
http.request.method
is set onhttp.server.request.duration
metric or activity whenOTEL_SEMCONV_STABILITY_OPT_IN
environment variable is set tohttp
orhttp/dup
.
(#5001) - For activity, if the method does not belong to one of the known values then the request method will be set on an additional tag
-
An additional attribute
error.type
will be added to activity andhttp.server.request.duration
metric when the request results in unhandled exception. The attribute value will be set to full name of exception type.
The attribute will only be added whenOTEL_SEMCONV_STABILITY_OPT_IN
environment variable is set tohttp
orhttp/dup
. (#4986) -
Fixed
network.protocol.version
attribute values to match the specification. (#5007) -
Calls to
/metrics
will now be included in thehttp.server.request.duration
metric. This change may affect Prometheus pull scenario if the Prometheus server sends request to the scraping endpoint that contains/metrics
in path. (#5044) -
Fixes the
http.route
attribute for scenarios in which it was previously missing or incorrect. Additionally, thehttp.route
attribute is now the same for both the metric andActivity
emitted for a request
Lastly, theActivity.DisplayName
has been adjusted to have the format{http.request.method} {http.route}
to conform with the specification. There remain scenarios when using conventional routing or Razor pages wherehttp.route
is still incorrect. See #5056 and #5057 for more details. (#5026) -
Removed
network.protocol.name
fromhttp.server.request.duration
metric as per spec. (#5049)
OpenTelemetry.Instrumentation.Http
-
Removed the Activity Status Description that was being set during exceptions. Activity Status will continue to be reported as
Error
. This is a breaking change.EnrichWithException
can be leveraged to restore this behavior. (#5025) -
Updated
http.request.method
to match specification guidelines.- For activity, if the method does not belong to one of the known values then the request method will be set on an additional tag
http.request.method.original
andhttp.request.method
will be set to_OTHER
. - For metrics, if the original method does not belong to one of the known values then
http.request.method
onhttp.client.request.duration
metric will be set to_OTHER
http.request.method
is set onhttp.client.request.duration
metric or activity whenOTEL_SEMCONV_STABILITY_OPT_IN
environment variable is set tohttp
orhttp/dup
. (#5003) - For activity, if the method does not belong to one of the known values then the request method will be set on an additional tag
-
An additional attribute
error.type
will be added to activity andhttp.client.request.duration
metric in case of failed requests as per the specification.Users moving to
net8.0
or newer frameworks from lower versions will see difference in values in case of an exception.net8.0
or newer frameworks add the ability to further drill down the exceptions to a specific type through HttpRequestError enum. For lower versions, the individual types will be rolled in to a single type. This could be a breaking change if alerts are set based on the values.The attribute will only be added when
OTEL_SEMCONV_STABILITY_OPT_IN
environment variable is set tohttp
orhttp/dup
. (#5005) (#5034) -
Fixed
network.protocol.version
attribute values to match the specification. (#5006) -
Set
network.protocol.version
value using the protocol version on the received response. If the request fails without response, thennetwork.protocol.version
attribute will not be set on Activity andhttp.client.request.duration
metric. (#5043)
OpenTelemetry.Instrumentation.SqlClient
- Updated
Microsoft.Extensions.Configuration
andMicrosoft.Extensions.Options
package version to8.0.0
. (#5051)
1.6.0-beta.2 of instrumentation libraries
OpenTelemetry.Instrumentation.AspNetCore
- Introduced a new metric,
http.server.request.duration
measured in seconds. The OTel SDK (starting with version 1.6.0) applies custom histogram buckets for this metric to comply with the Semantic Convention for Http Metrics.
This new metric is only available for users who opt-in to the new semantic convention by configuring the OTEL_SEMCONV_STABILITY_OPT_IN
environment variable to either http
(to emit only the new metric) or http/dup
(to emit both the new and old metrics). (#4802)
- New metric:
http.server.request.duration
- Unit:
s
(seconds) - Histogram Buckets:
0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
- Unit:
- Old metric:
http.server.duration
- Unit:
ms
(milliseconds) - Histogram Buckets:
0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000
- Unit:
Note: the older http.server.duration
metric and OTEL_SEMCONV_STABILITY_OPT_IN
environment variable will eventually be removed after the HTTP semantic conventions are marked stable. At which time this instrumentation can publish a stable release. Refer to the specification for more information regarding the new HTTP semantic conventions for both spans and metrics.
-
Following metrics will now be enabled by default when targeting
.NET8.0
or newer framework:-
Meter :
Microsoft.AspNetCore.Hosting
http.server.request.duration
http.server.active_requests
-
Meter :
Microsoft.AspNetCore.Server.Kestrel
kestrel.active_connections
kestrel.connection.duration
kestrel.rejected_connections
kestrel.queued_connections
kestrel.queued_requests
kestrel.upgraded_connections
kestrel.tls_handshake.duration
kestrel.active_tls_handshakes
-
Meter :
Microsoft.AspNetCore.Http.Connections
signalr.server.connection.duration
signalr.server.active_connections
-
Meter :
Microsoft.AspNetCore.Routing
aspnetcore.routing.match_attempts
-
Meter :
Microsoft.AspNetCore.Diagnostics
aspnetcore.diagnostics.exceptions
-
Meter :
Microsoft.AspNetCore.RateLimiting
aspnetcore.rate_limiting.active_request_leases
aspnetcore.rate_limiting.request_lease.duration
aspnetcore.rate_limiting.queued_requests
aspnetcore.rate_limiting.request.time_in_queue
aspnetcore.rate_limiting.requests
For details about each individual metric check ASP.NET Core docs page.
NOTES:
- When targeting
.NET8.0
framework or newer,http.server.request.duration
metric will only follow v1.22.0 semantic conventions specification. Ability to switch behavior to older conventions usingOTEL_SEMCONV_STABILITY_OPT_IN
environment variable is not available. - Users can opt-out of metrics that are not required using views.
(#4934)
-
-
Added
network.protocol.name
dimension tohttp.server.request.duration
metric. This change only affects users settingOTEL_SEMCONV_STABILITY_OPT_IN
tohttp
orhttp/dup
. (#4934) -
Breaking: Removed
Enrich
andFilter
support for metrics instrumentation. With this change,AspNetCoreMetricsInstrumentationOptions
is no longer available. (#4981)-
Enrich
migration:An enrichment API for the
http.server.request.duration
metric is available inside AspNetCore for users targeting .NET 8.0 (or newer). For details see: Enrich the ASP.NET Core request
metric. -
Filter
migration:There is no comparable filter mechanism currently available for any .NET version. Please share your feedback if you are impacted by this feature gap.
Note
The View API may be used to drop dimensions.
-
-
Updated description for
http.server.request.duration
metrics to match spec definition. (#4990)
OpenTelemetry.Instrumentation.Http
- Introduced a new metric for
HttpClient
,http.client.request.duration
measured in seconds. The OTel SDK (starting with version 1.6.0) applies custom histogram buckets for this metric to comply with the Semantic Convention for Http Metrics.
This new metric is only available for users who opt-in to the new semantic convention by configuring the OTEL_SEMCONV_STABILITY_OPT_IN
environment variable to either http
(to emit only the new metric) or http/dup
(to emit both the new and old metrics). (#4870)
- New metric:
http.client.request.duration
- Unit:
s
(seconds) - Histogram Buckets:
0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10
- Unit:
- Old metric:
http.client.duration
- Unit:
ms
(milliseconds) - Histogram Buckets:
0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000
- Unit:
Note: The older http.client.duration
metric and OTEL_SEMCONV_STABILITY_OPT_IN
environment variable will eventually be removed after the HTTP semantic conventions are marked stable. At which time this instrumentation can publish a stable release. Refer to the specification for more information regarding the new HTTP semantic conventions:
-
Added support for publishing
http.client.duration
&http.client.request.duration
metrics on .NET Framework forHttpWebRequest
. (#4870) -
Following
HttpClient
metrics will now be enabled by default when targeting.NET8.0
framework or newer.-
Meter :
System.Net.Http
http.client.request.duration
http.client.active_requests
http.client.open_connections
http.client.connection.duration
http.client.request.time_in_queue
-
Meter :
System.Net.NameResolution
dns.lookups.duration
For details about each individual metric check System.Net metrics docs page.
NOTES:
- When targeting
.NET8.0
framework or newer,http.client.request.duration
metric will only follow v1.22.0 semantic conventions specification. Ability to switch behavior to older conventions usingOTEL_SEMCONV_STABILITY_OPT_IN
environment variable is
not available. - Users can opt-out of metrics that are not required using views.
(#4931)
-
-
Added
url.scheme
attribute tohttp.client.request.duration
metric. The metric will be emitted whenOTEL_SEMCONV_STABILITY_OPT_IN
environment variable is set tohttp
orhttp/dup
. (#4989) -
Updated description for
http.client.request.duration
metrics to match spec definition. (#4990)
core-1.7.0-alpha.1
OpenTelemetry
-
Update
AggregatorStore
to reclaim unused MetricPoints for Delta aggregation temporality. (#4486) -
Fixed a bug where
TracerProviderBuilderBase
was not invoking theinstrumentationFactory
delegate passed to theprotected
AddInstrumentation
method. (#4873) -
Allowed metric instrument names to contain
/
characters. (#4882) -
Breaking Change
[Tracer|Meter|Logger]ProviderBuilder.Build
extension will now throw aNotSupportedException
if invoked on a non-SDK builder type. Previously it would returnnull
. (#4885) -
Updated
Microsoft.Extensions.Logging
package version to8.0.0-rc.1.23419.4
. (#4920, #4933)
OpenTelemetry.Api
-
Fixed a bug which caused
Tracer.StartRootSpan
to generate a child span if a trace was running (Activity.Current != null
). (#4890) -
Added a
Tracer
cache inside ofTracerProvider
to prevent repeated calls toGetTracer
from leaking memory. (#4906) -
Fix
TraceContextPropagator
by validating the first digit of the hex-encodedtrace-flags
field of thetraceparent
header. (#4893)
OpenTelemetry.Exporter.OpenTelemetryProtocol
-
Bumped the version of
Google.Protobuf
used by the project to3.22.5
so that consuming applications can be published as NativeAOT successfully. Also, a new performance feature can be used instead of reflection emit, which is not AOT-compatible. Removed the dependency onSystem.Reflection.Emit.Lightweight
. (#4859) -
Added support for
OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT
andOTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT
. (#4887) -
Added ability to export attributes corresponding to
LogRecord.Exception
i.e.exception.type
,exception.message
andexception.stacktrace
. These attributes will be exported whenOTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EXCEPTION_LOG_ATTRIBUTES
environment variable will be set totrue
.NOTE: These attributes were removed in 1.6.0-rc.1 release in order to support stable release of OTLP Log Exporter. The attributes will now be available via environment variable mentioned above. (#4892)
-
Added ability to export attributes corresponding to
LogRecord.EventId.Id
aslogrecord.event.id
andLogRecord.EventId.Name
aslogrecord.event.name
. The attributes will be exported whenOTEL_DOTNET_EXPERIMENTAL_OTLP_EMIT_EVENT_LOG_ATTRIBUTES
will be set totrue
.NOTE: These attributes were removed in 1.6.0-rc.1 release in order to support stable release of OTLP Log Exporter. The attributes will now be available via environment variable mentioned above. (#4925)
-
LogRecord.CategoryName
will now be exported as InstrumentationScopename
field under ScopeLogs. (#4941)
OpenTelemetry.Exporter.Prometheus.AspNetCore
- Fixed writing boolean values to use the JSON representation (#4823)
OpenTelemetry.Exporter.Prometheus.HttpListener
- Fixed writing boolean values to use the JSON representation (#4823)
OpenTelemetry.Extensions.Hosting
- Changed the behavior of the
OpenTelemetryBuilder.AddOpenTelemetry
extension to INSERT OpenTelemetry services at the beginning of theIServiceCollection
in an attempt to provide a better experience for end users capturing telemetry in hosted services. Note that this does not guarantee that OpenTelemetry services will be initialized while other hosted services start, so it is possible to miss telemetry until OpenTelemetry services are fully initialized. (#4883)
1.6.0 / 1.6.0-beta.1
1.6.0 release for core components
Note: The below only shows the changes that were added to the core components post 1.6.0-rc.1
release. If you're interested in knowing all of the changes that went into 1.6.0
release, please go through the Release notes of all the previous pre-release versions for 1.6.0
.
OpenTelemetry
-
Increased the character limit of the Meter instrument name from 63 to 255.
(#4774) -
Update default size for
SimpleExemplarReservoir
to1
.
(#4803)
1.6.0-beta.1 release for non-core components
Note: Instrumentation libraries were not included for 1.6.0-beta.1
.
OpenTelemetry.Shims.OpenTracing
core-1.6.0-rc.1
OpenTelemetry
- Experimental Feature Added an opt-in feature to aggregate any metric
measurements that were dropped due to reaching the max MetricPoints
limit.
When this feature is enabled, SDK would aggregate such measurements using a
reserved MetricPoint with a single tag with key asotel.metric.overflow
and
value astrue
. The feature is turned-off by default. You can enable it by
setting the environment variable
OTEL_DOTNET_EXPERIMENTAL_METRICS_EMIT_OVERFLOW_ATTRIBUTE
totrue
before
setting up theMeterProvider
.
(#4737)
OpenTelemetry.Exporter.OpenTelemetryProtocol
-
Excluded attributes corresponding to
LogRecord.EventId
,
LogRecord.CategoryName
andLogRecord.Exception
from the exported data. This
is done as the semantic conventions for these attributes are not yet stable.
(#4781) -
Added extension method for configuring export processor options for otlp log
exporter.
(#4733) -
Added support for configuring the metric exporter's temporality using the
environment variableOTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE
as
defined in the
specification.
(#4667)
OpenTelemetry.Exporter.Prometheus.AspNetCore
- Added support for unit and name conversion following the OpenTelemetry Specification
(#4753)
OpenTelemetry.Exporter.Prometheus.HttpListener
- Added support for unit and name conversion following the OpenTelemetry Specification
(#4753)
OpenTelemetry.Extensions.Hosting
- Experimental (pre-release builds only): Added Logs Bridge
API
implementation (OpenTelemetryBuilder.WithLogging
).
(#4735)
1.5.1-beta.1 of instrumentation libraries
For all the four instrumentation libraries: AspNetCore, HttpClient, GrpcNetClient, SqlClient:
- The new HTTP and network semantic conventions can be opted in to by setting
theOTEL_SEMCONV_STABILITY_OPT_IN
environment variable. This allows for a
transition period for users to experiment with the new semantic conventions
and adapt as necessary. The environment variable supports the following
values:http
- emit the new, frozen (proposed for stable) HTTP and networking
attributes, and stop emitting the old experimental HTTP and networking
attributes that the instrumentation emitted previously.http/dup
- emit both the old and the frozen (proposed for stable) HTTP
and networking attributes, allowing for a more seamless transition.- The default behavior (in the absence of one of these values) is to continue
emitting the same HTTP and network semantic conventions that were emitted in
1.5.0-beta.1
. - Note: this option will eventually be removed after the new HTTP and
network semantic conventions are marked stable. At which time this
instrumentation can receive a stable release, and the old HTTP and
network semantic conventions will no longer be supported. Refer to the
specification for more information regarding the new HTTP and network
semantic conventions for both spans and metrics.
OpenTelemetry.Instrumentation.AspNetCore
- Fixed an issue affecting NET 7.0+. If custom propagation is being used
and tags are added to an Activity during sampling then that Activity would be dropped.
(#4637)