Add a more flexible sampling strategy data model

Signed-off-by: Garrett Li <garrett.li.sh@gmail.com>

Author: xiancli

proto/api_v2/sampling.proto

@@ -74,7 +74,7 @@ message PerOperationSamplingStrategies {
   // one of the perOperationStrategies.
   double defaultLowerBoundTracesPerSecond = 2;
 
-  // perOperationStrategies describes sampling strategiesf for individual operations within
+  // perOperationStrategies describes sampling strategies for individual operations within
   // a given service.
   repeated OperationSamplingStrategy perOperationStrategies = 3;
 
@@ -83,6 +83,33 @@ message PerOperationSamplingStrategies {
   double defaultUpperBoundTracesPerSecond = 4;
 }
 
+// Dimension is a key-value pair that represents a single arbitrary combinations of dimensions.
+message Dimension {
+  string key = 1;
+  string value = 2;
+}
+
+// MultiDimensionalSamplingStrategy is a sampling strategy that takes into account arbitrary
+// combinations of dimensions (aka user session). Only probabilistic sampling is currently supported.
+message MultiDimensionalSamplingStrategy {
+  repeated Dimension dimensions = 1;
+  ProbabilisticSamplingStrategy probabilisticSampling = 2;
+}
+
+// PerMultiDimensionalSamplingStrategy is a combination of strategies for different dimensions
+// as well as some service-wide defaults. It is particularly useful for services whose
+// dimensions receive vastly different traffic, so that any single rate of sampling would
+// result in either too much data for some dimensions or almost no data for other dimensions.
+message PerMultiDimensionalSamplingStrategy {
+  // defaultSamplingProbability is the sampling probability for spans that do not match
+  // any of the perOperationStrategies.
+  double defaultSamplingProbability = 1;
+
+  // perMultiDimensionalStrategies describes sampling strategies for arbitrary combinations
+  // of dimensions within a given service.
+  repeated MultiDimensionalSamplingStrategy perMultiDimensionalStrategies = 2;
+}
+
 // SamplingStrategyResponse contains an overall sampling strategy for a given service.
 // This type should be treated as a union where only one of the strategy field is present.
 message SamplingStrategyResponse {
@@ -92,15 +119,17 @@ message SamplingStrategyResponse {
   // The recommended approach for consumers is to ignore this field and instead
   // checks the other fields being not null (starting with operationSampling).
   // For producers, it is recommended to set this field correctly for probabilistic
-  // and rate-limiting strategies, but if per-operation strategy is returned,
-  // the enum can be set to 0 (probabilistic).
+  // and rate-limiting strategies, but if per-operation or per-multi-dimensional
+  // strategy is returned, the enum can be set to 0 (probabilistic).
   SamplingStrategyType strategyType = 1;
 
   ProbabilisticSamplingStrategy probabilisticSampling = 2;
 
   RateLimitingSamplingStrategy rateLimitingSampling = 3;
 
   PerOperationSamplingStrategies operationSampling = 4;
+
+  PerMultiDimensionalSamplingStrategy multiDimensionalSampling = 5;
 }
 
 // SamplingStrategyParameters defines request parameters for remote sampler.
@@ -117,4 +146,13 @@ service SamplingManager {
             body: "*"
         };
   }
+  // The OTel Collector Jaeger's Remote Sampling extension can be configured to proxy requests
+  // to a backend remote sampling server. This means that a server-side streaming API with
+  // delta updates can significantly reduce network bandwidth usage.
+  rpc WatchSamplingStrategy(SamplingStrategyParameters) returns (stream SamplingStrategyResponse) {
+    option (google.api.http) = {
+      post: "/api/v2/samplingStrategyStream"
+      body: "*"
+    };
+  }
 }