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. 109