Add support for custom MR mappings (#346)

* Add support for custom MR mappings

* Add missing Javadoc for MonitoredResourceMapping

* Add unit tests for custom MR mappings

* Update platform metric mapping logic and rename MonitoredResourceDescription

* fix values in unit test

* Add unit test for no labels

* refactor: convert to unmodifieable set in constructor

* Add unit test for empty resource attributes

* remove redundant reference to this

* update formatting; add missing Javadoc

* Add warning message for MR type mismatch

* Update label name in test to avoid confusion

* rename DEFAULT_MONITORED_RESOURCE_DESCRIPTION -> EMPTY_MONITORED_RESOURCE_DESCRIPTION

* Set MR labels only if found

exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/AggregateByLabelMetricTimeSeriesBuilder.java

@@ -59,19 +59,34 @@ public final class AggregateByLabelMetricTimeSeriesBuilder implements MetricTime
   private final String projectId;
   private final String prefix;
   private final Predicate<AttributeKey<?>> resourceAttributeFilter;
+  private final MonitoredResourceDescription monitoredResourceDescription;
 
   @Deprecated
   public AggregateByLabelMetricTimeSeriesBuilder(String projectId, String prefix) {
     this.projectId = projectId;
     this.prefix = prefix;
     this.resourceAttributeFilter = MetricConfiguration.NO_RESOURCE_ATTRIBUTES;
+    this.monitoredResourceDescription = MetricConfiguration.EMPTY_MONITORED_RESOURCE_DESCRIPTION;
   }
 
+  @Deprecated
   public AggregateByLabelMetricTimeSeriesBuilder(
       String projectId, String prefix, Predicate<AttributeKey<?>> resourceAttributeFilter) {
     this.projectId = projectId;
     this.prefix = prefix;
     this.resourceAttributeFilter = resourceAttributeFilter;
+    this.monitoredResourceDescription = MetricConfiguration.EMPTY_MONITORED_RESOURCE_DESCRIPTION;
+  }
+
+  public AggregateByLabelMetricTimeSeriesBuilder(
+      String projectId,
+      String prefix,
+      Predicate<AttributeKey<?>> resourceAttributeFilter,
+      MonitoredResourceDescription monitoredResourceDescription) {
+    this.projectId = projectId;
+    this.prefix = prefix;
+    this.resourceAttributeFilter = resourceAttributeFilter;
+    this.monitoredResourceDescription = monitoredResourceDescription;
   }
 
   @Override
@@ -135,7 +150,7 @@ private TimeSeries.Builder makeTimeSeriesHeader(
     return TimeSeries.newBuilder()
         .setMetric(mapMetric(attributes, descriptor.getType()))
         .setMetricKind(descriptor.getMetricKind())
-        .setResource(mapResource(metric.getResource()));
+        .setResource(mapResource(metric.getResource(), monitoredResourceDescription));
   }
 
   private Attributes extraLabelsFromResource(Resource resource) {

exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/InternalMetricExporter.java

@@ -68,20 +68,23 @@ class InternalMetricExporter implements MetricExporter {
   private final MetricDescriptorStrategy metricDescriptorStrategy;
   private final Predicate<AttributeKey<?>> resourceAttributesFilter;
   private final boolean useCreateServiceTimeSeries;
+  private final MonitoredResourceDescription monitoredResourceDescription;
 
   InternalMetricExporter(
       String projectId,
       String prefix,
       CloudMetricClient client,
       MetricDescriptorStrategy descriptorStrategy,
       Predicate<AttributeKey<?>> resourceAttributesFilter,
-      boolean useCreateServiceTimeSeries) {
+      boolean useCreateServiceTimeSeries,
+      MonitoredResourceDescription monitoredResourceDescription) {
     this.projectId = projectId;
     this.prefix = prefix;
     this.metricServiceClient = client;
     this.metricDescriptorStrategy = descriptorStrategy;
     this.resourceAttributesFilter = resourceAttributesFilter;
     this.useCreateServiceTimeSeries = useCreateServiceTimeSeries;
+    this.monitoredResourceDescription = monitoredResourceDescription;
   }
 
   static InternalMetricExporter createWithConfiguration(MetricConfiguration configuration)
@@ -120,7 +123,8 @@ static InternalMetricExporter createWithConfiguration(MetricConfiguration config
         new CloudMetricClientImpl(MetricServiceClient.create(builder.build())),
         configuration.getDescriptorStrategy(),
         configuration.getResourceAttributesFilter(),
-        configuration.getUseServiceTimeSeries());
+        configuration.getUseServiceTimeSeries(),
+        configuration.getMonitoredResourceDescription());
   }
 
   @VisibleForTesting
@@ -130,14 +134,16 @@ static InternalMetricExporter createWithClient(
       CloudMetricClient metricServiceClient,
       MetricDescriptorStrategy descriptorStrategy,
       Predicate<AttributeKey<?>> resourceAttributesFilter,
-      boolean useCreateServiceTimeSeries) {
+      boolean useCreateServiceTimeSeries,
+      MonitoredResourceDescription monitoredResourceDescription) {
     return new InternalMetricExporter(
         projectId,
         prefix,
         metricServiceClient,
         descriptorStrategy,
         resourceAttributesFilter,
-        useCreateServiceTimeSeries);
+        useCreateServiceTimeSeries,
+        monitoredResourceDescription);
   }
 
   private void exportDescriptor(MetricDescriptor descriptor) {
@@ -161,7 +167,8 @@ public CompletableResultCode export(Collection<MetricData> metrics) {
     // 2. Attempt to register MetricDescriptors (using configured strategy)
     // 3. Fire the set of time series off.
     MetricTimeSeriesBuilder builder =
-        new AggregateByLabelMetricTimeSeriesBuilder(projectId, prefix, resourceAttributesFilter);
+        new AggregateByLabelMetricTimeSeriesBuilder(
+            projectId, prefix, resourceAttributesFilter, monitoredResourceDescription);
     for (final MetricData metricData : metrics) {
       // Extract all the underlying points.
       switch (metricData.getType()) {

exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricConfiguration.java

@@ -28,6 +28,7 @@
 import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.semconv.ResourceAttributes;
 import java.time.Duration;
+import java.util.Collections;
 import java.util.List;
 import java.util.function.Predicate;
 import java.util.function.Supplier;
@@ -45,6 +46,9 @@ public abstract class MetricConfiguration {
   /** Resource attribute filter that disables addition of resource attributes to metric labels. */
   public static final Predicate<AttributeKey<?>> NO_RESOURCE_ATTRIBUTES = attributeKey -> false;
 
+  public static final MonitoredResourceDescription EMPTY_MONITORED_RESOURCE_DESCRIPTION =
+      new MonitoredResourceDescription("", Collections.emptySet());
+
   /**
    * Default resource attribute filter that adds recommended resource attributes to metric labels.
    */
@@ -151,6 +155,19 @@ public final String getProjectId() {
    */
   public abstract boolean getUseServiceTimeSeries();
 
+  /**
+   * Returns the custom {@link MonitoredResourceDescription} that is used to map the OpenTelemetry
+   * {@link io.opentelemetry.sdk.resources.Resource} to Google specific {@link
+   * com.google.api.MonitoredResource}.
+   *
+   * <p>This returns the {@link MetricConfiguration#EMPTY_MONITORED_RESOURCE_DESCRIPTION} if not set
+   * through exporter configuration.
+   *
+   * @return The {@link MonitoredResourceDescription} object containing the MonitoredResource type
+   *     and its expected labels.
+   */
+  public abstract MonitoredResourceDescription getMonitoredResourceDescription();
+
   @VisibleForTesting
   abstract boolean getInsecureEndpoint();
 
@@ -176,6 +193,7 @@ public static Builder builder() {
         .setInsecureEndpoint(false)
         .setUseServiceTimeSeries(false)
         .setResourceAttributesFilter(DEFAULT_RESOURCE_ATTRIBUTES_FILTER)
+        .setMonitoredResourceDescription(EMPTY_MONITORED_RESOURCE_DESCRIPTION)
         .setMetricServiceEndpoint(MetricServiceStubSettings.getDefaultEndpoint());
   }
 
@@ -238,6 +256,19 @@ public final Builder setProjectId(String projectId) {
      */
     public abstract Builder setUseServiceTimeSeries(boolean useServiceTimeSeries);
 
+    /**
+     * Sets the {@link MonitoredResourceDescription} that is used to map OpenTelemetry {@link
+     * io.opentelemetry.sdk.resources.Resource}s to Google specific {@link
+     * com.google.api.MonitoredResource}s.
+     *
+     * @param monitoredResourceDescription the {@link MonitoredResourceDescription} object
+     *     responsible for providing mapping between the custom {@link
+     *     com.google.api.MonitoredResource} and the expected labels.
+     * @return this.
+     */
+    public abstract Builder setMonitoredResourceDescription(
+        MonitoredResourceDescription monitoredResourceDescription);
+
     /**
      * Set a filter to determine which resource attributes to add to metrics as metric labels. By
      * default, it adds service.name, service.namespace, and service.instance.id. This is

exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MonitoredResourceDescription.java

@@ -0,0 +1,59 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.google.cloud.opentelemetry.metric;
+
+import java.util.Collections;
+import java.util.Set;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * This class holds the mapping between Google Cloud's monitored resource type and the labels for
+ * identifying the given monitored resource type.
+ */
+@Immutable
+public final class MonitoredResourceDescription {
+  private final String mrType;
+  private final Set<String> mrLabels;
+
+  /**
+   * Public constructor.
+   *
+   * @param mrType The monitored resource type for which the mapping is being specified.
+   * @param mrLabels A set of labels which uniquely identify a given monitored resource.
+   */
+  public MonitoredResourceDescription(String mrType, Set<String> mrLabels) {
+    this.mrType = mrType;
+    this.mrLabels = Collections.unmodifiableSet(mrLabels);
+  }
+
+  /**
+   * Returns the set of labels used to identify the monitored resource represented in this mapping.
+   *
+   * @return Immutable set of labels that map to the specified monitored resource type.
+   */
+  public Set<String> getMonitoredResourceLabels() {
+    return mrLabels;
+  }
+
+  /**
+   * The type of the monitored resource for which mapping is defined.
+   *
+   * @return The type of the monitored resource.
+   */
+  public String getMonitoredResourceType() {
+    return mrType;
+  }
+}

exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/ResourceTranslator.java

@@ -17,13 +17,22 @@
 
 import com.google.api.MonitoredResource;
 import com.google.cloud.opentelemetry.resource.GcpResource;
+import com.google.common.base.Strings;
+import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.sdk.resources.Resource;
+import java.util.Set;
+import java.util.logging.Logger;
 
 /** Translates from OpenTelemetry Resource into Google Cloud Monitoring's MonitoredResource. */
 public class ResourceTranslator {
+  private static final String CUSTOM_MR_KEY = "gcp.resource_type";
+  private static final Logger LOGGER =
+      Logger.getLogger(ResourceTranslator.class.getCanonicalName());
+
   private ResourceTranslator() {}
 
   /** Converts a Java OpenTelemetry SDK resource into a MonitoredResource from GCP. */
+  @Deprecated
   public static MonitoredResource mapResource(Resource resource) {
     GcpResource gcpResource =
         com.google.cloud.opentelemetry.resource.ResourceTranslator.mapResource(resource);
@@ -32,4 +41,59 @@ public static MonitoredResource mapResource(Resource resource) {
     gcpResource.getResourceLabels().getLabels().forEach(mr::putLabels);
     return mr.build();
   }
+
+  /**
+   * Converts a Java OpenTelemetry SDK {@link Resource} into a Google specific {@link
+   * MonitoredResource}.
+   *
+   * @param resource The OpenTelemetry {@link Resource} to be converted.
+   * @param mrDescription The {@link MonitoredResourceDescription} in case the OpenTelemetry SDK
+   *     {@link Resource} needs to be converted to a custom {@link MonitoredResource}. For use-cases
+   *     not requiring custom {@link MonitoredResource}s, use the {@link
+   *     MetricConfiguration#EMPTY_MONITORED_RESOURCE_DESCRIPTION}.
+   * @return The converted {@link MonitoredResource} based on the provided {@link
+   *     MonitoredResourceDescription}.
+   */
+  static MonitoredResource mapResource(
+      Resource resource, MonitoredResourceDescription mrDescription) {
+    String mrTypeToMap = resource.getAttributes().get(AttributeKey.stringKey(CUSTOM_MR_KEY));
+    if (Strings.isNullOrEmpty(mrTypeToMap)) {
+      return mapResourceUsingCustomerMappings(resource);
+    } else if (!mrTypeToMap.equals(mrDescription.getMonitoredResourceType())) {
+      LOGGER.warning(
+          String.format(
+              "MonitoredResource type mismatch: Description provided for %s, but found %s in resource attributes. Defaulting to standard mappings.",
+              mrDescription.getMonitoredResourceType(), mrTypeToMap));
+      return mapResourceUsingCustomerMappings(resource);
+    } else {
+      return mapResourceUsingPlatformMappings(resource, mrTypeToMap, mrDescription);
+    }
+  }
+
+  private static MonitoredResource mapResourceUsingPlatformMappings(
+      Resource resource,
+      String mrTypeToMap,
+      MonitoredResourceDescription monitoredResourceDescription) {
+    Set<String> expectedMRLabels = monitoredResourceDescription.getMonitoredResourceLabels();
+    MonitoredResource.Builder mr = MonitoredResource.newBuilder();
+    mr.setType(mrTypeToMap);
+    expectedMRLabels.forEach(
+        expectedLabel -> {
+          String foundValue = resource.getAttribute(AttributeKey.stringKey(expectedLabel));
+          if (foundValue != null) {
+            // only put labels for found value
+            mr.putLabels(expectedLabel, foundValue);
+          }
+        });
+    return mr.build();
+  }
+
+  private static MonitoredResource mapResourceUsingCustomerMappings(Resource resource) {
+    GcpResource gcpResource =
+        com.google.cloud.opentelemetry.resource.ResourceTranslator.mapResource(resource);
+    MonitoredResource.Builder mr = MonitoredResource.newBuilder();
+    mr.setType(gcpResource.getResourceType());
+    gcpResource.getResourceLabels().getLabels().forEach(mr::putLabels);
+    return mr.build();
+  }
 }

exporters/metrics/src/test/java/com/google/cloud/opentelemetry/metric/FakeData.java

@@ -61,6 +61,20 @@ public class FakeData {
   static final Attributes someLabels =
       Attributes.builder().put("label1", "value1").put("label2", "False").build();
 
+  static final Attributes someCustomMRAttributes =
+      Attributes.builder()
+          .put("gcp.resource_type", "custom_mr_instance") // required to trigger platform mapping
+          .put("host_id", aHostId)
+          .put("location", aCloudZone)
+          .put("service_instance_id", "test-gcs-service-id")
+          .put("foo", "bar") // extra label, gets ignored
+          .build();
+
+  static final Resource aCustomMonitoredResource = Resource.create(someCustomMRAttributes);
+
+  static final Resource aCustomMonitoredResourceWithNoAttributes =
+      Resource.create(Attributes.builder().put("gcp.resource_type", "custom_mr_instance").build());
+
   static final Attributes someGceAttributes =
       Attributes.builder()
           .put(
@@ -119,6 +133,26 @@ public class FakeData {
           ImmutableSumData.create(
               true, AggregationTemporality.CUMULATIVE, ImmutableList.of(aLongPoint)));
 
+  static final MetricData aMetricDataWithCustomResource =
+      ImmutableMetricData.createLongSum(
+          aCustomMonitoredResource,
+          anInstrumentationLibraryInfo,
+          "opentelemetry/name",
+          "description",
+          "ns",
+          ImmutableSumData.create(
+              true, AggregationTemporality.CUMULATIVE, ImmutableList.of(aLongPoint)));
+
+  static final MetricData aMetricDataWithEmptyResourceAttributes =
+      ImmutableMetricData.createLongSum(
+          aCustomMonitoredResourceWithNoAttributes,
+          anInstrumentationLibraryInfo,
+          "opentelemetry/name",
+          "description",
+          "ns",
+          ImmutableSumData.create(
+              true, AggregationTemporality.CUMULATIVE, ImmutableList.of(aLongPoint)));
+
   static final MetricData googleComputeServiceMetricData =
       ImmutableMetricData.createLongSum(
           aGceResource,