add high level interface

* standardized on encoding/decoding terminology
* renamed encodings to bytes to avoid confusion with encode/decode terminology
* added high level interfaces to top level protocols package that goes directly pdata <-> bytes

Author: jrcamp

protocols/README.md

@@ -0,0 +1,9 @@
+# Protocols
+
+This package provides common ways for decoding bytes into data models (e.g. Zipkin Span). These data models can then be decoded into internal pdata representations. Similarly, pdata can be encoded into a data model which can then be encoded into bytes.
+
+[bytes](bytes): Common interfaces for encoding/decoding bytes from/to data models.
+
+[models](models): Common interfaces for encoding/decoding data models from/to pdata.
+
+This package provides higher level APIs that do both encoding of bytes and data model if going directly pdata <-> bytes.

protocols/encoding/decoder.go protocols/bytes/decoder.goprotocols/encoding/decoder.go renamed to protocols/bytes/decoder.go

@@ -12,19 +12,19 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package encoding
+package bytes
 
-// MetricsDecoder decodes bytes into pdata.
+// MetricsDecoder decodes bytes into data model.
 type MetricsDecoder interface {
 	DecodeMetrics(bytes []byte) (interface{}, error)
 }
 
-// TracesDecoder decodes bytes into pdata.
+// TracesDecoder decodes bytes into data model.
 type TracesDecoder interface {
 	DecodeTraces(bytes []byte) (interface{}, error)
 }
 
-// LogsDecoder decodes bytes into pdata.
+// LogsDecoder decodes bytes into data model.
 type LogsDecoder interface {
 	DecodeLogs(bytes []byte) (interface{}, error)
 }

protocols/encoding/encoder.go protocols/bytes/encoder.goprotocols/encoding/encoder.go renamed to protocols/bytes/encoder.go

@@ -12,19 +12,19 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package encoding
+package bytes
 
-// MetricsEncoder encodes pdata into bytes.
+// MetricsEncoder encodes data model into bytes.
 type MetricsEncoder interface {
 	EncodeMetrics(model interface{}) ([]byte, error)
 }
 
-// TracesEncoder encodes pdata into bytes.
+// TracesEncoder encodes data model into bytes.
 type TracesEncoder interface {
 	EncodeTraces(model interface{}) ([]byte, error)
 }
 
-// LogsEncoder encodes pdata into bytes.
+// LogsEncoder encodes data model into bytes.
 type LogsEncoder interface {
 	EncodeLogs(model interface{}) ([]byte, error)
 }

protocols/encoding/encoding.go protocols/bytes/encoding.goprotocols/encoding/encoding.go renamed to protocols/bytes/encoding.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-package encoding
+package bytes
 
 import "fmt"
 
@@ -29,11 +29,15 @@ func (e Type) String() string {
 	return string(e)
 }
 
-// ErrUnavailableEncoding is returned when the requested encoding is not present.
+// ErrUnavailableEncoding is returned when the requested encoding is not supported.
 type ErrUnavailableEncoding struct {
-	Encoding Type
+	encoding Type
 }
 
 func (e *ErrUnavailableEncoding) Error() string {
-	return fmt.Sprintf("unsupported encoding %q", e.Encoding)
+	return fmt.Sprintf("unsupported encoding %q", e.encoding)
 }
+
+func NewErrUnavailableEncoding(encoding Type) *ErrUnavailableEncoding {
+	return &ErrUnavailableEncoding{encoding: encoding}
+}

protocols/decoder.go

@@ -0,0 +1,63 @@
+// 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 protocols
+
+import (
+	"go.opentelemetry.io/collector/consumer/pdata"
+	"go.opentelemetry.io/collector/protocols/models"
+	"go.opentelemetry.io/collector/protocols/bytes"
+)
+
+type MetricsDecoder struct {
+	mod models.MetricsDecoder
+	enc bytes.MetricsDecoder
+}
+
+type TracesDecoder struct {
+	mod models.TracesDecoder
+	enc bytes.TracesDecoder
+}
+
+type LogsDecoder struct {
+	mod models.LogsDecoder
+	enc bytes.LogsDecoder
+}
+
+// MetricsDecoder decodes bytes to pdata.
+func (t *MetricsDecoder) DecodeMetrics(data []byte) (pdata.Metrics, error) {
+	model, err := t.enc.DecodeMetrics(data)
+	if err != nil {
+		return pdata.NewMetrics(), err
+	}
+	return t.mod.ToMetrics(model)
+}
+
+// TracesDecoder decodes bytes to pdata.
+func (t *TracesDecoder) DecodeTraces(data []byte) (pdata.Traces, error) {
+	model, err := t.enc.DecodeTraces(data)
+	if err != nil {
+		return pdata.NewTraces(), err
+	}
+	return t.mod.ToTraces(model)
+}
+
+// LogsDecoder decodes bytes to pdata.
+func (t *LogsDecoder) DecodeLogs(data []byte) (pdata.Logs, error) {
+	model, err := t.enc.DecodeLogs(data)
+	if err != nil {
+		return pdata.NewLogs(), err
+	}
+	return t.mod.ToLogs(model)
+}

protocols/encoder.go

@@ -0,0 +1,63 @@
+// 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 protocols
+
+import (
+	"go.opentelemetry.io/collector/consumer/pdata"
+	"go.opentelemetry.io/collector/protocols/models"
+	"go.opentelemetry.io/collector/protocols/bytes"
+)
+
+type MetricsEncoder struct {
+	mod models.MetricsEncoder
+	enc bytes.MetricsEncoder
+}
+
+type TracesEncoder struct {
+	mod models.TracesEncoder
+	enc bytes.TracesEncoder
+}
+
+type LogsEncoder struct {
+	mod models.LogsEncoder
+	enc bytes.LogsEncoder
+}
+
+// EncodeMetrics encodes pdata to bytes.
+func (t *MetricsEncoder) EncodeMetrics(td pdata.Metrics) ([]byte, error) {
+	out := t.mod.Type()
+	if err := t.mod.FromMetrics(td, &out); err != nil {
+		return nil, err
+	}
+	return t.enc.EncodeMetrics(out)
+}
+
+// EncodeTraces encodes pdata to bytes.
+func (t *TracesEncoder) EncodeTraces(td pdata.Traces) ([]byte, error) {
+	out := t.mod.Type()
+	if err := t.mod.FromTraces(td, &out); err != nil {
+		return nil, err
+	}
+	return t.enc.EncodeTraces(out)
+}
+
+// EncodeLogs encodes pdata to bytes.
+func (t *LogsEncoder) EncodeLogs(td pdata.Logs) ([]byte, error) {
+	out := t.mod.Type()
+	if err := t.mod.FromLogs(td, &out); err != nil {
+		return nil, err
+	}
+	return t.enc.EncodeLogs(out)
+}

protocols/models/decoder.go

@@ -0,0 +1,38 @@
+// 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 models
+
+import "go.opentelemetry.io/collector/consumer/pdata"
+
+type MetricsDecoder interface {
+	// ToMetrics converts a data model of another protocol into pdata.
+	ToMetrics(src interface{}) (pdata.Metrics, error)
+	// Type returns an instance of the model.
+	Type() interface{}
+}
+
+type TracesDecoder interface {
+	// ToTraces converts a data model of another protocol into pdata.
+	ToTraces(src interface{}) (pdata.Traces, error)
+	// Type returns an instance of the model.
+	Type() interface{}
+}
+
+type LogsDecoder interface {
+	// ToLogs converts a data model of another protocol into pdata.
+	ToLogs(src interface{}) (pdata.Logs, error)
+	// Type returns an instance of the model.
+	Type() interface{}
+}

protocols/models/encoder.go

@@ -0,0 +1,38 @@
+// 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 models
+
+import "go.opentelemetry.io/collector/consumer/pdata"
+
+type MetricsEncoder interface {
+	// FromMetrics converts pdata to data model.
+	FromMetrics(md pdata.Metrics, out interface{}) error
+	// Type returns an instance of the model.
+	Type() interface{}
+}
+
+type TracesEncoder interface {
+	// FromTraces converts pdata to data model.
+	FromTraces(md pdata.Traces, out interface{}) error
+	// Type returns an instance of the model.
+	Type() interface{}
+}
+
+type LogsEncoder interface {
+	// FromLogs converts pdata to data model.
+	FromLogs(md pdata.Logs, out interface{}) error
+	// Type returns an instance of the model.
+	Type() interface{}
+}

protocols/models/models.go

@@ -16,38 +16,22 @@ package models
 
 import (
 	"fmt"
-	"go.opentelemetry.io/collector/consumer/pdata"
 )
 
-type MetricsModelTranslator interface {
-	// MetricsFromModel converts a data model of another protocol into pdata.
-	MetricsFromModel(src interface{}) (pdata.Metrics, error)
-	// MetricsToModel converts pdata to data model.
-	MetricsToModel(md pdata.Metrics, out interface{}) error
-}
-
-type TracesModelTranslator interface {
-	// TracesFromModel converts a data model of another protocol into pdata.
-	TracesFromModel(src interface{}) (pdata.Traces, error)
-	// TracesToModel converts pdata to data model.
-	TracesToModel(md pdata.Traces, out interface{}) error
-
-	Type() interface{}
-}
-
-type LogsModelTranslator interface {
-	// LogsFromModel converts a data model of another protocol into pdata.
-	LogsFromModel(src interface{}) (pdata.Logs, error)
-	// LogsToModel converts pdata to data model.
-	LogsToModel(md pdata.Logs, out interface{}) error
-}
-
 // ErrIncompatibleType details a type conversion error during translation.
 type ErrIncompatibleType struct {
-	Model interface{}
-	// TODO: maybe do expected vs. actual?
+	given interface{}
+	expected interface{}
 }
 
 func (i *ErrIncompatibleType) Error() string {
-	return fmt.Sprintf("model type %T is incompatible", i.Model)
+	return fmt.Sprintf("model type %T is expected but given %T ", i.expected, i.given)
 }
+
+// NewErrIncompatibleType returns ErrIncompatibleType instance
+func NewErrIncompatibleType(expected, given interface{}) *ErrIncompatibleType {
+	return &ErrIncompatibleType{
+		given:    given,
+		expected: expected,
+	}
+}