[sql] Stats gathering for sql/ APIs.

sql/connection.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef SQL_CONNECTION_H_
 #define SQL_CONNECTION_H_
 
 #include <stdint.h>
 #include <map>
 #include <set>
 #include <string>
 #include <vector>
 
 #include "base/callback.h"
 #include "base/compiler_specific.h"
 #include "base/macros.h"
 #include "base/memory/ref_counted.h"
 #include "base/memory/scoped_ptr.h"
 #include "base/threading/thread_restrictions.h"
 #include "base/time/time.h"
 #include "sql/sql_export.h"
 
 struct sqlite3;
 struct sqlite3_stmt;
 
 namespace base {
 class FilePath;
+class HistogramBase;
 }
 
 namespace sql {
 
 class Recovery;
 class Statement;
 
+// To allow some test classes to be friended.
+namespace test {
+class ScopedCommitHook;
+class ScopedScalarFunction;
+class ScopedMockTimeSource;
+}
+
 // Uniquely identifies a statement. There are two modes of operation:
 //
 // - In the most common mode, you will use the source file and line number to
 //   identify your statement. This is a convienient way to get uniqueness for
 //   a statement that is only used in one place. Use the SQL_FROM_HERE macro
 //   to generate a StatementID.
 //
 // - In the "custom" mode you may use the statement from different places or
 //   need to manage it yourself for whatever reason. In this case, you should
 //   make up your own unique name and pass it to the StatementID. This name
@@ skipping 28 matching lines @@
 
  private:
   int number_;
   const char* str_;
 };
 
 #define SQL_FROM_HERE sql::StatementID(__FILE__, __LINE__)
 
 class Connection;
 
+// Abstract the source of timing information for metrics (RecordCommitTime, etc)
+// to allow testing control.
+class SQL_EXPORT TimeSource {
+ public:
+  TimeSource() {}
+  virtual ~TimeSource() {}
+
+  // Return the current time (by default base::TimeTicks::Now()).
+  virtual base::TimeTicks Now();
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(TimeSource);
+};
+
 class SQL_EXPORT Connection {
  private:
   class StatementRef;  // Forward declaration, see real one below.
 
  public:
   // The database is opened by calling Open[InMemory](). Any uncommitted
   // transactions will be rolled back when this object is deleted.
   Connection();
   ~Connection();
 
@@ skipping 40 matching lines @@
   void set_error_callback(const ErrorCallback& callback) {
     error_callback_ = callback;
   }
   bool has_error_callback() const {
     return !error_callback_.is_null();
   }
   void reset_error_callback() {
     error_callback_.Reset();
   }
 
-  // Set this tag to enable additional connection-type histogramming
-  // for SQLite error codes and database version numbers.
-  void set_histogram_tag(const std::string& tag) {
-    histogram_tag_ = tag;
-  }
+  // Set this to enable additional per-connection histogramming.  Must be called
+  // before Open().
+  void set_histogram_tag(const std::string& tag);
 
   // Record a sparse UMA histogram sample under
   // |name|+"."+|histogram_tag_|.  If |histogram_tag_| is empty, no
   // histogram is recorded.
   void AddTaggedHistogram(const std::string& name, size_t sample) const;
 
+  // Track various API calls and results.

[Alexei Svitkine (slow), 2015/06/02 21:29:51]

Nit: Mention that these are used in UMA and so shouldn't be renumbered or
deleted.

[Scott Hess - ex-Googler, 2015/06/02 22:13:44]

Done.

+  enum Events {
+    // Number of statements run, either with sql::Statement or Execute*().
+    EVENT_STATEMENT_RUN = 0,
+
+    // Number of rows returned by statements run.
+    EVENT_STATEMENT_ROWS,
+
+    // Number of statements successfully run (all steps returned SQLITE_DONE or
+    // SQLITE_ROW).
+    EVENT_STATEMENT_SUCCESS,
+
+    // Number of statements run by Execute() or ExecuteAndReturnErrorCode().
+    EVENT_EXECUTE,
+
+    // Number of rows changed by autocommit statements.
+    EVENT_CHANGES_AUTOCOMMIT,
+
+    // Number of rows changed by statements in transactions.
+    EVENT_CHANGES,
+
+    // Count actual SQLite transaction statements (not including nesting).
+    EVENT_BEGIN,
+    EVENT_COMMIT,
+    EVENT_ROLLBACK,
+
+    // Leave this at the end.
+    // TODO(shess): |EVENT_MAX| causes compile fail on Windows.
+    EVENT_MX

[Alexei Svitkine (slow), 2015/06/02 21:29:51]

Nit: How about EVENT_MAX_VALUE or EVENT_HISTOGRAM_MAX?

[Scott Hess - ex-Googler, 2015/06/02 22:13:44]

Done.  Main reason was not to have to reflow a couple places it was used, but
now it's in a helper so *shrug*.

+  };
+  void RecordEvent(Events event, size_t count);
+  void RecordOneEvent(Events event) {
+    RecordEvent(event, 1);
+  }
+
   // Run "PRAGMA integrity_check" and post each line of
   // results into |messages|.  Returns the success of running the
   // statement - per the SQLite documentation, if no errors are found the
   // call should succeed, and a single value "ok" should be in messages.
   bool FullIntegrityCheck(std::vector<std::string>* messages);
 
   // Runs "PRAGMA quick_check" and, unlike the FullIntegrityCheck method,
   // interprets the results returning true if the the statement executes
   // without error and results in a single "ok" value.
   bool QuickIntegrityCheck() WARN_UNUSED_RESULT;
@@ skipping 244 matching lines @@
   // For recovery module.
   friend class Recovery;
 
   // Allow test-support code to set/reset error ignorer.
   friend class ScopedErrorIgnorer;
 
   // Statement accesses StatementRef which we don't want to expose to everybody
   // (they should go through Statement).
   friend class Statement;
 
+  friend class test::ScopedCommitHook;
+  friend class test::ScopedScalarFunction;
+  friend class test::ScopedMockTimeSource;
+
   // Internal initialize function used by both Init and InitInMemory. The file
   // name is always 8 bits since we want to use the 8-bit version of
   // sqlite3_open. The string can also be sqlite's special ":memory:" string.
   //
   // |retry_flag| controls retrying the open if the error callback
   // addressed errors using RazeAndClose().
   enum Retry {
     NO_RETRY = 0,
     RETRY_ON_POISON
   };
@@ skipping 113 matching lines @@
   // allowing this function to be const.  Open statements can block
   // closing the database, so only use in cases where the last ref is
   // released before close could be called (which should always be the
   // case for const functions).
   scoped_refptr<StatementRef> GetUntrackedStatement(const char* sql) const;
 
   bool IntegrityCheckHelper(
       const char* pragma_sql,
       std::vector<std::string>* messages) WARN_UNUSED_RESULT;
 
+  // Record time spent executing explicit COMMIT statements.
+  void RecordCommitTime(const base::TimeDelta& delta);
+
+  // Record time in DML (Data Manipulation Language) statements such as INSERT
+  // or UPDATE outside of an explicit transaction.  Due to implementation
+  // limitations time spent on DDL (Data Definition Language) statements such as
+  // ALTER and CREATE is not included.
+  void RecordAutoCommitTime(const base::TimeDelta& delta);
+
+  // Record all time spent on updating the database.  This includes CommitTime()
+  // and AutoCommitTime(), plus any time spent spilling to the journal if
+  // transactions do not fit in cache.
+  void RecordUpdateTime(const base::TimeDelta& delta);
+
+  // Record all time spent running statements, including time spent doing
+  // updates and time spent on read-only queries.
+  void RecordQueryTime(const base::TimeDelta& delta);
+
+  // Record |delta| as query time if |read_only| (from sqlite3_stmt_readonly) is
+  // true, autocommit time if the database is not in a transaction, or update
+  // time if the database is in a transaction.  Also records change count to
+  // EVENT_CHANGES_AUTOCOMMIT or EVENT_CHANGES_COMMIT.
+  void RecordTimeAndChanges(const base::TimeDelta& delta, bool read_only);
+
+  // Helper to return the current time from the time source.
+  base::TimeTicks Now() {
+    return clock_->Now();
+  }
+
   // The actual sqlite database. Will be NULL before Init has been called or if
   // Init resulted in an error.
   sqlite3* db_;
 
   // Parameters we'll configure in sqlite before doing anything else. Zero means
   // use the default value.
   int page_size_;
   int cache_size_;
   bool exclusive_locking_;
   bool restrict_to_user_;
@@ skipping 26 matching lines @@
   // to enable diagnostics to distinguish calls to never-opened
   // databases (incorrect use of the API) from calls to once-valid
   // databases.
   bool poisoned_;
 
   ErrorCallback error_callback_;
 
   // Tag for auxiliary histograms.
   std::string histogram_tag_;
 
+  // Linear histogram for RecordEvent().
+  base::HistogramBase* stats_histogram_;
+
+  // Histogram for tracking time taken in commit.
+  base::HistogramBase* commit_time_histogram_;
+
+  // Histogram for tracking time taken in autocommit updates.
+  base::HistogramBase* autocommit_time_histogram_;
+
+  // Histogram for tracking time taken in updates (including commit and
+  // autocommit).
+  base::HistogramBase* update_time_histogram_;
+
+  // Histogram for tracking time taken in all queries.
+  base::HistogramBase* query_time_histogram_;
+
+  // Source for timing information, provided to allow tests to inject time
+  // changes.
+  scoped_ptr<TimeSource> clock_;
+
   DISALLOW_COPY_AND_ASSIGN(Connection);
 };
 
 }  // namespace sql
 
 #endif  // SQL_CONNECTION_H_