Skip to content
This repository has been archived by the owner on May 23, 2023. It is now read-only.

Change method siganture to ToTraceID and ToSpanID #125

Merged
merged 3 commits into from
Nov 12, 2018
Merged

Change method siganture to ToTraceID and ToSpanID #125

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bdb0802
Change method siganture to ToTraceID and ToSpanID
tedsuo Aug 17, 2018
312d90e
typo
tedsuo Nov 12, 2018
b362ba2
clarify future formats
tedsuo Nov 12, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 14 additions & 6 deletions rfc/trace_identifiers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand All @@ -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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changing the header from "alternate" to "future" seems to say "we may add other methods to the official spec in the future for these reasons" rather than just "current tracing implementations may have other methods for these reasons". Was that your intention? If so, we could say so more explicitly.

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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/methods/method

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.
Expand Down