diff --git a/proto/api_v2/sampling.proto b/proto/api_v2/sampling.proto index 0e53bd9..24adbc0 100644 --- a/proto/api_v2/sampling.proto +++ b/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,8 +119,8 @@ 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; @@ -101,6 +128,8 @@ message SamplingStrategyResponse { 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: "*" + }; + } }