README.md

BMC Helix Exporter

Status
Stability	alpha: metrics
Distributions	contrib
Issues
Code coverage
Code Owners	@bertysentry, @NassimBtk, @MovieStoreGuy

This exporter supports sending metrics to BMC Helix Operations Management through its metric ingestion REST API.

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.

Example:

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

Optional Settings

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
  • enabled (default = true)
  • initial_interval (default = 5s) Time to wait after the first failure before retrying; ignored if enabled is false.
  • max_interval (default = 30s) The upper bound on backoff; ignored if enabled is false.
  • max_elapsed_time (default = 300s) The maximum amount of time spent trying to send a batch; ignored if enabled is false. If set to 0, the retries are never stopped.

Example:

exporters:
  bmchelix/helix2:
    endpoint: https://company.onbmc.com
    api_key: <api-key>
    timeout: 20s
    enrich_metric_with_attributes: false
    sending_queue:
      batch:
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 1m
      max_elapsed_time: 8m

---

Setting Required Attributes for Metrics

To ensure metrics are correctly populated in BMC Helix, the following attributes must be set either at the Resource level, or at the Metric level:

• entityName: Unique identifier for the entity. Used as display name if instanceName is missing.
• entityTypeId: Type identifier for the entity.
• instanceName: Display name of the entity.

Note: If entityName or entityTypeId is missing, the metric will not be exported.

To ensure the necessary attributes are present, it is recommended to leverage the transform processor with OTTL, and include it in the configuration of the telemetry pipeline.

The minimal pipeline most often looks like: OTEL metrics --> (memory limit) --> transform processor --> bmchelix exporter.

Transformer Example for Hardware Metrics

You can use the following OpenTelemetry Transformation Language (OTTL) configuration to map these attributes dynamically:

  transform/hw_to_helix:
   # Apply transformations to all metrics
    metric_statements:

      - context: datapoint
        statements:
          # Create a new attribute 'entityName' with the value of 'id'
          - set(attributes["entityName"], attributes["id"]) where attributes["id"] != nil
          # Create a new attribute 'instanceName' with the value of 'name'
          - set(attributes["instanceName"], attributes["name"]) where attributes["name"] != nil

      - context: datapoint
        conditions:
          - IsMatch(metric.name, ".*\\.agent\\..*")
        statements:
          - set(attributes["entityName"], attributes["host.id"]) where attributes["host.id"] != nil
          - set(attributes["instanceName"], attributes["service.name"]) where attributes["service.name"] != nil
          - set(attributes["entityTypeId"], "agent")

      - context: datapoint
        statements:
          # Mapping entityTypeId based on metric names and attributes
          - set(attributes["entityTypeId"], "connector") where IsMatch(metric.name, ".*\\.connector\\..*")
          - set(attributes["entityTypeId"], "host") where IsMatch(metric.name, ".*\\.host\\..*") or attributes["hw.type"] == "host"
          - set(attributes["entityTypeId"], "battery") where IsMatch(metric.name, "hw\\.battery\\..*") or attributes["hw.type"] == "battery"
          - set(attributes["entityTypeId"], "blade") where IsMatch(metric.name, "hw\\.blade\\..*") or attributes["hw.type"] == "blade"
          - set(attributes["entityTypeId"], "cpu") where IsMatch(metric.name, "hw\\.cpu\\..*") or attributes["hw.type"] == "cpu"
          - set(attributes["entityTypeId"], "disk_controller") where IsMatch(metric.name, "hw\\.disk_controller\\..*") or attributes["hw.type"] == "disk_controller"
          - set(attributes["entityTypeId"], "enclosure") where IsMatch(metric.name, "hw\\.enclosure\\..*") or attributes["hw.type"] == "enclosure"
          - set(attributes["entityTypeId"], "fan") where IsMatch(metric.name, "hw\\.fan\\..*") or attributes["hw.type"] == "fan"
          - set(attributes["entityTypeId"], "gpu") where IsMatch(metric.name, "hw\\.gpu\\..*") or attributes["hw.type"] == "gpu"
          - set(attributes["entityTypeId"], "led") where IsMatch(metric.name, "hw\\.led\\..*") or attributes["hw.type"] == "led"
          - set(attributes["entityTypeId"], "logical_disk") where IsMatch(metric.name, "hw\\.logical_disk\\..*") or attributes["hw.type"] == "logical_disk"
          - set(attributes["entityTypeId"], "lun") where IsMatch(metric.name, "hw\\.lun\\..*") or attributes["hw.type"] == "lun"
          - set(attributes["entityTypeId"], "memory") where IsMatch(metric.name, "hw\\.memory\\..*") or attributes["hw.type"] == "memory"
          - set(attributes["entityTypeId"], "network") where IsMatch(metric.name, "hw\\.network\\..*") or attributes["hw.type"] == "network"
          - set(attributes["entityTypeId"], "other_device") where IsMatch(metric.name, "hw\\.other_device\\..*") or attributes["hw.type"] == "other_device"
          - set(attributes["entityTypeId"], "physical_disk") where IsMatch(metric.name, "hw\\.physical_disk\\..*") or attributes["hw.type"] == "physical_disk"
          - set(attributes["entityTypeId"], "power_supply") where IsMatch(metric.name, "hw\\.power_supply\\..*") or attributes["hw.type"] == "power_supply"
          - set(attributes["entityTypeId"], "robotics") where IsMatch(metric.name, "hw\\.robotics\\..*") or attributes["hw.type"] == "robotics"
          - set(attributes["entityTypeId"], "tape_drive") where IsMatch(metric.name, "hw\\.tape_drive\\..*") or attributes["hw.type"] == "tape_drive"
          - set(attributes["entityTypeId"], "temperature") where IsMatch(metric.name, "hw\\.temperature.*") or attributes["hw.type"] == "temperature"
          - set(attributes["entityTypeId"], "vm") where IsMatch(metric.name, "hw\\.vm\\..*") or attributes["hw.type"] == "vm"
          - set(attributes["entityTypeId"], "voltage") where IsMatch(metric.name, "hw\\.voltage.*") or attributes["hw.type"] == "voltage"

This transformer dynamically sets the attributes required for BMC Helix based on metric names and resource attributes.