diff --git a/content/en/docs/instrumentation/ruby/sampling.md b/content/en/docs/instrumentation/ruby/sampling.md new file mode 100644 index 000000000000..0133585760b8 --- /dev/null +++ b/content/en/docs/instrumentation/ruby/sampling.md @@ -0,0 +1,50 @@ +--- +title: Sampling +weight: 6 +--- + +[Sampling](/docs/concepts/sampling/) is a process that restricts the amount of +traces that are generated by a system. The Ruby SDK offers several +[head samplers](/docs/concepts/sampling#head-sampling). + +## Default behavior + +By default, all spans are sampled, and thus, 100% of traces are sampled. If you +do not need to manage data volume, don't bother setting a sampler. + +Specifically, the default sampler is a composite of [ParentBased][] and +[ALWAYS_ON][] that ensures the root span in a trace is always sampled, and that +all child spans respect use their parent's sampling flag to make a sampling +decision. This guarantees that all spans in a trace are sampled by default. + +[ParentBased]: + https://www.rubydoc.info/gems/opentelemetry-sdk/OpenTelemetry/SDK/Trace/Samplers/ParentBased +[ALWAYS_ON]: + https://www.rubydoc.info/gems/opentelemetry-sdk/OpenTelemetry/SDK/Trace/Samplers + +## TraceIDRatioBased Sampler + +The most common head sampler to use is the [TraceIdRatioBased][] sampler. It +deterministically samples a percentage of traces that you pass in as a +parameter. + +[TraceIdRatioBased]: + https://www.rubydoc.info/gems/opentelemetry-sdk/OpenTelemetry/SDK/Trace/Samplers/TraceIdRatioBased + +### Environment Variables + +You can configure a `TraceIdRatioBased` sampler with environment variables: + +```shell +export OTEL_TRACES_SAMPLER="traceidratio" +export OTEL_TRACES_SAMPLER_ARG="0.1" +``` + +This tells the SDK to sample spans such that only 10% of traces get exported. + +### Configuration in Code + +Although it is possible to configure a `TraceIdRatioBased` sampler in code, it's +not recommended. Doing so requires you to manually set up a Tracer Provider with +all the right configuration options, which is hard to get right compared to just +using `OpenTelemetry::SDK.configure`. diff --git a/static/refcache.json b/static/refcache.json index 0ebc7ade8811..5f656320efa4 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -4003,6 +4003,18 @@ "StatusCode": 200, "LastSeen": "2023-02-18T13:38:57.647971-05:00" }, + "https://www.rubydoc.info/gems/opentelemetry-sdk/OpenTelemetry/SDK/Trace/Samplers": { + "StatusCode": 200, + "LastSeen": "2023-03-14T22:39:10.837691902Z" + }, + "https://www.rubydoc.info/gems/opentelemetry-sdk/OpenTelemetry/SDK/Trace/Samplers/ParentBased": { + "StatusCode": 200, + "LastSeen": "2023-03-14T22:39:10.744485794Z" + }, + "https://www.rubydoc.info/gems/opentelemetry-sdk/OpenTelemetry/SDK/Trace/Samplers/TraceIdRatioBased": { + "StatusCode": 200, + "LastSeen": "2023-03-14T22:32:16.257935604Z" + }, "https://www.sentrysoftware.com/products/hardware-sentry-opentelemetry-collector.html": { "StatusCode": 206, "LastSeen": "2023-02-18T13:34:23.69633-05:00"