Introduce model translation and encoding interfaces

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.
+
+[encoding](encoding): Common interfaces for encoding/decoding bytes from/to data models.
+
+[translation](translation): 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

@@ -0,0 +1,30 @@
+// 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 encoding
+
+// MetricsDecoder decodes bytes into data model.
+type MetricsDecoder interface {
+	DecodeMetrics(bytes []byte) (interface{}, error)
+}
+
+// TracesDecoder decodes bytes into data model.
+type TracesDecoder interface {
+	DecodeTraces(bytes []byte) (interface{}, error)
+}
+
+// LogsDecoder decodes bytes into data model.
+type LogsDecoder interface {
+	DecodeLogs(bytes []byte) (interface{}, error)
+}

protocols/encoding/encoder.go

@@ -0,0 +1,30 @@
+// 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 encoding
+
+// MetricsEncoder encodes data model into bytes.
+type MetricsEncoder interface {
+	EncodeMetrics(model interface{}) ([]byte, error)
+}
+
+// TracesEncoder encodes data model into bytes.
+type TracesEncoder interface {
+	EncodeTraces(model interface{}) ([]byte, error)
+}
+
+// LogsEncoder encodes data model into bytes.
+type LogsEncoder interface {
+	EncodeLogs(model interface{}) ([]byte, error)
+}

protocols/encoding/encoding.go

@@ -0,0 +1,43 @@
+// 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 encoding
+
+import "fmt"
+
+// Type is the encoding format that a model is serialized to.
+type Type string
+
+const (
+	Protobuf Type = "protobuf"
+	JSON     Type = "json"
+	Thrift   Type = "thrift"
+)
+
+func (e Type) String() string {
+	return string(e)
+}
+
+// ErrUnavailableEncoding is returned when the requested encoding is not supported.
+type ErrUnavailableEncoding struct {
+	encoding Type
+}
+
+func (e *ErrUnavailableEncoding) Error() string {
+	return fmt.Sprintf("unsupported encoding %q", e.encoding)
+}
+
+func NewErrUnavailableEncoding(encoding Type) *ErrUnavailableEncoding {
+	return &ErrUnavailableEncoding{encoding: encoding}
+}

protocols/encoding/encoding_test.go

@@ -0,0 +1,31 @@
+// 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 encoding
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestNewErrUnavailableEncoding(t *testing.T) {
+	err := NewErrUnavailableEncoding("unknown")
+	assert.IsType(t, &ErrUnavailableEncoding{}, err)
+	assert.EqualError(t, err, `unsupported encoding "unknown"`)
+}
+
+func TestType_String(t *testing.T) {
+	assert.Equal(t, "protobuf", Protobuf.String())
+}

protocols/translation/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 translation
+
+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/translation/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 translation
+
+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/translation/translation.go

@@ -0,0 +1,37 @@
+// 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 translation
+
+import (
+	"fmt"
+)
+
+// ErrIncompatibleType details a type conversion error during translation.
+type ErrIncompatibleType struct {
+	given    interface{}
+	expected interface{}
+}
+
+func (i *ErrIncompatibleType) Error() string {
+	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,
+	}
+}

protocols/translation/translation_test.go

@@ -0,0 +1,28 @@
+// 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 translation
+
+import (
+	"testing"
+
+	zipkinmodel "github.com/openzipkin/zipkin-go/model"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestNewErrIncompatibleType(t *testing.T) {
+	err := NewErrIncompatibleType([]*zipkinmodel.SpanModel{}, "given")
+	assert.IsType(t, &ErrIncompatibleType{}, err)
+	assert.EqualError(t, err, "model type []*model.SpanModel is expected but given string")
+}