From ec3f84505a0952fca29cac4b0ed8a43cadc8edf7 Mon Sep 17 00:00:00 2001
From: Charly Gomez <charly.gomez@sentry.io>
Date: Thu, 25 Jul 2024 10:58:56 +0200
Subject: [PATCH] docs: add section for custom otel sampler

---
 .../tracing/instrumentation/opentelemetry.mdx | 69 +++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/docs/platforms/javascript/common/tracing/instrumentation/opentelemetry.mdx b/docs/platforms/javascript/common/tracing/instrumentation/opentelemetry.mdx
index 7f568b7fc36c0..b3f71027b60a7 100644
--- a/docs/platforms/javascript/common/tracing/instrumentation/opentelemetry.mdx
+++ b/docs/platforms/javascript/common/tracing/instrumentation/opentelemetry.mdx
@@ -113,3 +113,72 @@ tracer.startActiveSpan("span name", () => {
 ```
 
 You can also use any other tracer; all OpenTelemetry spans will be picked up by Sentry automatically.
+
+## Using a Custom Sampler
+
+We recommend using `SentrySampler` as this will correctly will ensure the correct subset of traces is sent to Sentry depending on your `tracesSampleRate`.
+If you however need to use your own sampler then make sure to wrap your `SamplingResult` wit our `wrapSamplingDecision` method:
+
+```js {filename: custom-sampler.js}
+const { wrapSamplingDecision } = require("@sentry/opentelemetry");
+
+// implements Sampler from "@opentelemetry/sdk-trace-node"
+class CustomSampler {
+  shouldSample(
+    context,
+    _traceId,
+    _spanName,
+    _spanKind,
+    attributes,
+    _links
+  ) {
+    const decision = yourDecisionLogic();
+    
+    // wrap the result
+    return wrapSamplingDecision({
+      decision,
+      context,
+      spanAttributes: attributes,
+    });
+  }
+
+  toString() {
+    return CustomSampler.name;
+  }
+}
+
+module.exports = CustomSampler;
+
+```
+
+Now use your sampler in your `TraceProvider`:
+
+```js {filename: instrument.js}
+const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
+const Sentry = require("@sentry/node");
+const {
+  SentrySpanProcessor,
+  SentryPropagator,
+  SentrySampler,
+} = require("@sentry/opentelemetry");
+const CustomSampler = require("./custom-sampler");
+
+const sentryClient = Sentry.init({
+  dsn: "__DSN__",
+  skipOpenTelemetrySetup: true,
+  
+  // By defining any sample rate,
+  // tracing intergations will be added by default
+  tracesSampleRate: 1.0,
+});
+
+
+const provider = new NodeTracerProvider({
+  sampler: new CustomSampler(sentryClient),
+});
+
+// ...rest of your setup
+
+// Validate that the setup is correct
+Sentry.validateOpenTelemetrySetup();
+```
\ No newline at end of file