Span Processors are basically undocumented

[genebean]

I have learned via chat that the SimpleSpanProcessor is not intended for anything other than local testing yet its all that is used in the examples. By trial and error I learned that the expected default is the BatchSpanProcessor. Having said that, I am not aware of any documentation of this or of when or how to use any of the span processors.

For me, this became a real issue today: the SimpleSpanProcessor paired with the Jaeger::CollectorExporter broke a service for us - it made an endpoint response time go from sub-1s to 20s. The batch processor fixed our issue. I also think there were additional issues that are harder to quantify too, fwiw.

[rachelleahklein]

I'm planning to help provide some documentation on this topic.

[genebean]

FWIW, I still feel that notable amounts of documentation are missing here. #461 only made changes in the comments of two of the four span processors. Additionally, two are located in https://github.com/open-telemetry/opentelemetry-ruby/tree/master/sdk/lib/opentelemetry/sdk/trace while the other two are located in https://github.com/open-telemetry/opentelemetry-ruby/tree/master/sdk/lib/opentelemetry/sdk/trace/export yet neither the trace nor the export folder contain a readme or other centralized documentation on the processors. While the additions are helpful and welcome, they do not provide what I think is needed for the average user of this project, myself included. I feel like there needs to be a readme somewhere, even if all it does is reference something over in the spec repo.

[plantfansam]

Is this still an active issue? We don't have a pattern of READMEs in sdk/ subdirectories, so I'd be hesitant to add one just for this. Perhaps we could log a silenceable warning in add_span_processor if you register a SimpleSpanProcessor. Something like

        # Adds a new SpanProcessor to this {Tracer}.
        #
        # @param span_processor the new SpanProcessor to be added.
        def add_span_processor(span_processor)
          @mutex.synchronize do
            if span_processor.is_a?(SimpleSpanProcessor) && !ENV["OTEL_RUBY_SILENCE_SPAN_PROCESSOR_WARNING"].nil?
              OpenTelemetry.logger.warn('you are using SimpleSpanProcessor are you sure about that, pal?')
            end
            if @stopped
              OpenTelemetry.logger.warn('calling Tracer#add_span_processor after shutdown.')
              return
            end
            @span_processors = @span_processors.dup.push(span_processor)
          end
        end

[ahayworth]

@plantfansam Yes, I do think this is still relevant actually. Outside of the default, happy-path case, it's hard to get started in my opinion.

Of course, many language SIGs have issues with documentation, but I think we could keep this open as a docs TODO.

[github-actions]

👋 This issue has been marked as stale because it has been open with no activity. You can: comment on the issue or remove the stale label to hold stale off for a while, add the keep label to hold stale off permanently, or do nothing. If you do nothing this issue will be closed eventually by the stale bot.