[exporter/bmchelix] Enrich metric names with datapoint attributes

.chloggen/bmchelix-enrich-metric-names.yaml

@@ -0,0 +1,33 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. receiver/filelog)
+component: exporter/bmchelix
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Enrich metric names with datapoint attributes for unique identification in BMC Helix Operations Management
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [46558]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  This feature is controlled by the `enrich_metric_with_attributes` configuration option (default: `true`).
+  Set to `false` to disable enrichment and reduce metric cardinality.
+  Normalization is applied to ensure BHOM compatibility:
+  - `entityTypeId` and `entityName`: Invalid characters replaced with underscores (colons not allowed as they are used as separators in entityId)
+  - `metricName`: Normalized to match pattern `[a-zA-Z_:.][a-zA-Z0-9_:.]*`
+  - Label values: Commas replaced with whitespaces
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

exporter/bmchelixexporter/README.md

@@ -12,14 +12,14 @@
 [contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib
 <!-- end autogenerated section -->
 
-This exporter supports sending metrics to [BMC Helix Operations Management](https://www.bmc.com/it-solutions/bmc-helix-operations-management.html) through its [metric ingestion REST API](https://docs.bmc.com/docs/helixoperationsmanagement/244/en/metric-operation-management-endpoints-in-the-rest-api-1392780044.html).
+This exporter supports sending metrics to [BMC Helix Operations Management](https://docs.bmc.com/xwiki/bin/view/IT-Operations-Management/Operations-Management/BMC-Helix-Operations-Management/bhom261/Getting-started/Product-overview/) through its [metric ingestion REST API](https://docs.bmc.com/docs/helixoperationsmanagement/244/en/metric-operation-management-endpoints-in-the-rest-api-1392780044.html).
 
 ## Getting Started
 
 The following settings are **required**:
 
 - `endpoint`: is the *BMC Helix Portal URL* of your environment, at **onbmc.com** for a BMC Helix SaaS tenant (e.g., `https://company.onbmc.com`), or your own Helix Portal URL for an on-prem instance.
-- `api_key`: API key to authenticate the exporter. Connect to BMC Helix Operations Management, go to the Administration > Repository page, and click on the Copy API Key button to get your API Key. Alternatively, it is recommended to create and use a dedicated [authentication key for external integration](https://docs.bmc.com/docs/helixportal244/using-api-keys-for-external-integrations-1391501992.html).
+- `api_key`: API key to authenticate the exporter. Connect to BMC Helix Operations Management, go to the Administration > Repository page, and click on the Copy API Key button to get your API Key. Alternatively, it is recommended to create and use a dedicated [authentication key for external integration](https://docs.bmc.com/xwiki/bin/view/Helix-Common-Services/BMC-Helix-Portal/BMC-Helix-Portal/helixportal261/Administering/Using-API-keys-for-external-integrations/).
 
 Example:
 
@@ -37,6 +37,7 @@ exporters:
 The following settings can be **optionally configured**:
 
 - `timeout`: (default = `10s`) Timeout for requests made to the BMC Helix.
+- `enrich_metric_with_attributes`: (default = `true`) When enabled, creates enriched metrics by appending datapoint attribute values to the metric name. This provides more detailed identification in BMC Helix Operations Management but increases metric cardinality. Set to `false` to reduce the number of unique metric series.
 - `retry_on_failure` [details here](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/exporterhelper#configuration)
   - `enabled` (default = true)
   - `initial_interval` (default = 5s) Time to wait after the first failure before retrying; ignored if `enabled` is false.
@@ -51,6 +52,7 @@ exporters:
     endpoint: https://company.onbmc.com
     api_key: <api-key>
     timeout: 20s
+    enrich_metric_with_attributes: false
     sending_queue:
       batch:
     retry_on_failure:

exporter/bmchelixexporter/config.go

@@ -14,8 +14,17 @@ import (
 // Config struct is used to store the configuration of the exporter
 type Config struct {
 	confighttp.ClientConfig `mapstructure:",squash"`
-	APIKey                  configopaque.String       `mapstructure:"api_key"`
-	RetryConfig             configretry.BackOffConfig `mapstructure:"retry_on_failure"`
+	// APIKey authenticates requests to BMC Helix Operations Management.
+	// Connect to BMC Helix Operations Management, go to the Administration > Repository page, and
+	// click on the Copy API Key button to get your API Key.
+	// Alternatively, it is recommended to create and use a dedicated authentication key for external integration:
+	// https://docs.bmc.com/xwiki/bin/view/Helix-Common-Services/BMC-Helix-Portal/BMC-Helix-Portal/helixportal261/Administering/Using-API-keys-for-external-integrations/
+	APIKey      configopaque.String       `mapstructure:"api_key"`
+	RetryConfig configretry.BackOffConfig `mapstructure:"retry_on_failure"`
+	// EnrichMetricWithAttributes enables enriched metric creation by appending datapoint
+	// attribute values to the metric name. This increases metric cardinality but provides
+	// more detailed identification in BMC Helix Operations Management. Default is true.
+	EnrichMetricWithAttributes bool `mapstructure:"enrich_metric_with_attributes"`
 }
 
 // validate the configuration

exporter/bmchelixexporter/config.schema.yaml

@@ -2,7 +2,11 @@ description: Config struct is used to store the configuration of the exporter
 type: object
 properties:
   api_key:
+    description: 'APIKey authenticates requests to BMC Helix Operations Management. Connect to BMC Helix Operations Management, go to the Administration > Repository page, and click on the Copy API Key button to get your API Key. Alternatively, it is recommended to create and use a dedicated authentication key for external integration: https://docs.bmc.com/xwiki/bin/view/Helix-Common-Services/BMC-Helix-Portal/BMC-Helix-Portal/helixportal261/Administering/Using-API-keys-for-external-integrations/'
     $ref: go.opentelemetry.io/collector/config/configopaque.string
+  enrich_metric_with_attributes:
+    description: EnrichMetricWithAttributes enables enriched metric creation by appending datapoint attribute values to the metric name. This increases metric cardinality but provides more detailed identification in BMC Helix Operations Management. Default is true.
+    type: boolean
   retry_on_failure:
     $ref: go.opentelemetry.io/collector/config/configretry.back_off_config
 allOf:

exporter/bmchelixexporter/config_test.go

@@ -33,9 +33,10 @@ func TestLoadConfig(t *testing.T) {
 		{
 			id: component.NewIDWithName(metadata.Type, "helix1"),
 			expected: &Config{
-				ClientConfig: createDefaultClientConfig("https://helix1:8080", 10*time.Second),
-				APIKey:       "api_key",
-				RetryConfig:  configretry.NewDefaultBackOffConfig(),
+				ClientConfig:               createDefaultClientConfig("https://helix1:8080", 10*time.Second),
+				APIKey:                     "api_key",
+				RetryConfig:                configretry.NewDefaultBackOffConfig(),
+				EnrichMetricWithAttributes: true,
 			},
 		},
 		{
@@ -51,6 +52,7 @@ func TestLoadConfig(t *testing.T) {
 					MaxInterval:         1 * time.Minute,
 					MaxElapsedTime:      8 * time.Minute,
 				},
+				EnrichMetricWithAttributes: true,
 			},
 		},
 	}

exporter/bmchelixexporter/exporter_metrics.go

@@ -61,7 +61,7 @@ func (me *metricsExporter) start(ctx context.Context, host component.Host) error
 	me.logger.Info("Starting BMC Helix Metrics Exporter")
 
 	// Initialize and store the MetricsProducer
-	me.producer = om.NewMetricsProducer(me.logger)
+	me.producer = om.NewMetricsProducer(me.logger, me.config.EnrichMetricWithAttributes)
 
 	// Initialize and store the MetricsClient
 	client, err := om.NewMetricsClient(ctx, me.config.ClientConfig, me.config.APIKey, host, me.telemetrySettings, me.logger)

exporter/bmchelixexporter/factory.go

@@ -31,8 +31,9 @@ func createDefaultConfig() component.Config {
 	httpClientConfig.Timeout = 10 * time.Second
 
 	return &Config{
-		ClientConfig: httpClientConfig,
-		RetryConfig:  configretry.NewDefaultBackOffConfig(),
+		ClientConfig:               httpClientConfig,
+		RetryConfig:                configretry.NewDefaultBackOffConfig(),
+		EnrichMetricWithAttributes: true,
 	}
 }