Rename tail sampling tag as attribute (#544)

BREAKING CHANGE!!! Addresses #532

Changes:
* `numeric-tag-filter` > `numeric-attribute-filter`
* `string-tag-filter` > `string-attribute-filter`
* `tag` > `key`

Author: flands

PERFORMANCE.MD

@@ -13,7 +13,7 @@ It is important to note that the performance of the OpenCensus Collector depends
 on a variety of factors including:
 
 * The receiving format: Jaeger thrift (14268) or Zipkin v2 JSON (9411)
-* The size of the spans (tests are based on number of tags): 20
+* The size of the spans (tests are based on number of attributes): 20
 * Whether tail-sampling is enabled or not
 * CPU / Memory allocation
 * Operating System: Linux

README.md

@@ -19,7 +19,7 @@
 - [OpenCensus Agent](#opencensus-agent)
     - [Usage](#agent-usage)
 - [OpenCensus Collector](#opencensus-collector)
-    - [Global Tags](#global-tags)
+    - [Global Attributes](#global-attributes)
     - [Intelligent Sampling](#tail-sampling)
     - [Usage](#collector-usage)
 
@@ -275,10 +275,10 @@ The collector also serves as a control plane for agents/clients by supplying
 them updated configuration (e.g. trace sampling policies), and reporting
 agent/client health information/inventory metadata to downstream exporters.
 
-### <a name="global-tags"></a> Global Tags
+### <a name="global-attributes"></a> Global Attributes
 
 The collector also takes some global configurations that modify its behavior for all receivers / exporters. One of the configurations
-available is to add Attributes or Tags to all spans passing through this collector. These additional tags can be configured to either overwrite
+available is to add Attributes or Tags to all spans passing through this collector. These additional attributes can be configured to either overwrite
 attributes if they already exists on the span, or respect the original values. An example of this is provided below.
 ```yaml
 global:
@@ -303,22 +303,22 @@ sampling:
   num-traces: 10000
   policies:
     # user-defined policy name
-    my-string-tag-filter:
+    my-string-attribute-filter:
       # exporters the policy applies to
       exporters:
         - jaeger
-      policy: string-tag-filter
+      policy: string-attribute-filter
       configuration:
-        tag: tag1
+        key: key1
         values:
           - value1
           - value2
-    my-numeric-tag-filter:
+    my-numeric-attribute-filter:
       exporters:
         - zipkin
-      policy: numeric-tag-filter
+      policy: numeric-attribute-filter
       configuration:
-        tag: tag1
+        key: key1
         min-value: 0
         max-value: 100
 ```

cmd/occollector/app/builder/builder_test.go

@@ -143,39 +143,39 @@ func TestTailSamplingPoliciesConfiguration(t *testing.T) {
 	wCfg.Mode = TailSampling
 	wCfg.Policies = []*PolicyCfg{
 		{
-			Name:      "string-tag-filter1",
-			Type:      StringTagFilter,
+			Name:      "string-attribute-filter1",
+			Type:      StringAttributeFilter,
 			Exporters: []string{"jaeger1"},
-			Configuration: &StringTagFilterCfg{
-				Tag:    "test",
+			Configuration: &StringAttributeFilterCfg{
+				Key:    "test",
 				Values: []string{"value 1", "value 2"},
 			},
 		},
 		{
-			Name:      "numeric-tag-filter2",
-			Type:      NumericTagFilter,
+			Name:      "numeric-attribute-filter2",
+			Type:      NumericAttributeFilter,
 			Exporters: []string{"jaeger2"},
-			Configuration: &NumericTagFilterCfg{
-				Tag:      "http.status_code",
+			Configuration: &NumericAttributeFilterCfg{
+				Key:      "http.status_code",
 				MinValue: 400,
 				MaxValue: 999,
 			},
 		},
 		{
-			Name:      "string-tag-filter3",
-			Type:      StringTagFilter,
+			Name:      "string-attribute-filter3",
+			Type:      StringAttributeFilter,
 			Exporters: []string{"jaeger3"},
-			Configuration: &StringTagFilterCfg{
-				Tag:    "test.different",
+			Configuration: &StringAttributeFilterCfg{
+				Key:    "test.different",
 				Values: []string{"key 1", "key 2"},
 			},
 		},
 		{
-			Name:      "numeric-tag-filter4",
-			Type:      NumericTagFilter,
+			Name:      "numeric-attribute-filter4",
+			Type:      NumericAttributeFilter,
 			Exporters: []string{"jaeger4", "jaeger5"},
-			Configuration: &NumericTagFilterCfg{
-				Tag:      "http.status_code",
+			Configuration: &NumericAttributeFilterCfg{
+				Key:      "http.status_code",
 				MinValue: 400,
 				MaxValue: 999,
 			},

cmd/occollector/app/builder/sampling_builder.go

@@ -44,12 +44,12 @@ type PolicyType string
 const (
 	// AlwaysSample samples all traces, typically used for debugging.
 	AlwaysSample PolicyType = "always-sample"
-	// NumericTagFilter sample traces that have a given numberic tag in a specified
-	// range, e.g.: tag "http.status_code" >= 399 and <= 999.
-	NumericTagFilter PolicyType = "numeric-tag-filter"
-	// StringTagFilter sample traces that a tag, of type string, matching
+	// NumericAttributeFilter sample traces that have a given numeric attribute in a specified
+	// range, e.g.: attribute "http.status_code" >= 399 and <= 999.
+	NumericAttributeFilter PolicyType = "numeric-attribute-filter"
+	// StringAttributeFilter sample traces that a attribute, of type string, matching
 	// one of the listed values.
-	StringTagFilter PolicyType = "string-tag-filter"
+	StringAttributeFilter PolicyType = "string-attribute-filter"
 	// RateLimiting allows all traces until the specified limits are satisfied.
 	RateLimiting PolicyType = "rate-limiting"
 )
@@ -67,27 +67,27 @@ type PolicyCfg struct {
 	Configuration interface{}
 }
 
-// NumericTagFilterCfg holds the configurable settings to create a numeric tag filter
+// NumericAttributeFilterCfg holds the configurable settings to create a numeric attribute filter
 // sampling policy evaluator.
-type NumericTagFilterCfg struct {
+type NumericAttributeFilterCfg struct {
 	// Tag that the filter is going to be matching against.
-	Tag string `mapstructure:"tag"`
-	// MinValue is the minimum value of the tag to be considered a match.
+	Key string `mapstructure:"key"`
+	// MinValue is the minimum value of the attribute to be considered a match.
 	MinValue int64 `mapstructure:"min-value"`
-	// MaxValue is the maximum value of the tag to be considered a match.
+	// MaxValue is the maximum value of the attribute to be considered a match.
 	MaxValue int64 `mapstructure:"max-value"`
 }
 
-// StringTagFilterCfg holds the configurable settings to create a string tag filter
+// StringAttributeFilterCfg holds the configurable settings to create a string attribute filter
 // sampling policy evaluator.
-type StringTagFilterCfg struct {
+type StringAttributeFilterCfg struct {
 	// Tag that the filter is going to be matching against.
-	Tag string `mapstructure:"tag"`
-	// Values is the set of tag values that if any is equal to the actual tag valueto be considered a match.
+	Key string `mapstructure:"key"`
+	// Values is the set of attribute values that if any is equal to the actual attribute value to be considered a match.
 	Values []string `mapstructure:"values"`
 }
 
-// RateLimitingCfg holds the configurable settings to create a string tag filter
+// RateLimitingCfg holds the configurable settings to create a string attribute filter
 // sampling policy evaluator.
 type RateLimitingCfg struct {
 	// SpansPerSecond limit to the number of spans per second
@@ -135,12 +135,12 @@ func (sCfg *SamplingCfg) InitFromViper(v *viper.Viper) *SamplingCfg {
 			// As the number of polices grow this likely should be in a map.
 			var cfg interface{}
 			switch polCfg.Type {
-			case NumericTagFilter:
-				numTagFilterCfg := &NumericTagFilterCfg{}
-				cfg = numTagFilterCfg
-			case StringTagFilter:
-				strTagFilterCfg := &StringTagFilterCfg{}
-				cfg = strTagFilterCfg
+			case NumericAttributeFilter:
+				numAttributeFilterCfg := &NumericAttributeFilterCfg{}
+				cfg = numAttributeFilterCfg
+			case StringAttributeFilter:
+				strAttributeFilterCfg := &StringAttributeFilterCfg{}
+				cfg = strAttributeFilterCfg
 			case RateLimiting:
 				rateLimitingCfg := &RateLimitingCfg{}
 				cfg = rateLimitingCfg

cmd/occollector/app/builder/testdata/sampling_config.yaml

@@ -29,38 +29,38 @@ sampling:
   decision-wait: 31s
   num-traces: 20001
   policies:
-    string-tag-filter1:
+    string-attribute-filter1:
         exporters: 
           - jaeger1
-        policy: string-tag-filter
+        policy: string-attribute-filter
         configuration:
-          tag: "test"
+          key: "test"
           values:
             - "value 1"
             - "value 2"
-    numeric-tag-filter2:
+    numeric-attribute-filter2:
         exporters:
           - jaeger2
-        policy: numeric-tag-filter
+        policy: numeric-attribute-filter
         configuration:
-          tag: "http.status_code"
+          key: "http.status_code"
           min-value: 400
           max-value: 999
-    string-tag-filter3: 
+    string-attribute-filter3: 
         exporters: 
           - jaeger3
-        policy: string-tag-filter
+        policy: string-attribute-filter
         configuration:
-          tag: "test.different"
+          key: "test.different"
           values:
             - "key 1"
             - "key 2"
-    numeric-tag-filter4:
+    numeric-attribute-filter4:
         exporters: 
           - jaeger4
           - jaeger5
-        policy: numeric-tag-filter
+        policy: numeric-attribute-filter
         configuration:
-          tag: "http.status_code"
+          key: "http.status_code"
           min-value: 400
           max-value: 999

cmd/occollector/app/collector/processors.go

@@ -176,12 +176,12 @@ func buildSamplingProcessor(cfg *builder.SamplingCfg, nameToTraceConsumer map[st
 		switch polCfg.Type {
 		case builder.AlwaysSample:
 			policy.Evaluator = sampling.NewAlwaysSample()
-		case builder.NumericTagFilter:
-			numTagFilterCfg := polCfg.Configuration.(*builder.NumericTagFilterCfg)
-			policy.Evaluator = sampling.NewNumericTagFilter(numTagFilterCfg.Tag, numTagFilterCfg.MinValue, numTagFilterCfg.MaxValue)
-		case builder.StringTagFilter:
-			strTagFilterCfg := polCfg.Configuration.(*builder.StringTagFilterCfg)
-			policy.Evaluator = sampling.NewStringTagFilter(strTagFilterCfg.Tag, strTagFilterCfg.Values)
+		case builder.NumericAttributeFilter:
+			numAttributeFilterCfg := polCfg.Configuration.(*builder.NumericAttributeFilterCfg)
+			policy.Evaluator = sampling.NewNumericAttributeFilter(numAttributeFilterCfg.Key, numAttributeFilterCfg.MinValue, numAttributeFilterCfg.MaxValue)
+		case builder.StringAttributeFilter:
+			strAttributeFilterCfg := polCfg.Configuration.(*builder.StringAttributeFilterCfg)
+			policy.Evaluator = sampling.NewStringAttributeFilter(strAttributeFilterCfg.Key, strAttributeFilterCfg.Values)
 		case builder.RateLimiting:
 			rateLimitingCfg := polCfg.Configuration.(*builder.RateLimitingCfg)
 			policy.Evaluator = sampling.NewRateLimiting(rateLimitingCfg.SpansPerSecond)

exporter/README.md

@@ -23,23 +23,23 @@ sampling:
       policy: rate-limiting
       configuration:
         spans-per-second: 1000
-    my-string-tag-filter:
+    my-string-attribute-filter:
       exporters:
         - jaeger
         - omnition
-      policy: string-tag-filter
+      policy: string-attribute-filter
       configuration:
-        tag: tag1
+        key: key1
         values:
           - value1
           - value2
-    my-numeric-tag-filter:
+    my-numeric-attribute-filter:
       exporters:
         - jaeger
         - omnition
-      policy: numeric-tag-filter
+      policy: numeric-attribute-filter
       configuration:
-        tag: tag1
+        key: key1
         min-value: 0
         max-value: 100
     my-always-sample:

internal/collector/sampling/numeric_tag_filter.go

@@ -16,18 +16,18 @@ package sampling
 
 import tracepb "github.com/census-instrumentation/opencensus-proto/gen-go/trace/v1"
 
-type numericTagFilter struct {
-	tag                string
+type numericAttributeFilter struct {
+	key                string
 	minValue, maxValue int64
 }
 
-var _ PolicyEvaluator = (*numericTagFilter)(nil)
+var _ PolicyEvaluator = (*numericAttributeFilter)(nil)
 
-// NewNumericTagFilter creates a policy evaluator that samples all traces with
-// the given tag in the given numeric range.
-func NewNumericTagFilter(tag string, minValue, maxValue int64) PolicyEvaluator {
-	return &numericTagFilter{
-		tag:      tag,
+// NewNumericAttributeFilter creates a policy evaluator that samples all traces with
+// the given attribute in the given numeric range.
+func NewNumericAttributeFilter(key string, minValue, maxValue int64) PolicyEvaluator {
+	return &numericAttributeFilter{
+		key:      key,
 		minValue: minValue,
 		maxValue: maxValue,
 	}
@@ -37,12 +37,12 @@ func NewNumericTagFilter(tag string, minValue, maxValue int64) PolicyEvaluator {
 // after the sampling decision was already taken for the trace.
 // This gives the evaluator a chance to log any message/metrics and/or update any
 // related internal state.
-func (ntf *numericTagFilter) OnLateArrivingSpans(earlyDecision Decision, spans []*tracepb.Span) error {
+func (naf *numericAttributeFilter) OnLateArrivingSpans(earlyDecision Decision, spans []*tracepb.Span) error {
 	return nil
 }
 
 // Evaluate looks at the trace data and returns a corresponding SamplingDecision.
-func (ntf *numericTagFilter) Evaluate(traceID []byte, trace *TraceData) (Decision, error) {
+func (naf *numericAttributeFilter) Evaluate(traceID []byte, trace *TraceData) (Decision, error) {
 	trace.Lock()
 	batches := trace.ReceivedBatches
 	trace.Unlock()
@@ -51,9 +51,9 @@ func (ntf *numericTagFilter) Evaluate(traceID []byte, trace *TraceData) (Decisio
 			if span == nil || span.Attributes == nil {
 				continue
 			}
-			if v, ok := span.Attributes.AttributeMap[ntf.tag]; ok {
+			if v, ok := span.Attributes.AttributeMap[naf.key]; ok {
 				value := v.GetIntValue()
-				if value >= ntf.minValue && value <= ntf.maxValue {
+				if value >= naf.minValue && value <= naf.maxValue {
 					return Sampled, nil
 				}
 			}
@@ -65,6 +65,6 @@ func (ntf *numericTagFilter) Evaluate(traceID []byte, trace *TraceData) (Decisio
 
 // OnDroppedSpans is called when the trace needs to be dropped, due to memory
 // pressure, before the decision_wait time has been reached.
-func (ntf *numericTagFilter) OnDroppedSpans(traceID []byte, trace *TraceData) (Decision, error) {
+func (naf *numericAttributeFilter) OnDroppedSpans(traceID []byte, trace *TraceData) (Decision, error) {
 	return NotSampled, nil
 }