Compliance Matrix Validation for rel1.0.0 - TracerProvider, Context, Tracer, Span Context

[lalitb]

This ticket is to validate the below attributes of Spec Compliance Matrix for Rel 1.0.0. While validation, if there is any ticket created for non-compliance, mention that next the non-compliant point.

TracerProvider:

• Create TracerProvider
• Get a Tracer
• Safe for concurrent calls ( read below for exceptions - AddProcessor() and Shutdown() )
• Shutdown (SDK only required)

Trace / Context interaction

• Get active Span
• Set active Span

Tracer :

• Create a new Span
• Get active Span
• Mark Span active
• Safe for concurrent calls

SpanContext:

• IsValid
• IsRemote
• Conforms to the W3C TraceContext spec (W3C TraceContext compliance #74)

[lalitb]

TracerProvider

Tracers can be accessed with a TracerProvider.

opentelemetry-cpp/api/include/opentelemetry/trace/tracer_provider.h

Lines 23 to 25 in 5914160

	virtual nostd::shared_ptr<Tracer> GetTracer(nostd::string_view library_name,
	nostd::string_view library_version = "") = 0;
	};

the API SHOULD provide a way to set/register and access a global default TracerProvider.

opentelemetry-cpp/api/include/opentelemetry/trace/provider.h

Line 25 in 5914160

static nostd::shared_ptr<TracerProvider> GetTracerProvider() noexcept

opentelemetry-cpp/api/include/opentelemetry/trace/provider.h

Line 34 in 5914160

static void SetTracerProvider(nostd::shared_ptr<TracerProvider> tp) noexcept

implementations of TracerProvider SHOULD allow creating an arbitrary number of TracerProvider instances.

As the constructor of TracerProvider is public, it is possible to create multiple instances of TracerProvider each injected with it's own TracerContext

opentelemetry-cpp/sdk/include/opentelemetry/sdk/trace/tracer_provider.h

Line 57 in 5914160

explicit TracerProvider(std::shared_ptr<sdk::trace::TracerContext> context) noexcept;

Implementations MUST NOT require users to repeatedly obtain a Tracer again with the same name+version to pick up configuration changes

The TracerProvider doesn't support updating configuration after creation. Only a new SpanProcessor can be added, and this configuration is visible to the existing Tracer and used for any new spans created after the update.

TracerProvider - all methods are safe to be called concurrently.

With exception of TracerProvider::AddProceesor(), all methods are thread-safe. This method is documented to be called sequentially, as the order of adding processors could be important.

opentelemetry-cpp/sdk/include/opentelemetry/sdk/trace/tracer_provider.h

Lines 69 to 73 in 5914160

	* Note: This method is not thread safe, and should ideally be called from main thread.
	*/
	void AddProcessor(std::unique_ptr<SpanProcessor> processor) noexcept;
	/**

The name and version arguments supplied to the TracerProvider must be used to create an InstrumentationLibrary instance which is stored on the created Tracer.

opentelemetry-cpp/sdk/src/trace/tracer_provider.cc

Lines 55 to 58 in 5914160

	auto lib = InstrumentationLibrary::create(library_name, library_version);
	tracers_.push_back(std::shared_ptr<opentelemetry::sdk::trace::Tracer>(
	new sdk::trace::Tracer(context_, std::move(lib))));
	return nostd::shared_ptr<opentelemetry::trace::Tracer>{tracers_.back()};

Configuration (i.e., SpanProcessors, IdGenerator, SpanLimits and Sampler) MUST be managed solely by the TracerProvider and it MUST provide some way to configure all of them that are implemented in the SDK, at least when creating or initializing it.

Configuration is solely managed by TracerContext which is shared by all the Tracers managed by TracerContext

Shutdown: This method provides a way for provider to do any cleanup required.

opentelemetry-cpp/sdk/include/opentelemetry/sdk/trace/tracer_provider.h

Lines 86 to 88 in 5278e8c

	* Shutdown the span processor associated with this tracer provider.
	*/
	bool Shutdown() noexcept;

Shutdown should be called ONLY once .And it is not required to be thread-safe as per the specs: Shutdown MUST be called only once for each TracerProvider instance.

[lalitb]

Tracer / Context Interaction

Extract the Span from a Context instance

opentelemetry-cpp/api/include/opentelemetry/trace/propagation/detail/context.h

Line 11 in 5278e8c

inline nostd::shared_ptr<trace::Span> GetSpan(const context::Context &context)

Insert the Span to a Context instance

opentelemetry-cpp/api/include/opentelemetry/trace/propagation/detail/context.h

Line 21 in 5278e8c

inline context::Context SetSpan(context::Context &context, nostd::shared_ptr<trace::Span> span)

Get the currently active span from the implicit context. This is equivalent to getting the implicit context, then extracting the Span from the context.

opentelemetry-cpp/api/include/opentelemetry/trace/tracer.h

Line 153 in 5278e8c

static nostd::shared_ptr<Span> GetCurrentSpan() noexcept

Set the currently active span to the implicit context. This is equivalent to getting the implicit context, then inserting the Span to the context.

opentelemetry-cpp/api/include/opentelemetry/trace/tracer.h

Line 143 in 5278e8c

static nostd::unique_ptr<Scope> WithActiveSpan(nostd::shared_ptr<Span> &span) noexcept

[lalitb]

Tracer

Create a new Span

opentelemetry-cpp/api/include/opentelemetry/trace/tracer.h

Line 36 in 5278e8c

virtual nostd::shared_ptr<Span> StartSpan(nostd::string_view name,

opentelemetry-cpp/sdk/src/trace/tracer.cc

Line 41 in 5278e8c

auto span = nostd::shared_ptr<trace_api::Span>{

Get active Span

opentelemetry-cpp/api/include/opentelemetry/trace/tracer.h

Line 153 in 5278e8c

static nostd::shared_ptr<Span> GetCurrentSpan() noexcept

Mark Span active

opentelemetry-cpp/api/include/opentelemetry/trace/tracer.h

Line 143 in 5278e8c

static nostd::unique_ptr<Scope> WithActiveSpan(nostd::shared_ptr<Span> &span) noexcept

Safe for concurrent calls

As context is thread-local, tracer API is safe for concurrent calls.

[lalitb]

SpanContext

IsValid - returns a boolean value, which is true if the SpanContext has a non-zero TraceID and a non-zero SpanID

opentelemetry-cpp/api/include/opentelemetry/trace/span_context.h

Line 65 in 5278e8c

bool IsValid() const noexcept { return trace_id_.IsValid() && span_id_.IsValid(); }

**IsRemote - that returns a boolean value, which is true if the SpanContext was propagated from a remote parent

opentelemetry-cpp/api/include/opentelemetry/trace/span_context.h

Line 95 in 5278e8c

bool IsRemote() const noexcept { return is_remote_; }

Conforms to the W3C TraceContext spec

This doesn't fully conforms to W3C TraceContext yet ( #74 )

SpanContexts are immutable.

SpanContext class doesn't provide any method to update the state of the object once created.

[lalitb]

Closing, as validation complete and created required tickets.