New api/label package, common label set impl

api/label/encoder.go

@@ -0,0 +1,147 @@
+// Copyright The OpenTelemetry Authors
+//
+// 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 label
+
+import (
+	"bytes"
+	"sync"
+	"sync/atomic"
+
+	"go.opentelemetry.io/otel/api/core"
+)
+
+type (
+	// Encoder is a mechanism.
+	Encoder interface {
+		// Encode is called (concurrently) in instrumentation context.
+		//
+		// The expectation is that when setting up an export pipeline
+		// both the batcher and the exporter will use the same label
+		// encoder to avoid the duplicate computation of the encoded
+		// labels in the export path.
+		Encode(Iterator) string
+
+		// ID returns a value that is unique for each class of
+		// label encoder.  Label encoders allocate these using
+		// `NewEncoderID`.
+		ID() EncoderID
+	}
+
+	// EncoderID
+	EncoderID struct {
+		value int64
+	}
+
+	defaultLabelEncoder struct {
+		// pool is a pool of labelset builders.  The buffers in this
+		// pool grow to a size that most label encodings will not
+		// allocate new memory.
+		pool sync.Pool // *bytes.Buffer
+	}
+)
+
+// escapeChar is used to ensure uniqueness of the label encoding where
+// keys or values contain either '=' or ','.  Since there is no parser
+// needed for this encoding and its only requirement is to be unique,
+// this choice is arbitrary.  Users will see these in some exporters
+// (e.g., stdout), so the backslash ('\') is used a conventional choice.
+const escapeChar = '\\'
+
+var (
+	_ Encoder = &defaultLabelEncoder{}
+
+	// labelEncoderIDCounter is for generating IDs for other label
+	// encoders.
+	encoderIDCounter int64 = 1
+
+	defaultEncoderOnce     sync.Once
+	defaultEncoderID       = NewEncoderID()
+	defaultEncoderInstance *defaultLabelEncoder
+)
+
+// NewEncoderID returns a unique label encoder ID. It should be
+// called once per each type of label encoder. Preferably in init() or
+// in var definition.
+func NewEncoderID() EncoderID {
+	return EncoderID{value: atomic.AddInt64(&encoderIDCounter, 1)}
+}
+
+// DefaultEncoder returns a label encoder that encodes labels
+// in such a way that each escaped label's key is followed by an equal
+// sign and then by an escaped label's value. All key-value pairs are
+// separated by a comma.
+//
+// Escaping is done by prepending a backslash before either a
+// backslash, equal sign or a comma.
+func DefaultEncoder() Encoder {
+	defaultEncoderOnce.Do(func() {
+		defaultEncoderInstance = &defaultLabelEncoder{
+			pool: sync.Pool{
+				New: func() interface{} {
+					return &bytes.Buffer{}
+				},
+			},
+		}
+	})
+	return defaultEncoderInstance
+}
+
+// Encode is a part of an implementation of the LabelEncoder
+// interface.
+func (d *defaultLabelEncoder) Encode(iter Iterator) string {
+	buf := d.pool.Get().(*bytes.Buffer)
+	defer d.pool.Put(buf)
+	buf.Reset()
+
+	for iter.Next() {
+		i, kv := iter.IndexedLabel()
+		if i > 0 {
+			_, _ = buf.WriteRune(',')
+		}
+		copyAndEscape(buf, string(kv.Key))
+
+		_, _ = buf.WriteRune('=')
+
+		if kv.Value.Type() == core.STRING {
+			copyAndEscape(buf, kv.Value.AsString())
+		} else {
+			_, _ = buf.WriteString(kv.Value.Emit())
+		}
+	}
+	return buf.String()
+}
+
+// ID is a part of an implementation of the LabelEncoder interface.
+func (*defaultLabelEncoder) ID() EncoderID {
+	return defaultEncoderID
+}
+
+// copyAndEscape escapes `=`, `,` and its own escape character (`\`),
+// making the default encoding unique.
+func copyAndEscape(buf *bytes.Buffer, val string) {
+	for _, ch := range val {
+		switch ch {
+		case '=', ',', escapeChar:
+			buf.WriteRune(escapeChar)
+		}
+		buf.WriteRune(ch)
+	}
+}
+
+// Valid returns true if this encoder ID was allocated by
+// `NewEncoderID`.  Invalid encoder IDs will not be cached.
+func (id EncoderID) Valid() bool {
+	return id.value > 0
+}

api/label/iterator.go

@@ -0,0 +1,60 @@
+// Copyright The OpenTelemetry Authors
+//
+// 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 label
+
+import (
+	"go.opentelemetry.io/otel/api/core"
+)
+
+// Next moves the iterator to the next label. Returns false if there
+// are no more labels.
+func (i *Iterator) Next() bool {
+	i.idx++
+	return i.idx < i.Len()
+}
+
+// Label returns current label. Must be called only after Next returns
+// true.
+func (i *Iterator) Label() core.KeyValue {
+	kv, _ := i.storage.Get(i.idx)
+	return kv
+}
+
+// IndexedLabel returns current index and label. Must be called only
+// after Next returns true.
+func (i *Iterator) IndexedLabel() (int, core.KeyValue) {
+	return i.idx, i.Label()
+}
+
+// Len returns a number of labels in the iterator's `*Set`.
+func (i *Iterator) Len() int {
+	return i.storage.Len()
+}
+
+// ToSlice is a convenience function that creates a slice of labels
+// from the passed iterator. The iterator is set up to start from the
+// beginning before creating the slice.
+func (i *Iterator) ToSlice() []core.KeyValue {
+	l := i.Len()
+	if l == 0 {
+		return nil
+	}
+	i.idx = -1
+	slice := make([]core.KeyValue, 0, l)
+	for i.Next() {
+		slice = append(slice, i.Label())
+	}
+	return slice
+}