Merge branch 'master' into grpc-interceptor

api/core/doc.go

@@ -14,4 +14,7 @@
 
 // This package provides basic types used in OpenTelemetry - keys,
 // values, numbers and span contexts.
+//
+// See the api/key package for convenience functions for creating keys
+// and key-value pairs.
 package core // import "go.opentelemetry.io/otel/api/core"

api/core/key.go

@@ -139,6 +139,11 @@ func Uint(v uint) Value {
 }
 
 // Bool creates a KeyValue instance with a BOOL Value.
+//
+// If creating both key and a bool value at the same time, then
+// instead of calling core.Key(name).Bool(value) consider using a
+// convenience function provided by the api/key package -
+// key.Bool(name, value).
 func (k Key) Bool(v bool) KeyValue {
  return KeyValue{
  Key: k,
@@ -147,6 +152,11 @@ func (k Key) Bool(v bool) KeyValue {
 }
 
 // Int64 creates a KeyValue instance with an INT64 Value.
+//
+// If creating both key and an int64 value at the same time, then
+// instead of calling core.Key(name).Int64(value) consider using a
+// convenience function provided by the api/key package -
+// key.Int64(name, value).
 func (k Key) Int64(v int64) KeyValue {
  return KeyValue{
  Key: k,
@@ -155,6 +165,11 @@ func (k Key) Int64(v int64) KeyValue {
 }
 
 // Uint64 creates a KeyValue instance with a UINT64 Value.
+//
+// If creating both key and a uint64 value at the same time, then
+// instead of calling core.Key(name).Uint64(value) consider using a
+// convenience function provided by the api/key package -
+// key.Uint64(name, value).
 func (k Key) Uint64(v uint64) KeyValue {
  return KeyValue{
  Key: k,
@@ -163,6 +178,11 @@ func (k Key) Uint64(v uint64) KeyValue {
 }
 
 // Float64 creates a KeyValue instance with a FLOAT64 Value.
+//
+// If creating both key and a float64 value at the same time, then
+// instead of calling core.Key(name).Float64(value) consider using a
+// convenience function provided by the api/key package -
+// key.Float64(name, value).
 func (k Key) Float64(v float64) KeyValue {
  return KeyValue{
  Key: k,
@@ -171,6 +191,11 @@ func (k Key) Float64(v float64) KeyValue {
 }
 
 // Int32 creates a KeyValue instance with an INT32 Value.
+//
+// If creating both key and an int32 value at the same time, then
+// instead of calling core.Key(name).Int32(value) consider using a
+// convenience function provided by the api/key package -
+// key.Int32(name, value).
 func (k Key) Int32(v int32) KeyValue {
  return KeyValue{
  Key: k,
@@ -179,6 +204,11 @@ func (k Key) Int32(v int32) KeyValue {
 }
 
 // Uint32 creates a KeyValue instance with a UINT32 Value.
+//
+// If creating both key and a uint32 value at the same time, then
+// instead of calling core.Key(name).Uint32(value) consider using a
+// convenience function provided by the api/key package -
+// key.Uint32(name, value).
 func (k Key) Uint32(v uint32) KeyValue {
  return KeyValue{
  Key: k,
@@ -187,6 +217,11 @@ func (k Key) Uint32(v uint32) KeyValue {
 }
 
 // Float32 creates a KeyValue instance with a FLOAT32 Value.
+//
+// If creating both key and a float32 value at the same time, then
+// instead of calling core.Key(name).Float32(value) consider using a
+// convenience function provided by the api/key package -
+// key.Float32(name, value).
 func (k Key) Float32(v float32) KeyValue {
  return KeyValue{
  Key: k,
@@ -195,6 +230,11 @@ func (k Key) Float32(v float32) KeyValue {
 }
 
 // String creates a KeyValue instance with a STRING Value.
+//
+// If creating both key and a string value at the same time, then
+// instead of calling core.Key(name).String(value) consider using a
+// convenience function provided by the api/key package -
+// key.String(name, value).
 func (k Key) String(v string) KeyValue {
  return KeyValue{
  Key: k,
@@ -204,15 +244,25 @@ func (k Key) String(v string) KeyValue {
 
 // Int creates a KeyValue instance with either an INT32 or an INT64
 // Value, depending on whether the int type is 32 or 64 bits wide.
+//
+// If creating both key and an int value at the same time, then
+// instead of calling core.Key(name).Int(value) consider using a
+// convenience function provided by the api/key package -
+// key.Int(name, value).
 func (k Key) Int(v int) KeyValue {
  return KeyValue{
  Key: k,
  Value: Int(v),
  }
 }
 
-// Uint creates a KeyValue instance with either an UINT32 or an UINT64
+// Uint creates a KeyValue instance with either a UINT32 or a UINT64
 // Value, depending on whether the uint type is 32 or 64 bits wide.
+//
+// If creating both key and a uint value at the same time, then
+// instead of calling core.Key(name).Uint(value) consider using a
+// convenience function provided by the api/key package -
+// key.Uint(name, value).
 func (k Key) Uint(v uint) KeyValue {
  return KeyValue{
  Key: k,
@@ -226,62 +276,62 @@ func (k Key) Defined() bool {
 }
 
 // Type returns a type of the Value.
-func (v *Value) Type() ValueType {
+func (v Value) Type() ValueType {
  return v.vtype
 }
 
-// Bool returns the bool value. Make sure that the Value's type is
+// AsBool returns the bool value. Make sure that the Value's type is
 // BOOL.
-func (v *Value) AsBool() bool {
+func (v Value) AsBool() bool {
  return rawToBool(v.numeric)
 }
 
 // AsInt32 returns the int32 value. Make sure that the Value's type is
 // INT32.
-func (v *Value) AsInt32() int32 {
+func (v Value) AsInt32() int32 {
  return rawToInt32(v.numeric)
 }
 
 // AsInt64 returns the int64 value. Make sure that the Value's type is
 // INT64.
-func (v *Value) AsInt64() int64 {
+func (v Value) AsInt64() int64 {
  return rawToInt64(v.numeric)
 }
 
 // AsUint32 returns the uint32 value. Make sure that the Value's type
 // is UINT32.
-func (v *Value) AsUint32() uint32 {
+func (v Value) AsUint32() uint32 {
  return rawToUint32(v.numeric)
 }
 
 // AsUint64 returns the uint64 value. Make sure that the Value's type is
 // UINT64.
-func (v *Value) AsUint64() uint64 {
+func (v Value) AsUint64() uint64 {
  return rawToUint64(v.numeric)
 }
 
 // AsFloat32 returns the float32 value. Make sure that the Value's
 // type is FLOAT32.
-func (v *Value) AsFloat32() float32 {
+func (v Value) AsFloat32() float32 {
  return rawToFloat32(v.numeric)
 }
 
 // AsFloat64 returns the float64 value. Make sure that the Value's
 // type is FLOAT64.
-func (v *Value) AsFloat64() float64 {
+func (v Value) AsFloat64() float64 {
  return rawToFloat64(v.numeric)
 }
 
 // AsString returns the string value. Make sure that the Value's type
 // is STRING.
-func (v *Value) AsString() string {
+func (v Value) AsString() string {
  return v.stringly
 }
 
 type unknownValueType struct{}
 
 // AsInterface returns Value's data as interface{}.
-func (v *Value) AsInterface() interface{} {
+func (v Value) AsInterface() interface{} {
  switch v.Type() {
  case BOOL:
  return v.AsBool()
@@ -304,7 +354,7 @@ func (v *Value) AsInterface() interface{} {
 }
 
 // Emit returns a string representation of Value's data.
-func (v *Value) Emit() string {
+func (v Value) Emit() string {
  switch v.Type() {
  case BOOL:
  return strconv.FormatBool(v.AsBool())
@@ -328,7 +378,7 @@ func (v *Value) Emit() string {
 }
 
 // MarshalJSON returns the JSON encoding of the Value.
-func (v *Value) MarshalJSON() ([]byte, error) {
+func (v Value) MarshalJSON() ([]byte, error) {
  var jsonVal struct {
  Type string
  Value interface{}

api/core/key_test.go

@@ -15,12 +15,15 @@
 package core_test
 
 import (
+ "encoding/json"
  "testing"
  "unsafe"
 
  "github.com/google/go-cmp/cmp"
+ "github.com/stretchr/testify/require"
 
  "go.opentelemetry.io/otel/api/core"
+ "go.opentelemetry.io/otel/api/key"
 )
 
 func TestValue(t *testing.T) {
@@ -161,6 +164,19 @@ func TestDefined(t *testing.T) {
  }
 }
 
+func TestJSONValue(t *testing.T) {
+ var kvs interface{} = [2]core.KeyValue{
+ key.String("A", "B"),
+ key.Int64("C", 1),
+ }
+
+ data, err := json.Marshal(kvs)
+ require.NoError(t, err)
+ require.Equal(t,
+ `[{"Key":"A","Value":{"Type":"STRING","Value":"B"}},{"Key":"C","Value":{"Type":"INT64","Value":1}}]`,
+ string(data))
+}
+
 func TestEmit(t *testing.T) {
  for _, testcase := range []struct {
  name string

api/core/span_context.go

@@ -59,7 +59,12 @@ func (t TraceID) IsValid() bool {
 // MarshalJSON implements a custom marshal function to encode TraceID
 // as a hex string.
 func (t TraceID) MarshalJSON() ([]byte, error) {
- return json.Marshal(hex.EncodeToString(t[:]))
+ return json.Marshal(t.String())
+}
+
+// String returns the hex string representation form of a TraceID
+func (t TraceID) String() string {
+ return hex.EncodeToString(t[:])
 }
 
 // SpanID is a unique identify of a span in a trace.
@@ -77,7 +82,12 @@ func (s SpanID) IsValid() bool {
 // MarshalJSON implements a custom marshal function to encode SpanID
 // as a hex string.
 func (s SpanID) MarshalJSON() ([]byte, error) {
- return json.Marshal(hex.EncodeToString(s[:]))
+ return json.Marshal(s.String())
+}
+
+// String returns the hex string representation form of a SpanID
+func (s SpanID) String() string {
+ return hex.EncodeToString(s[:])
 }
 
 // TraceIDFromHex returns a TraceID from a hex string if it is compliant
@@ -169,18 +179,6 @@ func (sc SpanContext) HasSpanID() bool {
  return sc.SpanID.IsValid()
 }
 
-// SpanIDString returns a hex string representation of the span ID in
-// the span context.
-func (sc SpanContext) SpanIDString() string {
- return hex.EncodeToString(sc.SpanID[:])
-}
-
-// TraceIDString returns a hex string representation of the trace ID
-// in the span context.
-func (sc SpanContext) TraceIDString() string {
- return hex.EncodeToString(sc.TraceID[:])
-}
-
 // IsSampled check if the sampling bit in trace flags is set.
 func (sc SpanContext) IsSampled() bool {
  return sc.TraceFlags&traceFlagsBitMaskSampled == traceFlagsBitMaskSampled