Proposal: Instead of a global tracer singleton, every library needs to create it's own tracer, which also has a proper name that identifies the library/component that uses the tracer.

Motivation: "Configurability of library/component instrumentation"

• Identify the library/component that created a span
• Be able to turn the instrumentation of a certain library/component on/off. This might be necessary if the instrumentation
  • causes too much overhead
  • is buggy (e.g. does not call span.end in every case)
  • avoid "double-tracing". E.g. a tracing vendor (e.g. Dynatrace) might already have built-in auto-instrumentation for a certain library. In this case the vendor might want to decide (automatically or config-based) which of the implementations should be enabled/disabled.

Technically, this could be achieved similar to how logging frameworks deal with Loggers and LoggerFactories (log4j).

Tracer tracer = OpenConsensus.Tracing.getTracer("io.opensomething.contrib.mongo");

Every span would contain the information about the Tracer that it was created with. Based on that a span can be discarded or not.

Not sure how a naming convention could look like. Not sure if "component" is the right word, as it has already been used in the past as attribute name. At Dynatrace we call that a "Sensor". Not sure about granularity of "Tracers". Should every class have one? Should Tracing act as a registry (cache already created instances) or as a factory (just create new ones at every call)?

This is kind of related to the GlobalTracer discussion (#107).

Java repo was used to combine APIs from OpenTracing and OpenCensus.
Most of APIs are ready to be documented in a form of cross-language specification.

Resources API needs to be described

Current Issue:

• Tags in OpenTracing currently maps to Attributes in OpenTelemetry.
• Tags in OpenCensus are also slightly different: no getters, and they are only available for metrics.

There is a fair amount of evidence that using the name Tags to describe this package is confusing to existing users of the previous projects.

Potential names:

• Baggage
• Labels
• ???
• Live with Tags and confuse some people...

FAQ: What is the difference between Tags with TTL=0 and Context?

• If you put a value in Tags, that value is available via for OpenTelemetry to consume in metrics, traces, and logs. Context is purely for propagating application information within a single process: Context information not placed directly in Tags is not visible to the telemetry system.

Conclusion:

Currently, there is a preference for calling this Baggage.

• Users may want to propagate baggage for reasons beyond just labelling telemetry data. For example, feature flagging in a distributed system.
• The term Baggage helps indicate to users that they are bloating their RPC calls with this information, so they should be careful about what they put in there. The costs associated with using this mechanism is a very important thing for users to understand.

We are planning to go with Baggage for now. Please post questions and comments if you feel this name is not accurate.

Pros: Shorter

Describe the concept of adapters

As we discussed in census-instrumentation/opencensus-csharp#134 there are scenarios that require reading properties from the incomplete Spans. It is needed when one want to put Span properties into the tracestate for instance.

Some sort of looking inside the Span may need to be implemented on API level.

API vs SDK: This method should be implemented in the same layer as the callback that will be used. E.g. if the callback will be in API - hook cannot be relying on safe casting to SDK's Span object. Thus should be operating with API's interface of Span. If the hook is implemeted in SDK - then it's OK to only have this method on SDK's SpanSDK class.

CC: @discostu105

Current section about the Span doesn't say anything about the fact that is is an interface that may have an alternative implementation

From open-telemetry/opentelemetry-js#5

Span has a private tracer property, NoRecordSpan doesn't. I'd prefer to make tracer always available on Span like in OpenTracing. Coming from OpenTracing, I found it challenging not having tracer available on spans, especially that first I assumed it is and started to use it, then my code broke one NoRecordSpan(s).

@hekike, @rochdev

Describe from high-level tags concepts

See discussion: #14 (comment)

The proposal is to have a strongly-typed field on a span that will define its type and ultimately - the set of attributed one should expect to see on it and interpret.

The alternative is to have a predefined attribute name for this type.

This change should be driven by scenarios we plan to enable in OpenTelemetry that will use this field. For instance, a strongly typed field can be justified by a scenario like metrics extraction from the specific span types.

Can be taken from here: open-telemetry/opentelemetry-collector#9

First let me say I'm happy to see the combined efforts here, I'm a strong believer in the value added by this projects goals. The goal of this post is to get some clarification on some of the projects goals and design decisions. I have a lot of opinions on this area but for sake of productive discussion I want to focus on two key areas:

1. Defining a formal structural specification for trace events.
2. Declaring distinct events for things that require nesting child objects or holding buffers for any period of time.

The initial rough draft that I used to start the conversation in gitter can be found in this gist, it covers the two points above in more details. I'll be happy to fill this issue out with a more intelligible digest of the gist by request or once I have a better understanding of the projects direction.

Thanks a lot for the efforts being started here.

There should be some common description of the package structure. See open-telemetry/opentelemetry-js#6 for example of package structure discussion

Java repo was used to combine APIs from OpenTracing and OpenCensus.
Most of APIs are ready to be documented in a form of cross-language specification.

Metrics API needs to be described

The semantics of IsRecordingEvents is not only about recording events but also setting attributes.

Should it be called IsActive?

I can imagine scenarios where async operation may want to implement different behavior depending on whether the Span that started it up ended or nor. For instance, instead of adding Event to Span, report a separate Span. Or simply log information.

I hit this scenario in the following case:

Redis library in .NET allows to associate "session" with the current span. And there is a way to get all the redis operations happened in the "session". I need an indication that "session" has ended and span.HasEnded is a great way to check it.

Basically, any logic that requires to cache Span objects and then do some logic when Span in this cache ended would need this method.

API vs SDK: I need this on data collection module. So it will be great to have this method a part of API.

Ideally, both in-process and inter-process propagation should be a standalone module that can operate without the involvement of the Tracer.

Placeholder for more discussion.

Align on https://github.com/opentracing/specification/blob/master/semantic_conventions.md vs,

https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/HTTP.md
https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/gRPC.md
https://github.com/census-instrumentation/opencensus-specs/blob/master/resource/StandardResources.md

See open-telemetry/opentelemetry-java#325.

The random generation of the Trace/Span id will be in the SDK. Main reason is that for example to support Amazon X-Ray the TraceID needs to be a specific format for example, also that is an implementation detail.

The question is whether it is a requirement for SDK to allow custom ID generators.

Java repo was used to combine APIs from OpenTracing and OpenCensus.
Most of APIs are ready to be documented in a form of cross-language specification.

Tracing API needs to be described

Describe high-level resources terminilogy

Describe Status class and canonical codes

Java repo was used to combine APIs from OpenTracing and OpenCensus.
Most of APIs are ready to be documented in a form of cross-language specification.

Tags API needs to be described

In OpenTracing, we have CHILD_OF and FOLLOWS_FROM. In the new project, we are considering whether to include this concept as a flag on the SpanBuilder option when setting the span parent. The new naming is proposed to be sync and async children, to make the relationship more clear.

Reference PR: open-telemetry/opentelemetry-java#130

Questions:

• Do we still want this at all? It can be useful for critical path and other types of trace analysis.
• Do we also need an unknown flag as well?

Java repo was used to combine APIs from OpenTracing and OpenCensus.
Most of APIs are ready to be documented in a form of cross-language specification.

SpanBuilder and the ways to construct Span needs to be described

See open-telemetry/opentelemetry-java#347

Re-posting questions from open-telemetry/opentelemetry-java#226 (comment)

• in many other metrics APIs that allow recording gauges, timers, and/or histograms, the recording API is still about recording the raw measure, but behind the scene the library may or may not perform some form of aggregation, like LastValue for gauges, or Histogram for timers. So the distinction between raw measure and Gauge/Histogram is not clear to me, since from instrumentation point of view it's always recording the raw value.
• on the other hand, counters seem to be fundamentally different and can never be captured via raw measure, is that correct? This breaks the mental model for me.
• being able to change aggregation without touching instrumentation is great - I often wanted to see something like queue_length not as a gauge but as a histogram (incidentally tally didn't support histograms for non-timer values)
• application of request-scoped tags is also very tricky. As @bogdandrutu said, there are some stats that don't make sense to be labeled with request-scoped tags, e.g. CPU utilization. For measures where we do want to apply context tags, the ability to define views also provides a place to define context tag rules, potentially on a per-measure basis, e.g. "allow tags A and B for measureX, but only tag B for measure Y" (however, see next item).

Describe SpanContext properties

Document decisions made in Java repository: document processor API

Includes at least docs for:

• New APIs
• Changes from OC/OT
• Rationale

Current implementation of binary context inject/extract expects that entire SpanContext can be encoded in a single field:

https://github.com/bogdandrutu/openconsensus/blob/42f90bf8196cc1e3913510160cdfdc3995a7119d/api/src/main/java/openconsensus/context/propagation/BinaryFormat.java#L26-L33

However current proposal lists traceparent and tracestate as separate headers. See w3c/trace-context-binary#7 with the proposal to change it

Java repo was used to combine APIs from OpenTracing and OpenCensus.
Most of APIs are ready to be documented in a form of cross-language specification.

Tracing class construction needs to be described. Tracer for specific library. Global Tracer, etc.

Originates from open-telemetry/opentelemetry-java#337 (comment).

In Java we currently use:

We assume the lower 64 bits of the traceId's are randomly distributed around the whole (long)
range. We convert an incoming probability into an upper bound on that value, such that we can
just compare the absolute value of the id and the bound to see if we are within the desired
probability range. Using the low bits of the traceId also ensures that systems that only use 64
bit ID's will also work with this sampler.

Modules that can automatically collect telemetry from various technologies needs a common name consistent across the projects. How to name it:

Plugins? Instrumentation? AutoCollector? Other?

1. Define the list of propagation formats that the OpenTelemetry will officially support, proposal:
   • W3C for trace https://github.com/w3c/trace-context
   • W3c for tags/baggage https://github.com/w3c/correlation-context
   • B3, do we commit to support this?
   • Jaeger, do we commit to support this?
2. Where does the implementation for each format live?
   • In API?
   • In SDK?
   • In contrib?

A high-level description of metrics terminology.

Create a spec for the opentelemetry API and SDK in the style of opencensus-specs.

The spec should describe the opentelemetry java client as it's implemented now. Where the API isn't well defined (as in issues labeled "Agreement Required"), the spec should note this.

This spec isn't meant to be authoritative yet, it's just meant to help the authors of other opentelemetry clients as we finalize the API.

See discussion at open-telemetry/opentelemetry-js#4

See discussion here open-telemetry/opentelemetry-java#347

Java repo was used to combine APIs from OpenTracing and OpenCensus. Most of APIs are ready to be documented in a form of cross-language specification.

SpanData class and it's operations needs to be described

Document decisions made in Java repository: describe sampler API

Explain how the resources API is extended by SDK. Specifically:

• how resources can be associated with Span Protos
• how resoruces can be populated from environment variables

Move this document https://github.com/open-telemetry/opentelemetry-specification/blob/master/work_in_progress/specification/resource/Resource.md to the root folder

Proposal for trace:

1. OpenTelemetry exporter (decide if HTTP vs gRPC).
2. Jaeger exporter (decide if the new gRPC or Thrift).
3. Zipkin exporter (probably v2)

Proposal for metrics:

1. OpenTelemetry exporter (decide if HTTP vs gRPC).
2. Prometheus exporter.

Another question is, do we want to have these standard exporters in the SDK artifact/package?

In some cases some of the sidecar/load_balancer implementations will generate only one span between a client and a server spans. Do we want to have a kind that describes this case so that backends will know this is an rpc like client -> proxie -> server?