Merge pull request #171 from newrelic/IHOST-1997_identifier_attributes

Protocol V3: Added identifier attributes

Author: varas

CHANGELOG.md

@@ -23,8 +23,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 
-- Added metadata optional decoration for entity metrics (`hostname`, 
-  `clusterName` and `serviceName`), [check doc](/docs/entity-definition.md)
+- Added metadata optional decoration for entity metrics (`hostname`), [check doc](/docs/entity-definition.md)
+- Added `identifier attributes` for entity metadata.
 
 
 ## 3.0.3

integration/entity.go

@@ -23,10 +23,14 @@ type Entity struct {
 	customAttributes []metric.Attribute
 }
 
+//IDAttributes used for the entity key uniqueness
+type IDAttributes []IDAttribute
+
 // EntityMetadata stores entity Metadata
 type EntityMetadata struct {
-	Name      string `json:"name"`
-	Namespace string `json:"type"` // For compatibility reasons we keep the type.
+	Name      string       `json:"name"`
+	Namespace string       `json:"type"`          // For compatibility reasons we keep the type.
+	IDAttrs   IDAttributes `json:"id_attributes"` // For entity Key uniqueness
 }
 
 // newLocalEntity creates unique default entity without identifier (name & type)
@@ -42,9 +46,15 @@ func newLocalEntity(storer persist.Storer, addHostnameToMetadata bool) *Entity {
 	}
 }
 
-// newEntity creates a new remote-entity.
-func newEntity(name, namespace string, storer persist.Storer, addHostnameToMetadata bool) (*Entity, error) {
-	// If one of the attributes is defined, both Name and Namespace are needed.
+// newEntity creates a new remote-entity with entity attributes.
+func newEntity(
+	name,
+	namespace string,
+	storer persist.Storer,
+	addHostnameToMetadata bool,
+	idAttrs ...IDAttribute,
+) (*Entity, error) {
+
 	if name == "" || namespace == "" {
 		return nil, errors.New("entity name and type are required when defining one")
 	}
@@ -57,19 +67,28 @@ func newEntity(name, namespace string, storer persist.Storer, addHostnameToMetad
 		AddHostname: addHostnameToMetadata,
 		storer:      storer,
 		lock:        &sync.Mutex{},
-	}
-
-	// Entity data is optional. When not specified, data from the integration is reported for the agent's own entity.
-	if name != "" && namespace != "" {
-		d.Metadata = &EntityMetadata{
+		Metadata: &EntityMetadata{
 			Name:      name,
 			Namespace: namespace,
-		}
+			IDAttrs:   idAttributes(idAttrs...),
+		},
 	}
 
 	return &d, nil
 }
 
+func idAttributes(idAttrs ...IDAttribute) IDAttributes {
+	attrs := make(IDAttributes, len(idAttrs))
+	if len(attrs) == 0 {
+		return attrs
+	}
+	for i, attr := range idAttrs {
+		attrs[i] = attr
+	}
+
+	return attrs
+}
+
 // isLocalEntity returns true if entity is the default one (has no identifier: name & type)
 func (e *Entity) isLocalEntity() bool {
 	return e.Metadata == nil || e.Metadata.Name == ""

integration/entity_test.go

@@ -19,6 +19,43 @@ func TestNewEntity(t *testing.T) {
 	assert.NoError(t, err)
 	assert.Equal(t, "name", e.Metadata.Name)
 	assert.Equal(t, "type", e.Metadata.Namespace)
+	assert.False(t, e.AddHostname)
+	assert.Empty(t, e.Metadata.IDAttrs)
+}
+
+func TestNewEntityWithAttributes(t *testing.T) {
+	attr1 := NewIDAttribute("env", "prod")
+	attr2 := NewIDAttribute("srv", "auth")
+	e, err := newEntity(
+		"name",
+		"type",
+		persist.NewInMemoryStore(),
+		true,
+		attr1,
+		attr2,
+	)
+
+	assert.NoError(t, err)
+	assert.True(t, e.AddHostname)
+	assert.Len(t, e.Metadata.IDAttrs, 2)
+	assert.Equal(t, e.Metadata.IDAttrs[0], attr1)
+	assert.Equal(t, e.Metadata.IDAttrs[1], attr2)
+}
+
+func TestNewEntityWithOneAttribute(t *testing.T) {
+	attr1 := NewIDAttribute("env", "prod")
+	e, err := newEntity(
+		"name",
+		"type",
+		persist.NewInMemoryStore(),
+		true,
+		attr1,
+	)
+
+	assert.NoError(t, err)
+	assert.True(t, e.AddHostname)
+	assert.Len(t, e.Metadata.IDAttrs, 1)
+	assert.Equal(t, e.Metadata.IDAttrs[0], attr1)
 }
 
 func TestEntitiesRequireNameAndType(t *testing.T) {

integration/integration.go

@@ -25,7 +25,7 @@ const (
 
 // NR infrastructure agent protocol version
 const (
-	protocolVersion = "2"
+	protocolVersion = "3"
 )
 
 // Integration defines the format of the output JSON that integrations will return for protocol 2.
@@ -43,6 +43,20 @@ type Integration struct {
 	args               interface{}
 }
 
+// IDAttribute is a Key Value struct which is used to have uniqueness during the entity Key resolution.
+type IDAttribute struct {
+	Key   string
+	Value string
+}
+
+// NewIDAttribute creates new identifier attribute.
+func NewIDAttribute(key, value string) IDAttribute {
+	return IDAttribute{
+		Key:   key,
+		Value: value,
+	}
+}
+
 // New creates new integration with sane default values.
 func New(name, version string, opts ...Option) (i *Integration, err error) {
 
@@ -118,7 +132,7 @@ func (i *Integration) LocalEntity() *Entity {
 }
 
 // Entity method creates or retrieves an already created entity.
-func (i *Integration) Entity(name, namespace string) (e *Entity, err error) {
+func (i *Integration) Entity(name, namespace string, idAttributes ...IDAttribute) (e *Entity, err error) {
 	i.locker.Lock()
 	defer i.locker.Unlock()
 
@@ -129,7 +143,7 @@ func (i *Integration) Entity(name, namespace string) (e *Entity, err error) {
 		}
 	}
 
-	e, err = newEntity(name, namespace, i.storer, i.addHostnameToMeta)
+	e, err = newEntity(name, namespace, i.storer, i.addHostnameToMeta, idAttributes...)
 	if err != nil {
 		return nil, err
 	}

integration/integration_test.go

@@ -8,8 +8,9 @@ import (
 	"strings"
 	"testing"
 
-	sdk_args "github.com/newrelic/infra-integrations-sdk/args"
 	"github.com/newrelic/infra-integrations-sdk/data/event"
+
+	sdk_args "github.com/newrelic/infra-integrations-sdk/args"
 	"github.com/newrelic/infra-integrations-sdk/data/metric"
 	"github.com/newrelic/infra-integrations-sdk/log"
 	"github.com/stretchr/testify/assert"
@@ -23,18 +24,10 @@ var (
 func TestCreation(t *testing.T) {
 	i := newTestIntegration(t)
 
-	if i.Name != "TestIntegration" {
-		t.Error()
-	}
-	if i.IntegrationVersion != "1.0" {
-		t.Error()
-	}
-	if i.ProtocolVersion != "2" {
-		t.Error()
-	}
-	if len(i.Entities) != 0 {
-		t.Error()
-	}
+	assert.Equal(t, "TestIntegration", i.Name)
+	assert.Equal(t, "1.0", i.IntegrationVersion)
+	assert.Equal(t, "3", i.ProtocolVersion)
+	assert.Len(t, i.Entities, 0)
 }
 
 func TestDefaultIntegrationWritesToStdout(t *testing.T) {
@@ -52,7 +45,7 @@ func TestDefaultIntegrationWritesToStdout(t *testing.T) {
 	assert.NoError(t, err)
 	assert.Equal(t, "integration", i.Name)
 	assert.Equal(t, "4.0", i.IntegrationVersion)
-	assert.Equal(t, "2", i.ProtocolVersion)
+	assert.Equal(t, "3", i.ProtocolVersion)
 	assert.Equal(t, 0, len(i.Entities))
 
 	assert.NoError(t, i.Publish())
@@ -61,7 +54,7 @@ func TestDefaultIntegrationWritesToStdout(t *testing.T) {
 	f.Close()
 	payload, err := ioutil.ReadFile(f.Name())
 	assert.NoError(t, err)
-	assert.Equal(t, `{"name":"integration","protocol_version":"2","integration_version":"4.0","data":[]}`+"\n", string(payload))
+	assert.Equal(t, `{"name":"integration","protocol_version":"3","integration_version":"4.0","data":[]}`+"\n", string(payload))
 }
 
 func TestIntegration_DefaultEntity(t *testing.T) {
@@ -78,27 +71,13 @@ func TestDefaultArguments(t *testing.T) {
 	i, err := New("TestIntegration", "1.0", Logger(log.Discard), Writer(ioutil.Discard), Args(&al))
 	assert.NoError(t, err)
 
-	if i.Name != "TestIntegration" {
-		t.Error()
-	}
-	if i.IntegrationVersion != "1.0" {
-		t.Error()
-	}
-	if i.ProtocolVersion != "2" {
-		t.Error()
-	}
-	if len(i.Entities) != 0 {
-		t.Error()
-	}
-	if !al.All() {
-		t.Error()
-	}
-	if al.Pretty {
-		t.Error()
-	}
-	if al.Verbose {
-		t.Error()
-	}
+	assert.Equal(t, "TestIntegration", i.Name)
+	assert.Equal(t, "1.0", i.IntegrationVersion)
+	assert.Equal(t, "3", i.ProtocolVersion)
+	assert.Len(t, i.Entities, 0)
+	assert.True(t, al.All())
+	assert.False(t, al.Pretty)
+	assert.False(t, al.Verbose)
 }
 
 func TestClusterAndServiceArgumentsAreAddedToMetadata(t *testing.T) {
@@ -244,13 +223,19 @@ func TestIntegration_Publish(t *testing.T) {
 			expectedOutputRaw := []byte(`
 			{
 			  "name": "TestIntegration",
-			  "protocol_version": "2",
+			  "protocol_version": "3",
 			  "integration_version": "1.0",
 			  "data": [
 				{
 				  "entity": {
 					"name": "EntityOne",
-					"type": "test"
+					"type": "test",
+					"id_attributes": [
+					  {
+						"Key":"env",
+						"Value":"prod"
+					  }
+					]
 				  },
 				  "metrics": [
 					{
@@ -275,7 +260,8 @@ func TestIntegration_Publish(t *testing.T) {
 				{
 				  "entity": {
 					"name": "EntityTwo",
-					"type": "test"
+					"type": "test",
+					"id_attributes": []
 				  },
 				  "metrics": [
 					{
@@ -304,7 +290,7 @@ func TestIntegration_Publish(t *testing.T) {
 	i, err := New("TestIntegration", "1.0", Logger(log.Discard), Writer(w))
 	assert.NoError(t, err)
 
-	e, err := i.Entity("EntityOne", "test")
+	e, err := i.Entity("EntityOne", "test", NewIDAttribute("env", "prod"))
 	assert.NoError(t, err)
 	ms := e.NewMetricSet("EventTypeForEntityOne")
 	assert.NoError(t, ms.SetMetric("metricOne", 1, metric.GAUGE))

integration/options_test.go

@@ -25,7 +25,7 @@ func TestWriter(t *testing.T) {
 
 	assert.NoError(t, i.Publish())
 
-	assert.Equal(t, `{"name":"integration","protocol_version":"2","integration_version":"7.0","data":[]}`+"\n", w.String())
+	assert.Equal(t, `{"name":"integration","protocol_version":"3","integration_version":"7.0","data":[]}`+"\n", w.String())
 }
 
 func TestArgs(t *testing.T) {