Restore export_unsampled_spans as opt-in feature maintaining spec compliance by default

Co-authored-by: lalitb <1196320+lalitb@users.noreply.github.com>

Author: Copilot

docs/export-unsampled-spans.md

@@ -0,0 +1,66 @@
+# Export Unsampled Spans Feature
+
+The OpenTelemetry C++ SDK supports an opt-in feature to export unsampled but recording spans from trace processors. This allows collectors to see the full request volume, which is useful for calculating accurate metrics and performing tail-based sampling.
+
+**⚠️ IMPORTANT**: This feature intentionally violates the OpenTelemetry specification when enabled. According to the OpenTelemetry specification, RECORD_ONLY spans should be processed by SpanProcessors but should NEVER be sent to SpanExporters. Use this feature only when you specifically need this behavior and understand the specification implications.
+
+## Overview
+
+By default, the C++ SDK maintains OpenTelemetry specification compliance by only exporting sampled spans (`Decision::RECORD_AND_SAMPLE`). With this feature enabled, spans with `Decision::RECORD_ONLY` (unsampled but recording) will also be exported, which violates the specification.
+
+## Usage
+
+### BatchSpanProcessor
+
+```cpp
+#include "opentelemetry/sdk/trace/batch_span_processor.h"
+#include "opentelemetry/sdk/trace/batch_span_processor_options.h"
+
+// Configure BatchSpanProcessor to export unsampled spans
+opentelemetry::sdk::trace::BatchSpanProcessorOptions options;
+options.export_unsampled_spans = true; // Default is false
+
+auto processor = std::make_unique<opentelemetry::sdk::trace::BatchSpanProcessor>(
+ std::move(exporter), options);
+```
+
+### SimpleSpanProcessor
+
+```cpp
+#include "opentelemetry/sdk/trace/simple_processor.h"
+#include "opentelemetry/sdk/trace/simple_processor_options.h"
+
+// Configure SimpleSpanProcessor to export unsampled spans
+opentelemetry::sdk::trace::SimpleSpanProcessorOptions options;
+options.export_unsampled_spans = true; // Default is false
+
+auto processor = std::make_unique<opentelemetry::sdk::trace::SimpleSpanProcessor>(
+ std::move(exporter), options);
+```
+
+## Behavior
+
+When `export_unsampled_spans` is:
+
+- **false** (default): Only sampled spans are exported
+- **true**: Both sampled and unsampled recording spans are exported
+
+## Sampling Decisions
+
+The feature respects the sampling decisions made during span creation:
+
+- `Decision::DROP`: Spans are not recorded and never reach the processor (not affected)
+- `Decision::RECORD_ONLY`: Spans are recorded but not sampled by default (affected by this feature)
+- `Decision::RECORD_AND_SAMPLE`: Spans are recorded and sampled (always exported)
+
+## Backward Compatibility
+
+This feature maintains full backward compatibility:
+
+- Default behavior is unchanged (only sampled spans are exported)
+- Existing constructors continue to work as before
+- Test spans with invalid contexts are always exported for compatibility
+
+## Example
+
+See [examples/unsampled_spans_demo.cc](../examples/unsampled_spans_demo.cc) for a complete working example demonstrating the feature.

examples/CMakeLists.txt

@@ -28,6 +28,10 @@ add_subdirectory(metrics_simple)
 add_subdirectory(multithreaded)
 add_subdirectory(multi_processor)
 
+# Add unsampled spans demo example
+add_executable(unsampled_spans_demo unsampled_spans_demo.cc)
+target_link_libraries(unsampled_spans_demo PRIVATE opentelemetry-cpp::trace)
+
 if(WITH_EXAMPLES_HTTP)
  add_subdirectory(http)
 endif()

examples/unsampled_spans_demo.cc

@@ -0,0 +1,137 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// Example demonstrating export_unsampled_spans feature
+// This example shows how to configure span processors to export unsampled spans
+
+#include <iostream>
+#include <memory>
+
+#include "opentelemetry/sdk/trace/batch_span_processor.h"
+#include "opentelemetry/sdk/trace/batch_span_processor_options.h"
+#include "opentelemetry/sdk/trace/simple_processor.h"
+#include "opentelemetry/sdk/trace/simple_processor_options.h"
+#include "opentelemetry/sdk/trace/span_data.h"
+#include "opentelemetry/trace/span_context.h"
+#include "opentelemetry/trace/trace_flags.h"
+
+namespace trace_sdk = opentelemetry::sdk::trace;
+namespace trace_api = opentelemetry::trace;
+
+// Simple mock exporter for demonstration
+class MockExporter : public trace_sdk::SpanExporter
+{
+public:
+ explicit MockExporter(const std::string &name) : name_(name) {}
+
+ std::unique_ptr<trace_sdk::Recordable> MakeRecordable() noexcept override
+ {
+ return std::make_unique<trace_sdk::SpanData>();
+ }
+
+ opentelemetry::sdk::common::ExportResult Export(
+ const opentelemetry::nostd::span<std::unique_ptr<trace_sdk::Recordable>>
+ &recordables) noexcept override
+ {
+ std::cout << name_ << " exported " << recordables.size() << " spans" << std::endl;
+ return opentelemetry::sdk::common::ExportResult::kSuccess;
+ }
+
+ bool ForceFlush(std::chrono::microseconds) noexcept override { return true; }
+ bool Shutdown(std::chrono::microseconds) noexcept override { return true; }
+
+private:
+ std::string name_;
+};
+
+// Create a test span with specific sampling status
+std::unique_ptr<trace_sdk::SpanData> CreateTestSpan(bool sampled)
+{
+ auto span = std::make_unique<trace_sdk::SpanData>();
+ span->SetName("test_span");
+
+ // Set up valid context with proper sampling
+ trace_api::TraceFlags flags(sampled ? trace_api::TraceFlags::kIsSampled : 0);
+ uint8_t trace_id_bytes[16] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16};
+ uint8_t span_id_bytes[8] = {1, 2, 3, 4, 5, 6, 7, 8};
+
+ trace_api::TraceId trace_id{opentelemetry::nostd::span<const uint8_t, 16>(trace_id_bytes)};
+ trace_api::SpanId span_id{opentelemetry::nostd::span<const uint8_t, 8>(span_id_bytes)};
+
+ trace_api::SpanContext context(trace_id, span_id, flags, false);
+ span->SetIdentity(context, trace_api::SpanId());
+
+ return span;
+}
+
+int main()
+{
+ std::cout << "OpenTelemetry C++ Export Unsampled Spans Demo\n" << std::endl;
+
+ // Example 1: BatchSpanProcessor without export_unsampled_spans (default behavior)
+ {
+ std::cout << "=== Example 1: BatchSpanProcessor (default behavior) ===" << std::endl;
+
+ trace_sdk::BatchSpanProcessorOptions options;
+ // export_unsampled_spans is false by default
+
+ auto processor = std::make_unique<trace_sdk::BatchSpanProcessor>(
+ std::make_unique<MockExporter>("BatchProcessor-Default"), options);
+
+ // Create one sampled and one unsampled span
+ auto sampled_span = CreateTestSpan(true);
+ auto unsampled_span = CreateTestSpan(false);
+
+ processor->OnEnd(std::unique_ptr<trace_sdk::Recordable>(sampled_span.release()));
+ processor->OnEnd(std::unique_ptr<trace_sdk::Recordable>(unsampled_span.release()));
+
+ processor->ForceFlush();
+ std::cout << "Expected: Only 1 span exported (sampled span only)\n" << std::endl;
+ }
+
+ // Example 2: BatchSpanProcessor with export_unsampled_spans enabled
+ {
+ std::cout << "=== Example 2: BatchSpanProcessor (export_unsampled_spans = true) ==="
+ << std::endl;
+
+ trace_sdk::BatchSpanProcessorOptions options;
+ options.export_unsampled_spans = true; // Enable exporting unsampled spans
+
+ auto processor = std::make_unique<trace_sdk::BatchSpanProcessor>(
+ std::make_unique<MockExporter>("BatchProcessor-WithUnsampled"), options);
+
+ // Create one sampled and one unsampled span
+ auto sampled_span = CreateTestSpan(true);
+ auto unsampled_span = CreateTestSpan(false);
+
+ processor->OnEnd(std::unique_ptr<trace_sdk::Recordable>(sampled_span.release()));
+ processor->OnEnd(std::unique_ptr<trace_sdk::Recordable>(unsampled_span.release()));
+
+ processor->ForceFlush();
+ std::cout << "Expected: 2 spans exported (both sampled and unsampled)\n" << std::endl;
+ }
+
+ // Example 3: SimpleSpanProcessor with export_unsampled_spans enabled
+ {
+ std::cout << "=== Example 3: SimpleSpanProcessor (export_unsampled_spans = true) ==="
+ << std::endl;
+
+ trace_sdk::SimpleSpanProcessorOptions options;
+ options.export_unsampled_spans = true; // Enable exporting unsampled spans
+
+ auto processor = std::make_unique<trace_sdk::SimpleSpanProcessor>(
+ std::make_unique<MockExporter>("SimpleProcessor-WithUnsampled"), options);
+
+ // Create one sampled and one unsampled span
+ auto sampled_span = CreateTestSpan(true);
+ auto unsampled_span = CreateTestSpan(false);
+
+ processor->OnEnd(std::unique_ptr<trace_sdk::Recordable>(sampled_span.release()));
+ processor->OnEnd(std::unique_ptr<trace_sdk::Recordable>(unsampled_span.release()));
+
+ std::cout << "Expected: 2 separate exports (one for each span)\n" << std::endl;
+ }
+
+ std::cout << "Demo completed!" << std::endl;
+ return 0;
+}

sdk/include/opentelemetry/sdk/trace/batch_span_processor.h

@@ -164,6 +164,7 @@ class BatchSpanProcessor : public SpanProcessor
  const size_t max_queue_size_;
  const std::chrono::milliseconds schedule_delay_millis_;
  const size_t max_export_batch_size_;
+ const bool export_unsampled_spans_;
 
  /* The buffer/queue to which the ended spans are added */
  opentelemetry::sdk::common::CircularBuffer<Recordable> buffer_;

sdk/include/opentelemetry/sdk/trace/batch_span_processor_options.h

@@ -33,6 +33,15 @@ struct BatchSpanProcessorOptions
  * equal to max_queue_size.
  */
  size_t max_export_batch_size = 512;
+
+ /**
+ * Whether to export unsampled but recording spans.
+ * By default, only sampled spans (Decision::RECORD_AND_SAMPLE) are exported to maintain
+ * OpenTelemetry specification compliance.
+ * When set to true, unsampled recording spans (Decision::RECORD_ONLY) are also exported,
+ * which intentionally violates the OpenTelemetry specification.
+ */
+ bool export_unsampled_spans = false;
 };
 
 } // namespace trace

sdk/include/opentelemetry/sdk/trace/simple_processor.h

@@ -15,6 +15,8 @@
 #include "opentelemetry/sdk/trace/exporter.h"
 #include "opentelemetry/sdk/trace/processor.h"
 #include "opentelemetry/sdk/trace/recordable.h"
+#include "opentelemetry/sdk/trace/simple_processor_options.h"
+#include "opentelemetry/sdk/trace/span_data.h"
 #include "opentelemetry/trace/span_context.h"
 #include "opentelemetry/version.h"
 
@@ -40,7 +42,17 @@ class SimpleSpanProcessor : public SpanProcessor
  * @param exporter the exporter used by the span processor
  */
  explicit SimpleSpanProcessor(std::unique_ptr<SpanExporter> &&exporter) noexcept
- : exporter_(std::move(exporter))
+ : exporter_(std::move(exporter)), export_unsampled_spans_(false)
+ {}
+
+ /**
+ * Initialize a simple span processor with options.
+ * @param exporter the exporter used by the span processor
+ * @param options the processor options
+ */
+ explicit SimpleSpanProcessor(std::unique_ptr<SpanExporter> &&exporter,
+ const SimpleSpanProcessorOptions &options) noexcept
+ : exporter_(std::move(exporter)), export_unsampled_spans_(options.export_unsampled_spans)
  {}
 
  std::unique_ptr<Recordable> MakeRecordable() noexcept override
@@ -54,6 +66,22 @@ class SimpleSpanProcessor : public SpanProcessor
 
  void OnEnd(std::unique_ptr<Recordable> &&span) noexcept override
  {
+ // Check if we should export this span based on sampling status
+ auto *span_data = static_cast<SpanData *>(span.get());
+ const auto &span_context = span_data->GetSpanContext();
+
+ // For backward compatibility: always export spans with invalid context (e.g., test spans)
+ // For valid contexts: export sampled spans or unsampled spans if export_unsampled_spans is
+ // enabled
+ bool should_export =
+ !span_context.IsValid() || span_context.IsSampled() || export_unsampled_spans_;
+
+ if (!should_export)
+ {
+ // Drop unsampled spans if export_unsampled_spans is not enabled
+ return;
+ }
+
  nostd::span<std::unique_ptr<Recordable>> batch(&span, 1);
  const std::lock_guard<opentelemetry::common::SpinLockMutex> locked(lock_);
  if (exporter_->Export(batch) == sdk::common::ExportResult::kFailure)
@@ -89,6 +117,7 @@ class SimpleSpanProcessor : public SpanProcessor
 
 private:
  std::unique_ptr<SpanExporter> exporter_;
+ const bool export_unsampled_spans_;
  opentelemetry::common::SpinLockMutex lock_;
 #if defined(__cpp_lib_atomic_value_initialization) && \
  __cpp_lib_atomic_value_initialization >= 201911L

sdk/include/opentelemetry/sdk/trace/simple_processor_options.h

@@ -0,0 +1,32 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include "opentelemetry/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+
+namespace trace
+{
+
+/**
+ * Struct to hold simple SpanProcessor options.
+ */
+struct SimpleSpanProcessorOptions
+{
+ /**
+ * Whether to export unsampled but recording spans.
+ * By default, only sampled spans (Decision::RECORD_AND_SAMPLE) are exported to maintain
+ * OpenTelemetry specification compliance.
+ * When set to true, unsampled recording spans (Decision::RECORD_ONLY) are also exported,
+ * which intentionally violates the OpenTelemetry specification.
+ */
+ bool export_unsampled_spans = false;
+};
+
+} // namespace trace
+} // namespace sdk
+OPENTELEMETRY_END_NAMESPACE

sdk/src/trace/batch_span_processor.cc

@@ -25,6 +25,7 @@
 #include "opentelemetry/sdk/trace/exporter.h"
 #include "opentelemetry/sdk/trace/processor.h"
 #include "opentelemetry/sdk/trace/recordable.h"
+#include "opentelemetry/sdk/trace/span_data.h"
 #include "opentelemetry/version.h"
 
 #ifdef ENABLE_THREAD_INSTRUMENTATION_PREVIEW
@@ -47,6 +48,7 @@ BatchSpanProcessor::BatchSpanProcessor(std::unique_ptr<SpanExporter> &&exporter,
  max_queue_size_(options.max_queue_size),
  schedule_delay_millis_(options.schedule_delay_millis),
  max_export_batch_size_(options.max_export_batch_size),
+ export_unsampled_spans_(options.export_unsampled_spans),
  buffer_(max_queue_size_),
  synchronization_data_(std::make_shared<SynchronizationData>()),
  worker_thread_instrumentation_(nullptr),
@@ -63,6 +65,7 @@ BatchSpanProcessor::BatchSpanProcessor(std::unique_ptr<SpanExporter> &&exporter,
  max_queue_size_(options.max_queue_size),
  schedule_delay_millis_(options.schedule_delay_millis),
  max_export_batch_size_(options.max_export_batch_size),
+ export_unsampled_spans_(options.export_unsampled_spans),
  buffer_(max_queue_size_),
  synchronization_data_(std::make_shared<SynchronizationData>()),
  worker_thread_instrumentation_(runtime_options.thread_instrumentation),
@@ -89,6 +92,22 @@ void BatchSpanProcessor::OnEnd(std::unique_ptr<Recordable> &&span) noexcept
  return;
  }
 
+ // Check if we should export this span based on sampling status
+ auto *span_data = static_cast<SpanData *>(span.get());
+ const auto &span_context = span_data->GetSpanContext();
+
+ // For backward compatibility: always export spans with invalid context (e.g., test spans)
+ // For valid contexts: export sampled spans or unsampled spans if export_unsampled_spans is
+ // enabled
+ bool should_export =
+ !span_context.IsValid() || span_context.IsSampled() || export_unsampled_spans_;
+
+ if (!should_export)
+ {
+ // Drop unsampled spans if export_unsampled_spans is not enabled
+ return;
+ }
+
  if (buffer_.Add(std::move(span)) == false)
  {
  OTEL_INTERNAL_LOG_WARN("BatchSpanProcessor queue is full - dropping span.");

sdk/test/trace/CMakeLists.txt

@@ -13,7 +13,8 @@ foreach(
  parent_sampler_test
  trace_id_ratio_sampler_test
  batch_span_processor_test
- tracer_config_test)
+ tracer_config_test
+ unsampled_span_processor_test)
  add_executable(${testname} "${testname}.cc")
  target_link_libraries(
  ${testname}