Add ruby head sampling doc (open-telemetry#2505)

Co-authored-by: Patrice Chalin <[email protected]>

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`.

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"