1
0
mirror of https://github.com/open-telemetry/opentelemetry-go.git synced 2024-12-14 10:13:10 +02:00
opentelemetry-go/api/trace/span_context.go

198 lines
5.1 KiB
Go
Raw Normal View History

// Copyright The OpenTelemetry Authors
2019-07-01 21:17:50 +02:00
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package trace
2019-07-01 21:17:50 +02:00
import (
"bytes"
"encoding/hex"
"encoding/json"
2019-07-01 21:17:50 +02:00
)
const (
Fix B3 propagator and add tests (#882) * Correct B3 propagators and add tests * Break up external integration and internal unit tests * Add changes to Changelog. * Update Changelog with PR number * Fix lint issues * Update trace flags Add a new "not sampled" mask to complement the existing "sampled" one. Rename `FlagsUnused` to `FlagsUnset`. Add documentation for each of the flags to help understand their purpose. * Update extractSingle to support unset sampling * Update existing tests to appropriately use FlagsUnset * Remove bogus debug flag test The B3 specification states "Debug is encoded as `X-B3-Flags: 1`. Absent or any other values can be ignored", so testing of other values should not result in an error. * B3 Extract now supports parsing both headers Remove test cases that would fail if the fallback header format was expected to not be used. * Feedback * Switch to bitmask inject encoding field Add the B3Encoding and valid HTTP based values. Change the B3 propagator to use these bitmask fields to specify the inject encoding it will propagate. * Add comments * Migrate B3 integration tests to existing testtrace * Update comment * Benchmark invalid B3 injects as well * Update trace flags Add a FlagsDebug and FlagsDeferred to track the B3 trace state. Add helper methods to the SpanContext to check the debug and deferred bit of the trace flags. Update SpanContext.IsSampled to return if the sampling decision is to sample rather than if the sample bit is set. This means that if the debug bit is also set it will return true. * Revert SpanContext.IsSampled back * Add comment to b3 test data generation * Update Changelog * Fix trace flag name in Changelog * Fix Changelog formatting * Update Changelog * Remove valid check at start of B3 injectg This check makes sample only headers not propagate. * Update B3 inject integration tests Use the passed SpanContext and check directly the span ID. * Update B3 integration tests Run update checked SpanID to match sent. Add tests to validate sample only transmissions and debug flag support. * Rename injectTest parentSc to sc This is no longer the parent. * Update GetAllKeys for B3 * Un-Export the B3 headers The B3SingleHeader name will conflict with the upcoming change to prefix the SingleHeader encoding with "B3". There are a few options to address this conflict, but in the end we do not need to be exporting these values. They are duplicates of the OpenZipkin package and users should use those. * Rename B3 encodings and move support method to B3Encoding Include a `B3` prefix to scope the encoding names. Move the related support method to the B3Encoding itself, instead of the B3 propagator. Add tests to provide a sanity check for encoding bitmasks. * Update span_context_test tests Update test name to better describe how unused bits have no affect on the sampling decision. Include the inverse of this test as well: not sampled but has unused bits. * Use named const for Single Header decoding widths * Update api/trace/b3_propagator.go Co-authored-by: Anthony Mirabella <a9@aneurysm9.com> Co-authored-by: Anthony Mirabella <a9@aneurysm9.com>
2020-07-08 01:38:52 +02:00
// FlagsSampled is a bitmask with the sampled bit set. A SpanContext
// with the sampling bit set means the span is sampled.
FlagsSampled = byte(0x01)
// FlagsDeferred is a bitmask with the deferred bit set. A SpanContext
// with the deferred bit set means the sampling decision has been
// defered to the receiver.
FlagsDeferred = byte(0x02)
// FlagsDebug is a bitmask with the debug bit set.
FlagsDebug = byte(0x04)
ErrInvalidHexID errorConst = "trace-id and span-id can only contain [0-9a-f] characters, all lowercase"
ErrInvalidTraceIDLength errorConst = "hex encoded trace-id must have length equals to 32"
ErrNilTraceID errorConst = "trace-id can't be all zero"
ErrInvalidSpanIDLength errorConst = "hex encoded span-id must have length equals to 16"
ErrNilSpanID errorConst = "span-id can't be all zero"
)
type errorConst string
func (e errorConst) Error() string {
return string(e)
}
// ID is a unique identity of a trace.
type ID [16]byte
var nilTraceID ID
var _ json.Marshaler = nilTraceID
// IsValid checks whether the trace ID is valid. A valid trace ID does
// not consist of zeros only.
func (t ID) IsValid() bool {
return !bytes.Equal(t[:], nilTraceID[:])
}
// MarshalJSON implements a custom marshal function to encode TraceID
// as a hex string.
func (t ID) MarshalJSON() ([]byte, error) {
return json.Marshal(t.String())
}
// String returns the hex string representation form of a TraceID
func (t ID) String() string {
return hex.EncodeToString(t[:])
}
// SpanID is a unique identify of a span in a trace.
type SpanID [8]byte
var nilSpanID SpanID
var _ json.Marshaler = nilSpanID
// IsValid checks whether the span ID is valid. A valid span ID does
// not consist of zeros only.
func (s SpanID) IsValid() bool {
return !bytes.Equal(s[:], nilSpanID[:])
}
// MarshalJSON implements a custom marshal function to encode SpanID
// as a hex string.
func (s SpanID) MarshalJSON() ([]byte, error) {
return json.Marshal(s.String())
}
// String returns the hex string representation form of a SpanID
func (s SpanID) String() string {
return hex.EncodeToString(s[:])
}
// IDFromHex returns a TraceID from a hex string if it is compliant
// with the w3c trace-context specification.
// See more at https://www.w3.org/TR/trace-context/#trace-id
func IDFromHex(h string) (ID, error) {
t := ID{}
if len(h) != 32 {
return t, ErrInvalidTraceIDLength
}
if err := decodeHex(h, t[:]); err != nil {
return t, err
}
if !t.IsValid() {
return t, ErrNilTraceID
}
return t, nil
}
// SpanIDFromHex returns a SpanID from a hex string if it is compliant
// with the w3c trace-context specification.
// See more at https://www.w3.org/TR/trace-context/#parent-id
func SpanIDFromHex(h string) (SpanID, error) {
s := SpanID{}
if len(h) != 16 {
return s, ErrInvalidSpanIDLength
}
if err := decodeHex(h, s[:]); err != nil {
return s, err
}
if !s.IsValid() {
return s, ErrNilSpanID
}
return s, nil
}
func decodeHex(h string, b []byte) error {
for _, r := range h {
switch {
case 'a' <= r && r <= 'f':
continue
case '0' <= r && r <= '9':
continue
default:
return ErrInvalidHexID
}
}
decoded, err := hex.DecodeString(h)
if err != nil {
return err
}
2019-11-18 20:47:04 +02:00
copy(b, decoded)
return nil
}
// SpanContext contains basic information about the span - its trace
// ID, span ID and trace flags.
2019-07-01 21:17:50 +02:00
type SpanContext struct {
TraceID ID
SpanID SpanID
TraceFlags byte
2019-07-01 21:17:50 +02:00
}
// EmptySpanContext is meant for internal use to return invalid span
// context during error conditions.
func EmptySpanContext() SpanContext {
return SpanContext{}
}
2019-07-01 21:17:50 +02:00
// IsValid checks if the span context is valid. A valid span context
// has a valid trace ID and a valid span ID.
func (sc SpanContext) IsValid() bool {
return sc.HasTraceID() && sc.HasSpanID()
}
// HasTraceID checks if the span context has a valid trace ID.
2019-07-01 21:17:50 +02:00
func (sc SpanContext) HasTraceID() bool {
return sc.TraceID.IsValid()
2019-07-01 21:17:50 +02:00
}
// HasSpanID checks if the span context has a valid span ID.
2019-07-01 21:17:50 +02:00
func (sc SpanContext) HasSpanID() bool {
return sc.SpanID.IsValid()
2019-07-01 21:17:50 +02:00
}
Fix B3 propagator and add tests (#882) * Correct B3 propagators and add tests * Break up external integration and internal unit tests * Add changes to Changelog. * Update Changelog with PR number * Fix lint issues * Update trace flags Add a new "not sampled" mask to complement the existing "sampled" one. Rename `FlagsUnused` to `FlagsUnset`. Add documentation for each of the flags to help understand their purpose. * Update extractSingle to support unset sampling * Update existing tests to appropriately use FlagsUnset * Remove bogus debug flag test The B3 specification states "Debug is encoded as `X-B3-Flags: 1`. Absent or any other values can be ignored", so testing of other values should not result in an error. * B3 Extract now supports parsing both headers Remove test cases that would fail if the fallback header format was expected to not be used. * Feedback * Switch to bitmask inject encoding field Add the B3Encoding and valid HTTP based values. Change the B3 propagator to use these bitmask fields to specify the inject encoding it will propagate. * Add comments * Migrate B3 integration tests to existing testtrace * Update comment * Benchmark invalid B3 injects as well * Update trace flags Add a FlagsDebug and FlagsDeferred to track the B3 trace state. Add helper methods to the SpanContext to check the debug and deferred bit of the trace flags. Update SpanContext.IsSampled to return if the sampling decision is to sample rather than if the sample bit is set. This means that if the debug bit is also set it will return true. * Revert SpanContext.IsSampled back * Add comment to b3 test data generation * Update Changelog * Fix trace flag name in Changelog * Fix Changelog formatting * Update Changelog * Remove valid check at start of B3 injectg This check makes sample only headers not propagate. * Update B3 inject integration tests Use the passed SpanContext and check directly the span ID. * Update B3 integration tests Run update checked SpanID to match sent. Add tests to validate sample only transmissions and debug flag support. * Rename injectTest parentSc to sc This is no longer the parent. * Update GetAllKeys for B3 * Un-Export the B3 headers The B3SingleHeader name will conflict with the upcoming change to prefix the SingleHeader encoding with "B3". There are a few options to address this conflict, but in the end we do not need to be exporting these values. They are duplicates of the OpenZipkin package and users should use those. * Rename B3 encodings and move support method to B3Encoding Include a `B3` prefix to scope the encoding names. Move the related support method to the B3Encoding itself, instead of the B3 propagator. Add tests to provide a sanity check for encoding bitmasks. * Update span_context_test tests Update test name to better describe how unused bits have no affect on the sampling decision. Include the inverse of this test as well: not sampled but has unused bits. * Use named const for Single Header decoding widths * Update api/trace/b3_propagator.go Co-authored-by: Anthony Mirabella <a9@aneurysm9.com> Co-authored-by: Anthony Mirabella <a9@aneurysm9.com>
2020-07-08 01:38:52 +02:00
// isDeferred returns if the deferred bit is set in the trace flags.
func (sc SpanContext) isDeferred() bool {
return sc.TraceFlags&FlagsDeferred == FlagsDeferred
}
// isDebug returns if the debug bit is set in the trace flags.
func (sc SpanContext) isDebug() bool {
return sc.TraceFlags&FlagsDebug == FlagsDebug
}
// IsSampled returns if the sampling bit is set in the trace flags.
func (sc SpanContext) IsSampled() bool {
Fix B3 propagator and add tests (#882) * Correct B3 propagators and add tests * Break up external integration and internal unit tests * Add changes to Changelog. * Update Changelog with PR number * Fix lint issues * Update trace flags Add a new "not sampled" mask to complement the existing "sampled" one. Rename `FlagsUnused` to `FlagsUnset`. Add documentation for each of the flags to help understand their purpose. * Update extractSingle to support unset sampling * Update existing tests to appropriately use FlagsUnset * Remove bogus debug flag test The B3 specification states "Debug is encoded as `X-B3-Flags: 1`. Absent or any other values can be ignored", so testing of other values should not result in an error. * B3 Extract now supports parsing both headers Remove test cases that would fail if the fallback header format was expected to not be used. * Feedback * Switch to bitmask inject encoding field Add the B3Encoding and valid HTTP based values. Change the B3 propagator to use these bitmask fields to specify the inject encoding it will propagate. * Add comments * Migrate B3 integration tests to existing testtrace * Update comment * Benchmark invalid B3 injects as well * Update trace flags Add a FlagsDebug and FlagsDeferred to track the B3 trace state. Add helper methods to the SpanContext to check the debug and deferred bit of the trace flags. Update SpanContext.IsSampled to return if the sampling decision is to sample rather than if the sample bit is set. This means that if the debug bit is also set it will return true. * Revert SpanContext.IsSampled back * Add comment to b3 test data generation * Update Changelog * Fix trace flag name in Changelog * Fix Changelog formatting * Update Changelog * Remove valid check at start of B3 injectg This check makes sample only headers not propagate. * Update B3 inject integration tests Use the passed SpanContext and check directly the span ID. * Update B3 integration tests Run update checked SpanID to match sent. Add tests to validate sample only transmissions and debug flag support. * Rename injectTest parentSc to sc This is no longer the parent. * Update GetAllKeys for B3 * Un-Export the B3 headers The B3SingleHeader name will conflict with the upcoming change to prefix the SingleHeader encoding with "B3". There are a few options to address this conflict, but in the end we do not need to be exporting these values. They are duplicates of the OpenZipkin package and users should use those. * Rename B3 encodings and move support method to B3Encoding Include a `B3` prefix to scope the encoding names. Move the related support method to the B3Encoding itself, instead of the B3 propagator. Add tests to provide a sanity check for encoding bitmasks. * Update span_context_test tests Update test name to better describe how unused bits have no affect on the sampling decision. Include the inverse of this test as well: not sampled but has unused bits. * Use named const for Single Header decoding widths * Update api/trace/b3_propagator.go Co-authored-by: Anthony Mirabella <a9@aneurysm9.com> Co-authored-by: Anthony Mirabella <a9@aneurysm9.com>
2020-07-08 01:38:52 +02:00
return sc.TraceFlags&FlagsSampled == FlagsSampled
}