1. Developer's Guide
  2. Features of Oracle Data Provider for .NET
  3. .NET Metrics

.NET Metrics

.NET Metrics are application numerical measurements collected at regular time intervals for the purposes of monitoring and alerting about application health. Typically, these metrics are delivered to a monitoring system. In an ODP.NET setting, metrics can monitor connection statistics, such as number of ODP.NET hard connections to the database, number of active connections, or number of free connections.

Starting with version 23.3.2, ODP.NET Core and managed ODP.NET support .NET Metrics. ODP.NET Core supports metrics on .NET (Core) for all operating systems ODP.NET Core is certified with. To use .NET Metrics, ODP.NET projects must include the NuGet package, System.Diagnostics.DiagnosticSource 6.0.0 or higher. This package includes the System.Diagnostics.Metrics APIs and allows ODP.NET code to be instrumented for rich data payload logging for consumption within the same process.

For metrics instrumentation, developers will associate the metric name Oracle.ManagedDataAccess.Core for ODP.NET Core or Oracle.ManagedDataAccess for managed ODP.NET to subscribe to and monitor ODP.NET measurements, such as for the MeterListener Meter Name property.

For metrics collection, ODP.NET metrics is tightly integrated with .NET OpenTelelmetry. This means that ODP.NET metrics can be published to and analyzed by the rich and expansive toolsets integrated with OpenTelemetry, such as Grafana and Prometheus. Developers can also use common .NET SDK tools, such as dotnet-counters. For example, to live monitor all metrics for all ODP.NET Core processes, execute the command:

dotnet-counters monitor "Oracle.ManagedDataAccess.Core"

You may indicate a specific process and metric to monitor:

dotnet-counters monitor -n <process name> <metrics source name>

You may identify the process by its identifier:

dotnet-counters monitor <metrics source name> -p <process id>

Unlike ODP.NET performance counters, there is no need to enable metrics explicitly. ODP.NET metrics counters instances are always available in-memory after an application starts. However, these metrics values are only published for active subscribers.

Note:

.NET Metrics cannot be consumed by Windows Performance Monitor.

ODP.NET can flexibly collect and distinguish connection metrics at multiple granularity levels, including the:

  • AppDomain level

  • Connection string or pool manager level

  • Database instance level

ODP.NET supports the following metric measurements and levels.

Table 3-42 Metric Counters and Levels

Metrics Counters Description Levels Supported

HardConnects

Number of sessions established with database

All

HardDisconnects

Number of sessions severed from database

All

SoftConnects

Number of soft connects

All

SoftDisconnects

Number of soft disconnects

All

NumberOfActiveConnectionPools

Number of active connection pools, which are pools with at least one connection

All

NumberOfInactiveConnectionPools

Number of inactive connection pools, which are pools with zero connections

All

NumberOfActiveConnections

Number of connections in use, also known as checked out connections

All

NumberOfFreeConnections

Number of connections available for use in connection pool, also known as queued connections

All

NumberOfPooledConnections

Number of pooled connections, which are the total of checked out and queued connections

All

NumberOfNonPooledConnections

Number of non-pooled active connections

All

NumberOfReclaimedConnections

Number of implicitly garbage-collected connections

All

NumberOfActiveHardConnections

Number of opened database connections

All

NumberOfActiveSoftConnections

Number of connections checked out from the pool

All

NumberOfActiveConnectionPoolGroups

Number of pool groups (i.e., number of unique connection strings) with at least one connection

AppDomain level only

NumberOfInactiveConnectionPoolGroups

Number of pool groups (i.e., number of unique connection strings) with zero connections

AppDomain level only

.NET uses long metric level identifiers that are not easily human readable. They consist of a string with the application name, process id, and connection string. To make identifying the metric level easier, ODP.NET developers can customize the connection string identifier name in the OraclePoolNameCollection PoolNames property. Managed ODP.NET developers also have the option to use the <connectionPools> section of the .NET configuration file. Developers will be able to configure a different pool name for each unique connection string.

Each cluster of Oracle Real Application Cluster (RAC) instances will use the same pool name configuration since all the instances in a cluster have an identical connection string.