Add export_unsampled option to batch processor (export recording but unsampled spans)

[agent-adam]

Background / Problem

By default, the Erlang SDK only exports sampled spans. The OpenTelemetry Trace SDK specification states that exporters MUST receive sampled spans and SHOULD NOT receive non-sampled spans. That “SHOULD NOT” allows for language-level opt-in behaviors.

In the Java SDK, this was discussed and tracked in:

• Issue #4990 — Proposal to forward non-sampled spans to processors/exporters
• PR #6057 — Merged implementation adding setExportUnsampledSpans(true) option

The Erlang SDK has improved handling of non-recording spans (for example, not inserting them into ETS tables). However, there is no knob to export recording but unsampled spans, which can be useful for collector-side metrics and tail-based sampling where full request counts are needed.

---

Motivation / Use Cases

• Allow users to forward recording but unsampled spans to the Collector so that RED metrics, error ratios, and SLO burn rates can be computed with full coverage.
• Support Collector-level tail-based sampling with complete data, without forcing 100% head sampling at the agent.
• Preserve default spec-compliant behavior while enabling advanced users to opt-in.

---

Proposed Design

Add a new option to the batch processor:

%% sys.config / app env example
{opentelemetry, [
  {traces, [
    {processors, [
      {batch, #{
          exporter => otlp,
          export_unsampled => true
      }}
    ]}
  ]}
]}.

[tsloughter]

Thanks. I had seen this in the spec discussion and even with your explanation I can't say I understand exactly why this is better than just setting the sampler to always sample? I'd like to have that click before I agreed we should have it.

[agent-adam]

Thanks for the quick follow up @tsloughter ! Here is a bit more info about how it's useful and an example:

---

This feature is most valuable when users run ParentBased + TraceIdRatio (or similar) head sampling, where only a small % of traces are sampled and that decision is respected across all downstream services.

In high-throughput systems you often want to:

• Export all locally recorded spans to a local Collector (sidecar/daemonset) so it can compute span-to-metrics (RED metrics, error ratios, SLO burn) with full request counts—without flipping the sampled bit to true.
• Forward only sampled spans upstream to a remote, centralized backend to control egress and storage costs.

If you instead use always_on, you end up marking every span as Sampled=true. Under parent-based sampling, that forces all downstream services to also sample and export every span to the backend, which can introduce a major performance hit.

With an export_unsampled option, only the select services that have a local Collector running can enable it. Those services send both sampled and unsampled spans to their local Collector for accurate RED metrics, but still forward just the small % of sampled spans to the centralized backend. Meanwhile, all other downstream services continue to honor the parent-based sampling decision and only export sampled spans—keeping the backend costs and performance overhead low.

---

Example: Imagine a request flows through Service A → Service B → Service C. Service A makes the head sampling decision and sets the sampling bit. Service B is critical and runs with a local Collector—it enables export_unsampled, so it exports both sampled and unsampled spans locally to calculate accurate RED metrics, while still forwarding only sampled spans to the remote backend. Service C (and Service B for remote export) simply respects the sampling bit because they all use parent-based sampling, so they only send the sampled traces upstream. This way, you get full-fidelity RED metrics where you need them (Service B) without forcing every service in the path to export all spans to the backend.