vendor/go.opencensus.io/trace/propagation/propagation.go

   1 // Copyright 2017, OpenCensus Authors
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6 //
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14
  15 // Package propagation implements the binary trace context format.
  16 package propagation // import "go.opencensus.io/trace/propagation"
  17
  18 // TODO: link to external spec document.
  19
  20 // BinaryFormat format:
  21 //
  22 // Binary value: <version_id><version_format>
  23 // version_id: 1 byte representing the version id.
  24 //
  25 // For version_id = 0:
  26 //
  27 // version_format: <field><field>
  28 // field_format: <field_id><field_format>
  29 //
  30 // Fields:
  31 //
  32 // TraceId: (field_id = 0, len = 16, default = "0000000000000000") - 16-byte array representing the trace_id.
  33 // SpanId: (field_id = 1, len = 8, default = "00000000") - 8-byte array representing the span_id.
  34 // TraceOptions: (field_id = 2, len = 1, default = "0") - 1-byte array representing the trace_options.
  35 //
  36 // Fields MUST be encoded using the field id order (smaller to higher).
  37 //
  38 // Valid value example:
  39 //
  40 // {0, 0, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 1, 97,
  41 // 98, 99, 100, 101, 102, 103, 104, 2, 1}
  42 //
  43 // version_id = 0;
  44 // trace_id = {64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79}
  45 // span_id = {97, 98, 99, 100, 101, 102, 103, 104};
  46 // trace_options = {1};
  47
  48 import (
  49         "net/http"
  50
  51         "go.opencensus.io/trace"
  52 )
  53
  54 // Binary returns the binary format representation of a SpanContext.
  55 //
  56 // If sc is the zero value, Binary returns nil.
  57 func Binary(sc trace.SpanContext) []byte {
  58         if sc == (trace.SpanContext{}) {
  59                 return nil
  60         }
  61         var b [29]byte
  62         copy(b[2:18], sc.TraceID[:])
  63         b[18] = 1
  64         copy(b[19:27], sc.SpanID[:])
  65         b[27] = 2
  66         b[28] = uint8(sc.TraceOptions)
  67         return b[:]
  68 }
  69
  70 // FromBinary returns the SpanContext represented by b.
  71 //
  72 // If b has an unsupported version ID or contains no TraceID, FromBinary
  73 // returns with ok==false.
  74 func FromBinary(b []byte) (sc trace.SpanContext, ok bool) {
  75         if len(b) == 0 || b[0] != 0 {
  76                 return trace.SpanContext{}, false
  77         }
  78         b = b[1:]
  79         if len(b) >= 17 && b[0] == 0 {
  80                 copy(sc.TraceID[:], b[1:17])
  81                 b = b[17:]
  82         } else {
  83                 return trace.SpanContext{}, false
  84         }
  85         if len(b) >= 9 && b[0] == 1 {
  86                 copy(sc.SpanID[:], b[1:9])
  87                 b = b[9:]
  88         }
  89         if len(b) >= 2 && b[0] == 2 {
  90                 sc.TraceOptions = trace.TraceOptions(b[1])
  91         }
  92         return sc, true
  93 }
  94
  95 // HTTPFormat implementations propagate span contexts
  96 // in HTTP requests.
  97 //
  98 // SpanContextFromRequest extracts a span context from incoming
  99 // requests.
 100 //
 101 // SpanContextToRequest modifies the given request to include the given
 102 // span context.
 103 type HTTPFormat interface {
 104         SpanContextFromRequest(req *http.Request) (sc trace.SpanContext, ok bool)
 105         SpanContextToRequest(sc trace.SpanContext, req *http.Request)
 106 }
 107
 108 // TODO(jbd): Find a more representative but short name for HTTPFormat.