.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 44 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.
Metrics Filtering
You can filter ODP.NET metrics to publish at the AppDomain, pool, or instance level. By default, all three are published.
Set the filter using the MetricsLevel setting in managed ODP.NET configuration files, or the OracleConfiguration MetricsLevel property in core or managed ODP.NET. The OracleMetricsLevel enumeration lists available integer levels.
ODP.NET metrics adds a “Level” tag to differentiate counters originating at the AppDomain (Level=”AppDomain”), pool (Level=”ConnectionPool”), or database (Level=”DbInstance”) level.
<div class="infoboxnote" markdown="1">
**See Also:**
[OracleMetricsLevel Enumeration](OracleMetricsLevelEnumeration.html#GUID-421C672D-004C-4741-BD32-EBB4F46158D7)
OracleConfiguration [MetricsLevel](ConfigurationMetricsLevel.html#GUID-D68331A4-607D-4E7D-B9E7-CB4270005940) property
</div>