[privacy budget] Documentation on instrumentation

Bug: 973801
Change-Id: I4567b856ab55097edddf8939cb5c1c3cff6f5768
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2422618
Commit-Queue: Asanka Herath <asanka@chromium.org>
Reviewed-by: Paul Jensen <pauljensen@chromium.org>
Cr-Commit-Position: refs/heads/master@{#809628}

docs/privacy_budget_code_locations.md

@@ -24,6 +24,8 @@ Includes:
 
   This is what one would use when reporting identifiability study samples.
   Centralized logic makes it easier to construct consistent and stable samples.
+  All logic for supporting the construction of [`blink::IdentifiableToken`]
+  values from `std::` types and `base::` types should go here.
 
 * Per-process aggregation of metrics.
 
@@ -36,6 +38,37 @@ The code in this directory is shared across `//content`, `//chrome`, and
 In addition, this directory also contains logic for per-process aggregation of
 metrics so that they can be efficiently communicated across process boundaries.
 
+## Metrics Calculation for types visible to blink/renderer/platform
+
+Locations:
+
+* [`third_party/blink/renderer/platform/privacy_budget`](../third_party/blink/renderer/platform/privacy_budget)
+
+Functions for constructing [`blink::IdentifiableToken`] values from
+`platform/wtf` types. E.g. `WTF::String`.
+
+See the [`DEPS`][platform/pb/deps] in that directory for the paths that this
+component can depend on. In particular:
+
+* `blink/renderer/platform` can't depend on `modules/` or `core/` which means
+  that types from those source locations will need to be supported elsewhere.
+* `blink/renderer/platform/foo` can depend on other features under `platform/`.
+  So it would be possible to add support for types in `platform/` in this
+  directory.
+
+[`blink::IdentifiableToken`]: ../third_party/blink/public/common/privacy_budget/identifiable_token.h
+[platform/pb/deps]: ../third_party/blink/renderer/platform/privacy_budget/DEPS
+
+## Metrics calculation for types used in bindings based instrumentation
+
+Bindings based instrumentation is discussed in [Annotating Direct Surfaces vis
+WebIDL Bindings](privacy_budget_instrumentation.md#annotating-direct-surfaces).
+
+The generated bindings invoke `Dactyloscoper::RecordDirectSurface()` overrides
+for sampling and reporting. Hence support for types visible to
+`renderer/core/frame` lives in
+[`dactyloscoper.cc`/`.h`](../third_party/blink/renderer/core/frame/dactyloscoper.h)
+
 ## Static study settings
 
 Locations:
@@ -62,7 +95,7 @@ reasons.
 
 Locations:
 * [`chrome/browser/privacy_budget`](../chrome/browser/privacy_budget)
+* [`chrome/test/data/privacy_budget`](../chrome/test/data/privacy_budget): Test data
 
 Per-client state is primarily used and exposed by `IdentifiabilityStudyState`
 ([Source](../chrome/browser/privacy_budget/identifiability_study_state.h)).
-

docs/privacy_budget_glossary.md

+# Privacy Budget: Glossary
+
+<!-- Keep definitions sorted topologically, but also:
+
+* Add a named anchor. See
+  https://gerrit.googlesource.com/gitiles/+/HEAD/Documentation/markdown.md#Named-anchors
+
+* Use [this kind of reference], which you can define at the bottom of this
+  document.
+
+-->
+
+## Identifiable Surface {#identifiablesurface}
+
+Concretely, defined in [`identifiable_surface.h`]. Represents a single source of
+partially identifying information.
+
+### Direct Identifiable Surface {#direct} {#directsurface}
+
+An [identifiable surface](#identifiablesurface) where the value returned by an
+operation or an attribute defined in an IDL file independently reports the
+partial fingerprint. No additional contextual information is necessary to
+interpret the meaning of the returned value.
+
+E.g.: `Screen.width` which is exposed as `window.screen.width`.
+
+Direct identifiable surfaces are a special case of [Keyed Identifiable
+Surface](#keyedsurface)s where the key is implicit and global.
+
+### Keyed Identifiable Surface {#keyedsurface}
+
+An [identifiable surface](#identifiablesurface) where the partial fingerprint is
+only meaningful if its context is fully qualified.
+
+E.g.: `HTMLElement.scrollWidth` depends on the contents and styling of the
+element. Hence for the return value to qualify as a partial fingerprint it needs
+to be interpreted in the context of the content and styling.
+
+### Identifiable Surface Type {#surfacetype}
+
+See [Surface Types].
+
+### Volatile Identifiable Surface {#volatilesurface}
+
+An [identifiable surface](#identifiablesurface) which changes semi-frequently
+but whose change events can be correlated to join identities across browsing
+contexts.
+
+<!-- References go here. Keep them sorted. -->
+[`identifiable_surface.h`]: ../third_party/blink/public/common/privacy_budget/identifiable_surface.h
+[Surface Types]: privacy_budget_instrumentation.md#surface-types

third_party/blink/public/common/privacy_budget/identifiability_study_participation.h

@@ -16,6 +16,10 @@ namespace blink {
 // study, such as complex digest calculation on canvas operations; for UKM
 // reporting, filtering should happen automatically.
 //
+// DEPRECATED: Please use IdentifiabilityStudySettings::Get()->IsActive()
+// instead. Better yet see //docs/privacy_budget_instrumentation.md#gating for
+// details on more granular conditions for gating sample collection.
+//
 // TODO(asanka): Migrate callers to IdentifiabilityStudySettings.
 bool BLINK_COMMON_EXPORT IsUserInIdentifiabilityStudy();
 

third_party/blink/public/common/privacy_budget/identifiability_study_settings.h

@@ -20,6 +20,11 @@ namespace blink {
 // synchronization.
 //
 // See documentation on individual methods for notes on thread safety.
+//
+// Guidelines for when and how to use it can be found in:
+//
+//     //docs/privacy_budget_instrumentation.md#gating
+//
 class BLINK_COMMON_EXPORT IdentifiabilityStudySettings {
  public:
   // Constructs a default IdentifiabilityStudySettings instance. By default the

third_party/blink/public/common/privacy_budget/identifiable_surface.h

@@ -18,8 +18,8 @@ namespace blink {
 
 // An identifiable surface.
 //
-// This class intends to be a lightweight wrapper over a simple integer. It
-// exhibits the following characteristics:
+// This class intends to be a lightweight wrapper over a simple 64-bit integer.
+// It exhibits the following characteristics:
 //
 //   * All methods are constexpr.
 //   * Immutable.
@@ -30,7 +30,28 @@ namespace blink {
 //
 // The least-significant |kTypeBits| of the value is used to store
 // a IdentifiableSurface::Type value. The remainder stores the 56
-// least-significant bits of an IdentifiableToken.
+// least-significant bits of an `IdentifiableToken` as illustrated below:
+//              ✂
+//    ┌─────────┊────────────────────────────────────────┐ ┌──────────┐
+//    │(discard)✂           IdentifiableToken            │ │   Type   │
+//    └─────────┊───────────────────┬────────────────────┘ └────┬─────┘
+// Bit 64       ┊55                 ┊                   0   7   ┊    0
+//              ✂                   ↓                           ↓
+//              ┌────────────────────────────────────────┬──────────┐
+//              │                                        │          │
+//              └────────────────────────────────────────┴──────────┘
+//           Bit 64                                     8 7        0
+//              │←────────────── IdentifiableSurface ──────────────→│
+//
+// Only the lower 56 bits of `IdentifiableToken` contribute to an
+// `IdentifiableSurface`.
+//
+// See descriptions for the `Type` enum values for details on how the
+// `IdentifiableToken` is generated for each type. The descriptions use the
+// following notation to indicate how the value is recorded:
+//
+//     IdentifiableSurface = { IdentifiableToken value, Type value }
+//     Value = [description of how the value is constructed]
 class IdentifiableSurface {
  public:
   // Number of bits used by Type.
@@ -47,7 +68,7 @@ class IdentifiableSurface {
   // (Type::kCanvasReadback), bits [4-6] are skipped ops, sensitive ops, and
   // partial image ops bits, respectively. The remaining bits are for the canvas
   // operations digest. If the digest wasn't calculated (there's no digest for
-  // webgl, for instance), the digest field is 0.
+  // WebGL, for instance), the digest field is 0.
   enum CanvasTaintBit : uint64_t {
     // At least one drawing operation didn't update the digest -- this is ether
     // due to performance or resource consumption reasons.
@@ -72,9 +93,27 @@ class IdentifiableSurface {
   enum class Type : uint64_t {
     // This type is reserved for internal use and should not be used for
     // reporting any identifiability metrics.
+    //
+    // All metrics defined under the Identifiability event in
+    // tools/metrics/ukm.xml fall into this type. Hence using
+    // `ukm::builders::Identifiability` results in metrics with this type.
     kReservedInternal = 0,
 
-    // Input is a mojom::WebFeature
+    // Represents a web feature whose output directly contributes to
+    // identifiability.
+    //
+    // These APIs are annotated with the `[HighEntropy=Direct]` extended WebIDL
+    // attribute in their respective IDL file. Each such API also has an
+    // associated `UseCounter` value specified directly via the
+    // `[MeasureAs=??]` attribute or indirectly via the `[Measure]` attribute.
+    // This `UseCounter` value is the key for recording the output of the API.
+    // `web_feature.mojom`[1] defines all the `UseCounter` values and is
+    // available as mojom::WebFeature.
+    //
+    //     IdentifiableSurface = { mojom::WebFeature, kWebFeature }
+    //     Value = IdentifiableToken( $(output of the attribute or method) )
+    //
+    // [1]: //blink/public/mojom/web_feature/web_feature.mojom
     kWebFeature = 1,
 
     // Represents a readback of a canvas. Input is the
@@ -154,6 +193,8 @@ class IdentifiableSurface {
   }
 
   // Construct an IdentifiableSurface based on a surface type and an input hash.
+  //
+  // DEPRECATED: Prefer FromTypeAndToken instead.
   static constexpr IdentifiableSurface FromTypeAndInput(Type type,
                                                         uint64_t input) {
     return IdentifiableSurface(KeyFromSurfaceTypeAndInput(type, input));