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

chrome/renderer/translate/translate_helper.h

 // Copyright (c) 2011 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 CHROME_RENDERER_TRANSLATE_TRANSLATE_HELPER_H_
 #define CHROME_RENDERER_TRANSLATE_TRANSLATE_HELPER_H_
 
 #include <string>
 
 #include "base/gtest_prod_util.h"
@@ skipping 10 matching lines @@
 class WebDocument;
 class WebFrame;
 }
 
 namespace content {
 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);
   virtual ~TranslateHelper();
 
   // Informs us that the page's text has been extracted.
   void PageCaptured(const base::string16& contents);
 
   // Lets the translation system know that we are preparing to navigate to
   // the specified URL. If there is anything that can or should be done before
@@ skipping 64 matching lines @@
   FRIEND_TEST_ALL_PREFIXES(TranslateHelperTest,
                            CLDDisagreeWithWrongLanguageCode);
   FRIEND_TEST_ALL_PREFIXES(TranslateHelperTest,
                            InvalidLanguageMetaTagProviding);
   FRIEND_TEST_ALL_PREFIXES(TranslateHelperTest, LanguageCodeTypoCorrection);
   FRIEND_TEST_ALL_PREFIXES(TranslateHelperTest, LanguageCodeSynonyms);
   FRIEND_TEST_ALL_PREFIXES(TranslateHelperTest, ResetInvalidLanguageCode);
   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  // bounding value for this enum

[Alexei Svitkine (slow), 2014/07/17 14:39:03]

Nit: Use full sentences - capitalized and terminated with a .

+  };
+
   // Converts language code to the one used in server supporting list.
   static void ConvertLanguageCodeSynonym(std::string* code);
 
   // Returns whether the page associated with |document| is a candidate for
   // translation.  Some pages can explictly specify (via a meta-tag) that they
   // should not be translated.
   static bool IsTranslationAllowed(blink::WebDocument* document);
 
   // RenderViewObserver implementation.
   virtual bool OnMessageReceived(const IPC::Message& message) OVERRIDE;
@@ skipping 34 matching lines @@
   void DeferPageCaptured(const int page_id, const base::string16& contents);
 
   // Start polling for CLD data.
   // Polling will automatically halt as soon as the renderer obtains a
   // reference to the data file.
   void SendCldDataRequest(const int delay_millis, const int next_delay_millis);
 
   // 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);

[Alexei Svitkine (slow), 2014/07/17 14:39:03]

Since this is Chromium code (and not blink), please keep the param name in the
method signature.

+
   // An ever-increasing sequence number of the current page, used to match up
   // translation requests with responses.
   int page_seq_no_;
 
   // The states associated with the current translation.
   bool translation_pending_;
   std::string source_lang_;
   std::string target_lang_;
 
   // Time when a page langauge is determined. This is used to know a duration
@@ skipping 21 matching lines @@
   int deferred_page_seq_no_;
 
   // The contents of the page most recently reported to PageCaptured if
   // deferred_page_capture_ is true.
   base::string16 deferred_contents_;
 
   DISALLOW_COPY_AND_ASSIGN(TranslateHelper);
 };
 
 #endif  // CHROME_RENDERER_TRANSLATE_TRANSLATE_HELPER_H_