user_metrics.h 3.7 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889
  1. // Copyright 2014 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef BASE_METRICS_USER_METRICS_H_
  5. #define BASE_METRICS_USER_METRICS_H_
  6. #include <string>
  7. #include "base/base_export.h"
  8. #include "base/callback.h"
  9. #include "base/metrics/user_metrics_action.h"
  10. #include "base/task/single_thread_task_runner.h"
  11. namespace base {
  12. class TimeTicks;
  13. // This module provides some helper functions for logging actions tracked by
  14. // the user metrics system.
  15. // For best practices on deciding when to emit a user action, see
  16. // https://chromium.googlesource.com/chromium/src.git/+/HEAD/tools/metrics/actions/README.md
  17. // Record that the user performed an action.
  18. // This function must be called after the task runner has been set with
  19. // SetRecordActionTaskRunner().
  20. //
  21. // "Action" here means a user-generated event:
  22. // good: "Reload", "CloseTab", and "IMEInvoked"
  23. // not good: "SSLDialogShown", "PageLoaded", "DiskFull"
  24. // We use this to gather anonymized information about how users are
  25. // interacting with the browser.
  26. // WARNING: In calls to this function, UserMetricsAction should be followed by a
  27. // string literal parameter and not a variable e.g.
  28. // RecordAction(UserMetricsAction("my action name"));
  29. // This ensures that our processing scripts can associate this action's hash
  30. // with its metric name. Therefore, it will be possible to retrieve the metric
  31. // name from the hash later on.
  32. //
  33. // Once a new recorded action is added, run
  34. // tools/metrics/actions/extract_actions.py
  35. // to add the metric to actions.xml, then update the <owner>s and <description>
  36. // sections. Make sure to include the actions.xml file when you upload your code
  37. // for review!
  38. //
  39. // For more complicated situations (like when there are many different
  40. // possible actions), see RecordComputedAction().
  41. BASE_EXPORT void RecordAction(const UserMetricsAction& action);
  42. // This function has identical input and behavior to RecordAction(), but is
  43. // not automatically found by the action-processing scripts. It can be used
  44. // when it's a pain to enumerate all possible actions, but if you use this
  45. // you need to also update the rules for extracting known actions in
  46. // tools/metrics/actions/extract_actions.py.
  47. // This function must be called after the task runner has been set with
  48. // SetRecordActionTaskRunner().
  49. BASE_EXPORT void RecordComputedAction(const std::string& action);
  50. // Similar to RecordComputedAction, but also takes the time at which the action
  51. // was observed.
  52. BASE_EXPORT void RecordComputedActionAt(const std::string& action,
  53. TimeTicks action_time);
  54. // Similar to RecordComputedActionAt, but takes the amount of time elasped since
  55. // the action was observed.
  56. BASE_EXPORT void RecordComputedActionSince(const std::string& action,
  57. TimeDelta time_since);
  58. // Called with the action string.
  59. using ActionCallback = RepeatingCallback<void(const std::string&, TimeTicks)>;
  60. // Add/remove action callbacks (see above).
  61. // These functions must be called after the task runner has been set with
  62. // SetRecordActionTaskRunner().
  63. BASE_EXPORT void AddActionCallback(const ActionCallback& callback);
  64. BASE_EXPORT void RemoveActionCallback(const ActionCallback& callback);
  65. // Set the task runner on which to record actions.
  66. BASE_EXPORT void SetRecordActionTaskRunner(
  67. scoped_refptr<SingleThreadTaskRunner> task_runner);
  68. // Returns the task runner used to record actions. Returns null when not set.
  69. // This function is thread safe.
  70. BASE_EXPORT scoped_refptr<SingleThreadTaskRunner> GetRecordActionTaskRunner();
  71. } // namespace base
  72. #endif // BASE_METRICS_USER_METRICS_H_