doc(sdk): make JaegerRemoteSampler public, revise doc (open-telemet…

…ry#975)

* doc(sdk): make `JaegerRemoteSampler` public, revise doc

* Update README in examples

examples/jaeger-remote-sampler/README.md

@@ -5,6 +5,8 @@ When services generate too many spans. We need to sample some spans to save cost
 Adaptive sampling works in the Jaeger collector by observing the spans received from services and recalculating sampling
 probabilities for each service/endpoint combination to ensure that the volume is relatively constant.
 
+For a full list of configurations. See SDK docs of [JaegerRemoteSamplerBuilder](https://docs.rs/opentelemetry_sdk/latest/opentelemetry_sdk/trace/struct.JaegerRemoteSamplerBuilder.html).
+
 ## Setup
 
 Start a jaeger collector and an opentelemetry collector locally using docker
@@ -24,7 +26,7 @@ After start the jaeger remote sampling server successfully. We can run
 
 `cargo run`
 
-command to start the example, you should see something like only one span is printed out. 
+command to start the example, you should only see one span is printed out. 
 
 Looking at the example, you will notice we use `AlwaysOff` as our default sampler. It means before the SDK get the sampling strategy from remote server, no span will be sampled. 
 
@@ -44,4 +46,3 @@ The sampling strategies is defined in `srategies.json` files. It defines two set
 
 The first strategy is returned for `foo` service. The second strategy is catch all default strategy for all other
 services.
-

opentelemetry-sdk/src/trace/mod.rs

@@ -34,4 +34,4 @@ pub use span_processor::{
 pub use tracer::Tracer;
 
 #[cfg(feature = "jaeger_remote_sampler")]
-pub use sampler::JaegerRemoteSamplerBuilder;
+pub use sampler::{JaegerRemoteSampler, JaegerRemoteSamplerBuilder};

opentelemetry-sdk/src/trace/sampler.rs

@@ -12,9 +12,7 @@ use std::convert::TryInto;
 mod jaeger_remote;
 
 #[cfg(feature = "jaeger_remote_sampler")]
-use jaeger_remote::JaegerRemoteSampler;
-#[cfg(feature = "jaeger_remote_sampler")]
-pub use jaeger_remote::JaegerRemoteSamplerBuilder;
+pub use jaeger_remote::{JaegerRemoteSampler, JaegerRemoteSamplerBuilder};
 #[cfg(feature = "jaeger_remote_sampler")]
 use opentelemetry_http::HttpClient;
 
@@ -142,13 +140,13 @@ pub enum Sampler {
 }
 
 impl Sampler {
-    /// Create a jaeger remote sampler.
+    /// Create a jaeger remote sampler builder.
     ///
-    /// user needs to provide
-    /// - a `runtime` to run the http client
-    /// - a http client to query the sampling endpoint
-    /// - a default sampler to make sampling decision when the remote is unavailable or before the SDK receive the first response,
-    /// - the service name. This is a required parameter to query the sampling endpoint.
+    /// ### Arguments
+    /// * `runtime` - A runtime to run the HTTP client.
+    /// * `http_client` - An HTTP client to query the sampling endpoint.
+    /// * `default_sampler` - A default sampler to make a sampling decision when the remote is unavailable or before the SDK receives the first response from remote.
+    /// * `service_name` - The name of the service. This is a required parameter to query the sampling endpoint.
     ///
     /// See [here](https://github.com/open-telemetry/opentelemetry-rust/blob/main/examples/jaeger-remote-sampler/src/main.rs) for an example.
     #[cfg(feature = "jaeger_remote_sampler")]

opentelemetry-sdk/src/trace/sampler/jaeger_remote/mod.rs

@@ -3,8 +3,7 @@ mod remote;
 mod sampler;
 mod sampling_strategy;
 
-pub(crate) use sampler::JaegerRemoteSampler;
-pub use sampler::JaegerRemoteSamplerBuilder;
+pub use sampler::{JaegerRemoteSampler, JaegerRemoteSamplerBuilder};
 
 #[cfg(test)]
 mod tests {}

opentelemetry-sdk/src/trace/sampler/jaeger_remote/sampler.rs

@@ -12,7 +12,7 @@ use std::time::Duration;
 
 const DEFAULT_REMOTE_SAMPLER_ENDPOINT: &str = "http://localhost:5778/sampling";
 
-/// builder of JaegerRemoteSampler.
+/// Builder for [`JaegerRemoteSampler`].
 /// See [Sampler::jaeger_remote] for details.
 #[derive(Debug)]
 pub struct JaegerRemoteSamplerBuilder<C, S, R>
@@ -72,7 +72,7 @@ where
     ///
     /// By default it's `http://localhost:5778/sampling`.
     ///
-    /// If the service name is provided as part of the
+    /// If service name is provided as part of the endpoint, it will be ignored.
     pub fn with_endpoint<Str: Into<String>>(self, endpoint: Str) -> Self {
         Self {
             endpoint: endpoint.into(),
@@ -82,6 +82,8 @@ where
 
     /// The size of the leaky bucket.
     ///
+    /// By default the size is 100.
+    ///
     /// It's used when sampling strategy is rate limiting.
     pub fn with_leaky_bucket_size(self, size: f64) -> Self {
         Self {
@@ -90,9 +92,12 @@ where
         }
     }
 
-    /// Build a jaeger remote sampler.
+    /// Build a [JaegerRemoteSampler] using provided configuration.
+    ///
+    /// Return errors if:
     ///
-    /// Return errors when the endpoint provided is invalid(e.g, service name is empty)
+    /// - the endpoint provided is empty.
+    /// - the service name provided is empty.
     pub fn build(self) -> Result<Sampler, TraceError> {
         let endpoint = Self::get_endpoint(&self.endpoint, &self.service_name)
             .map_err(|err_str| TraceError::Other(err_str.into()))?;
@@ -113,6 +118,7 @@ where
         }
         let mut endpoint = url::Url::parse(endpoint)
             .unwrap_or_else(|_| url::Url::parse(DEFAULT_REMOTE_SAMPLER_ENDPOINT).unwrap());
+
         endpoint
             .query_pairs_mut()
             .append_pair("service", service_name);
@@ -123,6 +129,13 @@ where
 
 /// Sampler that fetches the sampling configuration from remotes.
 ///
+/// It offers the following sampling strategies:
+/// - **Probabilistic**, fetch a probability between [0.0, 1.0] from remotes and use it to sample traces. If the probability is 0.0, it will never sample traces. If the probability is 1.0, it will always sample traces.
+/// - **Rate limiting**, ses a leaky bucket rate limiter to ensure that traces are sampled with a certain constant rate.
+/// - **Per Operations**, instead of sampling all traces, it samples traces based on the span name. Only probabilistic sampling is supported at the moment.
+///
+/// User can build a [`JaegerRemoteSampler`] by getting a [`JaegerRemoteSamplerBuilder`] from [`Sampler::jaeger_remote`].
+///
 /// Note that the backend doesn't need to be Jaeger so long as it supports jaeger remote sampling
 /// protocol.
 #[derive(Clone, Debug)]