Add JaegerRemoteSampler spec

Signed-off-by: Pavol Loffay <[email protected]>

specification/sdk-environment-variables.md

@@ -65,13 +65,14 @@ Known values for `OTEL_TRACES_SAMPLER` are:
 - `"parentbased_always_on"`: `ParentBased(root=AlwaysOnSampler)`
 - `"parentbased_always_off"`: `ParentBased(root=AlwaysOffSampler)`
 - `"parentbased_traceidratio"`: `ParentBased(root=TraceIdRatioBased)`
+- `"parentbased_jaeger_remote"`: `ParentBased(root=JaegerRemoteSampler)`
 - `"jaeger_remote"`: `JaegerRemoteSampler`
 - `"xray"`: [AWS X-Ray Centralized Sampling](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html) (_third party_)
 
 Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may be set as follows:
 
 - For `traceidratio` and `parentbased_traceidratio` samplers: Sampling probability, a number in the [0..1] range, e.g. "0.25". Default is 1.0 if unset.
-- For `jaeger_remote`: The value is a comma separated list:
+- For `jaeger_remote` and `parentbased_jaeger_remote`: The value is a comma separated list:
   - `endpoint`: the endpoint in form of `host:port` of gRPC server that serves the sampling strategy for the service ([sampling.proto](https://github.com/jaegertracing/jaeger-idl/blob/master/proto/api_v2/sampling.proto)).
   - `pollingIntervalMs`:  in milliseconds indicating how often the sampler will poll the backend for updates to sampling strategy.
   - `initialSamplingRate`:  in the [0..1] range, which is used as the sampling probability when the backend cannot be reached to retrieve a sampling strategy. This value stops having an effect once a sampling strategy is retrieved successfully, as the remote strategy will be used until a new update is retrieved.

specification/trace/sdk.md

@@ -23,6 +23,8 @@
     + [TraceIdRatioBased](#traceidratiobased)
       - [Requirements for `TraceIdRatioBased` sampler algorithm](#requirements-for-traceidratiobased-sampler-algorithm)
     + [ParentBased](#parentbased)
+    + [JaegerRemoteSampler](#jaegerremotesampler)
+      - [Configuration](#configuration)
 - [Span Limits](#span-limits)
 - [Id Generators](#id-generators)
 - [Span processor](#span-processor)
@@ -352,6 +354,20 @@ Optional parameters:
 |present|false|true|`localParentSampled()`|
 |present|false|false|`localParentNotSampled()`|
 
+#### JaegerRemoteSampler
+
+[Jaeger remote sampler](https://www.jaegertracing.io/docs/1.29/sampling/#collector-sampling-configuration) allows remotely controlling the sampling configuration for the SDKs. The sampling is typically configured at the collector and the SDKs actively poll for changes. The sampler uses `TraceIdRatioBased` or `RateLimiting` sampler under the hood. These samplers can be configured per whole service (a.k.a default), or per span name in a given service (a.k.a per operation).
+
+The full Protobuf definition can be found at [jaegertracing/jaeger-idl/api_v2/sampling.proto](https://github.com/jaegertracing/jaeger-idl/blob/main/proto/api_v2/sampling.proto).
+
+##### Configuration
+
+Following configuration properties should be available when creating the sampler:
+
+* endpoint - collector address with running service with sampling manager
+* polling interval - polling interval for getting configuration from remote
+* initial sampler - initial sampler that is used before the first configuration is fetched
+
 ## Span Limits
 
 Span attributes MUST adhere to the [common rules of attribute limits](../common/common.md#attribute-limits).