Metrics API

The Metrics API provides metrics about internal resources used by Telerik Data Access. It allows you to observe the performance and the scalability of the system, the amounts of database connections, parallel context instances, and transactions.

Using the History Class

The Telerik.OpenAccess.Diagnostics.History class provides historic execution information regarding the application behavior:

Retrieving All Active Database Instances

The History.OpenDatabases static method allows you to retrieve a list of all active database instances. The method returns a string array with the connection names of all opened database instances. The following example demonstrates you how to use the OpenDatabases method.

C#


    using (EntitiesModel dbContext = new EntitiesModel())
    {
       string[] databases = History.OpenDatabases();
       Debug.Assert(databases.Length == 0);
    
       var categories = dbContext.Categories;
    
       databases = History.OpenDatabases();
       Debug.Assert(databases.Length == 1);
    }

VB


    Using dbContext As New EntitiesModel()
     Dim databases() As String = History.OpenDatabases()
     Debug.Assert(databases.Length = 0)
    
     Dim categories = dbContext.Categories
    
     databases = History.OpenDatabases()
     Debug.Assert(databases.Length = 1)
    End Using

If no database, scope or context instance is available, the OpenDatabases method returns the possible history entry points. In the following example the original context is disposed first, and then the OpenDatabases method is called. The OpenDatabases method will return one record.

C#


    using (EntitiesModel dbContext = new EntitiesModel())
    {
       var categories = dbContext.Categories;
    
       dbContext.Dispose();
    
       string[] databases = History.OpenDatabases();
       Debug.Assert(databases.Length == 1);
    }

VB


    Using dbContext As New EntitiesModel()
     Dim categories = dbContext.Categories
    
     dbContext.Dispose()
    
     Dim databases() As String = History.OpenDatabases()
     Debug.Assert(databases.Length = 1)
    End Using

Retrieving ContextMetrics

The GetContextMetrics method returns the metric counters for the specified context and optionally resets the internal values. The context metric counters can be used to obtain runtime behavior statistics in order to aid application monitoring. The counters returned by the method are affected by the actions that this context performs. The ContextMetrics class provides the following context specific metric values:

  • Sql_Query - gets the number of the executed SQL queries.
  • Sql_Delete - gets the number of the executed SQL delete statements.
  • Sql_Insert - gets the number of the executed SQL insert statements.
  • Sql_Update - gets the number of the executed SQL update statements.
  • Sql_FetchedRows - gets the number of the fetched rows.
  • Sql_Commit - gets the number of the executed SQL commit statements.
  • Sql_Rollback - gets the number of the executed SQL rollback statements.
  • Sql_Flush - gets the number of the flush operations to the relational server.
  • Sql_CommitError - gets the number of errors during SQL commit operations.
  • Sql_FlushError - gets the number of errors during flush operations.
  • Sql_QueryError - gets the number of errors during SQL query execution.
  • Sql_FetchError - gets the number of errors during fetch of the query result sets.
  • Sql_Enlist - gets the number of enlistments into system transactions.
  • Length - gets the number of metric values for the current ContextMetrics instance.

The following example demonstrates you how to get the ContextMetrics for the current context.

C#


    using (EntitiesModel dbContext = new EntitiesModel())
    {
       History history = new History(dbContext);
       ContextMetrics contextMetrics = history.GetContextMetrics(false);
    }

VB


    Using dbContext As New EntitiesModel()
     Dim _history As New History(dbContext)
     Dim _contextMetrics As ContextMetrics = _history.GetContextMetrics(False)
    End Using

Retrieving DatabaseMetrics

The GetDatabaseMetrics returns a filtered aggregated metric counters for the used database instance. The metric counters can be used to obtain runtime behavior statistics in order to aid application monitoring. The aggregated counters returned by the GetDatabaseMetrics method are affected by the actions of all context instances that use the same database. The DatabaseMetrics class provides the following database specific metric values:

  • Timestamp - gets the timestamp key for the metrics
  • Connection_ObtainedWait - gets the number connections that could not be obtained. This value indicates how often a connection could not be obtained immediately from the connection pool because the pool was empty and a blocking behavior was configured.
  • Connection_Open - gets the number of opened connections.
  • Connection_Close - gets the number of closed connections.
  • Connection_Bad - gets the number of connections found to be bad (not validatable).
  • Connection_Validate - gets the number of validated connections. A connection is validated when an error occurred.
  • Connection_Expired - gets the number of connections that expired (pooled/unpooled too often). A connection has only a certain life time and is closed when a configurable number of pool/unpool events have occurred.
  • Connection_Timeout - gets the number of connections that have been aborted due to timeout. Connections have a configurable timeout. When the timeout is reached during an active operation, the connection is aborted (closed). This is to protect the relational database server from query results that are not fetched in a timely manner.
  • Connection_Obtained - gets the number of connections obtained from the connection pool.
  • Connection_ObtainedFail - gets the number of failures because the connection pool is empty.
  • Connection_Active - gets the number currently used connections.
  • Connection_MaxActive - gets the maximum number of concurrently used connections.
  • Connection_Idle - gets the number of currently idle connections in the connection pool.
  • Context_Open - gets the number of allocated contexts.
  • Context_MaxActive - gets the maximum number of concurrently used contexts.
  • Context_Active - gets the number of currently active contexts.
  • Context_Idle - gets the number of currently idle contexts in the context pool.
  • Context_Obtained - gets the number of context obtained from the pool.
  • Context_Returned - gets the number of contexts returned to the pool.
  • L2Cache_Object_Hit - gets the number of successful read attempts from the object cache.
  • L2Cache_Object_Miss - gets the number of unsuccessful read attempts from the object cache.
  • L2Cache_Object_Add - gets the number of objects that were added to the object cache.
  • L2Cache_Object_Remove - gets the number of objects that got evicted from the object cache.
  • L2Cache_Object_Entries - gets the current number of entries in the object cache.
  • L2Cache_Object_Max - gets the configured maximum number of entries in the object cache.
  • L2Cache_Object_HitRatio - gets the ratio of hits/attempts for the object cache.
  • L2Cache_Object_FillRatio - gets the fill ratio of the state cache.
  • L2Cache_Query_Hit - gets the number of successful read attempts from the query cache.
  • L2Cache_Query_Miss - gets the number of unsuccessful read attempts from the query cache.
  • L2Cache_Query_Add - gets the number of queries that were added to the query cache.
  • L2Cache_Query_Remove - gets the number of queries that got evicted from the query cache.
  • L2Cache_Query_Entries - gets the current number of entries in the query cache.
  • L2Cache_Query_Max - gets the configured maximum number of entries in the query cache.
  • L2Cache_Query_HitRatio - gets the ratio of hits/attempts for the query cache.
  • L2Cache_Query_FillRatio - gets the fill ratio of the query cache.
  • L2Cache_Cluster_Send - gets the number of eviction messages that were send into the cache cluster.
  • L2Cache_Cluster_Receive - gets the number of eviction messages that were received from the cache cluster.
  • Events_Count - gets the number of log events (global for all databases).
  • Events_LastId - gets the last log event identifier for this database.

In order to use the GetDatabaseMetrics method, you should turn on the metric snapshot feature by specifying the interval of the snapshots and the capacity. You can achieve this via the BackendConfiguration class in the following manner:

C#


    BackendConfiguration backend = EntitiesModel.GetBackendConfiguration();
    backend.Runtime.MetricCapacity = 100;
    backend.Runtime.MetricInterval = 2000;
    
    using (EntitiesModel dbContext = new EntitiesModel(backend))
    {
    }

VB


    Dim backend As BackendConfiguration = EntitiesModel.GetBackendConfiguration()
    backend.Runtime.MetricCapacity = 100
    backend.Runtime.MetricInterval = 2000
    
    Using dbContext As New EntitiesModel(backend)
    End Using

Where EntitiesModel is the context class generated by the Telerik Data Access Create Model Wizard. The MetricCapacity property controls the number of metric snapshots that will be held internally. The default value for the MetricCapacity property is 0. The MetricInterval property controls the time span between two metric snapshots in milliseconds. The default value for the the MetricInterval property is 1000 (1 second).

The following example demonstrates you how to get the DatabaseMetrics for the current database.

C#


    BackendConfiguration backend = EntitiesModel.GetBackendConfiguration();
    backend.Runtime.MetricCapacity = 100;
    backend.Runtime.MetricInterval = 1000;
    
    using (EntitiesModel dbContext = new EntitiesModel(backend))
    {
       var items = dbContext.Categories.ToList();
       History history = new History(dbContext);
       DatabaseMetricsCollection contextMetrics = history.GetDatabaseMetrics(null, null, null);
    
       if (contextMetrics != null && contextMetrics.Count > 0)
       {
           DatabaseMetrics dbMetrics = contextMetrics[0];
       }
    }

VB


    Dim backend As BackendConfiguration = EntitiesModel.GetBackendConfiguration()
    backend.Runtime.MetricCapacity = 100
    backend.Runtime.MetricInterval = 1000
    
    Using dbContext As New EntitiesModel(backend)
     Dim items = dbContext.Categories.ToList()
     Dim _history As New History(dbContext)
     Dim contextMetrics As DatabaseMetricsCollection = _history.GetDatabaseMetrics(Nothing, Nothing, Nothing)
    
     If contextMetrics IsNot Nothing AndAlso contextMetrics.Count > 0 Then
      Dim dbMetrics As DatabaseMetrics = contextMetrics(0)
     End If
    End Using

Retrieving DatabaseEvents

The GetDatabaseEvents method returns the filtered aggregated events for the used database instance. The event collections can be used to observe the runtime behavior, internal pooling activity, SQL execution, configuration etc. In order to use the GetDatabaseMetrics method, you should turn on the metric snapshot feature by specifying the interval of the snapshots and the capacity. For more information, see the Retrieving DatabaseMetrics section. The database events metrics provide the following information:

  • Name - gets the name of the event.
  • Description - gets the description of the event. Event descriptions contain the logical parameters of the performed action.
  • EventId - gets the event instance identification. During the creation of the event, an unique number is assigned to it.
  • ConnectionId - gets the identification of the physical connection. There is no general correspondence between physical connections and an user visible context.
  • StatementId - gets the database statement identification. The value returned identifies a driver statement.
  • ResultId - gets the database result set identification. The value returned identifies a driver result set.
  • ContextId -gets the context identification. The value returned identifies a pooled instance.
  • ErrorMessage - gets the error message. In case an error was raised during the execution of a method, the error message can provide useful information. Note, that the error message format is driver and database specific.
  • FetchGroup - gets the name of the fetch group used. The value returned can be used to trace the fetch group resolution.
  • FieldName - gets the name of the field causing lazy loading or modification. The value returned can be used to obtain information about the access pattern of the database.
  • Query - gets the actual query string. The value returned can be used to obtain insight in the executed queries.
  • Timestamp - gets the start time (UTC). Events are marked with a start time in UTC.
  • Duration - gets the duration. Events are marked with a duration if they are client/server actions.
  • Information - gets the information associated with this event (query, correlation, etc.). Events usually have some properties associated with it like query string or correlation. The information most important to the event can be accessed by this property.
  • ContextName - gets the name of the context that caused this event.

The following example demonstrates you how to get the DatabaseEvents for the current database.

C#


    BackendConfiguration backend = EntitiesModel.GetBackendConfiguration();
    backend.Runtime.MetricCapacity = 100;
    backend.Runtime.MetricInterval = 1000;
    
    using (EntitiesModel dbContext = new EntitiesModel(backend))
    {
       var items = dbContext.Categories.ToList();
       History history = new History(dbContext);
       DatabaseEventsCollection events = history.GetDatabaseEvents(null, null, null);
    
       if (events != null && events.Count > 0)
       {
           foreach (ITraceEvent item in events)
           {
           }
       }
    }

VB


    Dim backend As BackendConfiguration = EntitiesModel.GetBackendConfiguration()
    backend.Runtime.MetricCapacity = 100
    backend.Runtime.MetricInterval = 1000
    
    Using dbContext As New EntitiesModel(backend)
     Dim items = dbContext.Categories.ToList()
     Dim _history As New History(dbContext)
     Dim events As DatabaseEventsCollection = _history.GetDatabaseEvents(Nothing, Nothing, Nothing)
    
     If events IsNot Nothing AndAlso events.Count > 0 Then
      For Each item As ITraceEvent In events
      Next item
     End If
    End Using

The DatabaseEvents are tightly connected with the Log Level setting of the domain model.

For example, if you set the Log Level setting to errors (logs only serious errors such as connections time out - this is the default value) and no errors occur during the execution of the program, then the GetDatabaseEvents method will return null.