All notable changes to this component are documented in this file.
The format is based on Keep a Changelog. This component adheres to Semantic Versioning.
- Support for .NET9.
- Support for RabbitMQ.Client
traces instrumentation for versions
7.0.0
+.
- Support for .NET 6 and .NET 7. Both framework reached end of support.
- Support for macOS Monterey 12 x64. macOs libraries are built and tested against macOS Ventura 13 x64.
- Musl-based (Alpine) libraries are compiled on Alpine v3.20.
- Following packages updated
OpenTelemetry.Instrumentation.Wcf
from1.0.0-rc.17
to1.0.0-rc.18
,
- .NET Framework only, following packages updated
Google.Protobuf
updated from3.28.2
to3.28.3
,Grpc.Core.Api
from2.66.0
to2.67.0
,Microsoft.Extensions.DependencyInjection
from8.0.0
to8.0.1
,Microsoft.Extensions.DependencyInjection.Abstractions
from8.0.1
to8.0.2
,System.Diagnostics.DiagnosticSource
from8.0.0
to8.0.1
,System.Text.Json
from8.0.4
to8.0.5
.
- Support for macOS Monterey 12 x64. All further releases will be supporting macOS Ventura 13 x64 and newer.
- Drop support for following environment variables:
OTEL_DOTNET_AUTO_TRACES_CONSOLE_EXPORTER_ENABLED
,OTEL_DOTNET_AUTO_METRICS_CONSOLE_EXPORTER_ENABLED
, andOTEL_DOTNET_AUTO_LOGS_CONSOLE_EXPORTER_ENABLED
. Instead, useconsole
as one of the values for the following environment variables:OTEL_TRACES_EXPORTER
OTEL_METRICS_EXPORTER
OTEL_LOGS_EXPORTER
.
- Support for Operating System resource detector.
- Support for RabbitMQ.Client
traces instrumentation for versions
6.0.0
-6.*.*
- Support for NServiceBus 9.1+ metrics instrumentations.
- Added support for OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER to handle comma-separated list.
- The environment variables
OTEL_TRACES_EXPORTER
,OTEL_METRICS_EXPORTER
, andOTEL_LOGS_EXPORTER
now support configuring console exporters for traces, metrics, and logs, respectively. - Support signal specific OTLP exporter variables (See docs):
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
,OTEL_EXPORTER_OTLP_TRACES_HEADERS
,OTEL_EXPORTER_OTLP_TRACES_TIMEOUT
,OTEL_EXPORTER_OTLP_TRACES_PROTOCOL
,OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
,OTEL_EXPORTER_OTLP_METRICS_HEADERS
,OTEL_EXPORTER_OTLP_METRICS_TIMEOUT
,OTEL_EXPORTER_OTLP_METRICS_PROTOCOL
,OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
,OTEL_EXPORTER_OTLP_LOGS_HEADERS
,OTEL_EXPORTER_OTLP_LOGS_TIMEOUT
,OTEL_EXPORTER_OTLP_LOGS_PROTOCOL
.
- Support for air-gapped installations through
DOWNLOAD_DIR
orLOCAL_PATH
arguments tootel-dotnet-auto-install.sh
. - Added
OTEL_DOTNET_AUTO_LOGGER
to select preferred sink for AutoInstrumentation diagnostic logs. - Issue a warning before publish if auto-instrumentation NuGet package is referenced and runtime identifier is not specified.
- More restrictive handling of invalid values in comma-separated lists.
When invalid value is recognized (unsupported option, supported option
with leading or trailing whitespaces, empty value, duplicate)
warning is logged, and if
FailFast
is enabled, exception is thrown. - Referencing
OpenTelemetry.AutoInstrumentation
manually no longer visibly injects instrumentation scripts into projects in an editor's solution window.
- Following packages updated
MongoDB.Driver.Core.Extensions.DiagnosticSources
from1.4.0
to1.5.0
,OpenTelemetry.Exporter.Prometheus.HttpListener
from1.9.0-beta.1
to1.9.0-beta.2
,OpenTelemetry.Instrumentation.Process
from0.5.0-beta.6
to0.5.0-beta.7
,OpenTelemetry.Resources.Azure
from1.0.0-beta.8
to1.0.0-beta.9
,OpenTelemetry.Resources.Host
from0.1.0-beta.2
to0.1.0-beta.3
,OpenTelemetry.Resources.Process
from0.1.0-beta.2
to0.1.0-beta.3
,OpenTelemetry.Shims.OpenTracing
from1.9.0-beta.1
to1.9.0-beta.2
.
- .NET only, following packages updated
OpenTelemetry.Instrumentation.StackExchangeRedis
from1.0.0-rc9.15
to1.9.0-beta.1
.
- .NET Framework only, following packages updated
Google.Protobuf
updated from3.27.1
to3.28.2
,Grpc.Core.Api
from2.63.0
to2.66.0
,Microsoft.Extensions.Configuration.Binder
from8.0.1
to8.0.2
,System.Text.Json
from8.0.3
to8.0.4
.
- Environment variables
OTEL_DOTNET_AUTO_TRACES_CONSOLE_EXPORTER_ENABLED
,OTEL_DOTNET_AUTO_METRICS_CONSOLE_EXPORTER_ENABLED
, andOTEL_DOTNET_AUTO_LOGS_CONSOLE_EXPORTER_ENABLED
are now marked as deprecated.
- Support for macOS Big Sur 11 x64. macOs libraries are built and tested against macOS Monterey 12 x64.
- Support for
MongoDB.Driver.Core
< 2.28.0. - Support for
StackExchange.Redis
< 2.6.122.
- Initialize WCF instrumentation only when necessary (#3650)
- Core components:
1.9.0
System.Diagnostics.DiagnosticSource
:8.0.0
- Support for capturing HTTP headers for following traces instrumentations:
- ASP.NET, configurable by
OTEL_DOTNET_AUTO_TRACES_ASPNET_INSTRUMENTATION_CAPTURE_REQUEST_HEADERS
andOTEL_DOTNET_AUTO_TRACES_ASPNET_INSTRUMENTATION_CAPTURE_RESPONSE_HEADERS
, - ASP.NET Core, configurable by
OTEL_DOTNET_AUTO_TRACES_ASPNETCORE_INSTRUMENTATION_CAPTURE_REQUEST_HEADERS
andOTEL_DOTNET_AUTO_TRACES_ASPNETCORE_INSTRUMENTATION_CAPTURE_RESPONSE_HEADERS
, - HTTP Client, configurable by
OTEL_DOTNET_AUTO_TRACES_HTTP_INSTRUMENTATION_CAPTURE_REQUEST_HEADERS
andOTEL_DOTNET_AUTO_TRACES_HTTP_INSTRUMENTATION_CAPTURE_RESPONSE_HEADERS
.
- ASP.NET, configurable by
- Support for capturing gRPC metadata for Grpc.Net.Client traces instrumentation.
It can by configured by
OTEL_DOTNET_AUTO_TRACES_GRPCNETCLIENT_INSTRUMENTATION_CAPTURE_REQUEST_METADATA
andOTEL_DOTNET_AUTO_TRACES_GRPCNETCLIENT_INSTRUMENTATION_CAPTURE_RESPONSE_METADATA
. - Support for Oracle.ManagedDataAccess.Core
and Oracle.ManagedDataAccess
traces instrumentation from 23.4.0 together with support for
OTEL_DOTNET_AUTO_ORACLEMDA_SET_DBSTATEMENT_FOR_TEXT
environment variable. ARM64 platform is not supported. - Add support for NServiceBus 9.x metrics and traces instrumentations.
- Musl-based (Alpine) libraries are compiled on Alpine v3.19.
- Do not use message creation context as a parent for consumer spans for
Confluent.Kafka
client instrumentation. See the issue for details. - Do not create consumer spans related to
PartitionEOF
events forConfluent.Kafka
client instrumentation. - Following properties can be set before calling plugins:
OpenTelemetry.Instrumentation.AspNetCore.AspNetCoreTraceInstrumentationOptions.EnrichWithHttpRequest
,OpenTelemetry.Instrumentation.AspNetCore.AspNetCoreTraceInstrumentationOptions.EnrichWithHttpResponse
,OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions.EnrichWithHttpRequest
,OpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions.EnrichWithHttpResponse
,OpenTelemetry.Instrumentation.GrpcNetClient.GrpcClientTraceInstrumentationOptions.EnrichWithHttpRequestMessage
,OpenTelemetry.Instrumentation.GrpcNetClient.GrpcClientTraceInstrumentationOptions.EnrichWithHttpResponseMessage
,OpenTelemetry.Instrumentation.Http.HttpClientTraceInstrumentationOptions.EnrichWithHttpRequestMessage
,OpenTelemetry.Instrumentation.Http.HttpClientTraceInstrumentationOptions.EnrichWithHttpWebRequest
,OpenTelemetry.Instrumentation.Http.HttpClientTraceInstrumentationOptions.EnrichWithHttpResponseMessage
,OpenTelemetry.Instrumentation.Http.HttpClientTraceInstrumentationOptions.EnrichWithHttpWebResponse
.
- Updated Core components:
1.9.0
. - Following packages updated
OpenTelemetry.Exporter.Prometheus.HttpListener
from1.8.0-rc.1
to1.9.0-beta.1
,OpenTelemetry.Instrumentation.GrpcNetClient
from1.8.0-beta.1
to1.9.0-beta.1
,OpenTelemetry.Instrumentation.Http
from1.8.1
to1.9.0
,OpenTelemetry.Instrumentation.Process
from0.5.0-beta.5
to0.5.0-beta.6
,OpenTelemetry.Instrumentation.Quartz
from1.0.0-beta.2
to1.0.0-beta.3
,OpenTelemetry.Instrumentation.Runtime
from1.8.0
to1.9.0
,OpenTelemetry.Instrumentation.SqlClient
from1.8.0-beta.1
to1.9.0-beta.1
,OpenTelemetry.Instrumentation.StackExchangeRedis
from1.0.0-rc9.14
to1.0.0-rc9.15
,OpenTelemetry.Instrumentation.Wcf
from1.0.0-rc.16
to1.0.0-rc.17
,OpenTelemetry.Shims.OpenTracing
from1.7.0-beta.1
to1.9.0-beta.1
,OpenTelemetry.Resources.Azure
from1.0.0-beta.7
to1.0.0-beta.8
,OpenTelemetry.Resources.Host
from0.1.0-beta.1
to0.1.0-beta.2
.OpenTelemetry.Resources.Process
from0.1.0-beta.1
to0.1.0-beta.2
.OpenTelemetry.Resources.ProcessRuntime
from0.1.0-beta.1
to0.1.0-beta.2
.
- .NET only, following packages updated
OpenTelemetry.Instrumentation.AspNetCore
from1.8.1
to1.9.0
,OpenTelemetry.Instrumentation.EntityFrameworkCore
from1.0.0-beta.11
to1.0.0-beta.12
,OpenTelemetry.Resources.Container
from1.0.0-beta.7
to1.0.0-beta.9
.
- .NET Framework only, following packages updated
OpenTelemetry.Instrumentation.AspNet
from1.8.0-beta.2
to1.9.0-beta.1
.
- Support for macOS Big Sur 11 x64. All further releases will be supporting macOS Monterey 12 x64 and newer.
- Core components:
1.8.1
System.Diagnostics.DiagnosticSource
:8.0.0
- To prevent sensitive information from leaking through query strings, the
following instrumentations redact by default any value detected in query string
components when building the
url.query
or theurl.full
attributes:OpenTelemetry.Instrumentation.Http
,OpenTelemetry.Instrumentation.AspNetCore
,OpenTelemetry.Instrumentation.AspNet
. For example,?key1=value1&key2=value2
becomes?key1=Redacted&key2=Redacted
. You can customize this behavior through the environment variables. See the instrumentation options table for details.
- Following packages updated
OpenTelemetry.Instrumentation.Http
from1.8.0
to1.8.1
.
- Following packages replaced
OpenTelemetry.ResourceDetectors.Azure
version1.0.0-beta.6
byOpenTelemetry.Resources.Azure
version1.0.0-beta.7
,OpenTelemetry.ResourceDetectors.Host
version0.1.0-alpha.3
byOpenTelemetry.Resources.Host
version0.1.0-beta.1
,OpenTelemetry.ResourceDetectors.Process
version0.1.0-alpha.3
byOpenTelemetry.Resources.Process
version0.1.0-beta.1
,OpenTelemetry.ResourceDetectors.ProcessRuntime
version0.1.0-alpha.3
byOpenTelemetry.Resources.ProcessRuntime
version0.1.0-beta.1
.
- .NET only, following packages updated
Microsoft.Extensions.Configuration.Binder
from8.0.0
to8.0.1
,OpenTelemetry.Instrumentation.AspNetCore
from1.8.0
to1.8.1
.
- .NET only, following packages replaced:
OpenTelemetry.ResourceDetectors.Container
version1.0.0-beta.7
byOpenTelemetry.Resources.Container
version1.0.0-beta.8
.
- .NET Framework only, following packages updated
Grpc.Core.Api
from2.62.0
to2.63.0
,OpenTelemetry.Instrumentation.AspNet
from1.8.0-beta.1
to1.8.0-beta.2
.
- Stop creating
receive
consumer spans for consume attempts that returned no message. For details, see #3367
- Updated Core components:
1.8.1
. - Core components:
1.8.0
System.Diagnostics.DiagnosticSource
:8.0.0
- .NET only, warning in logs about End of Support date and upcoming End of Support date for .NET version.
- Experimental support for ARM64 on Ubuntu, Alpine and Debian based images.
- Experimental ARM64 support for the
OpenTelemetry.AutoInstrumentation
NuGet package.
- Changed supported method parameters for plugins
- from
OpenTelemetry.Instrumentation.AspNet.AspNetInstrumentationOptions
toOpenTelemetry.Instrumentation.AspNet.AspNetTraceInstrumentationOptions
.
- from
- Updated Core components:
1.8.0
. - Following packages updated
MongoDB.Driver.Core.Extensions.DiagnosticSources
from1.3.0
to1.4.0
.OpenTelemetry.Exporter.Prometheus.HttpListener
from1.7.0-rc.1
to1.8.0-rc.1
,OpenTelemetry.Instrumentation.Http
from1.7.1
to1.8.0
,OpenTelemetry.Instrumentation.Process
from0.5.0-beta.4
to0.5.0-beta.5
,OpenTelemetry.Instrumentation.Quartz
from1.0.0-beta.1
to1.0.0-beta.2
,OpenTelemetry.Instrumentation.Runtime
from1.7.0
to1.8.0
,OpenTelemetry.Instrumentation.SqlClient
from1.7.0-beta.1
to1.8.0-beta.1
,OpenTelemetry.Instrumentation.StackExchangeRedis
from1.0.0-rc9.13
to1.0.0-rc9.14
,OpenTelemetry.Instrumentation.Wcf
from1.0.0-rc.15
to1.0.0-rc.16
,OpenTelemetry.ResourceDetectors.Azure
from1.0.0-beta.5
to1.0.0-beta.6
,OpenTelemetry.ResourceDetectors.Host
from0.1.0-alpha.2
to0.1.0-alpha.3
.OpenTelemetry.ResourceDetectors.Process
from0.1.0-alpha.2
to0.1.0-alpha.3
.OpenTelemetry.ResourceDetectors.ProcessRuntime
from0.1.0-alpha.2
to0.1.0-alpha.3
.
- .NET only, following packages updated
OpenTelemetry.Instrumentation.AspNetCore
from1.7.1
to1.8.0
,OpenTelemetry.Instrumentation.EntityFrameworkCore
from1.0.0-beta.10
to1.0.0-beta.11
,OpenTelemetry.ResourceDetectors.Container
from1.0.0-beta.6
to1.0.0-beta.7
.
- .NET Framework only, following packages updated
Google.Protobuf
updated from3.25.2
to3.27.1
,Grpc.Core.Api
from2.60.0
to2.62.0
,Microsoft.Extensions.DependencyInjection.Abstractions
from8.0.0
to8.0.1
,Microsoft.Extensions.Options
from8.0.1
to8.0.2
,Microsoft.Extensions.Logging.Abstractions
from8.0.0
to8.0.1
,OpenTelemetry.Instrumentation.AspNet
from1.7.0-beta.2
to1.8.0-beta.1
,System.Text.Json
from8.0.1
to8.0.3
.
- Resolved a crash issue caused by
System.IO.FileLoadException
forMicrosoft.Extensions*.dll
libraries. This issue was due to a conflict with runtime store libraries, impacting applications with mismatched dependency versions. This fix enhances stability by addressing the underlying compatibility concerns. For details see: (#3075, #3168)
- Support for
OTEL_DOTNET_AUTO_SQLCLIENT_SET_DBSTATEMENT_FOR_TEXT
andOTEL_DOTNET_AUTO_ENTITYFRAMEWORKCORE_SET_DBSTATEMENT_FOR_TEXT
environment variables which controls whether thedb.statement
attribute is set for SQL statements for SQL Client and Entity Framework Core instrumentations. The default value for both environment variables isfalse
due to the risk of leaking sensitive information in the collected database queries.
- Changed supported method parameters for plugins
- from
OpenTelemetry.Instrumentation.GrpcNetClient.GrpcClientInstrumentationOptions
toOpenTelemetry.Instrumentation.GrpcNetClient.GrpcClientTraceInstrumentationOptions
, - from
OpenTelemetry.Instrumentation.SqlClient.SqlClientInstrumentationOptions
toOpenTelemetry.Instrumentation.SqlClient.SqlClientTraceInstrumentationOptions
.
- from
- Following packages updated
OpenTelemetry.ResourceDetectors.Azure
from1.0.0-beta.4
to1.0.0-beta.5
,OpenTelemetry.ResourceDetectors.Container
from1.0.0-beta.5
to1.0.0-beta.6
.OpenTelemetry.Instrumentation.Http
from1.7.0
to1.7.1
,OpenTelemetry.Instrumentation.SqlClient
from1.6.0-beta.3
to1.7.0-beta.1
,OpenTelemetry.Instrumentation.Wcf
from1.0.0-rc.14
to1.0.0-rc.15
,
- .NET only, following packages updated
OpenTelemetry.Instrumentation.AspNetCore
from1.7.0
to1.7.1
,OpenTelemetry.Instrumentation.EntityFrameworkCore
from1.0.0-beta.9
to1.0.0-beta.10
,OpenTelemetry.Instrumentation.GrpcNetClient
from1.6.0-beta.3
to1.7.0-beta.1
.
- .NET Framework only, following packages updated
OpenTelemetry.Instrumentation.AspNet
from1.7.0-beta.1
to1.7.0-beta.2
.
- Container resource detector will be not executed on .NET Framework. It was not giving any results before changes.
- Fix ASP.NET Core traces instrumentation for .NET7. It is now using native
support by
Microsoft.AspNetCore
instead ofOpenTelemetry.Instrumentation.AspNetCore
.
- Core components:
1.7.0
System.Diagnostics.DiagnosticSource
:8.0.0
- Support for Host, Process, and Process Runtime resource detectors.
- Support for
OpenTelemetry.Instrumentation.AspNet.AspNetMetricsInstrumentationOptions
for plugins. - Support for Confluent.Kafka traces instrumentation from 1.4.0 to 3.0.0 (excluding).
- Changed minimal supported version of
Microsoft.Extensions.Logging
forILOGGER
instrumentation from6.0.0
to8.0.0
. - Changed supported method parameters for plugins
- from
OpenTelemetry.Instrumentation.AspNetCore.AspNetCoreInstrumentationOptions
toOpenTelemetry.Instrumentation.AspNetCore.AspNetCoreTraceInstrumentationOptions
, - from
OpenTelemetry.Instrumentation.Http.HttpClientInstrumentationOptions
toOpenTelemetry.Instrumentation.Http.HttpClientTraceInstrumentationOptions
.
- from
- Updated Core components:
1.7.0
. - Following packages updated
OpenTelemetry.Exporter.Prometheus.HttpListener
from1.6.0-rc.1
to1.7.0-rc.1
,OpenTelemetry.Instrumentation.Http
from1.6.0
to1.7.0
,OpenTelemetry.Instrumentation.Process
from0.5.0-beta.3
to0.5.0-beta.4
,OpenTelemetry.Instrumentation.Quartz
from1.0.0-alpha.3
to1.0.0-beta.1
,OpenTelemetry.Instrumentation.Runtime
from1.5.1
to1.7.0
,OpenTelemetry.Instrumentation.SqlClient
from1.6.0-beta.2
to1.6.0-beta.3
,OpenTelemetry.Instrumentation.StackExchangeRedis
from1.0.0-rc9.12
to1.0.0-rc9.13
,OpenTelemetry.Instrumentation.Wcf
from1.0.0-rc.13
to1.0.0-rc.14
,OpenTelemetry.Shims.OpenTracing
from1.6.0-beta.1
to1.7.0-beta.1
,OpenTelemetry.ResourceDetectors.Azure
from1.0.0-beta.3
to1.0.0-beta.4
,OpenTelemetry.ResourceDetectors.Container
from1.0.0-beta.4
to1.0.0-beta.5
,OpenTelemetry.ResourceDetectors.ProcessRuntime
from0.1.0-alpha.1
to0.1.0-alpha.2
.
- .NET only, following packages updated
Google.Protobuf
updated from3.19.4
to3.22.5
.Microsoft.Extensions.Configuration
from3.1.0
to8.0.0
,Microsoft.Extensions.Configuration.Abstractions
from3.1.0
to8.0.0
,Microsoft.Extensions.Configuration.Binder
from3.1.0
to8.0.0
,Microsoft.Extensions.DependencyInjection
from3.1.0
to8.0.0
,Microsoft.Extensions.DependencyInjection.Abstractions
from3.1.0
to8.0.0
,Microsoft.Extensions.Logging
from6.0.0
to8.0.0
,Microsoft.Extensions.Options
from3.1.0
to8.0.0
,Microsoft.Extensions.Options.ConfigurationExtensions
from3.1.0
to8.0.0
,Microsoft.Extensions.Primitives
from3.1.0
to8.0.0
,OpenTelemetry.Instrumentation.AspNetCore
from1.6.0-beta.3
to1.7.0
,OpenTelemetry.Instrumentation.EntityFrameworkCore
from1.0.0-beta.8
to1.0.0-beta.9
.
- .NET Framework only, following packages updated
Google.Protobuf
updated from3.25.1
to3.25.2
,Grpc.Core.Api
from2.59.0
to2.60.0
,Microsoft.Extensions.Configuration.Binder
from8.0.0
to8.0.1
,Microsoft.Extensions.Options
from8.0.0
to8.0.1
,OpenTelemetry.Instrumentation.AspNet
from1.6.0-beta.2
to1.7.0-beta.1
,System.Text.Json
from8.0.0
to8.0.1
.
Removed support for Microsoft.Extensions.Logging
for ILOGGER
for versions older than 8.0.0
.
- Set
service.name
resource attribute before invoking the plugin.
- Core components:
1.6.0
System.Diagnostics.DiagnosticSource
:8.0.0
- Add support for .NET 8.
- Added support for System.Data.SqlClient
(NuGet package) traces instrumentation from
4.8.5
. - Ability to update installation via PS module (
OpenTelemetry.DotNet.Auto.psm1
).
- .NET Framework only,
Grpc.Core.Api
updated from2.57.0
to2.59.0
. - .NET only,
OpenTelemetry.Instrumentation.EntityFrameworkCore
updated from1.0.0-beta.7
to1.0.0-beta.8
. - .NET only,
OpenTelemetry.Instrumentation.AspNetCore
updated from1.5.1-beta.1
to1.6.0-beta.3
. OpenTelemetry.Instrumentation.GrpcNetClient
, andOpenTelemetry.Instrumentation.Http
updated from1.5.1-beta.1
to1.6.0-beta.3
.OpenTelemetry.Instrumentation.SqlClient
updated from1.5.1-beta.1
to1.6.0-beta.2
.- .NET only,
OpenTelemetry.Instrumentation.StackExchangeRedis
updated from1.0.0-rc9.10
to1.0.0-rc9.12
. - .NET Framework only,
Google.Protobuf
updated from3.24.4
to3.25.1
. - .NET Framework only,
OpenTelemetry.Instrumentation.AspNet
andOpenTelemetry.Instrumentation.AspNet.TelemetryHttpModule
updated from1.6.0-beta.1
to1.6.0-beta.2
. OpenTelemetry.Instrumentation.Wcf
updated from1.0.0-rc.12
to1.0.0-rc.13
.- .NET Framework only, following packages updated
Microsoft.Bcl.AsyncInterfaces
from7.0.0
to8.0.0
,Microsoft.Extensions.Configuration
from7.0.0
to8.0.0
,Microsoft.Extensions.Configuration.Abstractions
from7.0.0
to8.0.0
,Microsoft.Extensions.Configuration.Binder
from7.0.4
to8.0.0
,Microsoft.Extensions.DependencyInjection
from7.0.0
to8.0.0
,Microsoft.Extensions.DependencyInjection.Abstractions
from7.0.0
to8.0.0
,Microsoft.Extensions.Logging
from7.0.0
to8.0.0
,Microsoft.Extensions.Options
from7.0.1
to8.0.0
,Microsoft.Extensions.Options.ConfigurationExtensions
from7.0.0
to8.0.0
,Microsoft.Extensions.Primitives
from7.0.0
to8.0.0
,System.Text.Encodings.Web
from7.0.0
to8.0.0
,System.Text.Json
from7.0.3
to8.0.0
.
- Following packages updated
Microsoft.Extensions.Logging.Abstractions
from7.0.1
to8.0.0
,Microsoft.Extensions.Logging.Configuration
from7.0.0
to8.0.0
,System.Diagnostics.DiagnosticSource
from7.0.2
to8.0.0
.
- Removed support for
OpenTelemetry.Instrumentation.AspNetCore.AspNetCoreMetricsInstrumentationOptions
for plugins.
- Added support for
Elastic.Transport
traces instrumentation 0.4.16+.Elastic.Clients.Elasticsearch
8.10.0+ traces instrumentation is covered byElastic.Transport
traces instrumentation. - Added
telemetry.distro.name
resource attribute. The value is set toopentelemetry-dotnet-instrumentation
.
- Change telemetry resource attribute name from
telemetry.auto.version
totelemetry.distro.version
.
- .NET Framework only,
Google.Protobuf
updated from3.24.3
to3.24.4
. - .NET Framework only,
OpenTelemetry.Instrumentation.AspNet
andOpenTelemetry.Instrumentation.AspNet.TelemetryHttpModule
updated from1.0.0-rc9.9
to1.6.0-beta.1
.
- Fixed log emission issue which resulted in same logs being exported multiple
times for ASP.NET Core 6.0 apps when bytecode instrumentation was enabled
and
WebApplicationBuilder
was used.
- Fixed log emission issue for ASP.NET Core 6.0 apps and enhanced diagnostics.
- .NET Framework only,
Google.Protobuf
updated from3.24.2
to3.24.3
. OpenTelemetry.ResourceDetectors.Azure
updated from1.0.0-beta.2
to1.0.0-beta.3
.
- Fixed Rule checking System.Diagnostics.DiagnosticSource version for net7.0 failing on correct configuration #2950.
This release is built on top of OpenTelemetry .NET:
- Core components:
1.6.0
System.Diagnostics.DiagnosticSource
:7.0.2
- Added support for Azure SDK traces instrumentation on .NET Framework.
- Added support for
WCFCLIENT
instrumentation on .NET.
- Updated Core components:
1.6.0
. - MySql.Data instrumentation is now supported from version 8.1.0 working on .NET.
- OpenTracing spans are registered under
opentracing-shim
name instead ofOpenTelemetry.AutoInstrumentation.OpenTracingShim
.
- Removed MySql.Data instrumentation for versions 6.10.7-8.0.33.
- Removed support for
OpenTelemetry.Instrumentation.MySqlData.MySqlDataInstrumentationOptions
for plugins.
- Fixed instrumentation loading issue where delayed instrumentation initialization could not bootstrap both traces and metrics. Affected scope: ASP.NET Core and HttpClient instrumentations.
- Fixed
ILogger
log instrumentation issue that caused logs to be exported multiple times.
-
Support for Azure App Service resource detector.
-
Added
BeforeConfigureTracerProvider
,BeforeConfigureMeterProvider
,TracerProviderInitialized
andMeterProviderInitialized
for plugins. See plugins documentation for details. -
Added support for Azure SDK traces instrumentation on .NET.
- In plugins
ConfigureTracerProvider
andConfigureMeterProvider
are changed now toAfterConfigureTracerProvider
andAfterConfigureMeterProvider
. See plugins documentation for details. - Minimal version of
Grpc.Net.Client
supported on .NET updated to2.52.0
.
OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES
works correctly when .NET CLR Profiler is not enabled.- Fixed manual tracing when instrumented project is referencing
System.Diagnostics.DiagnosticSource
7.0.2
#2780.
This release is built on top of OpenTelemetry .NET:
- Core components:
1.5.1
System.Diagnostics.DiagnosticSource
:7.0.0
- The environment variable
OTEL_DOTNET_AUTO_FAIL_FAST_ENABLED
could be used to enable or disable the failing process when automatic instrumentation cannot be executed. - Add support for MySqlConnector traces instrumentation.
- Updated Core components:
1.5.1
. - ASP.NET instrumentation no longer requires manual modification
of config files to include
TelemetryHttpModule
. - Parameter for
ConfigureTracesOptions
extension point for StackExchangeRedis changed type fromOpenTelemetry.Instrumentation.StackExchangeRedis.StackExchangeRedisCallsInstrumentationOptions
toOpenTelemetry.Instrumentation.StackExchangeRedis.StackExchangeRedisInstrumentationOptions
. WCF
instrumentation split toWCFCLIENT
andWCFSERVICE
. Both supported only on .NET Framework.WCFCLIENT
andWCFSERVICE
no longer requires manual modification of config files to includeTelemetryEndpointBehaviorExtensionElement
.- GraphQL instrumentation is now supported from version 7.5.0 working on .NET.
- Removed
WCF
instrumentation for Core WCF Client working on .NET. - Removed GraphQL instrumentation for versions 2.3.0-2.4.*.
- Lack of support for MySql.Data 8.0.33. See #2542.
- Stability status added to the documentation.
- Support
OTEL_LOG_LEVEL
to configure SDK logging level. - Fallback for the service name.
If the service name is not configured, the automatic instrumentation uses
the entry assembly name instead, only falling back to the process name
in case of an error. If the application uses .NET Framework and is hosted
on IIS, the service name is determined using
SiteName/ApplicationVirtualPath
. - Add MongoDB instrumentation support for .NET Framework.
- Added a rule engine to validate potential conflicts and unsupported scenarios, ensuring back off instead of crashing, improving overall stability.
- The environment variable
OTEL_DOTNET_AUTO_RULE_ENGINE_ENABLED
could be used to enable or disable the rule engine. - Support for Container resource detector.
- Support for enabling well known resource detectors
by using the environment variables
OTEL_DOTNET_AUTO_RESOURCE_DETECTOR_ENABLED
OTEL_DOTNET_AUTO_{0}_RESOURCE_DETECTOR_ENABLED
.
- Remove support for enabling debugging mode with
OTEL_DOTNET_AUTO_DEBUG
. - Removed
OTEL_DOTNET_AUTO_INTEGRATIONS_FILE
as a required environment variable for bytecode instrumentation setup
This release is built on top of OpenTelemetry .NET:
- Core components:
1.4.0
System.Diagnostics.DiagnosticSource
:7.0.0
- Updated Core components:
1.4.0
.
This beta release is built on top of OpenTelemetry .NET:
- Core components:
1.4.0-rc.4
System.Diagnostics.DiagnosticSource
:7.0.0
- Support for systems with glibc versions 2.17-2.29.
- Updated Core components:
1.4.0-rc.4
. - Replace
OTEL_DOTNET_AUTO_LEGACY_SOURCES
withOTEL_DOTNET_AUTO_TRACES_ADDITIONAL_LEGACY_SOURCES
. - Updated the shared store to correctly support
framework roll-forward
from
net6.0
tonet7.0
.
- Remove support for plugin method
ConfigureMetricsOptions(OpenTelemetry.Instrumentation.Process.ProcessInstrumentationOptions)
.
- Fix location of
OpenTelemetry.AutoInstrumentation.Native.so
forlinux-musl-x64
. - Fix issues when instrumenting
dotnet
CLI #1477.
This beta release is built on top of OpenTelemetry .NET:
- Core components:
1.4.0-rc.3
System.Diagnostics.DiagnosticSource
:7.0.0
- Support configuring
OTEL_*
settings usingApp.config
andWeb.config
. - Add support for Quartz traces instrumentation.
- Add support for EntityFrameworkCore traces instrumentations.
- Add plugin support for
ResourceBuilder ConfigureResource(ResourceBuilder builder)
.
-
Updated Core components:
1.4.0-rc.3
-
Move
OpenTelemetry.AutoInstrumentation.Native.so
tolinux-x64
directory intracer-home
for Linux glibc,OpenTelemetry.AutoInstrumentation.Native.so
tolinux-musl-x64
for Linux musl andOpenTelemetry.AutoInstrumentation.Native.dylib
toosx-x64
for MacOS. -
Change the way to manage enabled instrumentations. The following environmental variables:
OTEL_DOTNET_AUTO_TRACES_ENABLED_INSTRUMENTATIONS
,OTEL_DOTNET_AUTO_TRACES_DISABLED_INSTRUMENTATIONS
,OTEL_DOTNET_AUTO_METRICS_ENABLED_INSTRUMENTATIONS
,OTEL_DOTNET_AUTO_METRICS_DISABLED_INSTRUMENTATIONS
,OTEL_DOTNET_AUTO_LOGS_ENABLED_INSTRUMENTATIONS
,OTEL_DOTNET_AUTO_LOGS_DISABLED_INSTRUMENTATIONS
are replaced by:
OTEL_DOTNET_AUTO_INSTRUMENTATION_ENABLED
,OTEL_DOTNET_AUTO_TRACES_INSTRUMENTATION_ENABLED
,OTEL_DOTNET_AUTO_TRACES_{0}_INSTRUMENTATION_ENABLED
,OTEL_DOTNET_AUTO_METRICS_INSTRUMENTATION_ENABLED
,OTEL_DOTNET_AUTO_METRICS_{0}_INSTRUMENTATION_ENABLED
,OTEL_DOTNET_AUTO_LOGS_INSTRUMENTATION_ENABLED
,OTEL_DOTNET_AUTO_LOGS_{0}_INSTRUMENTATION_ENABLED
.
-
Change instrumentation id for ASP.NET Core traces and metrics instrumentation from
AspNet
toASPNETCORE
.
- Fix console error messages
Log: Exception creating FileSink
#1885
This beta release is built on top of OpenTelemetry .NET:
- Core components:
1.4.0-rc.1
System.Diagnostics.DiagnosticSource
:7.0.0
- Add support for NServiceBus metrics and traces instrumentations.
- Add support for Elasticsearch traces instrumentations.
- Add plugin support for
ConfigureTracesOptions(StackExchangeRedisCallsInstrumentationOptions options)
. - Add plugin support for
ConfigureMetricsOptions(AspNetCoreMetricsInstrumentationOptions options)
. - Add automatic assembly redirection for .NET Framework applications. The redirection
can be enabled or disabled via the
OTEL_DOTNET_AUTO_NETFX_REDIRECT_ENABLED
environment variable. See the additional settings table for details. - Add automatic Global Assembly Cache (GAC) registration, of the distributed .NET Framework assemblies, to the PowerShell installation module.
- Updated Core components:
1.4.0-rc.1
- Remove support for Jaeger exporter.
- Fix WCF instrumentation on .NET Framework.
- Add support for
OTEL_TRACES_SAMPLER
andOTEL_TRACES_SAMPLER_ARG
. - Add
Initializing
plugin extension point that is invoked before OpenTelemetry SDK configuration.
This beta release is built on top of OpenTelemetry .NET:
- Core components:
1.4.0-beta.3
System.Diagnostics.DiagnosticSource
:7.0.0
- Add support for
OTEL_BSP_SCHEDULE_DELAY
,OTEL_BSP_EXPORT_TIMEOUT
,OTEL_BSP_MAX_QUEUE_SIZE
,OTEL_BSP_MAX_EXPORT_BATCH_SIZE
. - Add support for
OTEL_METRIC_EXPORT_TIMEOUT
. - Add support for
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT
,OTEL_ATTRIBUTE_COUNT_LIMIT
,OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT
,OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT
,OTEL_SPAN_EVENT_COUNT_LIMIT
,OTEL_SPAN_LINK_COUNT_LIMIT
,OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT
,OTEL_LINK_ATTRIBUTE_COUNT_LIMIT
forotlp
exporter.
- Updated Core components:
1.4.0-beta.3
- Updated plugins method signature to overwrite OpenTelemetry .NET SDK exporters'
and instrumentations' options.
ConfigureOptions
changed toConfigureTracesOptions
,ConfigureMetricsOptions
orConfigureLogsOptions
.
The is the first production-ready (non-beta) release. It is not stable yet.
- Add support for .NET 7.
- Add support for
OTEL_DOTNET_AUTO_LOGS_ENABLED
. - Add error log if bytecode instrumentation type is missing all instrumentation methods.
- Plugins can overwrite OpenTelemetry .NET SDK exporters' and instrumentations' options.
- Replace
OTEL_DOTNET_AUTO_LOAD_TRACER_AT_STARTUP
withOTEL_DOTNET_AUTO_TRACES_ENABLED
andOTEL_DOTNET_AUTO_LOAD_METER_AT_STARTUP
withOTEL_DOTNET_AUTO_METRICS_ENABLED
. - Disable OpenTracing by default. OpenTracing can be re-enabled via
OTEL_DOTNET_AUTO_OPENTRACING_ENABLED
. - GraphQL exceptions are recorded as OTel events.
DOTNET_STARTUP_HOOKS
required value changed to$INSTALL_DIR/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll
.
- Remove support for .NET Core 3.1.
- Remove support for
OTEL_DOTNET_AUTO_HTTP2UNENCRYPTEDSUPPORT_ENABLED
. - Remove support for
OTEL_DOTNET_AUTO_ENABLED
. UseCORECLR_ENABLE_PROFILING
orCOR_ENABLE_PROFILING
instead. - Remove support for
OTEL_DOTNET_AUTO_INCLUDE_PROCESSES
.
- Fix the IIS registration in the PowerShell script module for Windows Server 2016.
- Fix the IIS unregistration in the PowerShell script module.
- Get rid of unnecessary service restarts during the IIS unregistration, in the PowerShell script module.
OTEL_DOTNET_AUTO_TRACES_ENABLED
is also respected by bytecode instrumentations.
- Add WCF traces instrumentation (server-side for .NET Framework, client-side for both .NET Core and .NET Framework).
- Support ASP.NET Core OpenTelemetry Log exporter related environment variables:
OTEL_LOGS_EXPORTER
,OTEL_DOTNET_AUTO_LOGS_CONSOLE_EXPORTER_ENABLED
,OTEL_DOTNET_AUTO_LOGS_ENABLED_INSTRUMENTATIONS
,OTEL_DOTNET_AUTO_LOGS_DISABLED_INSTRUMENTATIONS
,OTEL_DOTNET_AUTO_LOGS_INCLUDE_FORMATTED_MESSAGE
.
- Support
OTEL_DOTNET_AUTO_GRAPHQL_SET_DOCUMENT
(default value:false
) environment variable which controls whethergraphql.document
attribute is set. - Add ILogger logging instrumentation for .NET Core 3.1+.
- Add telemetry resource attributes.
- Add support for the
b3
propagator. - Add MassTransit traces instrumentation.
- Add
OpenTelemetry.AutoInstrumentation
Nuget package. - Support for Process metrics collection using
the
OpenTelemetry.Instrumentation.Process
package. - Add Shell scripts for downloading and installing OpenTelemetry .NET Automatic Instrumentation and instrumenting .NET applications.
- Add PowerShell script module for downloading and installing OpenTelemetry .NET Automatic Instrumentation and instrumenting .NET applications.
- Replaced
OTEL_DOTNET_AUTO_TRACES_PLUGINS
andOTEL_DOTNET_AUTO_METRICS_PLUGINS
with new environment variableOTEL_DOTNET_AUTO_PLUGINS
. - Adjusted tags for MongoDB integration. See pull request for more details.
- Extend MySql.Data traces instrumentation for versions 8.0.31+. Versions 8.0.31+ require bytecode instrumentation.
- Removed support for MongoDB integration for MongoDB.Driver.Core prior to 2.13.3.
- Log folder structure is fully created on Linux.
- Update GraphQL instrumentation to follow the OpenTelemetry semantic conventions.
- Fixed the race between requesting ReJIT of methods targeted for bytecode instrumentation and their first execution. The race allowed, in rare occasions, for the first few executions of the method to not be instrumented. See issue #1242.
- Span kind for GraphQL instrumentation is set as span property instead of attribute.
- Application crash if "wrapper type" from bytecode instrumentation is missing #1469.
This release is built on top of OpenTelemetry .NET:
- Core components:
1.3.1
System.Diagnostics.DiagnosticSource
:6.0.0
- Add support for Alpine.
- Add strong name signature to the OpenTelemetry.AutoInstrumentation assembly used on the .NET Framework.
- Extend StackExchange.Redis traces instrumentation for versions 2.6.66+.
- Updated Core components:
1.3.1
This release add various new instrumentations and more propagation options.
- Add Grpc.Net.Client traces instrumentation.
- Add MySql.Data traces instrumentation.
- Add Npgsql traces instrumentation.
- Add StackExchange.Redis traces instrumentation.
- Add configuration option
none
toOTEL_DOTNET_AUTO_TRACES_ENABLED_INSTRUMENTATIONS
andOTEL_DOTNET_AUTO_METRICS_ENABLED_INSTRUMENTATIONS
. - Add support for the
b3multi
propagator. - Add support for the
OTEL_PROPAGATORS
environment variable. Supported configuration options areb3multi
,baggage
,tracecontext
. Default istracecontext,baggage
.
- Renamed
OTEL_DOTNET_AUTO_TRACES_ENABLED
toOTEL_DOTNET_AUTO_ENABLED
since it controls enabling or disabling the CLR profiler independent of the signal type. OTEL_DOTNET_AUTO_TRACES_ENABLED_INSTRUMENTATIONS
default value is changed to include all of the available instrumentations.OTEL_DOTNET_AUTO_METRICS_ENABLED_INSTRUMENTATIONS
default value is changed to include all of the available instrumentations.- Changed Tracing sampler from
always_on
toparentbased_always_on
. See the OpenTelemetry specification for more details.
- Remove
OTEL_DOTNET_AUTO_DOMAIN_NEUTRAL_INSTRUMENTATION
configuration as it is not needed. - Remove
OTEL_DOTNET_AUTO_{0}_ENABLED
configuration, useOTEL_DOTNET_AUTO_[TRACES/METRICS]_[ENABLED/DISABLED]_INSTRUMENTATIONS
instead. - Remove
OTEL_DOTNET_AUTO_METRICS_ENABLED
configuration as it is not needed.
The main feature of this release is the support for the metrics signal.
This release is built on top of OpenTelemetry .NET:
- Core components:
1.3.0
System.Diagnostics.DiagnosticSource
:6.0.0
You can find all OpenTelemetry references in OpenTelemetry.AutoInstrumentation.csproj.
- Add MongoDB instrumentation support from .NET Core 3.1+.
- Support for OpenTelemetry metric exporter related environment variables:
OTEL_DOTNET_AUTO_METRICS_ENABLED
,OTEL_DOTNET_AUTO_LOAD_METER_AT_STARTUP
,OTEL_METRICS_EXPORTER
,OTEL_DOTNET_AUTO_METRICS_CONSOLE_EXPORTER_ENABLED
,OTEL_DOTNET_AUTO_METRICS_ENABLED_INSTRUMENTATIONS
,OTEL_DOTNET_AUTO_METRICS_DISABLED_INSTRUMENTATIONS
,OTEL_DOTNET_AUTO_METRICS_PLUGINS
,OTEL_DOTNET_AUTO_METRICS_ADDITIONAL_SOURCES
.
- Support for .NET Runtime metrics collection using
the
OpenTelemetry.Instrumentation.Runtime
package. - Support for ASP.NET and HttpClient metrics instrumentations.
- Support for Prometheus Exporter HttpListener version.
OTEL_DOTNET_AUTO_INTEGRATIONS_FILE
can accept multiple filepaths delimited by the platform-specific path separator (;
on Windows,:
on Linux and macOS).- Support for metric exporter interval using environment variable:
OTEL_METRIC_EXPORT_INTERVAL
.
- Rename generic environment variables to include trace.
OTEL_DOTNET_AUTO_ENABLED
→OTEL_DOTNET_AUTO_TRACES_ENABLED
,OTEL_DOTNET_AUTO_LOAD_AT_STARTUP
→OTEL_DOTNET_AUTO_LOAD_TRACER_AT_STARTUP
,OTEL_DOTNET_AUTO_CONSOLE_EXPORTER_ENABLED
→OTEL_DOTNET_AUTO_TRACES_CONSOLE_EXPORTER_ENABLED
,OTEL_DOTNET_AUTO_ENABLED_INSTRUMENTATIONS
→OTEL_DOTNET_AUTO_TRACES_ENABLED_INSTRUMENTATIONS
,OTEL_DOTNET_AUTO_DISABLED_INSTRUMENTATIONS
→OTEL_DOTNET_AUTO_TRACES_DISABLED_INSTRUMENTATIONS
,OTEL_DOTNET_AUTO_INSTRUMENTATION_PLUGINS
→OTEL_DOTNET_AUTO_TRACES_PLUGINS
,OTEL_DOTNET_AUTO_ADDITIONAL_SOURCES
→OTEL_DOTNET_AUTO_TRACES_ADDITIONAL_SOURCES
.
- Support for .NET 5.0
- Use
,
as separator, as documented, instead of;
, for:OTEL_DOTNET_AUTO_INCLUDE_PROCESSES
,OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES
,OTEL_DOTNET_AUTO_TRACES_DISABLED_INSTRUMENTATIONS
.
- Remove invalid instrumentation for
MongoDB.Driver.Core
<2.3.0.
The is an initial, official beta release, built on top of OpenTelemetry .NET:
- Core components:
1.2.0
- Non-core components:
1.0.0-rc9.2
System.Diagnostics.DiagnosticSource
:6.0.0
- Support for .NET Framework 4.6.2 and higher.
- Support for .NET Core 3.1.
- Support for .NET 5.0 and 6.0.
- ASP.NET and ASP.NET Core source instrumentations.
- GraphQL bytecode instrumentation.
- Microsoft.Data.SqlClient and System.Data.SqlClient source instrumentation.
- OTLP, Jaeger, Zipkin and Console trace exporters.
- Global management using environment variables:
OTEL_DOTNET_AUTO_HOME
,OTEL_DOTNET_AUTO_ENABLED
,OTEL_DOTNET_AUTO_INCLUDE_PROCESSES
,OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES
,OTEL_DOTNET_AUTO_AZURE_APP_SERVICES
. - Support for OpenTelemetry resource environment variables:
OTEL_RESOURCE_ATTRIBUTES
,OTEL_SERVICE_NAME
. - Instrumentation management using environment variables:
OTEL_DOTNET_AUTO_INTEGRATIONS_FILE
,OTEL_DOTNET_AUTO_ENABLED_INSTRUMENTATIONS
,OTEL_DOTNET_AUTO_DISABLED_INSTRUMENTATIONS
,OTEL_DOTNET_AUTO_{0}_ENABLED
,OTEL_DOTNET_AUTO_DOMAIN_NEUTRAL_INSTRUMENTATION
,OTEL_DOTNET_AUTO_CLR_DISABLE_OPTIMIZATIONS
,OTEL_DOTNET_AUTO_CLR_ENABLE_INLINING
,OTEL_DOTNET_AUTO_CLR_ENABLE_NGEN
. - Support for OpenTelemetry exporter related environment variables:
OTEL_TRACES_EXPORTER
,OTEL_EXPORTER_OTLP_PROTOCOL
, - Customization and plugin capabilities which can be configured
using the following environment variables:
OTEL_DOTNET_AUTO_LOAD_AT_STARTUP
,OTEL_DOTNET_AUTO_ADDITIONAL_SOURCES
,OTEL_DOTNET_AUTO_LEGACY_SOURCES
,OTEL_DOTNET_AUTO_INSTRUMENTATION_PLUGINS
. OTEL_DOTNET_AUTO_HTTP2UNENCRYPTEDSUPPORT_ENABLED
environment variable which enablesSystem.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport
. See the official Microsoft documentation for more details.