TC Review of Trace API / SDK

[jsuereth]

This tracks the status of the TC review for 1.0 Trace release of OpenTelemetry C++

Status

• Review Compliance Matrix
  • Traces
  • Baggage
  • Resource
  • Context Propagation
  • Environment Variables
  • Exporters
• Review Versioning and Stability policy enforcement
  • API
  • SDK
• Ensure Consistent names across implementation
• Avoid confusions across implementation (e.g. same public API has different behaviors)
• Ensure no experimental features (signals) are part of the released packages (e.g. api, sdk, etc.).

Open TODOs / Cleanups

• Determine whether baggage should "merge" with previous, or overwrite
• Limits (of all sorts) Should be configurable by users. The Specification (today) requires environment variables. This is somewhat critical for instrumentation author vs. operations divides where someone writing instrumentation may aggresively add labels and then operators need to deal with fallout of having too-many and needing to limit for performance (or stability) reasons.
  • Dropped items tracking and exporting #324
  • Limit attribute value types #323
  • Optional timestamp for add_event #322
  • Link count limit - attributes #321
  • Event count limit - attributes #320
  • Span count limits - events #319
  • Span count limits - attributes #318
  • Span count limit - links #317

Optional Cleanup TODOs

• Jaeger exporter should fast-follow GA. Looks like it can be added in a non-breaking way
• HTTP OTLP exporter retries.

See open-telemetry/opentelemetry-specification#1418 for process details.

[tsloughter]

Did a rundown of the compliance matrix and noted what I need to update and what we need to still do. I'm including everything here even though some we will not want to do before the 1.0 release.

I'll send a PR to the spec repo in the morning to update the matrix to mark the following as completed:

• TracerProvider:
  • ForceFlush
  • Shutdown
• Span Linking:
  • Links can be recorded on span creation
  • Link order is preserved
• Span exceptions:
  • RecordException
  • RecordException with extra parameters
• SpanProcessor ForceFlush
• Composite Propagator
• Environment variables:
  • OTEL_EXPORTER_OTLP_*
• Exporter:
  • ForceFlush

For what is still not done in the matrix there is a mix of what should be done before 1.0 and what we can probably wait to do after, but I'm not positive about each.

What we should probably get done:

• Simple Span Processor
• IdGenerators
• Size limits:
  • events collection size limit
  • attribute collection size limit
  • links collection size limit
• SpanLimits
• Attribute Limits
• Environment Variables:
  • =OTEL_SERVICE_NAME=
  • =OTEL_EXPORTER_ZIPKIN_*=
  • limits
• Schema URL
• Resource detectors populate Schema URL]

All the exporter ones can probably wait, though I have already started on some rework of the exporter that will make some of it easier.

• Exporter:
  • OTLP/HTTP JSON Protobuf Exporter
  • OTLP/HTTP gzip Content-Encoding support
  • Concurrent sending
  • Honors retryable responses with backoff
  • Honors non-retryable responses
  • Honors throttling response
  • Multi-destination spec compliance
    • This works for grpc already
  • SchemaURL in ResourceSpans and InstrumentationLibrarySpans
  • Zipkin:
    • InstrumentationLibrary mapping
    • Error Status mapping
    • Integer microseconds in timestamps
  • Jaeger

[bryannaegele]

Just doing some organization over to issues.

1.0 GA Items

• Simple Span Processor
• IdGenerators
• Size limits:
  • events collection size limit
  • attribute collection size limit
  • links collection size limit
• SpanLimits
• Attribute Limits
• Environment Variables:
  • =OTEL_SERVICE_NAME=
• Schema URL
• Resource detectors populate Schema URL
• Tracer:
  • Get by version with optional schema?

Post 1.0 GA Items - Exporters

• OTLP/HTTP JSON Protobuf Exporter
• OTLP/HTTP gzip Content-Encoding support
• Concurrent sending
• Honors retryable responses with backoff
• Honors non-retryable responses
• Honors throttling response
• Multi-destination spec compliance
  • grpc
• SchemaURL in ResourceSpans and InstrumentationLibrarySpans
• Zipkin:
  • Env variable: =OTEL_EXPORTER_ZIPKIN_*=
  • InstrumentationLibrary mapping
  • Error Status mapping
  • Integer microseconds in timestamps
• Jaeger

[tsloughter]

I've been procrastinating on limits again because they are a little annoying.

They are yet another global configuration that I guess I have to shove in a persistent term to be read every time a span operation is done.

I wish these, like a number of other things (like propagators, which won't be configurable per-library like other stuff if Tracers become configurable per instrumentation library) were just part of the Tracer and modifying Spans went through the Tracer, but they aren't.

But I will knock it out this week I guess.

[jsuereth]

AFAIK - span limits don't need to change post-startup. Is that an expectation in erlang?

[bryannaegele]

Nah. We just have no limits at all right now

[tsloughter]

Closing, 1.0 was released a month ago. Thanks everyone!