From bdb0802536cd12cd74f2df4603416986c5755d37 Mon Sep 17 00:00:00 2001 From: tedsuo Date: Fri, 17 Aug 2018 11:29:37 -0700 Subject: [PATCH 1/3] Change method siganture to ToTraceID and ToSpanID * update reasoning * clarify alternate future methods --- rfc/trace_identifiers.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/rfc/trace_identifiers.md b/rfc/trace_identifiers.md index 93dd6af..a5fb540 100644 --- a/rfc/trace_identifiers.md +++ b/rfc/trace_identifiers.md @@ -3,7 +3,7 @@ **Current State:** Draft **Author:** [tedsuo](https://github.com/tedsuo) -The OpenTracing SpanContext interface is extended to include `SpanID` and `TraceID` accessors. +The OpenTracing `SpanContext` interface is extended to include `ToSpanID` and `ToTraceID` accessors. The OpenTracing model of computation specifies two primary object types, `Spans` and `Traces`, but does not specify identifiers for these objects. Identifiers for the two primary object types make it easier to correlate tracing data with data in other systems, simplify important tasks, and allow the creation of reusable trace observers. Some use cases are detailed below. @@ -33,8 +33,8 @@ The `SpanContext` section of the specification is extended to include the follow | method | format | description | | :--- | :--- | :--- | -| `TraceID` | string | Globally unique. Every span in a trace shares this ID. | -| `SpanID` | string | Unique within a trace. Each span within a trace contains a different ID. | +| `ToTraceID` | string | Globally unique. Every span in a trace shares this ID. | +| `ToSpanID` | string | Unique within a trace. Each span within a trace contains a different ID. | **String** values are used for identifiers. In this context, a string is defined as an immutable, variable length sequence of characters. The empty string is a valid return type. @@ -44,10 +44,18 @@ A string is preferred over other formats for the following reasons: * Backwards compatibility with pre-existing ID formats. * Strongly supported across many languages, and commonly used for transferring data between independent subsystems. -## Alternate Formats -In some cases, additional formats may be appropriate, if a language supports multiple common transport formats. Rather than manually converting the string value to another format, an additional accessors could be added to allow the tracer to do the conversion. +## Why `ToTraceID` instead of `TraceID`? -If tracing systems converge on common in-memory formats for Trace-Context identifiers, accessors may be added for those formats as well. +The method names `ToTraceID` and `ToSpanID` were chosen over `TraceID` and `SpanID` for two reasons: + +1) To avoid conflicts with tracer implementations, which often use `TraceID` and `SpanID` to expose their identifiers in their native format. +2) To communicate to the user that a format conversion may be occuring, and thus there may be some cost to calling these methods. + +## Future Formats +In some cases, additional formats may be appropriate, if a language supports multiple common transport formats. Two reasons for additional formats were identified: + +1) Avoiding double converstions. Rather than converting from a native format to a string value, and then directly into another format, an additional methods could be added to allow the tracer to do the conversion directly. +2) If tracing systems converge on common in-memory formats for Trace-Context identifiers, accessors may be added for those formats as well. ## Backwards Compatibility and Optional Support The OpenTracing specification does not currently require trace and span identifiers. To continue support for existing tracers, the empty string value can be returned when no ID has been set. From 312d90eb338a9ad6c433e060707f4344c039cd70 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Mon, 12 Nov 2018 10:43:20 -0600 Subject: [PATCH 2/3] typo --- rfc/trace_identifiers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/trace_identifiers.md b/rfc/trace_identifiers.md index a5fb540..a0e3383 100644 --- a/rfc/trace_identifiers.md +++ b/rfc/trace_identifiers.md @@ -54,7 +54,7 @@ The method names `ToTraceID` and `ToSpanID` were chosen over `TraceID` and `Span ## Future Formats In some cases, additional formats may be appropriate, if a language supports multiple common transport formats. Two reasons for additional formats were identified: -1) Avoiding double converstions. Rather than converting from a native format to a string value, and then directly into another format, an additional methods could be added to allow the tracer to do the conversion directly. +1) Avoiding double converstions. Rather than converting from a native format to a string value, and then directly into another format, an additional method could be added to allow the tracer to do the conversion directly. 2) If tracing systems converge on common in-memory formats for Trace-Context identifiers, accessors may be added for those formats as well. ## Backwards Compatibility and Optional Support From b362ba2f5a5e9d5caa0fcc81e1af3134e9330d96 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Mon, 12 Nov 2018 10:49:47 -0600 Subject: [PATCH 3/3] clarify future formats --- rfc/trace_identifiers.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rfc/trace_identifiers.md b/rfc/trace_identifiers.md index a0e3383..a5801b2 100644 --- a/rfc/trace_identifiers.md +++ b/rfc/trace_identifiers.md @@ -52,10 +52,10 @@ The method names `ToTraceID` and `ToSpanID` were chosen over `TraceID` and `Span 2) To communicate to the user that a format conversion may be occuring, and thus there may be some cost to calling these methods. ## Future Formats -In some cases, additional formats may be appropriate, if a language supports multiple common transport formats. Two reasons for additional formats were identified: +In some cases, additional identifier formats may be added, besides `string`. Two reasons for additional formats were identified: -1) Avoiding double converstions. Rather than converting from a native format to a string value, and then directly into another format, an additional method could be added to allow the tracer to do the conversion directly. -2) If tracing systems converge on common in-memory formats for Trace-Context identifiers, accessors may be added for those formats as well. +1) Avoiding double converstions. Rather than converting from a native format to a string value, and then directly into another format, an additional method could be added to allow the tracer to do the conversion directly. For example, using identifiers as byte arrays may turn out to be popular, and may incur an extra conversion cost from string. +2) If tracing systems converge on a common trace propagation format, such as [Trace-Context](https://github.com/w3c/trace-context), accessors may be added for that format as well. ## Backwards Compatibility and Optional Support The OpenTracing specification does not currently require trace and span identifiers. To continue support for existing tracers, the empty string value can be returned when no ID has been set.