[EXPORTER] Prometheus exporter: merge metric families across scopes and drop conflicting metric types

Update PrometheusExporterUtils::TranslateToPrometheus to conform to the Metric Metadata section of the OpenTelemetry Prometheus and OpenMetrics compatibility specification:
- Merge metrics across scopes (or unit/suffix-stripped instruments) that map to the same Prometheus metric name and MetricType into a single MetricFamily, retaining the first HELP description and logging a warning on description mismatch.
- Drop metrics that map to an existing Prometheus metric name with a conflicting MetricType and log a warning.

Part of #1841

Author: dashpole

CHANGELOG.md

@@ -15,6 +15,10 @@ Increment the:
 
 ## [Unreleased]
 
+* [EXPORTER] Prometheus exporter: merge metric families across scopes and drop
+  conflicting metric types
+  [#4736](https://github.com/open-telemetry/opentelemetry-cpp/pull/4736)
+
 ## [1.30.0] 2026-10-22
 
 This release contains:

exporters/prometheus/src/exporter_utils.cc

@@ -138,24 +138,55 @@ std::vector<prometheus_client::MetricFamily> PrometheusExporterUtils::TranslateT
               &output);
   }
 
+  std::unordered_map<std::string, std::size_t> family_index_by_name;
+
   for (const auto &instrumentation_info : data.scope_metric_data_)
   {
     for (const auto &metric_data : instrumentation_info.metric_data_)
     {
-      prometheus_client::MetricFamily metric_family;
-      metric_family.help = metric_data.instrument_descriptor.description_;
-      auto front         = metric_data.point_data_attr_.front();
-      auto kind          = getAggregationType(front.point_data);
-      bool is_monotonic  = true;
+      auto front        = metric_data.point_data_attr_.front();
+      auto kind         = getAggregationType(front.point_data);
+      bool is_monotonic = true;
       if (kind == sdk::metrics::AggregationType::kSum)
       {
         is_monotonic = nostd::get<sdk::metrics::SumPointData>(front.point_data).is_monotonic_;
       }
       const prometheus_client::MetricType type = TranslateType(kind, is_monotonic);
-      metric_family.name = MapToPrometheusName(metric_data.instrument_descriptor.name_,
-                                               metric_data.instrument_descriptor.unit_, type,
-                                               without_units, without_type_suffix);
-      metric_family.type = type;
+      const std::string name = MapToPrometheusName(metric_data.instrument_descriptor.name_,
+                                                   metric_data.instrument_descriptor.unit_, type,
+                                                   without_units, without_type_suffix);
+      prometheus_client::MetricFamily *metric_family_ptr = nullptr;
+      auto existing_it                                   = family_index_by_name.find(name);
+      if (existing_it != family_index_by_name.end())
+      {
+        auto &existing_family = output[existing_it->second];
+        if (existing_family.type != type)
+        {
+          OTEL_INTERNAL_LOG_WARN(
+              "[Prometheus Exporter] TranslateToPrometheus - "
+              "Instrument type conflict for metric '"
+              << name << "'. Dropping conflicting metric.");
+          continue;
+        }
+        if (existing_family.help != metric_data.instrument_descriptor.description_)
+        {
+          OTEL_INTERNAL_LOG_WARN(
+              "[Prometheus Exporter] TranslateToPrometheus - "
+              "Instrument description conflict for metric '"
+              << name << "': '" << metric_data.instrument_descriptor.description_
+              << "', using existing description: '" << existing_family.help << "'.");
+        }
+        metric_family_ptr = &existing_family;
+      }
+      else
+      {
+        family_index_by_name.emplace(name, output.size());
+        output.emplace_back();
+        metric_family_ptr       = &output.back();
+        metric_family_ptr->name = name;
+        metric_family_ptr->help = metric_data.instrument_descriptor.description_;
+        metric_family_ptr->type = type;
+      }
       const opentelemetry::sdk::instrumentationscope::InstrumentationScope *scope =
           without_otel_scope ? nullptr : instrumentation_info.scope_;
 
@@ -177,7 +208,7 @@ std::vector<prometheus_client::MetricFamily> PrometheusExporterUtils::TranslateT
             sum = static_cast<double>(nostd::get<int64_t>(histogram_point_data.sum_));
           }
           SetData(std::vector<double>{sum, static_cast<double>(histogram_point_data.count_)},
-                  boundaries, counts, point_data_attr.attributes, scope, &metric_family,
+                  boundaries, counts, point_data_attr.attributes, scope, metric_family_ptr,
                   data.resource_);
         }
         else if (type == prometheus_client::MetricType::Gauge)
@@ -188,15 +219,15 @@ std::vector<prometheus_client::MetricFamily> PrometheusExporterUtils::TranslateT
             auto last_value_point_data =
                 nostd::get<sdk::metrics::LastValuePointData>(point_data_attr.point_data);
             std::vector<metric_sdk::ValueType> values{last_value_point_data.value_};
-            SetData(values, point_data_attr.attributes, scope, type, &metric_family,
+            SetData(values, point_data_attr.attributes, scope, type, metric_family_ptr,
                     data.resource_);
           }
           else if (nostd::holds_alternative<sdk::metrics::SumPointData>(point_data_attr.point_data))
           {
             auto sum_point_data =
                 nostd::get<sdk::metrics::SumPointData>(point_data_attr.point_data);
             std::vector<metric_sdk::ValueType> values{sum_point_data.value_};
-            SetData(values, point_data_attr.attributes, scope, type, &metric_family,
+            SetData(values, point_data_attr.attributes, scope, type, metric_family_ptr,
                     data.resource_);
           }
           else
@@ -213,7 +244,7 @@ std::vector<prometheus_client::MetricFamily> PrometheusExporterUtils::TranslateT
             auto sum_point_data =
                 nostd::get<sdk::metrics::SumPointData>(point_data_attr.point_data);
             std::vector<metric_sdk::ValueType> values{sum_point_data.value_};
-            SetData(values, point_data_attr.attributes, scope, type, &metric_family,
+            SetData(values, point_data_attr.attributes, scope, type, metric_family_ptr,
                     data.resource_);
           }
           else
@@ -224,7 +255,6 @@ std::vector<prometheus_client::MetricFamily> PrometheusExporterUtils::TranslateT
           }
         }
       }
-      output.emplace_back(metric_family);
     }
   }
   return output;

exporters/prometheus/test/exporter_utils_test.cc

@@ -17,6 +17,7 @@
 #include "opentelemetry/nostd/unique_ptr.h"
 #include "opentelemetry/sdk/instrumentationscope/instrumentation_scope.h"
 #include "opentelemetry/sdk/metrics/data/metric_data.h"
+#include "opentelemetry/sdk/metrics/data/point_data.h"
 #include "opentelemetry/sdk/metrics/export/metric_producer.h"
 #include "opentelemetry/sdk/metrics/instruments.h"
 #include "opentelemetry/sdk/resource/resource.h"
@@ -547,4 +548,73 @@ TEST_F(AttributeCollisionTest, DropsInvertedKeys)
                     {"otel_scope_version", "1.2.0"}});
 }
 
+TEST(PrometheusExporterUtils, MultipleScopesMetricFamilyCollisions)
+{
+  Resource resource = Resource::Create(ResourceAttributes{});
+  auto scope1       = InstrumentationScope::Create("scope_1", "1.0.0");
+  auto scope2       = InstrumentationScope::Create("scope_2", "2.0.0");
+  auto scope3       = InstrumentationScope::Create("scope_3", "3.0.0");
+
+  metric_sdk::SumPointData counter_point_1{};
+  counter_point_1.value_        = 10.0;
+  counter_point_1.is_monotonic_ = true;
+
+  metric_sdk::SumPointData counter_point_2{};
+  counter_point_2.value_        = 20.0;
+  counter_point_2.is_monotonic_ = true;
+
+  metric_sdk::LastValuePointData gauge_point_3{};
+  gauge_point_3.value_              = 30.0;
+  gauge_point_3.is_lastvalue_valid_ = true;
+
+  // Scope 1 & Scope 2 emit the same metric name & type, but different descriptions.
+  metric_sdk::MetricData metric_scope_1{
+      metric_sdk::InstrumentDescriptor{"http.requests", "first description", "s",
+                                       metric_sdk::InstrumentType::kCounter,
+                                       metric_sdk::InstrumentValueType::kDouble},
+      metric_sdk::AggregationTemporality::kCumulative, opentelemetry::common::SystemTimestamp{},
+      opentelemetry::common::SystemTimestamp{},
+      std::vector<metric_sdk::PointDataAttributes>{{{{"env", "prod"}}, counter_point_1}}};
+
+  metric_sdk::MetricData metric_scope_2{
+      metric_sdk::InstrumentDescriptor{"http.requests", "conflicting description", "ms",
+                                       metric_sdk::InstrumentType::kCounter,
+                                       metric_sdk::InstrumentValueType::kDouble},
+      metric_sdk::AggregationTemporality::kCumulative, opentelemetry::common::SystemTimestamp{},
+      opentelemetry::common::SystemTimestamp{},
+      std::vector<metric_sdk::PointDataAttributes>{{{{"env", "dev"}}, counter_point_2}}};
+
+  // Scope 3 emits a conflicting type (Gauge) that maps to the same Prometheus name when
+  // without_units=true and without_type_suffix=true.
+  metric_sdk::MetricData metric_scope_3_conflict_type{
+      metric_sdk::InstrumentDescriptor{"http_requests", "gauge description", "1",
+                                       metric_sdk::InstrumentType::kObservableGauge,
+                                       metric_sdk::InstrumentValueType::kDouble},
+      metric_sdk::AggregationTemporality::kCumulative, opentelemetry::common::SystemTimestamp{},
+      opentelemetry::common::SystemTimestamp{},
+      std::vector<metric_sdk::PointDataAttributes>{{{{"env", "stage"}}, gauge_point_3}}};
+
+  metric_sdk::ResourceMetrics data{
+      &resource,
+      std::vector<metric_sdk::ScopeMetrics>{
+          {scope1.get(), std::vector<metric_sdk::MetricData>{metric_scope_1}},
+          {scope2.get(), std::vector<metric_sdk::MetricData>{metric_scope_2}},
+          {scope3.get(), std::vector<metric_sdk::MetricData>{metric_scope_3_conflict_type}}}};
+
+  // With without_units=true and without_type_suffix=true, all three map to "http_requests".
+  // Scope 1 and Scope 2 (both Counter) should be merged into a single MetricFamily keeping
+  // "first description", while Scope 3 (Gauge) should be dropped due to type conflict.
+  auto translated = PrometheusExporterUtils::TranslateToPrometheus(
+      data, /*populate_target_info=*/false, /*without_otel_scope=*/false,
+      /*without_units=*/true, /*without_type_suffix=*/true);
+
+  ASSERT_EQ(translated.size(), 1U);
+  EXPECT_EQ(translated[0].name, "http_requests");
+  EXPECT_EQ(translated[0].help, "first description");
+  EXPECT_EQ(translated[0].type, prometheus_client::MetricType::Counter);
+  ASSERT_EQ(translated[0].metric.size(), 2U);
+  EXPECT_DOUBLE_EQ(translated[0].metric[0].counter.value, 10.0);
+  EXPECT_DOUBLE_EQ(translated[0].metric[1].counter.value, 20.0);
+}
+
 OPENTELEMETRY_END_NAMESPACE