Merge pull request #291 from newrelic/ignore_host_entity

Add ignore_entity attribute

Author: rogercoll

docs/v3tov4.md

@@ -10,6 +10,7 @@ The Go SDK v4 contains the following changes:
 * New metric data types: `count`, `summary`, `cumulative-count` and `cumulative-rate`.
 * Support for Prometheus Histogram and Summary metrics
 * LocalEntity has been replaced by HostEntity.
+* Support for disabling entity registration (IgnoreEntity).
 * Support for Go Modules
 * Removed support for protocols prior to v4.x.
 
@@ -33,6 +34,7 @@ These are the most important changes:
   },
   "data":[                                    # List of objects containing entities, metrics, events and inventory
     {
+      "ignore_entity": false,
       "entity":{                              # this object is optional. If it's not provided, then the Entity will get 
                                               # the same entity ID as the agent that executes the integration. 
         "name":"redis:192.168.100.200:1234",  # unique entity name per customer account
@@ -160,6 +162,20 @@ To add a tag just call
 
 On both cases, if the `key` already exists the previous value will be overwritten with the new one.
 
+#### Ignore entity
+
+In older versions, the entity payload was decorated by the infra agent with an entity id to uniquely identify it in New 
+Relic One. The entity registration method for New Relic has changed, the current default strategy is named entity 
+synthesis, which can identify unique entities from its metadata and metrics name. You can find more information [here](https://docs.newrelic.com/docs/new-relic-one/core-concepts/what-entity-new-relic/).
+
+All new integrations should be able to register using the entity synthesis strategy, but for backwards compatability and
+possible new host integrations, you can use the `IgnoreEntity` attribute for each entity.
+
+By default, `IgnoreEntity` will be set to true, thus the agent will not register the entity. Nonetheless, if your entity
+needs to be registered or use the infra agent entity id just call:
+
+`func (i *Entity) SetIgnoreEntity(value bool)`
+
 ### Metrics
 
 #### Types

integration/entity.go

@@ -18,7 +18,10 @@ type Entity struct {
 	Metrics          metric.Metrics       `json:"metrics"`
 	Inventory        *inventory.Inventory `json:"inventory"`
 	Events           event.Events         `json:"events"`
-	lock             sync.Locker
+	// IgnoreEntity defines if the Entity should be registered within the infra agent, if true
+	// the Entity will not be attached to the infra agent entity neither registered.
+	IgnoreEntity bool `json:"ignore_entity"`
+	lock         sync.Locker
 }
 
 // Common is the producer of the common dimensions/attributes.
@@ -114,6 +117,11 @@ func (e *Entity) AddMetadata(key string, value interface{}) error {
 	return nil
 }
 
+// SetIgnoreEntity set if the infra agent should register the entity
+func (e *Entity) SetIgnoreEntity(value bool) {
+	e.IgnoreEntity = value
+}
+
 // Name is the unique entity identifier within a New Relic customer account.
 func (e *Entity) Name() string {
 	return e.Metadata.Name
@@ -127,11 +135,12 @@ func newHostEntity() *Entity {
 		CommonDimensions: Common{
 			Attributes: make(map[string]interface{}),
 		},
-		Metadata:  nil,
-		Metrics:   metric.Metrics{},
-		Inventory: inventory.New(),
-		Events:    event.Events{},
-		lock:      &sync.Mutex{},
+		Metadata:     nil,
+		Metrics:      metric.Metrics{},
+		Inventory:    inventory.New(),
+		Events:       event.Events{},
+		IgnoreEntity: true,
+		lock:         &sync.Mutex{},
 	}
 }
 

integration/entity_test.go

@@ -196,7 +196,7 @@ func Test_Entity_AnonymousEntityIsProperlySerialized(t *testing.T) {
 	j, err := json.Marshal(e)
 
 	assert.NoError(t, err)
-	assert.Equal(t, `{"common":{},"metrics":[],"inventory":{},"events":[]}`, string(j))
+	assert.Equal(t, `{"common":{},"metrics":[],"inventory":{},"events":[],"ignore_entity":true}`, string(j))
 }
 
 func Test_Entity_EntitiesWithSameMetadataAreSameAs(t *testing.T) {
@@ -228,11 +228,12 @@ func TestEntity_AddCommonDimension(t *testing.T) {
 					"k": "v",
 				},
 			},
-			Metadata:  nil,
-			Metrics:   metric.Metrics{},
-			Inventory: inventory.New(),
-			Events:    event.Events{},
-			lock:      &sync.Mutex{},
+			Metadata:     nil,
+			Metrics:      metric.Metrics{},
+			Inventory:    inventory.New(),
+			Events:       event.Events{},
+			lock:         &sync.Mutex{},
+			IgnoreEntity: true,
 		}},
 		{"two entries", metric.Dimensions{"k1": "v1", "k2": "v2"}, &Entity{
 			CommonDimensions: Common{
@@ -241,11 +242,12 @@ func TestEntity_AddCommonDimension(t *testing.T) {
 					"k2": "v2",
 				},
 			},
-			Metadata:  nil,
-			Metrics:   metric.Metrics{},
-			Inventory: inventory.New(),
-			Events:    event.Events{},
-			lock:      &sync.Mutex{},
+			Metadata:     nil,
+			Metrics:      metric.Metrics{},
+			Inventory:    inventory.New(),
+			Events:       event.Events{},
+			lock:         &sync.Mutex{},
+			IgnoreEntity: true,
 		}},
 	}
 	for _, tt := range tests {
@@ -320,3 +322,18 @@ func TestEntity_AddCommonInterval(t *testing.T) {
 		})
 	}
 }
+
+func Test_SetIgnoreEntity(t *testing.T) {
+	e := newHostEntity()
+	e.SetIgnoreEntity(true)
+	j, err := json.Marshal(e)
+	assert.NoError(t, err)
+	assert.Equal(t, `{"common":{},"metrics":[],"inventory":{},"events":[],"ignore_entity":true}`, string(j))
+	assert.Equal(t, true, e.IgnoreEntity)
+
+	e.SetIgnoreEntity(false)
+	j, err = json.Marshal(e)
+	assert.NoError(t, err)
+	assert.Equal(t, `{"common":{},"metrics":[],"inventory":{},"events":[],"ignore_entity":false}`, string(j))
+	assert.Equal(t, false, e.IgnoreEntity)
+}

integration/integration_test.go

@@ -222,7 +222,8 @@ func Test_Integration_PublishThrowsNoError(t *testing.T) {
 					  "summary": "evnt2sum",
 					  "category": "evnt2cat"
 					}
-				  ]
+				  ],
+				  "ignore_entity": false
 				},
 				{
 				  "common": {
@@ -248,7 +249,8 @@ func Test_Integration_PublishThrowsNoError(t *testing.T) {
 					}
 				  ],
 				  "inventory": {},
-				  "events": []
+				  "events": [],
+				  "ignore_entity": true
 				},
 				{
 				  "common": {
@@ -281,7 +283,8 @@ func Test_Integration_PublishThrowsNoError(t *testing.T) {
 					}
 				  ],
 				  "inventory": {},
-				  "events": []
+				  "events": [],
+				  "ignore_entity": true
 				},
 				{
 				  "common": {},
@@ -359,7 +362,8 @@ func Test_Integration_PublishThrowsNoError(t *testing.T) {
 					  "summary": "evnt2sum",
 					  "category": "evnt2cat"
 					}
-				  ]
+				  ],
+				  "ignore_entity": true
 				}
 			  ]
 			}`)
@@ -375,6 +379,7 @@ func Test_Integration_PublishThrowsNoError(t *testing.T) {
 	e, err := i.NewEntity("EntityOne", "test", "")
 	assert.NoError(t, err)
 	_ = e.AddTag("env", "prod")
+	e.SetIgnoreEntity(false)
 
 	gauge, _ := Gauge(time.Unix(10000000, 0), "metric-gauge", 1)
 	count, _ := Count(time.Unix(10000000, 0), "metric-count", 100)
@@ -488,7 +493,8 @@ func Test_Integration_HostId(t *testing.T) {
       },
       "metrics": [],
       "inventory": {},
-      "events": []
+      "events": [],
+      "ignore_entity": true
     },
     {
       "common": {
@@ -514,7 +520,8 @@ func Test_Integration_HostId(t *testing.T) {
         }
       ],
       "inventory": {},
-      "events": []
+      "events": [],
+      "ignore_entity": true
     }
   ]
 }`)