open-telemetry / opentelemetry-java

OpenTelemetry Java SDK

OpenTelemetry Java

Project Status

See Java status on OpenTelemetry.io.

Getting Started

If you are looking for an all-in-one, easy-to-install auto-instrumentation javaagent, see opentelemetry-java-instrumentation.

If you are looking for examples on how to use the OpenTelemetry API to write your own manual instrumentation, or how to set up the OpenTelemetry Java SDK, see Manual instrumentation. Fully-functional examples are available in opentelemetry-java-examples.

If you are looking for generated classes for the OpenTelemetry semantic conventions, see semantic-conventions-java.

For a general overview of OpenTelemetry, visit opentelemetry.io.

Would you like to get involved with the project? Read our contributing guide. We welcome contributions!

Contacting us

We hold regular meetings. See details at community page.

We use GitHub Discussions for support or general questions. Feel free to drop us a line.

We are also present in the #otel-java channel in the CNCF slack. Please join us for more informal discussions.

To report a bug, or request a new feature, please open an issue.

Overview

OpenTelemetry is the merging of OpenCensus and OpenTracing into a single project.

This project contains the following top level components:

• OpenTelemetry API:
  • stable apis including Tracer, Span, SpanContext, Meter, and Baggage.
  • context api The OpenTelemetry Context implementation.
  • incubating apis incubating APIs, including Events.
• extensions define additional API extensions not part of the core API, including propagators.
• sdk defines the implementation of the OpenTelemetry API.
• exporters trace, metric, and log exporters for the SDK.
• sdk-extensions defines additional SDK extensions, which are not part of the core SDK.
• OpenTracing shim defines a bridge layer from OpenTracing to the OpenTelemetry API.
• OpenCensus shim defines a bridge layer from OpenCensus to the OpenTelemetry API.

This project publishes a lot of artifacts, listed in releases. opentelemetry-bom (BOM = Bill of Materials) is provided to assist with synchronizing versions of dependencies. opentelemetry-bom-alpha provides the same function for unstable artifacts. See published releases for instructions on using the BOMs.

We would love to hear from the larger community: please provide feedback proactively.

Requirements

Unless otherwise noted, all published artifacts support Java 8 or higher. See language version compatibility for complete details.

Android Disclaimer: For compatibility reasons, library desugaring must be enabled.

See CONTRIBUTING.md for additional instructions for building this project for development.

Note about extensions

Both API and SDK extensions consist of various additional components which are excluded from the core artifacts to keep them from growing too large.

We still aim to provide the same level of quality and guarantee for them as for the core components. Please don't hesitate to use them if you find them useful.

Project setup and contributing

Please refer to the contribution guide on how to set up for development and contribute!

Published Releases

Published releases are available on maven central. We strongly recommend using our published BOM to keep all dependency versions in sync.

Maven

<project>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-bom</artifactId>
        <version>1.40.0</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
    </dependency>
  </dependencies>
</project>

Gradle

dependencies {
  implementation platform("io.opentelemetry:opentelemetry-bom:1.40.0")
  implementation('io.opentelemetry:opentelemetry-api')
}

Note that if you want to use any artifacts that have not fully stabilized yet (such as the prometheus exporter, then you will need to add an entry for the Alpha BOM as well, e.g.

dependencies {
  implementation platform("io.opentelemetry:opentelemetry-bom:1.40.0")
  implementation platform('io.opentelemetry:opentelemetry-bom-alpha:1.40.0-alpha')

  implementation('io.opentelemetry:opentelemetry-api')
  implementation('io.opentelemetry:opentelemetry-exporter-prometheus')
  implementation('io.opentelemetry:opentelemetry-sdk-extension-autoconfigure')
}

Snapshots

Snapshots based out the main branch are available for opentelemetry-api, opentelemetry-sdk and the rest of the artifacts. We strongly recommend using our published BOM to keep all dependency versions in sync.

Maven

<project>
  <repositories>
    <repository>
      <id>oss.sonatype.org-snapshot</id>
      <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    </repository>
  </repositories>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-bom</artifactId>
        <version>1.41.0-SNAPSHOT</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
    </dependency>
  </dependencies>
</project>

Gradle

repositories {
    maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
}

dependencies {
  implementation platform("io.opentelemetry:opentelemetry-bom:1.41.0-SNAPSHOT")
  implementation('io.opentelemetry:opentelemetry-api')
}

Libraries will usually only need opentelemetry-api, while applications will want to use the opentelemetry-sdk module which contains our standard implementation of the APIs.

Gradle composite builds

For opentelemetry-java developers that need to test the latest source code with another project, composite builds can be used as an alternative to publishToMavenLocal. This requires some setup which is explained here.

Releases

See the VERSIONING.md document for our policies for releases and compatibility guarantees.

Check out information about the latest release.

See the project milestones for details on upcoming releases. The dates and features described in issues and milestones are estimates, and subject to change.

The following tables describe the artifacts published by this project. To take a dependency, follow the instructions in Published Released to include the BOM, and specify the dependency as follows, replacing {{artifact-id}} with the value from the "Artifact ID" column:

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>{{artifact-id}}</artifactId>
</dependency>

  implementation('io.opentelemetry:{{artifact-id}}')

Bill of Material

Component	Description	Artifact ID	Version	Javadoc
Bill of Materials (BOM)	Bill of materials for stable artifacts	opentelemetry-bom	1.40.0	N/A
Alpha Bill of Materials (BOM)	Bill of materials for alpha artifacts	opentelemetry-bom-alpha	1.40.0-alpha	N/A

API

Component	Description	Artifact ID	Version	Javadoc
API	OpenTelemetry API, including metrics, traces, baggage, context	opentelemetry-api	1.40.0
API Incubator	API incubator, including pass through propagator, and extended tracer, and Event API	opentelemetry-api-incubator	1.40.0
Context API	OpenTelemetry context API	opentelemetry-context	1.40.0

API Extensions

Component	Description	Artifact ID	Version	Javadoc
Kotlin Extension	Context extension for coroutines	opentelemetry-extension-kotlin	1.40.0
Trace Propagators Extension	Trace propagators, including B3, Jaeger, OT Trace	opentelemetry-extension-trace-propagators	1.40.0

SDK

Component	Description	Artifact ID	Version	Javadoc
SDK	OpenTelemetry SDK, including metrics, traces, and logs	opentelemetry-sdk	1.40.0
Metrics SDK	OpenTelemetry metrics SDK	opentelemetry-sdk-metrics	1.40.0
Trace SDK	OpenTelemetry trace SDK	opentelemetry-sdk-trace	1.40.0
Log SDK	OpenTelemetry log SDK	opentelemetry-sdk-logs	1.40.0
SDK Common	Shared SDK components	opentelemetry-sdk-common	1.40.0
SDK Testing	Components for testing OpenTelemetry instrumentation	opentelemetry-sdk-testing	1.40.0

SDK Exporters

Component	Description	Artifact ID	Version	Javadoc
OTLP Exporters	OTLP gRPC & HTTP exporters, including traces, metrics, and logs	opentelemetry-exporter-otlp	1.40.0
OTLP Logging Exporters	Logging exporters in OTLP JSON encoding, including traces, metrics, and logs	opentelemetry-exporter-logging-otlp	1.40.0
OTLP Common	Shared OTLP components (internal)	opentelemetry-exporter-otlp-common	1.40.0
Logging Exporter	Logging exporters, including metrics, traces, and logs	opentelemetry-exporter-logging	1.40.0
Zipkin Exporter	Zipkin trace exporter	opentelemetry-exporter-zipkin	1.40.0
Prometheus Exporter	Prometheus metric exporter	opentelemetry-exporter-prometheus	1.40.0-alpha
Exporter Common	Shared exporter components (internal)	opentelemetry-exporter-common	1.40.0
OkHttp Sender	OkHttp implementation of HttpSender (internal)	opentelemetry-exporter-sender-okhttp	1.40.0
JDK Sender	Java 11+ native HttpClient implementation of HttpSender (internal)	opentelemetry-exporter-sender-jdk TODO: remove -alpha after release	1.40.0-alpha
gRPC ManagedChannel Sender	gRPC ManagedChannel implementation of GrpcSender (internal)	opentelemetry-exporter-sender-grpc-managed-channel	1.40.0

SDK Extensions

Component	Description	Artifact ID	Version	Javadoc
SDK Autoconfigure	Autoconfigure OpenTelemetry SDK from env vars, system properties, and SPI	opentelemetry-sdk-extension-autoconfigure	1.40.0
SDK Autoconfigure SPI	Service Provider Interface (SPI) definitions for autoconfigure	opentelemetry-sdk-extension-autoconfigure-spi	1.40.0
SDK Jaeger Remote Sampler Extension	Sampler which obtains sampling configuration from remote Jaeger server	opentelemetry-sdk-extension-jaeger-remote-sampler	1.40.0
SDK Incubator	SDK incubator, including YAML based view configuration, LeakDetectingSpanProcessor	opentelemetry-sdk-extension-incubator	1.40.0-alpha

Shims

Component	Description	Artifact ID	Version	Javadoc
OpenCensus Shim	Bridge opencensus metrics into the OpenTelemetry metrics SDK	opentelemetry-opencensus-shim	1.40.0-alpha
OpenTracing Shim	Bridge opentracing spans into the OpenTelemetry trace API	opentelemetry-opentracing-shim	1.40.0

Contributing

See CONTRIBUTING.md

Triagers:

• Gregor Zeitlinger, Grafana Labs

Find more about the triager role in community repository.

Approvers (@open-telemetry/java-approvers):

• Jason Plumb, Splunk
• Josh Suereth, Google
• Lauri Tulmin, Splunk
• Trask Stalnaker, Microsoft

Find more about the approver role in community repository.

Maintainers (@open-telemetry/java-maintainers):

• Jack Berg, New Relic
• John Watson, Verta.ai

Emeritus:

• Maintainer Bogdan Drutu
• Maintainer Carlos Alberto
• Approver Mateusz Rzeszutek

Find more about the maintainer role in community repository.

Thanks to all the people who have contributed

Made with contrib.rocks.

opentelemetry-java's Issues

Create README

Blog post: https://medium.com/opentracing/merging-opentracing-and-opencensus-f0fe9c7ca6f0

• Rough Timeline
• Links to Milestones
• Description of release

We hope to have the Java Alpha release ready by Kubecon Barcelona.

What's in the Alpha release?

• Abstract Interfaces for all major components
• Standard SDK that works out of the box
• OpenTracing Bridge
• OpenCensus Bridge

Sampling on the API and exporter layer

Based on previous feedback, some vendors wanted to have control of sampling at the exporter level - but sampling still exists at the API. I feel like we should probably do a clarification -for the users- on sampling at the api level AND (possible) sampling at the exporter level?

Also: for vendors subscribing to the API but not using the SDK, they might simply ignore the sampling info on our side.

(a possible action item is to have sampling with a default value specified by Tracer/Tracing, so each tracer provides the default API sampling decision).

Otherwise, we might revisit this item ;)

Remove all deprecations

API should not have anything deprecated as it's new:

  /**
   * Calculate mean on aggregated {@code MeasureValue}s.
   *
   * @since 0.1.0
   * @deprecated since 0.13, use {@link Distribution} instead.
   */
  @Immutable
  @AutoValue
  @Deprecated
  @AutoValue.CopyAnnotations
  public abstract static class Mean extends Aggregation {

confirm we can ignore span.kind after Span was created

Span doesn't allow to set span.kind. Confirm we OK with this and ok to ignore setting this tag in OT shim

Attributes in Links

This is not something we support in OT at the moment, and don't think many vendors support this underneath either.

Rename all occurrence of TagContext to TagMap.

Simplify SpanData

Consider to be removed:

• Has remote parent

Currently SpanData is written as a result of the default implementation for the Span (including notions like dropped events). Maybe we should simplify this and the SpanData defined in the API does not include dropped events, and in the SDK (default implementation) we use directly the protos which include the notion of dropped events.

Remove match pattern for stats

There is one more use of match pattern in API. Needs to be replaced with getType as well

Message Events

OT: Nothing like this exists.

OC: Defines this additional API.
Possible approaches:
Implement this is a specialized form of log/annotation (NOTE: Bogdan doesn’t like this. Might need to do further research of how this is handled underneath).
Keep this as an additional/separated API, but keep it abstract, so each Tracer implementation can choose whatever way to handle they want.
Do not expose it at the public level, but keep it as a OC specific feature.

Testing & `MockTracer`

In OT there is an in-memory Tracer instance called MockTracer (https://github.com/opentracing/opentracing-java/blob/master/opentracing-mock/src/main/java/io/opentracing/mock/MockTracer.java), used to test library instrumentation - essentially you provide a Tracer instance on which such instrumentation works.

Afterwards, finished Span objects can be checked (along with their operation name, tags, logs, etc), as shown in the OkHttp instrumentation: https://github.com/opentracing-contrib/java-okhttp/blob/master/opentracing-okhttp3/src/test/java/io/opentracing/contrib/okhttp3/AbstractOkHttpTest.java#L76

        MockTracer mockTracer = new MockTracer(new ThreadLocalScopeManager(), 
             MockTracer.Propagator.TEXT_MAP);
        ...
        List<MockSpan> mockSpans = mockTracer.finishedSpans();
        Assert.assertEquals(2, mockSpans.size());

        MockSpan networkSpan = mockSpans.get(0);
        Assert.assertEquals(8, networkSpan.tags().size());
        Assert.assertEquals(Tags.SPAN_KIND_CLIENT, 
                            networkSpan.tags().get(Tags.SPAN_KIND.getKey()));

The requirement then is to:

1. Obtain a Tracer instance, used by code testing instrumentation logic.
2. Later fetch information about the resulting Span objects - status overall.

My impression is that, yes, this could be achieved through a in-memory exporter - but I'm wondering how user-friendly that is.

Let me know ;)

Port OpenCensus to create the new SDK

Once we are clear on design, do a production ready port of OpenCensus.

Links vs. References

From: https://docs.google.com/document/d/1gOjNl7nYardzaQJVtJCFJUBUIOwssKN-r9IGyL7HCJc/edit#heading=h.bk2at8j2ubk8

Links and references are equivalent concepts, acting as edges to connect spans into a directed graph.
OT Reference

public final class References {
    public static final String CHILD_OF = "child_of";
    public static final String FOLLOWS_FROM = "follows_from";
}
SpanBuilder.addReference(String referenceType, SpanContext referencedContext);
OC Link
public abstract class Link {
  public enum Type {
    CHILD_LINKED_SPAN,
    PARENT_LINKED_SPAN
  }
  public static Link fromSpanContext(
      SpanContext context, Type type, Map<String, AttributeValue> attributes) {};
  public abstract TraceId getTraceId();
  public abstract SpanId getSpanId();
  public abstract Type getType();
  public abstract Map<String, AttributeValue> getAttributes();
}

Differences

OC Links can be added at any time; OT References must be added on Span creation.
Links can have Attributes; References cannot. (what is a link attribute?)
OC Link types are Child, Parent, and Unspecified; OT Reference types are ChildOf and FollowsFrom.

Proposed Resolutions
Only add References during Span start time
In order to support Zipkin’s reuse of spanID’s for client/server span pairs, OT only allows references to be added. Because Zipkin is an important tracing system, we feel it would be unfair to not support them. Unless we can resolve zipkin support without it, this is a requirement.

Update: ZipKin no longer requires this feature.
Questions
Does OC have plans for supporting Zipkin without this restriction?
Is the OC LinkTypeParent necessary or speculative? If necessary, what is the use case?
Would the OC team be fine with this restriction?
Would the OC team be fine with adding FollowsFrom?

span attributes "error" cannot be set in SpanBuilder

Creating an issue to confirm that we can safely ignore setting error status in SpanBuilder.

Resource reference on SpanData

SpanData may need to have it's own resource associated with it

Use ByteBuffer with Binary propagation instead of byte[]

I'm wondering what are the reasons to not use ByteBuffer with the Binary injection/extraction.

I'm thinking using ByteBuffer could be a nice thing to use (you can even wrap a byte[] with it), with all its range/limit capabilities (and potential re-use).

Set up CNCF CLA for this project

• If we want to move this codebase into the CNCF, committers need to sign a CLA
• Users can't sign a CLA because we're not in the CNCF yet
• So we cannot accept 3rd party PRs until the CNCF acceptance process is complete.
• Once we have a project name, github org, etc, we can start accepting PRs
• We can still accept comments and suggestions.

TODO: Mention this situation in the README.

I found that some libraries use Nop instead of Noop

Any proposal on this? Should we use Nop?

Names of resource env variables may be revisited

This may need to be re-visited:

https://github.com/bogdandrutu/openconsensus/blob/8535aabedcb0b5759047cdb2be2da285e9ca9279/api/src/main/java/openconsensus/resource/Resource.java#L44-L45

Allow update of Span name.

In order to support a bridge to OT, we need to allow Span's name to be updated.

The method that requires this, from the OT side, is Span.setOperationName().

Trace identifiers: strings vs. strongly typed

SpanContext
OT: SpanContext exposes Trace Identifiers as strings, hiding the native representation.

OC: SpanContext exposes the underneath Trace Identifiers implementation, as well as TraceState and sampling information.

Remove SpanBuilder.startScopedSpan()

As part of OT 0.32 we deprecated a few members (opentracing/opentracing-java#291 details the reasons to do this).

As part of this, I'd also like to see startScopedSpan() gone.

Spike a bridge from new interfaces to current OpenTracing interfaces

• the goal is backwards compatibility: prove that a new tracer – built only to support the new tracer interfaces – can consume existing OT instrumentation.
• The goal for the spike is to identify and understand any places where the new interface design will make backwards compatibility difficult.

Still many references to Open Census

Clean this up: https://github.com/bogdandrutu/openconsensus/search?p=2&q=OpenCensus&type=&utf8=%E2%9C%93

How does activate/deactivate relate to context propagation?

It is not clear how activate/deactivate relates to the underlying context propagation mechanism, given that they are separate.

Finalize design of new interfaces

Step 1

All issues labeled Terminology alignment must be marked as Agreed in order to close this issue.

Terminology: https://github.com/bogdandrutu/openconsensus/issues?q=is%3Aissue+is%3Aopen+label%3A%22Terminology+alignment%22

Step 2

All Agreed upon terminology must be implemented. Close each terminology ticket when this is complete.

Prior Research and Discussion

• https://docs.google.com/document/d/1helXkQkT8ZQm6kSB69465hL8trZ8k53knHOOB_bMK58/edit#
• https://docs.google.com/document/d/1ji0AjLNV1Mhc63GkK42dRAGoqmuPo5TrWuL4aPuTTYQ
• Java: https://docs.google.com/document/d/1gOjNl7nYardzaQJVtJCFJUBUIOwssKN-r9IGyL7HCJc/
• C#:
  https://docs.google.com/document/d/1O98St2QxwdwZuXJ1PhNGDni34K4C0mX6RYgTX6tDL8I
• Golang: https://docs.google.com/document/d/1OjSpMuF_-cLufVEEw2DGVqm2ZVyukhtmfpHeQ8NQU5Q/

Annotations vs. Logs

Annotations and logs are equivalents. However, annotations are more structured, with an explicit description field.
OT Log
public class Fields {
public static final String ERROR_KIND = "error.kind";
public static final String ERROR_OBJECT = "error.object";
// etc
}
Span.log(Map<String, ?> fields);
Span.log(long timestampMicroseconds, Map<String, ?> fields);
Span.log(long timestampMicroseconds, String event);

OC Annotation
public abstract class Annotation {
public static Annotation fromDescription(String description);
public static Annotation fromDescriptionAndAttributes(
String description, Map<String, AttributeValue> attributes);
public abstract String getDescription();
public abstract Map<String, AttributeValue> getAttributes();
}

TODO: what to do with the extra description field? How is it exported?

Link.Attributes limit is not enforced

SpanData uses Link class, same as Span. So getAttributes on Link returns the map of attributes and cannot return droppedAttributesCount. So the limit on number of allowed attributes in not enforced in runtime as for Span attributes and there is no way to express the fact that the number of attributes was limited when creating a SpanData.

What to do about GRPC context propagation?

Link: https://github.com/grpc/grpc-java/blob/master/context/src/main/java/io/grpc/Context.java

Currently, our context propagation package is embedded as a resource in gRPC. This does not result in all of gRPC becoming a dependency, but it is a surprising package name. It would be better if context propagation was removed from gRPC, so that it can be used by both projects without a strange looking dependency change.

Proposal:

• Continue to depend on GRPC in alpha.
• And then in beta, work with GRPC spin context propagation out into this project (or an independent repo).

API: Tags vs. Baggage

from https://docs.google.com/document/d/1WhmNrl7ZGBTYAyo23OjTW7IXj2G4AtsTcwv3Zieg2tk/edit#

OT: Tied to the Span, and part of SpanContext (which is immutable).

OC: Exist independently, can be propagated without a Span.
Possible approaches:
Have Baggage/Tags decoupled from the Span/SpanContext and have it stand independently (NOTE: this seems to be the path we will take).
Advantage: Simplicity, decoupling.
Disadvantage: Would need to provide a backwards layer for OT-compliant Tracers using the current approach.
Have Baggage/Tags moved to SpanContext.

Import MetricOptions which allows configuring Gauge and Cumulative APIs.

https://github.com/census-instrumentation/opencensus-java/blob/master/api/src/main/java/io/opencensus/metrics/MetricOptions.java.

Rename Tracer.withSpan() to something more meaningful

Tracer.withSpan(Span) sets the specified Span as the active/current instance - but personally I think the name is not meaningful enough.

Would it make sense to change it to Tracer.activateSpan() as we call it in OT? I'm open to alternatives too ;)

Bridge from the new SDK to current OT interfaces

• maintains backwards compatibility.
• allows for progressive adoption of new interfaces.

Match pattern for Attribute replacement

See #15

Tracer implementing Closable

In OT, Tracer implements Closable, which lets users flush pending Spans and dispose related resources.

Is there any point against this for the new API? I don't see any, but let me know ;)

Consistent Noop implementation

Currently for stats/tags we use a noop class that implements all the api vs in trace every class implements it's own noop. We should be consistent.

Should default for Span.Kind be Undefined or Client

Sub. Also, should we ask for spanKind in a constructor of a SpanBuilder?

Add Tracestate to Link

Interface vs Pure abstract class in the API

• Pros for Abstract
  • Keep backwards compatibility between the API and implementation.
• Cons for Abstract
  • No support for multiple inheritance.
  • Interfaces may be consider cleaner for API than abstract classes.

putAttribute vs. setAttribute

I am just curious if there was some consideration behind the put name, and if so to document it here.

Add HTTP text serializer API for TagMap.

OC Attributes vs. OT Tags

OC “Attributes” and OT “Tags” (not OC tags) are key value pairs used to decorate Spans with information.
OT Tag
public abstract class AbstractTag implements Tag {
public String getKey();
public abstract void set(Span span, T tagValue);
}
public class StringTag extends AbstractTag {
public StringTag(String key) {}

@Override
public void set(Span span, String tagValue) {}

}
OC Attribute
public abstract class AttributeValue {
public static AttributeValue stringAttributeValue(String stringValue);
public static AttributeValue booleanAttributeValue(boolean booleanValue);
public static AttributeValue longAttributeValue(long longValue);
public static AttributeValue doubleAttributeValue(double doubleValue);
public abstract T match(
Function<? super String, T> stringFunction,
Function<? super Boolean, T> booleanFunction,
Function<? super Long, T> longFunction,
Function<? super Double, T> doubleFunction,
Function<Object, T> defaultFunction);
}
abstract static class AttributeValueString extends AttributeValue {
abstract String getStringValue();
}
Differences
In OC, Spans, Annotations and Links can contain attributes. In OT, only Spans have Tags.
In OT, Tag objects are used as helpers to set a tag value, while in OC they are used as containers for boolean/string/double values.
Proposed Resolutions
Remove Attributes from Links
Alternatively, add tags to References. But we need to explain why they are important, how they are different from attributes on Spans, and what it means for tracers to support them, as opposed to just putting the tags on the spans.
Questions
Where do these attributes go when they are exported to various backends?

Support timestamp for Span.addEvent()

We need this to have the OT bridge - related to #22 it seems to be ;)

Context Propagation

I'm creating this issue to provide initial insight into the Context propagation design.

OT Tracers with custom propagation

One of the important questions has been what kind of custom propagation is done by Tracers. I reviewed DataDog. This is a simplified list of their extra needs:

• Need to provide events around Span operations (events after a Span has been activated or after it has been closed, for example).
• Need to do extra checks in order to either close or not the Span upon Scope being closed (similarly to how we do it for the ref-counting ScopeManager in opentracing-util). This checks are done on the actual Span underneath and its internal features.
• Stores a list of extra Context objects, which can be queried besides the TLS storage.
• Uses an actual Deque for storing the Scope objects (opposed to how this is done in OC/OT).

Tracers with bridges to OT

I reviewed Brave-Opentracing and found out it uses its very own context propagation layer. This one in turn is similar to the OC one, including the storage of the propagation layer exposed as a SPI component, in case the users wants to override it.

I quote the original feedback from Elastic, which also offers OT support as a bridge layer:

They have an existing context propagation mechanism in place, which doesn’t implement the OT interfaces, and hence bridges are built. This propagation mechanism is leveraged for their auto instrumentation mode too, and it co-exists with the manual mode (“mix and match mode” is called).

If Scope objects are created by an in-place propagation mechanism, they would be detached from the ones the auto agent creates.

Implementation wise, they use thread-local data, but they don’t use an implicit stack of Scope objects, but an explicit one (it keeps all the previously active Scope objects).

Do not throw SpanContextParseException upon extraction

Currently, the formats exposed by this API throw a SpanContextParseException upon extract() if the data is malformed - I think we should instead simply return null for this case.

Resource reference on Tracer

Resource reference on Span

Do we need an explicit resource reference on Span?

The stats/metrics getType pattern does not allow access to the value.

1. Decide if the right pattern is to have a getValueX on the super class or every sub-class implements a getValue and user has to convert the class to the sub-class.

@songy23 please make sure that the classes you modified allow access to the value using the decision from this issue.

Allow explicit start/end timestamp for Span

In order to support a OT bridge, we need to support explicit, optional values for start/end timestamp.

Rough port of OpenCensus for testing purposes

• Initial rough port of OC
• Review starting point
• Adjust terminology to match new terms for the new project

Attribute types

OC has limited set of primitives, OT has more types even an object