Split by dimensions extension

receiver/azuremonitorreceiver/README.md

@@ -31,6 +31,8 @@ The following settings are optional:
 - `maximum_number_of_records_per_resource` (default = 10): Maximum number of records to fetch per resource.
 - `initial_delay` (default = `1s`): defines how long this receiver waits before starting.
 - `cloud` (default = `AzureCloud`): defines which Azure cloud to use. Valid values: `AzureCloud`, `AzureUSGovernment`, `AzureChinaCloud`.
+- `dimensions.enabled` (default = `true`): allows to opt out from automatically split by all the dimensions of the resource type.
+- `dimensions.overrides` (default = `{}`): if dimensions are enabled, it allows you to specify a set of dimensions for a particular metric. This is a two levels map with first key being the resource type and second key being the metric name. Programmatic value should be used for metric name https://learn.microsoft.com/en-us/azure/azure-monitor/reference/metrics-index
 
 Authenticating using service principal requires following additional settings:
 
@@ -101,6 +103,22 @@ receivers:
     auth: "default_credentials"
 ```
 
+Overriding dimensions for a particular metric:
+```yaml
+receivers:
+  azuremonitor:
+    dimensions:
+      enabled: true
+      overrides:
+        "Microsoft.Network/azureFirewalls":
+          # Real example of an Azure limitation here:
+          # Dimensions exposed are Reason, Status, Protocol,
+          # but when selecting Protocol in the filters, it returns nothing.
+          # Note here that the metric display name is ``Network rules hit count`` but it's programmatic value is ``NetworkRuleHit``
+          # Ref: https://learn.microsoft.com/en-us/azure/azure-monitor/reference/supported-metrics/microsoft-network-azurefirewalls-metrics
+          "NetworkRuleHit": [Reason, Status]
+```
+
 
 ## Metrics
 

receiver/azuremonitorreceiver/config.go

@@ -229,6 +229,11 @@ var (
 	}
 )
 
+type DimensionsConfig struct {
+	Enabled   *bool                          `mapstructure:"enabled"`
+	Overrides map[string]map[string][]string `mapstructure:"overrides"`
+}
+
 // Config defines the configuration for the various elements of the receiver agent.
 type Config struct {
 	scraperhelper.ControllerConfig    `mapstructure:",squash"`
@@ -251,7 +256,7 @@ type Config struct {
 	UseBatchAPI                       bool                          `mapstructure:"use_batch_api"`
 	DiscoverSubscription              bool                          `mapstructure:"discover_subscriptions"`
 	Region                            string                        `mapstructure:"region"`
-	SplitByDimensions                 *bool                         `mapstructure:"split_by_dimensions"`
+	Dimensions                        DimensionsConfig              `mapstructure:"dimensions"`
 }
 
 const (

receiver/azuremonitorreceiver/dimension_test.go

@@ -0,0 +1,171 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package azuremonitorreceiver // import "github.com/open-telemetry/opentelemetry-collector-contrib/receiver/azuremonitorreceiver"
+
+import (
+	"testing"
+
+	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
+	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/monitor/armmonitor"
+	"github.com/stretchr/testify/require"
+)
+
+func newDimension(value string) *armmonitor.LocalizableString {
+	return to.Ptr(armmonitor.LocalizableString{Value: to.Ptr(value)})
+}
+
+func TestFilterDimensions(t *testing.T) {
+	type args struct {
+		dimensions   []*armmonitor.LocalizableString
+		cfg          DimensionsConfig
+		resourceType string
+		metricName   string
+	}
+
+	tests := []struct {
+		name     string
+		args     args
+		expected []string
+	}{
+		{
+			name: "always empty if dimensions disabled",
+			args: args{
+				dimensions: []*armmonitor.LocalizableString{
+					newDimension("foo"),
+					newDimension("bar"),
+				},
+				cfg: DimensionsConfig{
+					Enabled: to.Ptr(false),
+				},
+				resourceType: "rt1",
+				metricName:   "m1",
+			},
+			expected: nil,
+		},
+		{
+			name: "split by dimensions should be enabled by default",
+			args: args{
+				dimensions: []*armmonitor.LocalizableString{
+					newDimension("foo"),
+					newDimension("bar"),
+				},
+				cfg:          DimensionsConfig{}, // enabled by default
+				resourceType: "rt1",
+				metricName:   "m1",
+			},
+			expected: []string{"foo", "bar"},
+		},
+		{
+			name: "overrides takes precedence over input",
+			args: args{
+				dimensions: []*armmonitor.LocalizableString{
+					newDimension("foo"),
+					newDimension("bar"),
+				},
+				cfg: DimensionsConfig{
+					Enabled: to.Ptr(true),
+					Overrides: map[string]map[string][]string{
+						"rt1": {
+							"m1": {
+								"foo",
+							},
+						},
+					},
+				},
+				resourceType: "rt1",
+				metricName:   "m1",
+			},
+			expected: []string{"foo"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			actual := filterDimensions(tt.args.dimensions, tt.args.cfg, tt.args.resourceType, tt.args.metricName)
+			require.Equal(t, tt.expected, actual)
+		})
+	}
+}
+
+func TestBuildDimensionsFilter(t *testing.T) {
+	type args struct {
+		dimensionsStr string
+	}
+
+	tests := []struct {
+		name     string
+		args     args
+		expected *string
+	}{
+		{
+			name: "empty given dimensions string",
+			args: args{
+				dimensionsStr: "",
+			},
+			expected: nil,
+		},
+		{
+			name: "build dimensions filter",
+			args: args{
+				dimensionsStr: "bar,foo",
+			},
+			expected: to.Ptr("bar eq '*' and foo eq '*'"),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			actual := buildDimensionsFilter(tt.args.dimensionsStr)
+			require.EqualValues(t, tt.expected, actual)
+		})
+	}
+}
+
+func TestSerializeDimensions(t *testing.T) {
+	type args struct {
+		dimensions []string
+	}
+
+	tests := []struct {
+		name     string
+		args     args
+		expected string
+	}{
+		{
+			name: "empty given dimensions",
+			args: args{
+				dimensions: []string{},
+			},
+			expected: "",
+		},
+		{
+			name: "nil given dimensions",
+			args: args{
+				dimensions: []string{},
+			},
+			expected: "",
+		},
+		{
+			name: "reorder dimensions",
+			args: args{
+				dimensions: []string{"foo", "bar"},
+			},
+			expected: "bar,foo",
+		},
+		{
+			name: "trim spaces dimensions",
+			args: args{
+				dimensions: []string{"  bar", "foo "},
+			},
+			expected: "bar,foo",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			actual := serializeDimensions(tt.args.dimensions)
+			require.EqualValues(t, tt.expected, actual)
+		})
+	}
+}

receiver/azuremonitorreceiver/dimensions.go

@@ -0,0 +1,66 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package azuremonitorreceiver // import "github.com/open-telemetry/opentelemetry-collector-contrib/receiver/azuremonitorreceiver"
+
+import (
+	"bytes"
+	"sort"
+	"strings"
+
+	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/monitor/armmonitor"
+)
+
+// filterDimensions transforms a list of azure dimensions into a list of string, taking in account the DimensionConfig
+// given by the user.
+func filterDimensions(dimensions []*armmonitor.LocalizableString, cfg DimensionsConfig, resourceType, metricName string) []string {
+	// Only skip if explicitly disabled. Enabled by default.
+	if cfg.Enabled != nil && !*cfg.Enabled {
+		return nil
+	}
+
+	// If dimensions are overridden for that resource type and metric name, we take it
+	if _, resourceTypeFound := cfg.Overrides[resourceType]; resourceTypeFound {
+		if newDimensions, metricNameFound := cfg.Overrides[resourceType][metricName]; metricNameFound {
+			return newDimensions
+		}
+	}
+	// Otherwise we get all dimensions
+	var result []string
+	for _, dimension := range dimensions {
+		result = append(result, *dimension.Value)
+	}
+	return result
+}
+
+// serializeDimensions build a comma separated string from trimmed, sorted dimensions list.
+// It is designed to be used as a key in scraper maps.
+func serializeDimensions(dimensions []string) string {
+	var dimensionsSlice []string
+	for _, dimension := range dimensions {
+		if trimmedDimension := strings.TrimSpace(dimension); len(trimmedDimension) > 0 {
+			dimensionsSlice = append(dimensionsSlice, trimmedDimension)
+		}
+	}
+	sort.Strings(dimensionsSlice)
+	return strings.Join(dimensionsSlice, ",")
+}
+
+// buildDimensionsFilter takes a serialized dimensions input to build an Azure Request filter that will allow us to
+// receive metrics values split by these dimensions.
+func buildDimensionsFilter(dimensionsStr string) *string {
+	if len(dimensionsStr) == 0 {
+		return nil
+	}
+	var dimensionsFilter bytes.Buffer
+	dimensions := strings.Split(dimensionsStr, ",")
+	for i, dimension := range dimensions {
+		dimensionsFilter.WriteString(dimension)
+		dimensionsFilter.WriteString(" eq '*'")
+		if i < len(dimensions)-1 {
+			dimensionsFilter.WriteString(" and ")
+		}
+	}
+	result := dimensionsFilter.String()
+	return &result
+}

receiver/azuremonitorreceiver/factory.go

@@ -14,7 +14,6 @@ import (
 	"go.opentelemetry.io/collector/scraper"
 	"go.opentelemetry.io/collector/scraper/scraperhelper"
 
-	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/receiver/azuremonitorreceiver/internal/metadata"
 )
 
@@ -49,7 +48,6 @@ func createDefaultConfig() component.Config {
 		Services:                          monitorServices,
 		Authentication:                    servicePrincipal,
 		Cloud:                             defaultCloud,
-		SplitByDimensions:                 to.Ptr(defaultSplitByDimensions),
 	}
 }
 

receiver/azuremonitorreceiver/factory_test.go

@@ -8,7 +8,6 @@ import (
 	"testing"
 	"time"
 
-	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
 	"github.com/stretchr/testify/require"
 	"go.opentelemetry.io/collector/component"
 	"go.opentelemetry.io/collector/consumer/consumertest"
@@ -49,7 +48,6 @@ func TestNewFactory(t *testing.T) {
 					MaximumNumberOfRecordsPerResource: 10,
 					Authentication:                    servicePrincipal,
 					Cloud:                             defaultCloud,
-					SplitByDimensions:                 to.Ptr(defaultSplitByDimensions),
 				}
 
 				require.Equal(t, expectedCfg, factory.CreateDefaultConfig())