[receiver/hostmetrics] Add optional system.linux.memory.available metric (open-telemetry#27247)

Implement a new metric `system.linux.memory.available`,
which I defined in
open-telemetry/semantic-conventions#257.

**Link to tracking Issue:**
open-telemetry#7417

**Testing:** added a check to an existing unit test. I had to refactor
the test a bit: it assumed that a certain metric will be at position 0,
which is not true now.

**Documentation:** Added note in `metadata.yaml`

---------

Co-authored-by: Curtis Robert <[email protected]>

Author: 2 people

.chloggen/system_linux_memory_available.yaml

@@ -0,0 +1,32 @@
+# 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. filelogreceiver)
+component: hostmetricsreceiver
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add optional Linux-only metric `system.linux.memory.available`
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [7417]
+
+# (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 is an alternative to `system.memory.usage` metric with `state=free`.
+      Linux starting from 3.14 exports "available" memory. It takes "free" memory as a baseline, and then factors in kernel-specific values.
+      This is supposed to be more accurate than just "free" memory.
+      For reference, see the calculations [here](https://superuser.com/a/980821).
+      See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html).
+
+# 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: [user]

receiver/hostmetricsreceiver/internal/scraper/memoryscraper/documentation.md

@@ -38,6 +38,14 @@ metrics:
     enabled: true
 ```
 
+### system.linux.memory.available
+
+An estimate of how much memory is available for starting new applications, without swapping. This is a more accurate alternative than system.memory.usage with state=free. (Linux only)
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic |
+| ---- | ----------- | ---------- | ----------------------- | --------- |
+| By | Sum | Int | Cumulative | false |
+
 ### system.memory.utilization
 
 Percentage of memory bytes in use.

receiver/hostmetricsreceiver/internal/scraper/memoryscraper/internal/metadata/generated_config.go

@@ -1,12 +1,16 @@
 default:
 all_set:
   metrics:
+    system.linux.memory.available:
+      enabled: true
     system.memory.usage:
       enabled: true
     system.memory.utilization:
       enabled: true
 none_set:
   metrics:
+    system.linux.memory.available:
+      enabled: false
     system.memory.usage:
       enabled: false
     system.memory.utilization:

receiver/hostmetricsreceiver/internal/scraper/memoryscraper/internal/metadata/generated_config_test.go

@@ -69,6 +69,7 @@ func (s *scraper) scrape(ctx context.Context) (pmetric.Metrics, error) {
 				memInfo.Total), metricsLen)
 		}
 		s.recordMemoryUtilizationMetric(now, memInfo)
+		s.recordSystemSpecificMetrics(now, memInfo)
 	}
 
 	return s.mb.Emit(), nil

receiver/hostmetricsreceiver/internal/scraper/memoryscraper/internal/metadata/generated_metrics.go

@@ -30,3 +30,11 @@ func (s *scraper) recordMemoryUtilizationMetric(now pcommon.Timestamp, memInfo *
 	s.mb.RecordSystemMemoryUtilizationDataPoint(now, float64(memInfo.Sreclaimable)/float64(memInfo.Total), metadata.AttributeStateSlabReclaimable)
 	s.mb.RecordSystemMemoryUtilizationDataPoint(now, float64(memInfo.Sunreclaim)/float64(memInfo.Total), metadata.AttributeStateSlabUnreclaimable)
 }
+
+func (s *scraper) recordLinuxMemoryAvailableMetric(now pcommon.Timestamp, memInfo *mem.VirtualMemoryStat) {
+	s.mb.RecordSystemLinuxMemoryAvailableDataPoint(now, int64(memInfo.Available))
+}
+
+func (s *scraper) recordSystemSpecificMetrics(now pcommon.Timestamp, memInfo *mem.VirtualMemoryStat) {
+	s.recordLinuxMemoryAvailableMetric(now, memInfo)
+}

receiver/hostmetricsreceiver/internal/scraper/memoryscraper/internal/metadata/generated_metrics_test.go

@@ -24,3 +24,6 @@ func (s *scraper) recordMemoryUtilizationMetric(now pcommon.Timestamp, memInfo *
 	s.mb.RecordSystemMemoryUtilizationDataPoint(now, float64(memInfo.Free)/float64(memInfo.Total), metadata.AttributeStateFree)
 	s.mb.RecordSystemMemoryUtilizationDataPoint(now, float64(memInfo.Inactive)/float64(memInfo.Total), metadata.AttributeStateInactive)
 }
+
+func (s *scraper) recordSystemSpecificMetrics(now pcommon.Timestamp, memInfo *mem.VirtualMemoryStat) {
+}

receiver/hostmetricsreceiver/internal/scraper/memoryscraper/internal/metadata/testdata/config.yaml

@@ -52,10 +52,18 @@ func TestScrape(t *testing.T) {
 						SystemMemoryUsage: metadata.MetricConfig{
 							Enabled: true,
 						},
+						SystemLinuxMemoryAvailable: metadata.MetricConfig{
+							Enabled: true,
+						},
 					},
 				},
 			},
-			expectedMetricCount: 2,
+			expectedMetricCount: func() int {
+				if runtime.GOOS == "linux" {
+					return 3
+				}
+				return 2
+			}(),
 		},
 		{
 			name:              "Error",
@@ -112,12 +120,19 @@ func TestScrape(t *testing.T) {
 			assert.Equal(t, test.expectedMetricCount, md.MetricCount())
 
 			metrics := md.ResourceMetrics().At(0).ScopeMetrics().At(0).Metrics()
-			assertMemoryUsageMetricValid(t, metrics.At(0), "system.memory.usage")
+			memUsageIdx := -1
+			for i := 0; i < md.MetricCount(); i++ {
+				if metrics.At(i).Name() == "system.memory.usage" {
+					memUsageIdx = i
+				}
+			}
+			assert.NotEqual(t, memUsageIdx, -1)
+			assertMemoryUsageMetricValid(t, metrics.At(memUsageIdx), "system.memory.usage")
 
 			if runtime.GOOS == "linux" {
-				assertMemoryUsageMetricHasLinuxSpecificStateLabels(t, metrics.At(0))
+				assertMemoryUsageMetricHasLinuxSpecificStateLabels(t, metrics.At(memUsageIdx))
 			} else if runtime.GOOS != "windows" {
-				internal.AssertSumMetricHasAttributeValue(t, metrics.At(0), 2, "state",
+				internal.AssertSumMetricHasAttributeValue(t, metrics.At(memUsageIdx), 2, "state",
 					pcommon.NewValueStr(metadata.AttributeStateInactive.String()))
 			}
 

receiver/hostmetricsreceiver/internal/scraper/memoryscraper/memory_scraper.go

@@ -22,3 +22,6 @@ func (s *scraper) recordMemoryUtilizationMetric(now pcommon.Timestamp, memInfo *
 	s.mb.RecordSystemMemoryUtilizationDataPoint(now, float64(memInfo.Used)/float64(memInfo.Total), metadata.AttributeStateUsed)
 	s.mb.RecordSystemMemoryUtilizationDataPoint(now, float64(memInfo.Free)/float64(memInfo.Total), metadata.AttributeStateFree)
 }
+
+func (s *scraper) recordSystemSpecificMetrics(now pcommon.Timestamp, memInfo *mem.VirtualMemoryStat) {
+}

receiver/hostmetricsreceiver/internal/scraper/memoryscraper/memory_scraper_linux.go

@@ -28,3 +28,12 @@ metrics:
     gauge:
       value_type: double
     attributes: [state]
+
+  system.linux.memory.available:
+    enabled: false
+    description: An estimate of how much memory is available for starting new applications, without swapping. This is a more accurate alternative than system.memory.usage with state=free. (Linux only)
+    unit: By
+    sum:
+      value_type: int
+      aggregation_temporality: cumulative
+      monotonic: false