Clarification on Metric Name and Format for system_memory_utilization_ratio

[phaneendra-injarapu]

Component(s)

receiver/hostmetrics

What happened?

Description: system_memory_utilization_ratio reports a ratio (0.0 to 1.0), but the metric name suggests it represents a percentage (0-100).

Steps to Reproduce:

1. Set up the hostmetrics receiver.
2. Query the system_memory_utilization_ratio.
3. Observe that it returns a value between 0.0 and 1.0 (not a percentage).

Expected Result:

• Metric should either be renamed or clarified in the documentation.

ActualResult:

• Either change the metric name to reflect the ratio format (e.g., system_memory_utilization) or update the documentation for clarity.

Collector version

0.123.1

Environment information

Environment

OS: "Windows"

OpenTelemetry Collector configuration

receivers:
  otlp:
    protocols:
      http:
  prometheus/agent:
    config:
      scrape_configs:
        - job_name: otel-collector
          scrape_interval: 10s
          static_configs:
            - targets: [0.0.0.0:8888]
  hostmetrics/agent:
    collection_interval: 10s
    scrapers:
      cpu:
        metrics:
          system.cpu.logical.count:
            enabled: true
      memory:
        metrics:
          system.memory.usage:
            enabled: true
          system.memory.page_size:
            enabled: true
          system.memory.utilization:
            enabled: true
          system.memory.limit:
            enabled: true
      load:
      disk:
      filesystem:
        metrics:
          system.filesystem.utilization:
            enabled: true
      network:
      paging:
      processes:
      process:
        mute_process_user_error: true
        metrics:
          process.cpu.utilization:
            enabled: true
          process.memory.utilization:
            enabled: true
          process.threads:
            enabled: true
          process.paging.faults:
            enabled: true
 
processors:
  batch:
  batch/agent:
  resource/agent:
    attributes:
      - action: upsert
        key: service.namespace
        value: agent-otelcol
  attributes/agent:
    actions:
      - key: service.namespace
        action: upsert
        value: agent-otelcol
      - key: service.name
        action: upsert
        value: otel-collector
  resourcedetection/system:
    detectors: ["system"]
    system:
      hostname_sources: ["os"]
  transform:
    metric_statements:
      - context: datapoint
        statements:
          - set(attributes["host.name"], resource.attributes["host.name"])
          - set(attributes["process.command"], resource.attributes["process.command"])
          - set(attributes["process.command_line"], resource.attributes["process.command_line"])
          - set(attributes["process.executable.name"], resource.attributes["process.executable.name"])
          - set(attributes["process.executable.path"], resource.attributes["process.executable.path"])
          - set(attributes["process.owner"], resource.attributes["process.owner"])
          - set(attributes["process.parent_pid"], resource.attributes["process.parent_pid"])
          - set(attributes["process.pid"], resource.attributes["process.pid"])
 
exporters:
  debug:
    verbosity: detailed
 
  elasticsearch:
    endpoints: ["http://localhost:9200"]
    tls:
      insecure: true
 
  prometheusremotewrite:
    endpoint: "http://localhost:9090/api/v1/write"
    tls:
      insecure: true
 
  loki:
    endpoint: "http://localhost:3100/loki/api/v1/push"
    tls:
      insecure: true
 
  otlphttp/tempo:
    endpoint: "http://localhost:4218"
    tls:
      insecure: true
 
service:
  telemetry:
    metrics:
      address: 0.0.0.0:8888
      level: detailed
 
  pipelines:
    metrics/agent:
      receivers: [prometheus/agent, hostmetrics/agent]
      processors: [attributes/agent, resourcedetection/system, transform, batch/agent]
      exporters: [prometheusremotewrite]
 
    metrics/apm:
      receivers: [otlp]
      processors: [batch/agent]
      exporters: [prometheusremotewrite]
 
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [loki]
 
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/tempo]

Log output

system_memory_utilization_ratio{host_name="HYDPCM683524L", service_name="otel-collector", service_namespace="agent-otelcol", state="used"}	0.728255855998128
system_memory_utilization_ratio{host_name="HYDPCM683524L", service_name="otel-collector", service_namespace="agent-otelcol", state="free"}	0.27174414400187197

Additional context

[github-actions]

Pinging code owners:

• receiver/hostmetrics: @dmitryax @braydonk

See Adding Labels via Comments if you do not have permissions to add labels yourself.

[braydonk]

All utilization metrics follow semantic conventions naming rules (or at least should), and those rules state that utilization metrics are reported as a float value from [0, 1]. https://github.com/open-telemetry/semantic-conventions/blob/95c7f21dca35a99e8d40db622bd5907ce7e44d07/docs/general/naming.md?plain=1#L288

As this metric name already follows that rule, we won't be making any changes here. If there are any existing utilization metrics that actually report a percentage as a whole number rather than a fractional value from [0, 1], they should be changed to follow the rules laid out in semantic conventions.