Add metrics for tracking UX impact of non-static CLD data providers

chrome/renderer/translate/translate_helper.h

Index: chrome/renderer/translate/translate_helper.h
diff --git a/chrome/renderer/translate/translate_helper.h b/chrome/renderer/translate/translate_helper.h
index 1c357bf9e606308f1a6f2d9ff8fc487733b2c55e..fc2fc758365d6f281d9f8ae924ab9b1e6d42388e 100644
--- a/chrome/renderer/translate/translate_helper.h
+++ b/chrome/renderer/translate/translate_helper.h
@@ -28,7 +28,53 @@ class RendererCldDataProvider;
 
 // This class deals with page translation.
 // There is one TranslateHelper per RenderView.
-
+//
+// This class provides metrics that allow tracking the user experience impact
+// of non-static CldDataProvider implementations. For background on the data
+// providers, please refer to the following documentation:
+// http://www.chromium.org/developers/how-tos/compact-language-detector-cld-data-source-configuration
+//
+// Available metrics (from the LanguageDetectionTiming enum):
+// 1. ON_TIME
+//    Recorded if PageCaptured(...) is invoked after CLD is available. This is
+//    the ideal case, indicating that CLD is available before it is needed.
+// 2. DEFERRED
+//    Recorded if PageCaptured(...) is invoked before CLD is available.
+//    Sub-optimal case indicating that CLD wasn't available when it was needed,
+//    so the request for detection has been deferred until CLD is available or
+//    until the user navigates to a different page.
+// 3. RESUMED
+//    Recorded if CLD becomes available after a language detection request was
+//    deferred, but before the user navigated to a different page. Language
+//    detection is ultimately completed, it just didn't happen on time.
+//
+// Note that there is NOT a metric that records the number of times that
+// language detection had to be aborted because CLD never became available in
+// time. This is because there is no reasonable way to cover all the cases
+// under which this could occur, particularly the destruction of the renderer
+// for which this object was created. However, this value can be synthetically
+// derived, using the logic below.
+//
+// Every page load that triggers language detection will result in the
+// recording of exactly one of the first two events: ON_TIME or DEFERRED. If
+// CLD is available in time to satisfy the request, the third event (RESUMED)
+// will be recorded; thus, the number of times when language detection
+// ultimately fails because CLD isn't ever available is implied as the number of
+// times that detection is deferred minus the number of times that language
+// detection is late:
+//
+//   count(FAILED) ~= count(DEFERRED) - count(RESUMED)
+//
+// Note that this is not 100% accurate: some renderer process are so short-lived
+// that language detection wouldn't have been relevant anyway, and so a failure
+// to detect the language in a timely manner might be completely innocuous. The
+// overall problem with language detection is that it isn't possible to know
+// whether it was required or not until after it has been performed!
+//
+// We use histograms for recording these metrics. On Android, the renderer can
+// be killed without the chance to clean up or transmit these histograms,
+// leading to dropped metrics. To work around this, this method forces an IPC
+// message to be sent to the browser process immediately.
 class TranslateHelper : public content::RenderViewObserver {
  public:
   explicit TranslateHelper(content::RenderView* render_view);
@@ -113,6 +159,13 @@ class TranslateHelper : public content::RenderViewObserver {
   FRIEND_TEST_ALL_PREFIXES(TranslateHelperTest, SimilarLanguageCode);
   FRIEND_TEST_ALL_PREFIXES(TranslateHelperTest, WellKnownWrongConfiguration);
 
+  enum LanguageDetectionTiming {
+    ON_TIME,   // Language detection was performed as soon as it was requested
+    DEFERRED,  // Language detection couldn't be performed when it was requested
+    RESUMED,   // A deferred language detection attempt was completed later
+    LANGUAGE_DETECTION_TIMING_MAX_VALUE  // The bounding value for this enum
+  };
+
   // Converts language code to the one used in server supporting list.
   static void ConvertLanguageCodeSynonym(std::string* code);
 
@@ -167,6 +220,11 @@ class TranslateHelper : public content::RenderViewObserver {
   // Callback triggered when CLD data becomes available.
   void OnCldDataAvailable();
 
+  // Record the timing of language detection, immediately sending an IPC-based
+  // histogram delta update to the browser process in case the hosting renderer
+  // process terminates before the metrics would otherwise be transferred.
+  void RecordLanguageDetectionTiming(LanguageDetectionTiming timing);
+
   // An ever-increasing sequence number of the current page, used to match up
   // translation requests with responses.
   int page_seq_no_;