The purpose and use-cases of the new component

The BMC Helix Exporter will transmit metrics from the OpenTelemetry Collector to BMC Helix Operations Management platform. It is designed to meet BMC Helix’s specific requirements on how data (metrics) is sent through the BMC Helix REST API and entity mapping standards.

Use Cases:

1. Metrics Integration:
   Organizations using BMC Helix Operations Management would be able to integrate metrics received by the OpenTelemetry Collector.

2. Attributes to BMC Helix Mapping:
   The exporter should dynamically map attributes (e.g., host.name, service.name, name, id) to BMC Helix's labels. The exporter should not implement any logic to determine the values for the mandatory labels (attributes required by BMC Helix) entityName or entityTypeId; it should only ensure that these two labels are available for a given metric. This guarantees that the payload is accepted by BMC Helix and avoids rejection due to missing fields.
   BMC Helix Metrics payload example:

    [
     {
       "labels": {
         "isDeviceMappingEnabled": true,
         "entityId": "OTEL:server1:battery_cont:battery_container",
         "entityName": "battery_container",
         "entityTypeId": "battery_container",
         "hostType": "server",
         "hostname": "server1",
         "metricName": "identity",
         "source": "OTEL"
       },
       "samples": []
       },
       {
       "labels": {
         "isDeviceMappingEnabled": true,
         "entityId": "OTEL:server1:battery:battery1",
         "entityName": "battery1",
         "entityTypeId": "battery",
         "parentEntityName": "battery_container",
         "parentEntityTypeId": "battery_container",
         "hostType": "server",
         "hostname": "server1",
         "metricName": "hw.status.ok",
         "instanceName": "Battery 1",
         "source": "OTEL"
       },
       "samples": [{ "value": 1, "timestamp": 1733133695000 }]
     },
     {
       "labels": {
         "isDeviceMappingEnabled": true,
         "entityId": "OTEL:server1:battery:battery2",
         "entityName": "battery2",
         "entityTypeId": "battery",
         "parentEntityName": "battery_container",
         "parentEntityTypeId": "battery_container",
         "hostType": "server",
         "hostname": "server1",
         "metricName": "hw.status.ok",
         "instanceName": "Battery 2",
         "source": "OTEL"
       },
       "samples": [{ "value": 1, "timestamp": 1733133695000 }]
     }
   ]

3. Customization and Flexibility:

   • Users would have the ability to customize metric transformations using OpenTelemetry Transformation Language (OTTL) via the transformprocessor, for instance, to manage the mandatory labels entityName and entityTypeId.
   • The exporter would support optional retry mechanisms and timeout settings to ensure reliability in metric delivery.

Example configuration for the component

The following settings are required:

• endpoint: is the URL of your BMC Helix environment, at onbmc.com (e.g., https://company.onbmc.com).
• 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.

Example:

exporters:
  bmchelix/helix1:
    endpoint: https://company.onbmc.com
    api_key: <api-key>

Optional Settings

The following settings can be optionally configured:

• timeout: (default = 10s) Timeout for requests made to the BMC Helix.
• retry_on_failure:
  • enabled (default = false): Enables retries for failed requests.
  • initial_interval (default = 5s): The time to wait after the first failure before retrying.
  • randomization_factor (default = 0.5): Random factor used to calculate next backoffs.
  • multiplier (default = 1.5): The value multiplied by the backoff interval bounds.
  • max_interval (default = 30s): The upper bound on backoff interval.
  • max_elapsed_time (default = 5m): The maximum amount of time (including retries) spent trying to send a request.
• resource_to_telemetry_conversion:
  • enabled (default = true): Converts resource attributes to telemetry attributes

Example:

exporters:
  bmchelix/helix2:
    endpoint: https://company.onbmc.com
    api_key: <api-key>
    timeout: 20s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      randomization_factor: 0.5
      multiplier: 8.0
      max_interval: 1m
      max_elapsed_time: 8m
    resource_to_telemetry_conversion:
      enabled: true

Telemetry data types supported

• Metrics (to BMC Helix Operations Management)
• Logs (to BMC Helix Logs Analytics) [FUTURE]
• Traces (to BMC Netreo Stackify) [FUTURE]

Code Owner(s)

@bertysentry, @NassimBtk

Sponsor (optional)

• @MovieStoreGuy
• @fatsheep9146

Additional context

• The exporter will handle the supported metric types: MetricTypeSum and MetricTypeGauge.
• It will use an HTTP client to connect to the BMC Helix REST API.
• Sentry Software specializes in developing software that integrates with BMC Helix. Therefore, the necessary tools and expertise are available to test and validate the exporter within a BMC Helix environment.