Add guidance for custom samplers

Signed-off-by: Pratik Mahalle <mahallepratik683@gmail.com>

Author: pratik-mahalle

content/en/docs/languages/go/sampling.md

@@ -42,3 +42,170 @@ By default, the tracer provider uses a `ParentBased` sampler with the
 
 When in a production environment, consider using the `ParentBased` sampler with
 the `TraceIDRatioBased` sampler.
+
+## Custom samplers
+
+If the built-in samplers don't meet your needs, you can create a custom sampler
+by implementing the
+[`Sampler`](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/trace#Sampler)
+interface. A custom sampler must implement two methods:
+
+- `ShouldSample(parameters SamplingParameters) SamplingResult`: Makes the
+  sampling decision based on the provided parameters.
+- `Description() string`: Returns a description of the sampler.
+
+### Implementing the Sampler interface
+
+Here's the structure you need to implement:
+
+```go
+type Sampler interface {
+    ShouldSample(parameters SamplingParameters) SamplingResult
+    Description() string
+}
+```
+
+The
+[`SamplingParameters`](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/trace#SamplingParameters)
+struct provides context about the span being created:
+
+```go
+type SamplingParameters struct {
+    ParentContext context.Context
+    TraceID       trace.TraceID
+    Name          string
+    Kind          trace.SpanKind
+    Attributes    []attribute.KeyValue
+    Links         []trace.Link
+}
+```
+
+### Handling SamplingResult correctly
+
+The
+[`SamplingResult`](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/trace#SamplingResult)
+you return from `ShouldSample` has three fields:
+
+```go
+type SamplingResult struct {
+    Decision   SamplingDecision
+    Attributes []attribute.KeyValue
+    Tracestate trace.TraceState
+}
+```
+
+- **Decision**: One of `Drop`, `RecordOnly`, or `RecordAndSample`.
+- **Attributes**: Additional attributes to add to the span.
+- **Tracestate**: The tracestate to use for the span.
+
+{{% alert title="Critical: Preserve tracestate" color="warning" %}}
+
+When implementing a custom sampler, you **must** preserve the parent's
+tracestate in your `SamplingResult`. Failing to do so breaks context propagation
+in distributed systems that rely on tracestate for passing vendor-specific or
+application-specific trace data.
+
+Always extract the tracestate from the parent span context:
+
+```go
+psc := trace.SpanContextFromContext(parameters.ParentContext)
+// Use psc.TraceState() in your SamplingResult
+```
+
+{{% /alert %}}
+
+### Example
+
+The following example demonstrates a custom sampler that samples spans based on
+an attribute value while correctly preserving tracestate:
+
+```go
+package main
+
+import (
+    "context"
+
+    "go.opentelemetry.io/otel/attribute"
+    sdktrace "go.opentelemetry.io/otel/sdk/trace"
+    "go.opentelemetry.io/otel/trace"
+)
+
+// AttributeBasedSampler samples spans based on an attribute value.
+// It always samples spans with the "high.priority" attribute set to true.
+type AttributeBasedSampler struct {
+    fallback sdktrace.Sampler
+}
+
+// NewAttributeBasedSampler creates a new AttributeBasedSampler.
+func NewAttributeBasedSampler(fallback sdktrace.Sampler) *AttributeBasedSampler {
+    return &AttributeBasedSampler{fallback: fallback}
+}
+
+func (s *AttributeBasedSampler) ShouldSample(p sdktrace.SamplingParameters) sdktrace.SamplingResult {
+    // Always extract the parent span context to get the tracestate.
+    psc := trace.SpanContextFromContext(p.ParentContext)
+
+    // Check if any attribute indicates high priority.
+    for _, attr := range p.Attributes {
+        if attr.Key == "high.priority" && attr.Value.AsBool() {
+            return sdktrace.SamplingResult{
+                Decision:   sdktrace.RecordAndSample,
+                Attributes: p.Attributes,
+                // Critical: preserve the parent's tracestate
+                Tracestate: psc.TraceState(),
+            }
+        }
+    }
+
+    // Fall back to the default sampler for other spans.
+    result := s.fallback.ShouldSample(p)
+
+    // Ensure tracestate is preserved even when using fallback.
+    // Built-in samplers already handle this, but it's good practice to verify.
+    return sdktrace.SamplingResult{
+        Decision:   result.Decision,
+        Attributes: result.Attributes,
+        Tracestate: psc.TraceState(),
+    }
+}
+
+func (s *AttributeBasedSampler) Description() string {
+    return "AttributeBasedSampler"
+}
+```
+
+### Using your custom sampler
+
+You can use your custom sampler with the tracer provider:
+
+```go
+sampler := NewAttributeBasedSampler(sdktrace.TraceIDRatioBased(0.1))
+
+provider := sdktrace.NewTracerProvider(
+    sdktrace.WithSampler(sampler),
+)
+```
+
+You can also compose it with the `ParentBased` sampler:
+
+```go
+provider := sdktrace.NewTracerProvider(
+    sdktrace.WithSampler(
+        sdktrace.ParentBased(
+            NewAttributeBasedSampler(sdktrace.TraceIDRatioBased(0.1)),
+        ),
+    ),
+)
+```
+
+### Additional considerations
+
+When implementing custom samplers, keep these points in mind:
+
+1. **Ignoring the parent sampling decision**: If you want to respect parent
+   sampling decisions, wrap your sampler with `ParentBased` or check
+   `psc.IsSampled()` manually.
+
+2. **Heavy computations in ShouldSample**: The `ShouldSample` function is called
+   for every span creation. Avoid expensive operations like network calls or
+   complex computations that could impact performance.