Compliance Matrix Validation for rel1.0.0 -Span

[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 to the non-compliant point below in the description.

Link: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.0.0/spec-compliance-matrix.md#traces

Span:

• Create root span.
• Create with default parent (active span)
• Create with parent from Context -> ( supports parent from SpanContext )
• No explicit parent Span/SpanContext allowed -> ( support explicit parent SpanContext )
• SpanProcessor.OnStart receives parent Context -> ( receives parent SpanConext )
• UpdateName
• User-defined start timestamp
• End
• End with timestamp
• IsRecording
• IsRecording becomes false after End
• Set status with StatusCode (Unset, Ok, Error
• Safe for concurrent calls
• events collection size limit Adding span collection limits #365
• attribute collection size limit Adding span collection limits #365
• links collection size limit Adding span collection limits #365

Span Attributes:

• SetAttribute
• Set order preserved
• String type
• Boolean type
• Double floating-point type
• Signed int64 type -> (reserved for future support - uint32, int32, uint64 )
• Array of primitives (homogeneous) -> (reserved for future support - uint32[], int32[], uint64[]. uint8[] )
• null values documented as invalid/undefined
• Unicode support for keys and string values -> ( using nostd::string_view)

Span Linking:

• Add Links
• Safe for concurrent calls

Span Events:

• Add Events
• Add order preserved
• Safe for concurrent calls

Span Exceptions:

• RecordException (Recording exception to Span #760)
• RecordException with extra parameters (Recording exception to Span #760)

Sampling:

• Allow samplers to modify tracestate
• ShouldSample gets full parent Context

Others:

• New Span ID created also for non-recording Spans
• Id Generators
• Span Limits ( Optional ) (Adding span collection limits #365)

[lalitb]

Span

Create root span

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

Line 77 in b4584ad

trace_id = tracer_->GetIdGenerator().GenerateTraceId();

Create with default parent (active span)

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

Lines 25 to 26 in b4584ad

	trace_api::SpanContext parent =
	options.parent.IsValid() ? options.parent : GetCurrentSpan()->GetContext();

Create with parent from Context

This needs clarification as the API expects parent SpanContext, and not the Context object,

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

Lines 69 to 73 in b4584ad

	if (parent_span_context.IsValid())
	{
	trace_id = parent_span_context.trace_id();
	parent_span_id = parent_span_context.span_id();
	is_parent_span_valid = true;

No explicit parent Span/SpanContext allowed

This needs clarification as the API expects parent SpanContext, and not the full parent Context,

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

Line 64 in b4584ad

SpanContext parent = SpanContext::GetInvalid();

SpanProcessor.OnStart receives parent Context

This needs clarification as it receives parent span_context:

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

Line 106 in b4584ad

tracer_->GetProcessor().OnStart(*recordable_, parent_span_context);

UpdateName

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

Line 164 in b4584ad

void Span::UpdateName(nostd::string_view name) noexcept

User-defined start timestamp

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

Line 103 in b4584ad

recordable_->SetStartTime(NowOr(options.start_system_time));

End

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

Line 174 in b4584ad

void Span::End(const trace_api::EndSpanOptions &options) noexcept

End with timestamp

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

Lines 75 to 79 in b4584ad

	struct EndSpanOptions
	{
	// Optionally sets the end time of a Span.
	common::SteadyTimestamp end_steady_time;
	};

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

Line 174 in b4584ad

void Span::End(const trace_api::EndSpanOptions &options) noexcept

IsRecording

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

Line 197 in b4584ad

bool Span::IsRecording() const noexcept

** IsRecording becomes false after End**

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

Line 194 in b4584ad

recordable_.reset();

Set status with StatusCode (Unset, Ok, Error
https://github.com/open-telemetry/opentelemetry-cpp/blob/b4584adeaae259df89b33af884c641e70a60a7cf/api/include/opentelemetry/trace/span.h#L35-40

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

Line 154 in b4584ad

void Span::SetStatus(opentelemetry::trace::StatusCode code, nostd::string_view description) noexcept

Safe for concurrent calls
All the methods of sdk::trace::Span are guarder with a mutex.

opentelemetry-cpp/sdk/src/trace/span.h

Line 55 in b4584ad

mutable std::mutex mu_;

events collection size limit

Not supported, as Span Limits is optional #365

attribute collection size limit

Not supported, as Span Limits is optional #365

links collection size limit

Not supported, as Span Limits is optional #365

[lalitb]

Span Attributes

SetAttribute

Attributes can be set as part of Span constructor, and through Span::SetAttribute() method:

opentelemetry-cpp/sdk/src/trace/span.h

Lines 31 to 32 in b4584ad

	void SetAttribute(nostd::string_view key,
	const opentelemetry::common::AttributeValue &value) noexcept override;

Set order preserved

attributes are passed to the exporter in the same order as set through Span::SetAttribute() function.

String type

opentelemetry-cpp/api/include/opentelemetry/common/attribute_value.h

Line 46 in b4584ad

nostd::span<const nostd::string_view>,

Boolean type

opentelemetry-cpp/api/include/opentelemetry/common/attribute_value.h

Line 35 in b4584ad

nostd::variant<bool,

Double floating-point type

opentelemetry-cpp/api/include/opentelemetry/common/attribute_value.h

Line 39 in b4584ad

double,

Signed int64 type

opentelemetry-cpp/api/include/opentelemetry/common/attribute_value.h

Lines 36 to 38 in b4584ad

	int32_t,
	int64_t,
	uint32_t,

opentelemetry-cpp/api/include/opentelemetry/common/attribute_value.h

Line 49 in b4584ad

uint64_t,

(reserved for future support uint32, int32, uint64).

Array of primitives (homogeneous)

opentelemetry-cpp/api/include/opentelemetry/common/attribute_value.h

Lines 41 to 46 in b4584ad

	nostd::span<const bool>,
	nostd::span<const int32_t>,
	nostd::span<const int64_t>,
	nostd::span<const uint32_t>,
	nostd::span<const double>,
	nostd::span<const nostd::string_view>,

opentelemetry-cpp/api/include/opentelemetry/common/attribute_value.h

Line 52 in b4584ad

nostd::span<const uint64_t>,

opentelemetry-cpp/api/include/opentelemetry/common/attribute_value.h

Line 55 in b4584ad

nostd::span<const uint8_t>>;

(reserved for future support - uint32[], int32[], uint64[]. uint8[] )

null values documented as invalid/undefined

null values are not possible

Unicode support for keys and string values

Both key and value are passed as nostd::string_view, and it is possible to pass the unicode (UTF-8) character streams through it. Thoght it won't be possible to find the size of unicode string, or also not possible to work at code-point level. Exorter need to read the sequence of characters, and handle them accordingly.

[lalitb]

Span Linking

Add Links

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

Lines 96 to 100 in b4584ad

	links.ForEachKeyValue([&](opentelemetry::trace::SpanContext span_context,
	const opentelemetry::common::KeyValueIterable &attributes) {
	recordable_->AddLink(span_context, attributes);
	return true;
	});

Safe for concurrent calls

Links are added as part of span creating, so it is safe for concurrent call

[lalitb]

Span Events

Add Events

https://github.com/open-telemetry/opentelemetry-cpp/blob/v0.6.0/sdk/src/trace/span.cc#L142

Add order preserved

sdk::trace::SpanData preservers order by storing Events in std::vector:

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

Line 262 in b4584ad

std::vector<SpanDataEvent> events_;

Each exporter handles order separately.

Safe for concurrent calls

mutex guard.

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

Lines 142 to 146 in b4584ad

	void Span::AddEvent(nostd::string_view name,
	SystemTimestamp timestamp,
	const opentelemetry::common::KeyValueIterable &attributes) noexcept
	{
	std::lock_guard<std::mutex> lock_guard{mu_};

[lalitb]

Record Exception

Not Supported ( #760 )

[lalitb]

Sampling:

Allow samplers to modify tracestate

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

Lines 40 to 47 in b4584ad

	struct SamplingResult
	{
	Decision decision;
	// A set of span Attributes that will also be added to the Span. Can be nullptr.
	std::unique_ptr<const std::map<std::string, opentelemetry::common::AttributeValue>> attributes;
	// The tracestate used by the span.
	nostd::shared_ptr<opentelemetry::trace::TraceState> trace_state;
	};

ShouldSample gets full parent Context

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

Lines 72 to 74 in b4584ad

	virtual SamplingResult ShouldSample(
	const trace_api::SpanContext &parent_context,
	trace_api::TraceId trace_id,

[lalitb]

Others

New Span ID created also for non-recording Spans

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

Lines 30 to 37 in b4584ad

	if (sampling_result.decision == Decision::DROP)
	{
	// Don't allocate a no-op span for every DROP decision, but use a static
	// singleton for this case.
	static nostd::shared_ptr<trace_api::Span> noop_span(
	new trace_api::NoopSpan{this->shared_from_this()});
	return noop_span;

Id Generators

https://github.com/open-telemetry/opentelemetry-cpp/blob/v0.6.0/sdk/include/opentelemetry/sdk/trace/id_generator.h

Span Limits ( Optional )

Not planned. #365