open-telemetry / opentelemetry-java Goto Github PK
View Code? Open in Web Editor NEWOpenTelemetry Java SDK
Home Page: https://opentelemetry.io
License: Apache License 2.0
OpenTelemetry Java SDK
Home Page: https://opentelemetry.io
License: Apache License 2.0
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.
@songy23 please make sure that the classes you modified allow access to the value using the decision from this issue.
OC has limited set of primitives, OT has more types even an object
There is one more use of match pattern in API. Needs to be replaced with getType
as well
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.
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?
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.
SpanData may need to have it's own resource associated with it
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()
.
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.
Consider to be removed:
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.
It is not clear how activate/deactivate relates to the underlying context propagation mechanism, given that they are separate.
See #15
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 ;)
Span
doesn't allow to set span.kind
. Confirm we OK with this and ok to ignore setting this tag in OT shim
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?
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.
Any proposal on this? Should we use Nop?
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
.
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.
In OT, Tracer
implements Closable
, which lets users flush pending Span
s and dispose related resources.
Is there any point against this for the new API? I don't see any, but let me know ;)
I am just curious if there was some consideration behind the put
name, and if so to document it here.
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
All Agreed
upon terminology must be implemented. Close each terminology ticket when this is complete.
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).
TODO: Mention this situation in the README.
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 {
Blog post: https://medium.com/opentracing/merging-opentracing-and-opencensus-f0fe9c7ca6f0
We hope to have the Java Alpha release ready by Kubecon Barcelona.
What's in the Alpha release?
We need this to have the OT bridge - related to #22 it seems to be ;)
Creating an issue to confirm that we can safely ignore setting error
status in SpanBuilder
.
In order to support a OT bridge, we need to support explicit, optional values for start/end timestamp.
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:
Tracer
instance, used by code testing instrumentation logic.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 ;)
Once we are clear on design, do a production ready port of OpenCensus.
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:
I'm creating this issue to provide initial insight into the Context propagation design.
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:
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.Deque
for storing the Scope
objects (opposed to how this is done in OC/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).
This is not something we support in OT at the moment, and don't think many vendors support this underneath either.
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 ;)
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?
Sub. Also, should we ask for spanKind
in a constructor of a SpanBuilder
?
Do we need an explicit resource reference on Span
?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.