Exporter/Stackdriver: Allow to override the opencensus_task label. (#1845)

Author: songy23

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## Unreleased
 - Add HTTP text format serializer to Tag propagation component.
 - Support constant labels in Gauge APIs.
+- Add an option to allow users to override the default "opencensus_task" metric label in Stackdriver Stats Exporter.
 
 ## 0.20.0 - 2019-03-28
 - Add OpenCensus Java OC-Agent Trace Exporter.

exporters/stats/stackdriver/README.md

@@ -156,6 +156,15 @@ Stackdriver exporter adds a new `Metric` label for each custom `Metric` to ensur
 of the `Timeseries`. The format of the label is: `{LANGUAGE}-{PID}@{HOSTNAME}`, if `{PID}` is not
 available a random number will be used.
 
+You have the option to override the "opencensus_task" metric label with custom constant labels using
+`StackdriverStatsConfiguration.Builder.setConstantLabels()`. If you do so, make sure that the 
+monitored resource together with these labels is unique to the current process. This is to ensure 
+that there is only a single writer to each time series in Stackdriver.
+
+You can also set `StackdriverStatsConfiguration.Builder.setConstantLabels()` to an empty map to 
+avoid getting the default "opencensus_task" label. You should only do this if you know that the 
+monitored resource uniquely identifies this process.
+
 ### Why did I get an error "java.lang.NoSuchMethodError: com.google.common...", like "java.lang.NoSuchMethodError:com.google.common.base.Throwables.throwIfInstanceOf"?
 This is probably because there is a version conflict on Guava in the dependency tree.
 

exporters/stats/stackdriver/src/main/java/io/opencensus/exporter/stats/stackdriver/CreateMetricDescriptorExporter.java

@@ -23,6 +23,8 @@
 import com.google.monitoring.v3.CreateMetricDescriptorRequest;
 import com.google.monitoring.v3.ProjectName;
 import io.opencensus.exporter.metrics.util.MetricExporter;
+import io.opencensus.metrics.LabelKey;
+import io.opencensus.metrics.LabelValue;
 import io.opencensus.metrics.export.Metric;
 import io.opencensus.metrics.export.MetricDescriptor.Type;
 import io.opencensus.trace.Span;
@@ -51,18 +53,21 @@ final class CreateMetricDescriptorExporter extends MetricExporter {
   private final String displayNamePrefix;
   private final Map<String, io.opencensus.metrics.export.MetricDescriptor>
       registeredMetricDescriptors = new LinkedHashMap<>();
+  private final Map<LabelKey, LabelValue> constantLabels;
   private final MetricExporter nextExporter;
 
   CreateMetricDescriptorExporter(
       String projectId,
       MetricServiceClient metricServiceClient,
       @javax.annotation.Nullable String metricNamePrefix,
+      Map<LabelKey, LabelValue> constantLabels,
       MetricExporter nextExporter) {
     this.projectId = projectId;
     projectName = ProjectName.newBuilder().setProject(projectId).build();
     this.metricServiceClient = metricServiceClient;
     this.domain = StackdriverExportUtils.getDomain(metricNamePrefix);
     this.displayNamePrefix = StackdriverExportUtils.getDisplayNamePrefix(metricNamePrefix);
+    this.constantLabels = constantLabels;
     this.nextExporter = nextExporter;
   }
 
@@ -95,7 +100,7 @@ private boolean registerMetricDescriptor(
     span.addAnnotation("Create Stackdriver Metric.");
     MetricDescriptor stackDriverMetricDescriptor =
         StackdriverExportUtils.createMetricDescriptor(
-            metricDescriptor, projectId, domain, displayNamePrefix);
+            metricDescriptor, projectId, domain, displayNamePrefix, constantLabels);
 
     CreateMetricDescriptorRequest request =
         CreateMetricDescriptorRequest.newBuilder()

exporters/stats/stackdriver/src/main/java/io/opencensus/exporter/stats/stackdriver/CreateTimeSeriesExporter.java

@@ -26,6 +26,8 @@
 import com.google.monitoring.v3.ProjectName;
 import com.google.monitoring.v3.TimeSeries;
 import io.opencensus.exporter.metrics.util.MetricExporter;
+import io.opencensus.metrics.LabelKey;
+import io.opencensus.metrics.LabelValue;
 import io.opencensus.metrics.export.Metric;
 import io.opencensus.trace.Span;
 import io.opencensus.trace.Status;
@@ -34,6 +36,7 @@
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
+import java.util.Map;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
@@ -45,16 +48,19 @@ final class CreateTimeSeriesExporter extends MetricExporter {
   private final MetricServiceClient metricServiceClient;
   private final MonitoredResource monitoredResource;
   private final String domain;
+  private final Map<LabelKey, LabelValue> constantLabels;
 
   CreateTimeSeriesExporter(
       String projectId,
       MetricServiceClient metricServiceClient,
       MonitoredResource monitoredResource,
-      @javax.annotation.Nullable String metricNamePrefix) {
+      @javax.annotation.Nullable String metricNamePrefix,
+      Map<LabelKey, LabelValue> constantLabels) {
     projectName = ProjectName.newBuilder().setProject(projectId).build();
     this.metricServiceClient = metricServiceClient;
     this.monitoredResource = monitoredResource;
     this.domain = StackdriverExportUtils.getDomain(metricNamePrefix);
+    this.constantLabels = constantLabels;
   }
 
   @Override
@@ -63,7 +69,7 @@ public void export(Collection<Metric> metrics) {
     for (Metric metric : metrics) {
       timeSeriesList.addAll(
           StackdriverExportUtils.createTimeSeriesList(
-              metric, monitoredResource, domain, projectName.getProject()));
+              metric, monitoredResource, domain, projectName.getProject(), constantLabels));
     }
 
     Span span = tracer.getCurrentSpan();

exporters/stats/stackdriver/src/main/java/io/opencensus/exporter/stats/stackdriver/StackdriverExportUtils.java

@@ -79,9 +79,17 @@
 @SuppressWarnings("deprecation")
 final class StackdriverExportUtils {
 
-  // TODO(songya): do we want these constants to be customizable?
-  @VisibleForTesting static final String OPENCENSUS_TASK = "opencensus_task";
-  @VisibleForTesting static final String OPENCENSUS_TASK_DESCRIPTION = "Opencensus task identifier";
+  @VisibleForTesting
+  static final LabelKey OPENCENSUS_TASK_KEY =
+      LabelKey.create("opencensus_task", "Opencensus task identifier");
+
+  @VisibleForTesting
+  static final LabelValue OPENCENSUS_TASK_VALUE_DEFAULT =
+      LabelValue.create(generateDefaultTaskValue());
+
+  static final Map<LabelKey, LabelValue> DEFAULT_CONSTANT_LABELS =
+      Collections.singletonMap(OPENCENSUS_TASK_KEY, OPENCENSUS_TASK_VALUE_DEFAULT);
+
   @VisibleForTesting static final String STACKDRIVER_PROJECT_ID_KEY = "project_id";
   @VisibleForTesting static final String DEFAULT_DISPLAY_NAME_PREFIX = "OpenCensus/";
   @VisibleForTesting static final String CUSTOM_METRIC_DOMAIN = "custom.googleapis.com/";
@@ -97,7 +105,6 @@ final class StackdriverExportUtils {
   @VisibleForTesting static final String AWS_REGION_VALUE_PREFIX = "aws:";
 
   private static final Logger logger = Logger.getLogger(StackdriverExportUtils.class.getName());
-  private static final String OPENCENSUS_TASK_VALUE_DEFAULT = generateDefaultTaskValue();
 
   // Mappings for the well-known OC resources to applicable Stackdriver resources.
   private static final Map<String, String> GCP_RESOURCE_MAPPING = getGcpResourceLabelsMappings();
@@ -206,7 +213,8 @@ static MetricDescriptor createMetricDescriptor(
       io.opencensus.metrics.export.MetricDescriptor metricDescriptor,
       String projectId,
       String domain,
-      String displayNamePrefix) {
+      String displayNamePrefix,
+      Map<LabelKey, LabelValue> constantLabels) {
 
     MetricDescriptor.Builder builder = MetricDescriptor.newBuilder();
     String type = generateType(metricDescriptor.getName(), domain);
@@ -219,12 +227,9 @@ static MetricDescriptor createMetricDescriptor(
     for (LabelKey labelKey : metricDescriptor.getLabelKeys()) {
       builder.addLabels(createLabelDescriptor(labelKey));
     }
-    builder.addLabels(
-        LabelDescriptor.newBuilder()
-            .setKey(OPENCENSUS_TASK)
-            .setDescription(OPENCENSUS_TASK_DESCRIPTION)
-            .setValueType(ValueType.STRING)
-            .build());
+    for (LabelKey labelKey : constantLabels.keySet()) {
+      builder.addLabels(createLabelDescriptor(labelKey));
+    }
 
     builder.setUnit(metricDescriptor.getUnit());
     builder.setMetricKind(createMetricKind(metricDescriptor.getType()));
@@ -283,7 +288,8 @@ static List<TimeSeries> createTimeSeriesList(
       io.opencensus.metrics.export.Metric metric,
       MonitoredResource monitoredResource,
       String domain,
-      String projectId) {
+      String projectId,
+      Map<LabelKey, LabelValue> constantLabels) {
     List<TimeSeries> timeSeriesList = Lists.newArrayList();
     io.opencensus.metrics.export.MetricDescriptor metricDescriptor = metric.getMetricDescriptor();
 
@@ -301,7 +307,8 @@ static List<TimeSeries> createTimeSeriesList(
     for (io.opencensus.metrics.export.TimeSeries timeSeries : metric.getTimeSeriesList()) {
       // TODO(mayurkale): Consider using setPoints instead of builder clone and addPoints.
       TimeSeries.Builder builder = shared.clone();
-      builder.setMetric(createMetric(metricDescriptor, timeSeries.getLabelValues(), domain));
+      builder.setMetric(
+          createMetric(metricDescriptor, timeSeries.getLabelValues(), domain, constantLabels));
 
       io.opencensus.common.Timestamp startTimeStamp = timeSeries.getStartTimestamp();
       for (io.opencensus.metrics.export.Point point : timeSeries.getPoints()) {
@@ -317,7 +324,8 @@ static List<TimeSeries> createTimeSeriesList(
   static Metric createMetric(
       io.opencensus.metrics.export.MetricDescriptor metricDescriptor,
       List<LabelValue> labelValues,
-      String domain) {
+      String domain,
+      Map<LabelKey, LabelValue> constantLabels) {
     Metric.Builder builder = Metric.newBuilder();
     builder.setType(generateType(metricDescriptor.getName(), domain));
     Map<String, String> stringTagMap = Maps.newHashMap();
@@ -329,7 +337,12 @@ static Metric createMetric(
       }
       stringTagMap.put(labelKeys.get(i).getKey(), value);
     }
-    stringTagMap.put(OPENCENSUS_TASK, OPENCENSUS_TASK_VALUE_DEFAULT);
+    for (Map.Entry<LabelKey, LabelValue> constantLabel : constantLabels.entrySet()) {
+      String constantLabelKey = constantLabel.getKey().getKey();
+      String constantLabelValue = constantLabel.getValue().getValue();
+      constantLabelValue = constantLabelValue == null ? "" : constantLabelValue;
+      stringTagMap.put(constantLabelKey, constantLabelValue);
+    }
     builder.putAllLabels(stringTagMap);
     return builder.build();
   }

exporters/stats/stackdriver/src/main/java/io/opencensus/exporter/stats/stackdriver/StackdriverStatsConfiguration.java

@@ -16,10 +16,15 @@
 
 package io.opencensus.exporter.stats.stackdriver;
 
+import static io.opencensus.exporter.stats.stackdriver.StackdriverExportUtils.DEFAULT_CONSTANT_LABELS;
+
 import com.google.api.MonitoredResource;
 import com.google.auth.Credentials;
 import com.google.auto.value.AutoValue;
 import io.opencensus.common.Duration;
+import io.opencensus.metrics.LabelKey;
+import io.opencensus.metrics.LabelValue;
+import java.util.Map;
 import javax.annotation.Nullable;
 import javax.annotation.concurrent.Immutable;
 
@@ -79,14 +84,23 @@ public abstract class StackdriverStatsConfiguration {
   @Nullable
   public abstract String getMetricNamePrefix();
 
+  /**
+   * Returns the constant labels that will be applied to every Stackdriver metric.
+   *
+   * @return the constant labels.
+   * @since 0.21
+   */
+  public abstract Map<LabelKey, LabelValue> getConstantLabels();
+
   /**
    * Returns a new {@link Builder}.
    *
    * @return a {@code Builder}.
    * @since 0.11
    */
   public static Builder builder() {
-    return new AutoValue_StackdriverStatsConfiguration.Builder();
+    return new AutoValue_StackdriverStatsConfiguration.Builder()
+        .setConstantLabels(DEFAULT_CONSTANT_LABELS);
   }
 
   /**
@@ -148,6 +162,26 @@ public abstract static class Builder {
      */
     public abstract Builder setMetricNamePrefix(String prefix);
 
+    /**
+     * Sets the constant labels that will be applied to every Stackdriver metric. This default
+     * ensures that the set of labels together with the default resource (global) are unique to this
+     * process, as required by stackdriver.
+     *
+     * <p>If not set, the exporter will use the "opencensus_task" label.
+     *
+     * <p>If you set constant labels, make sure that the monitored resource together with these
+     * labels is unique to the current process. This is to ensure that there is only a single writer
+     * to each time series in Stackdriver.
+     *
+     * <p>Set constant labels to empty to avoid getting the default "opencensus_task" label. You
+     * should only do this if you know that the monitored resource uniquely identifies this process.
+     *
+     * @param constantLabels constant labels that will be applied to every Stackdriver metric.
+     * @return this
+     * @since 0.21
+     */
+    public abstract Builder setConstantLabels(Map<LabelKey, LabelValue> constantLabels);
+
     /**
      * Builds a new {@link StackdriverStatsConfiguration} with current settings.
      *