Improve documentation for samplers/jaegerremote by providing exampl…

…es of sampling endpoints (#3147) * Improve documentation for `samplers/jaegerremote` by providing examples of sampling endpoints Signed-off-by: Yuri Shkuro <[email protected]> * Fix changelog Signed-off-by: Yuri Shkuro <[email protected]>
open-telemetry · Jan 13, 2023 · fdbade3 · fdbade3
1 parent d2456f2
commit fdbade3
Show file tree

Hide file tree

Showing 2 changed files with 17 additions and 2 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 - Add the new `go.opentelemetry.io/contrib/instrgen` package to provide auto-generated source code instrumentation. (#3068)
 - `otelmux`: Add new `WithSpanNameFormatter` option to `go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux/otelmux` to allow customizing span names. (#3041)
+- Improve documentation for `samplers/jaegerremote` by providing examples of sampling endpoints. (#3147)
 
 ## [1.12.0/0.37.0/0.6.0]
 
@@ -33,7 +34,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Added
 
 - Add trace context propagation support to `instrumentation/github.com/aws/aws-sdk-go-v2/otelaws` (#2856).
-- [otelgrpc] Add `WithMeterProvider` function to enable metric and add metric `rpc.server.duration` to otelgrpc instrumentation library. (#2700) 
+- [otelgrpc] Add `WithMeterProvider` function to enable metric and add metric `rpc.server.duration` to otelgrpc instrumentation library. (#2700)
 
 ### Changed
 

diff --git a/samplers/jaegerremote/README.md b/samplers/jaegerremote/README.md
@@ -1,6 +1,12 @@
 # Jaeger Remote Sampler
 
 This package implements [Jaeger remote sampler](https://www.jaegertracing.io/docs/latest/sampling/#collector-sampling-configuration).
+Remote sampler allows defining sampling configuration for services at the backend, at the granularity of service + endpoint.
+When using the Jaeger backend, the sampling configuration can come from two sources:
+
+1. A static configuration file, with the ability to hot-reload it on changes.
+2. [Adaptive sampling](https://www.jaegertracing.io/docs/latest/sampling/#adaptive-sampling) where Jaeger backend
+   automatically calculates desired sampling probabilities based on the target volume of trace data per service.
 
 ## Usage
 
@@ -9,7 +15,7 @@ Configuration in the code:
 ```go
 	jaegerRemoteSampler := jaegerremote.New(
 		"your-service-name",
-		jaegerremote.WithSamplingServerURL("http://{sampling_service_host_name}:5778"),
+		jaegerremote.WithSamplingServerURL("http://{sampling_service_host_name}:5778/sampling"),
 		jaegerremote.WithSamplingRefreshInterval(10*time.Second),
 		jaegerremote.WithInitialSampler(trace.TraceIDRatioBased(0.5)),
 	)
@@ -21,6 +27,14 @@ Configuration in the code:
 	otel.SetTracerProvider(tp)
 ```
 
+Sampling server:
+
+* Historically, the Jaeger Agent provided the sampling server at `http://{agent_host}:5778/sampling`.
+* When not running the Jaeger Agent, the sampling server is also provided by the Jaeger Collector,
+  but at a slightly different endpoint: `http://collector_host:14268/api/sampling`.
+* The OpenTelemetry Collector can provide the sampling endpoint `http://{otel_collector_host}:5778/sampling`
+  by [configuring an extension](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/extension/jaegerremotesampling/README.md).
+
 Notes:
 
 * At this time, the Jaeger Remote Sampler can only be configured in the code,