From 213a3db046cc30f8ef34ae95cbd20fa217a7afc2 Mon Sep 17 00:00:00 2001 From: Pranav Sharma Date: Thu, 7 May 2026 16:27:47 +0000 Subject: [PATCH 01/10] Add deprecation warnings for artifacts --- README.md | 3 +++ build.gradle | 2 +- .../opentelemetry/auto/GoogleCloudMetricExporterFactory.java | 1 + .../opentelemetry/auto/GoogleCloudSpanExporterFactory.java | 1 + .../opentelemetry/metric/GoogleCloudMetricExporter.java | 5 +++++ .../com/google/cloud/opentelemetry/trace/TraceExporter.java | 5 +++++ .../OneWayXCloudTraceConfigurablePropagatorProvider.java | 1 + .../XCloudTraceConfigurablePropagatorProvider.java | 1 + .../propagators/XCloudTraceContextPropagator.java | 4 ++++ .../com/google/cloud/opentelemetry/resource/GcpResource.java | 1 + .../google/cloud/opentelemetry/resource/ResourceLabels.java | 1 + .../cloud/opentelemetry/resource/ResourceTranslator.java | 1 + 12 files changed, 25 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 511bc190..2f3579b4 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ # Open-Telemetry Operations Exporters for Java +> [!WARNING] +> **DEPRECATION NOTICE**: This project and all its published artifacts are deprecated. No new features will be added, and this repository may be archived in the future. + [![Maven Central][maven-image]][maven-url] Provides OpenTelemetry Exporters for Google Cloud Operations. diff --git a/build.gradle b/build.gradle index 5c02f06e..b6a162ff 100644 --- a/build.gradle +++ b/build.gradle @@ -311,7 +311,7 @@ subprojects { } afterEvaluate { // description is not available until evaluated. - description = project.description + description = "DEPRECATED: " + project.description } } } diff --git a/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudMetricExporterFactory.java b/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudMetricExporterFactory.java index 08efec4e..f29fe846 100644 --- a/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudMetricExporterFactory.java +++ b/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudMetricExporterFactory.java @@ -22,6 +22,7 @@ import io.opentelemetry.sdk.metrics.export.MetricExporter; @AutoService(ConfigurableMetricExporterProvider.class) +@Deprecated public class GoogleCloudMetricExporterFactory implements ConfigurableMetricExporterProvider { @Override public MetricExporter createExporter(ConfigProperties config) { diff --git a/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudSpanExporterFactory.java b/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudSpanExporterFactory.java index 578161cf..3d91e3fd 100644 --- a/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudSpanExporterFactory.java +++ b/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudSpanExporterFactory.java @@ -22,6 +22,7 @@ import io.opentelemetry.sdk.trace.export.SpanExporter; @AutoService(ConfigurableSpanExporterProvider.class) +@Deprecated public class GoogleCloudSpanExporterFactory implements ConfigurableSpanExporterProvider { @Override diff --git a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/GoogleCloudMetricExporter.java b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/GoogleCloudMetricExporter.java index 86445582..ab336274 100644 --- a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/GoogleCloudMetricExporter.java +++ b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/GoogleCloudMetricExporter.java @@ -29,6 +29,7 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; +@Deprecated public class GoogleCloudMetricExporter implements MetricExporter { private static final Logger logger = LoggerFactory.getLogger(GoogleCloudMetricExporter.class); @@ -64,7 +65,9 @@ private GoogleCloudMetricExporter(MetricConfiguration configuration) { * which gets initialized lazily once {@link GoogleCloudMetricExporter#export(Collection)} is * called. */ + @Deprecated public static MetricExporter createWithDefaultConfiguration() { + logger.warn("GoogleCloudMetricExporter is deprecated and will be removed in a future release."); return new GoogleCloudMetricExporter(MetricConfiguration.builder().build()); } @@ -81,7 +84,9 @@ public static MetricExporter createWithDefaultConfiguration() { * preferences for metrics. * @return An instance of {@link GoogleCloudMetricExporter} as a {@link MetricExporter} object. */ + @Deprecated public static MetricExporter createWithConfiguration(MetricConfiguration configuration) { + logger.warn("GoogleCloudMetricExporter is deprecated and will be removed in a future release."); return new GoogleCloudMetricExporter(configuration); } diff --git a/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceExporter.java b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceExporter.java index cab668b9..ef09f595 100644 --- a/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceExporter.java +++ b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceExporter.java @@ -27,6 +27,7 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; +@Deprecated public class TraceExporter implements SpanExporter { private static final Logger logger = LoggerFactory.getLogger(TraceExporter.class); @@ -62,7 +63,9 @@ private TraceExporter(TraceConfiguration configuration) { * @return A configured instance of {@link TraceExporter} which gets initialized lazily once * {@link TraceExporter#export(Collection)} is called. */ + @Deprecated public static SpanExporter createWithDefaultConfiguration() { + logger.warn("TraceExporter is deprecated and will be removed in a future release."); return new TraceExporter(TraceConfiguration.builder().build()); } @@ -79,7 +82,9 @@ public static SpanExporter createWithDefaultConfiguration() { * for trace. * @return An instance of {@link TraceExporter} as a {@link SpanExporter} object */ + @Deprecated public static SpanExporter createWithConfiguration(TraceConfiguration configuration) { + logger.warn("TraceExporter is deprecated and will be removed in a future release."); return new TraceExporter(configuration); } diff --git a/propagators/gcp/src/main/java/com/google/cloud/opentelemetry/propagators/OneWayXCloudTraceConfigurablePropagatorProvider.java b/propagators/gcp/src/main/java/com/google/cloud/opentelemetry/propagators/OneWayXCloudTraceConfigurablePropagatorProvider.java index 9921c3ea..dd36a0c0 100644 --- a/propagators/gcp/src/main/java/com/google/cloud/opentelemetry/propagators/OneWayXCloudTraceConfigurablePropagatorProvider.java +++ b/propagators/gcp/src/main/java/com/google/cloud/opentelemetry/propagators/OneWayXCloudTraceConfigurablePropagatorProvider.java @@ -29,6 +29,7 @@ * propagation. */ @AutoService(ConfigurablePropagatorProvider.class) +@Deprecated public class OneWayXCloudTraceConfigurablePropagatorProvider implements ConfigurablePropagatorProvider { @Override diff --git a/propagators/gcp/src/main/java/com/google/cloud/opentelemetry/propagators/XCloudTraceConfigurablePropagatorProvider.java b/propagators/gcp/src/main/java/com/google/cloud/opentelemetry/propagators/XCloudTraceConfigurablePropagatorProvider.java index 24a1b06d..bd224d9e 100644 --- a/propagators/gcp/src/main/java/com/google/cloud/opentelemetry/propagators/XCloudTraceConfigurablePropagatorProvider.java +++ b/propagators/gcp/src/main/java/com/google/cloud/opentelemetry/propagators/XCloudTraceConfigurablePropagatorProvider.java @@ -31,6 +31,7 @@ * @see OneWayXCloudTraceConfigurablePropagatorProvider */ @AutoService(ConfigurablePropagatorProvider.class) +@Deprecated public class XCloudTraceConfigurablePropagatorProvider implements ConfigurablePropagatorProvider { @Override public TextMapPropagator getPropagator(ConfigProperties config) { diff --git a/propagators/gcp/src/main/java/com/google/cloud/opentelemetry/propagators/XCloudTraceContextPropagator.java b/propagators/gcp/src/main/java/com/google/cloud/opentelemetry/propagators/XCloudTraceContextPropagator.java index e47d5d30..16531ffe 100644 --- a/propagators/gcp/src/main/java/com/google/cloud/opentelemetry/propagators/XCloudTraceContextPropagator.java +++ b/propagators/gcp/src/main/java/com/google/cloud/opentelemetry/propagators/XCloudTraceContextPropagator.java @@ -37,6 +37,7 @@ *

See: Google Cloud Trace * Documentation for details. */ +@Deprecated public final class XCloudTraceContextPropagator implements TextMapPropagator { private static final String FIELD = "x-cloud-trace-context"; @@ -53,7 +54,10 @@ public final class XCloudTraceContextPropagator implements TextMapPropagator { * * @param oneway boolean to configure if the trace should propagate in a single direction. */ + @Deprecated public XCloudTraceContextPropagator(boolean oneway) { + LOGGER.warning( + "XCloudTraceContextPropagator is deprecated and will be removed in a future release."); this.oneway = oneway; } diff --git a/shared/resourcemapping/src/main/java/com/google/cloud/opentelemetry/resource/GcpResource.java b/shared/resourcemapping/src/main/java/com/google/cloud/opentelemetry/resource/GcpResource.java index 5822b617..2b1bc736 100644 --- a/shared/resourcemapping/src/main/java/com/google/cloud/opentelemetry/resource/GcpResource.java +++ b/shared/resourcemapping/src/main/java/com/google/cloud/opentelemetry/resource/GcpResource.java @@ -23,6 +23,7 @@ *

Unlike pure OpenTelemetry, GCP adds a "type" to a raw bundle of labels. */ @AutoValue +@Deprecated public abstract class GcpResource { /** The type of resource, e.g. gce_instance. */ public abstract String getResourceType(); diff --git a/shared/resourcemapping/src/main/java/com/google/cloud/opentelemetry/resource/ResourceLabels.java b/shared/resourcemapping/src/main/java/com/google/cloud/opentelemetry/resource/ResourceLabels.java index 6beb497a..2d617c68 100644 --- a/shared/resourcemapping/src/main/java/com/google/cloud/opentelemetry/resource/ResourceLabels.java +++ b/shared/resourcemapping/src/main/java/com/google/cloud/opentelemetry/resource/ResourceLabels.java @@ -26,6 +26,7 @@ * Guice for collections. */ @AutoValue +@Deprecated public abstract class ResourceLabels { public abstract Map getLabels(); diff --git a/shared/resourcemapping/src/main/java/com/google/cloud/opentelemetry/resource/ResourceTranslator.java b/shared/resourcemapping/src/main/java/com/google/cloud/opentelemetry/resource/ResourceTranslator.java index 00c6e677..e0d69c79 100644 --- a/shared/resourcemapping/src/main/java/com/google/cloud/opentelemetry/resource/ResourceTranslator.java +++ b/shared/resourcemapping/src/main/java/com/google/cloud/opentelemetry/resource/ResourceTranslator.java @@ -30,6 +30,7 @@ import java.util.Optional; /** Translates from OpenTelemetry Resource into Google Cloud's notion of resource. */ +@Deprecated public class ResourceTranslator { private static final String UNKNOWN_SERVICE_PREFIX = "unknown_service"; From 8361ef178fed9746c79ce1989c481702021a0b3a Mon Sep 17 00:00:00 2001 From: Pranav Sharma Date: Thu, 7 May 2026 16:57:39 +0000 Subject: [PATCH 02/10] Add missing @Deprecated tags on remaining public classes --- .../java/com/google/cloud/opentelemetry/auto/Constants.java | 1 + .../metric/AggregateByLabelMetricTimeSeriesBuilder.java | 1 + .../google/cloud/opentelemetry/metric/CloudMetricClient.java | 1 + .../cloud/opentelemetry/metric/CloudMetricClientImpl.java | 1 + .../google/cloud/opentelemetry/metric/MetricConfiguration.java | 2 ++ .../cloud/opentelemetry/metric/MetricDescriptorStrategy.java | 1 + .../cloud/opentelemetry/metric/MetricTimeSeriesBuilder.java | 1 + .../com/google/cloud/opentelemetry/metric/MetricTranslator.java | 1 + .../opentelemetry/metric/MonitoredResourceDescription.java | 1 + .../google/cloud/opentelemetry/metric/ResourceTranslator.java | 1 + .../com/google/cloud/opentelemetry/trace/CloudTraceClient.java | 1 + .../google/cloud/opentelemetry/trace/CloudTraceClientImpl.java | 1 + .../google/cloud/opentelemetry/trace/TraceConfiguration.java | 2 ++ .../com/google/cloud/opentelemetry/trace/TraceVersions.java | 1 + 14 files changed, 16 insertions(+) diff --git a/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/Constants.java b/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/Constants.java index 3a9515e0..f6ae4e29 100644 --- a/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/Constants.java +++ b/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/Constants.java @@ -15,6 +15,7 @@ */ package com.google.cloud.opentelemetry.auto; +@Deprecated public class Constants { static final String CLOUD_TRACE_NAME = "google_cloud_trace"; diff --git a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/AggregateByLabelMetricTimeSeriesBuilder.java b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/AggregateByLabelMetricTimeSeriesBuilder.java index 7fdc3a85..97b1bfce 100644 --- a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/AggregateByLabelMetricTimeSeriesBuilder.java +++ b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/AggregateByLabelMetricTimeSeriesBuilder.java @@ -47,6 +47,7 @@ * Builds GCM TimeSeries from each OTEL metric point, creating metric descriptors based on the * "first" seen point for any given metric. */ +@Deprecated public final class AggregateByLabelMetricTimeSeriesBuilder implements MetricTimeSeriesBuilder { public static final String LABEL_INSTRUMENTATION_SOURCE = diff --git a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/CloudMetricClient.java b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/CloudMetricClient.java index 4073c422..5c305062 100644 --- a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/CloudMetricClient.java +++ b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/CloudMetricClient.java @@ -22,6 +22,7 @@ import java.util.List; /** Wrapper interface for writing to Google Cloud Monitoring. */ +@Deprecated public interface CloudMetricClient { /** * Construct a metric descriptor. diff --git a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/CloudMetricClientImpl.java b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/CloudMetricClientImpl.java index 7f510409..07014e6a 100644 --- a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/CloudMetricClientImpl.java +++ b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/CloudMetricClientImpl.java @@ -23,6 +23,7 @@ import java.util.List; /** Directly talks to Cloud Monitoring. */ +@Deprecated public final class CloudMetricClientImpl implements CloudMetricClient { private final MetricServiceClient metricServiceClient; diff --git a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricConfiguration.java b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricConfiguration.java index 2cd47660..2c4df3b9 100644 --- a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricConfiguration.java +++ b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricConfiguration.java @@ -44,6 +44,7 @@ */ @AutoValue @Immutable +@Deprecated public abstract class MetricConfiguration { static final String DEFAULT_PREFIX = "workload.googleapis.com"; @@ -224,6 +225,7 @@ public static Builder builder() { /** Builder for {@link MetricConfiguration}. */ @AutoValue.Builder + @Deprecated public abstract static class Builder { Builder() {} diff --git a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricDescriptorStrategy.java b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricDescriptorStrategy.java index 55319a5b..6c3a1829 100644 --- a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricDescriptorStrategy.java +++ b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricDescriptorStrategy.java @@ -21,6 +21,7 @@ import java.util.function.Consumer; /** The strategy for how to handle metric descriptors. */ +@Deprecated public interface MetricDescriptorStrategy { /** * Determines what to do with metric descriptors. diff --git a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricTimeSeriesBuilder.java b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricTimeSeriesBuilder.java index 0c266c96..a233086b 100644 --- a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricTimeSeriesBuilder.java +++ b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricTimeSeriesBuilder.java @@ -25,6 +25,7 @@ import java.util.List; /** An interface that denotes how we build our API calls from metric data. */ +@Deprecated public interface MetricTimeSeriesBuilder { /** Records a LongPoint of the given metric. */ void recordPoint(MetricData metric, LongPointData point); diff --git a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricTranslator.java b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricTranslator.java index a1208152..db907b8e 100644 --- a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricTranslator.java +++ b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MetricTranslator.java @@ -45,6 +45,7 @@ import org.slf4j.LoggerFactory; /** Utility methods to translate metrics from OTEL to GCM format. */ +@Deprecated public final class MetricTranslator { private static final Logger logger = LoggerFactory.getLogger(MetricTranslator.class); diff --git a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MonitoredResourceDescription.java b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MonitoredResourceDescription.java index 9427782a..dc8b63a6 100644 --- a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MonitoredResourceDescription.java +++ b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/MonitoredResourceDescription.java @@ -24,6 +24,7 @@ * identifying the given monitored resource type. */ @Immutable +@Deprecated public final class MonitoredResourceDescription { private final String mrType; private final Set mrLabels; diff --git a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/ResourceTranslator.java b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/ResourceTranslator.java index 51b65ae2..40ab4643 100644 --- a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/ResourceTranslator.java +++ b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/ResourceTranslator.java @@ -24,6 +24,7 @@ import java.util.logging.Logger; /** Translates from OpenTelemetry Resource into Google Cloud Monitoring's MonitoredResource. */ +@Deprecated public class ResourceTranslator { private static final String CUSTOM_MR_KEY = "gcp.resource_type"; private static final Logger LOGGER = diff --git a/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/CloudTraceClient.java b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/CloudTraceClient.java index caf4f899..424e8c5e 100644 --- a/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/CloudTraceClient.java +++ b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/CloudTraceClient.java @@ -19,6 +19,7 @@ import com.google.devtools.cloudtrace.v2.Span; import java.util.List; +@Deprecated public interface CloudTraceClient { void batchWriteSpans(ProjectName name, List spans); diff --git a/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/CloudTraceClientImpl.java b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/CloudTraceClientImpl.java index 9c917194..f626a4b5 100644 --- a/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/CloudTraceClientImpl.java +++ b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/CloudTraceClientImpl.java @@ -20,6 +20,7 @@ import com.google.devtools.cloudtrace.v2.Span; import java.util.List; +@Deprecated public class CloudTraceClientImpl implements CloudTraceClient { private final TraceServiceClient traceServiceClient; diff --git a/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceConfiguration.java b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceConfiguration.java index af42e9e5..b8f28bc5 100644 --- a/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceConfiguration.java +++ b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceConfiguration.java @@ -37,6 +37,7 @@ /** Configurations for {@link TraceExporter}. */ @AutoValue @Immutable +@Deprecated public abstract class TraceConfiguration { @VisibleForTesting static final Duration DEFAULT_DEADLINE = Duration.ofSeconds(10, 0); @@ -149,6 +150,7 @@ public static Builder builder() { /** Builder for {@link TraceConfiguration}. */ @AutoValue.Builder + @Deprecated public abstract static class Builder { @VisibleForTesting static final Duration ZERO = Duration.ZERO; diff --git a/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceVersions.java b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceVersions.java index 528240fb..8816f2c3 100644 --- a/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceVersions.java +++ b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceVersions.java @@ -22,6 +22,7 @@ import javax.annotation.Nullable; /** Helper to grab version numbers from builds. */ +@Deprecated public class TraceVersions { public static final String SDK_VERSION = readSdkVersion(); From ab54b0d1ef9d98f5e2b2e7358b1475898b3f6373 Mon Sep 17 00:00:00 2001 From: Pranav Sharma Date: Thu, 7 May 2026 19:06:24 +0000 Subject: [PATCH 03/10] Add runtime deprecation warnings in static block --- MIGRATION.md | 22 +++++++++++++++++++ .../GoogleCloudMetricExporterFactory.java | 10 +++++++++ .../auto/GoogleCloudSpanExporterFactory.java | 9 ++++++++ .../metric/GoogleCloudMetricExporter.java | 7 ++++-- .../opentelemetry/trace/TraceExporter.java | 7 ++++-- 5 files changed, 51 insertions(+), 4 deletions(-) create mode 100644 MIGRATION.md diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 00000000..a37c91f1 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,22 @@ +# Migration Guide + +This guide provides instructions on how to migrate from the custom exporters in this repository to the standard OpenTelemetry OTLP exporters. + +## Overview +Google Cloud now supports native OTLP (OpenTelemetry Protocol) ingestion for Cloud Trace and Cloud Monitoring via the [Telemetry API](https://docs.cloud.google.com/stackdriver/docs/reference/telemetry/overview). This allows you to use the standard OpenTelemetry OTLP exporters for sending telemetry data to Google Cloud. + +## Migrate from OpenTelemetry Google Cloud Trace Exporter to OTLP exporter + +Follow the [Migrate from the Trace exporter to the OTLP endpoint](https://docs.cloud.google.com/trace/docs/migrate-to-otlp-endpoints) guide for migration instructions. + +## Migrate from OpenTelemetry Google Cloud Monitoring Exporter to OTLP exporter + +> [!NOTE] The Google Cloud OTLP metrics endpoint is currently in preview and the migration guides are being developed. + +TODO: Add migration guide for metrics exporter + +## Migrate from OpenTelemetry Google Cloud Auto Exporter + +The Auto exporter allowed the [auto-configuration module](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#opentelemetry-sdk-autoconfigure) of OpenTelemetry Java to work with OpenTelemetry Google Cloud Trace and Monitoring exporters in this repository. + +The standard OpenTelemetry OTLP exporters natively support auto-configuration and are the recommended way to send telemetry to Google Cloud. You can configure the OTLP exporters using the standard [exporter properties](https://opentelemetry.io/docs/languages/java/configuration/#properties-exporters) that are supported by the autoconfiguration module. diff --git a/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudMetricExporterFactory.java b/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudMetricExporterFactory.java index f29fe846..5734d4e5 100644 --- a/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudMetricExporterFactory.java +++ b/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudMetricExporterFactory.java @@ -20,10 +20,20 @@ import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties; import io.opentelemetry.sdk.autoconfigure.spi.metrics.ConfigurableMetricExporterProvider; import io.opentelemetry.sdk.metrics.export.MetricExporter; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; @AutoService(ConfigurableMetricExporterProvider.class) @Deprecated public class GoogleCloudMetricExporterFactory implements ConfigurableMetricExporterProvider { + private static final Logger logger = + LoggerFactory.getLogger(GoogleCloudMetricExporterFactory.class); + + static { + logger.warn( + "Google Cloud OpenTelemetry Auto exporter for Java is deprecated. Please migrate to the OpenTelemetry OTLP exporters. For migration details, see https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/blob/main/MIGRATION.md"); + } + @Override public MetricExporter createExporter(ConfigProperties config) { return GoogleCloudMetricExporter.createWithDefaultConfiguration(); diff --git a/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudSpanExporterFactory.java b/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudSpanExporterFactory.java index 3d91e3fd..5cd2aee3 100644 --- a/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudSpanExporterFactory.java +++ b/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudSpanExporterFactory.java @@ -20,10 +20,19 @@ import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties; import io.opentelemetry.sdk.autoconfigure.spi.traces.ConfigurableSpanExporterProvider; import io.opentelemetry.sdk.trace.export.SpanExporter; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; @AutoService(ConfigurableSpanExporterProvider.class) @Deprecated public class GoogleCloudSpanExporterFactory implements ConfigurableSpanExporterProvider { + private static final Logger logger = + LoggerFactory.getLogger(GoogleCloudSpanExporterFactory.class); + + static { + logger.warn( + "Google Cloud OpenTelemetry Auto exporter for Java is deprecated. Please migrate to the OpenTelemetry OTLP exporters. For migration details, see https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/blob/main/MIGRATION.md"); + } @Override public SpanExporter createExporter(ConfigProperties config) { diff --git a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/GoogleCloudMetricExporter.java b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/GoogleCloudMetricExporter.java index ab336274..e3116c35 100644 --- a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/GoogleCloudMetricExporter.java +++ b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/GoogleCloudMetricExporter.java @@ -33,6 +33,11 @@ public class GoogleCloudMetricExporter implements MetricExporter { private static final Logger logger = LoggerFactory.getLogger(GoogleCloudMetricExporter.class); + static { + logger.warn( + "Google Cloud OpenTelemetry Metric exporter for Java is deprecated. Please migrate to the OpenTelemetry OTLP exporters. For migration details, see https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/blob/main/MIGRATION.md"); + } + private final Supplier internalMetricExporterSupplier; private GoogleCloudMetricExporter(MetricConfiguration configuration) { @@ -67,7 +72,6 @@ private GoogleCloudMetricExporter(MetricConfiguration configuration) { */ @Deprecated public static MetricExporter createWithDefaultConfiguration() { - logger.warn("GoogleCloudMetricExporter is deprecated and will be removed in a future release."); return new GoogleCloudMetricExporter(MetricConfiguration.builder().build()); } @@ -86,7 +90,6 @@ public static MetricExporter createWithDefaultConfiguration() { */ @Deprecated public static MetricExporter createWithConfiguration(MetricConfiguration configuration) { - logger.warn("GoogleCloudMetricExporter is deprecated and will be removed in a future release."); return new GoogleCloudMetricExporter(configuration); } diff --git a/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceExporter.java b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceExporter.java index ef09f595..bb21d8c6 100644 --- a/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceExporter.java +++ b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceExporter.java @@ -32,6 +32,11 @@ public class TraceExporter implements SpanExporter { private static final Logger logger = LoggerFactory.getLogger(TraceExporter.class); + static { + logger.warn( + "Google Cloud OpenTelemetry Trace exporter for Java is deprecated. Please migrate to the OpenTelemetry OTLP exporters. For migration details, see https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/blob/main/MIGRATION.md"); + } + private final Supplier internalTraceExporterSupplier; private TraceExporter(TraceConfiguration configuration) { @@ -65,7 +70,6 @@ private TraceExporter(TraceConfiguration configuration) { */ @Deprecated public static SpanExporter createWithDefaultConfiguration() { - logger.warn("TraceExporter is deprecated and will be removed in a future release."); return new TraceExporter(TraceConfiguration.builder().build()); } @@ -84,7 +88,6 @@ public static SpanExporter createWithDefaultConfiguration() { */ @Deprecated public static SpanExporter createWithConfiguration(TraceConfiguration configuration) { - logger.warn("TraceExporter is deprecated and will be removed in a future release."); return new TraceExporter(configuration); } From ae01e43b6aa1557a9d225ce7a2756d5c8a1cb7fc Mon Sep 17 00:00:00 2001 From: Pranav Sharma Date: Wed, 13 May 2026 20:59:58 +0000 Subject: [PATCH 04/10] Add migration instructions for OTLP Trace --- MIGRATION.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/MIGRATION.md b/MIGRATION.md index a37c91f1..285e9dda 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -7,7 +7,57 @@ Google Cloud now supports native OTLP (OpenTelemetry Protocol) ingestion for Clo ## Migrate from OpenTelemetry Google Cloud Trace Exporter to OTLP exporter -Follow the [Migrate from the Trace exporter to the OTLP endpoint](https://docs.cloud.google.com/trace/docs/migrate-to-otlp-endpoints) guide for migration instructions. +To migrate from the deprecated Google Cloud Trace exporter to the standard OpenTelemetry OTLP exporter, follow these steps: + +### 1. Add Dependencies + +Add the following dependencies to your `build.gradle` file: + +```groovy +implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.56.0") +implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.56.0") +// Recommended for authentication when using autoconfigure module +implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension:1.52.0-alpha") +``` + +### 2. Configure the SDK + +Use the OpenTelemetry SDK Autoconfigure module to configure the SDK. You can set the following system properties or environment variables: + +```bash +# System Properties +-Dotel.exporter.otlp.endpoint=https://telemetry.googleapis.com +-Dotel.traces.exporter=otlp +-Dotel.exporter.otlp.protocol=http/protobuf + +# Or Environment Variables +OTEL_EXPORTER_OTLP_ENDPOINT=https://telemetry.googleapis.com +OTEL_TRACES_EXPORTER=otlp +OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +``` + +### Configuration Mapping + +The following table maps the configurations available in `TraceConfiguration` to their OTLP equivalents: + +| TraceConfiguration Option | OTLP Equivalent Property / Env Var | Notes | +| :--- | :--- | :--- | +| `setProjectId(String)` | Use resource attribute: `gcp.project_id` | If using the `opentelemetry-gcp-auth-extension`, the project ID can be inferred from the credentials or the environment. | +| `setCredentials(Credentials)` | Pass the bearer token as Authorization Header in the exporter | Handled automatically by `opentelemetry-gcp-auth-extension`. | +| `setTraceServiceEndpoint(String)` | `otel.exporter.otlp.endpoint` / `OTEL_EXPORTER_OTLP_ENDPOINT` | Default is `https://telemetry.googleapis.com`. | +| `setFixedAttributes(Map)` | `otel.resource.attributes` / `OTEL_RESOURCE_ATTRIBUTES` | Maps to Resource attributes in OTel, which are added to all telemetry data, not just spans. | +| `setDeadline(Duration)` | `otel.exporter.otlp.timeout` / `OTEL_EXPORTER_OTLP_TIMEOUT` | Default is 10 seconds. | + +### Unsupported Features + +The following features of the Google Cloud Trace exporter are not supported by the standard OTLP exporter: + +* **Attribute Mapping (`setAttributeMapping`)**: The OTLP exporter does not support renaming attributes (e.g., renaming OpenTelemetry standard attributes to legacy Stackdriver attributes). You should use standard OpenTelemetry attributes. +* **Custom Trace Service Stub (`setTraceServiceStub`)**: You cannot pass a pre-configured `TraceServiceStub` to the OTLP exporter via configuration properties. If you need custom channel configuration, you must use programmatic configuration with `OtlpGrpcSpanExporter.builder()`. + +### Migration Guide + +For a complete migration guide, please visit the [Migrate from the Trace exporter to the OTLP endpoint](https://docs.cloud.google.com/trace/docs/migrate-to-otlp-endpoints) guide. ## Migrate from OpenTelemetry Google Cloud Monitoring Exporter to OTLP exporter From 2bf5704398c9be5e86b2c239d05a0818ef716aad Mon Sep 17 00:00:00 2001 From: Pranav Sharma Date: Wed, 13 May 2026 21:35:42 +0000 Subject: [PATCH 05/10] Update the content structure --- MIGRATION.md | 117 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 109 insertions(+), 8 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 285e9dda..222cb13e 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -9,7 +9,7 @@ Google Cloud now supports native OTLP (OpenTelemetry Protocol) ingestion for Clo To migrate from the deprecated Google Cloud Trace exporter to the standard OpenTelemetry OTLP exporter, follow these steps: -### 1. Add Dependencies +#### 1. Add Dependencies Add the following dependencies to your `build.gradle` file: @@ -20,7 +20,7 @@ implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.56. implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension:1.52.0-alpha") ``` -### 2. Configure the SDK +#### 2. Configure the SDK Use the OpenTelemetry SDK Autoconfigure module to configure the SDK. You can set the following system properties or environment variables: @@ -36,7 +36,13 @@ OTEL_TRACES_EXPORTER=otlp OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf ``` -### Configuration Mapping +#### 3. Follow the Migration Guide + +For a code walkthrough, follow the migration guide published at [Migrate from the Trace exporter to the OTLP endpoint](https://docs.cloud.google.com/trace/docs/migrate-to-otlp-endpoints). + +### Mapping and Limitations + +#### Configuration Mapping The following table maps the configurations available in `TraceConfiguration` to their OTLP equivalents: @@ -48,22 +54,117 @@ The following table maps the configurations available in `TraceConfiguration` to | `setFixedAttributes(Map)` | `otel.resource.attributes` / `OTEL_RESOURCE_ATTRIBUTES` | Maps to Resource attributes in OTel, which are added to all telemetry data, not just spans. | | `setDeadline(Duration)` | `otel.exporter.otlp.timeout` / `OTEL_EXPORTER_OTLP_TIMEOUT` | Default is 10 seconds. | -### Unsupported Features +#### Unsupported Features The following features of the Google Cloud Trace exporter are not supported by the standard OTLP exporter: * **Attribute Mapping (`setAttributeMapping`)**: The OTLP exporter does not support renaming attributes (e.g., renaming OpenTelemetry standard attributes to legacy Stackdriver attributes). You should use standard OpenTelemetry attributes. * **Custom Trace Service Stub (`setTraceServiceStub`)**: You cannot pass a pre-configured `TraceServiceStub` to the OTLP exporter via configuration properties. If you need custom channel configuration, you must use programmatic configuration with `OtlpGrpcSpanExporter.builder()`. -### Migration Guide +#### Complete Sample -For a complete migration guide, please visit the [Migrate from the Trace exporter to the OTLP endpoint](https://docs.cloud.google.com/trace/docs/migrate-to-otlp-endpoints) guide. +For a complete sample demonstrating how to export traces to Google Cloud using OTLP, see the [examples/otlptrace](examples/otlptrace) folder. ## Migrate from OpenTelemetry Google Cloud Monitoring Exporter to OTLP exporter -> [!NOTE] The Google Cloud OTLP metrics endpoint is currently in preview and the migration guides are being developed. +To migrate from the deprecated Google Cloud Monitoring exporter to the standard OpenTelemetry OTLP exporter, follow these steps: + +#### 1. Add Dependencies + +Add the following dependencies to your `build.gradle` file: + +```groovy +implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.56.0") +implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.56.0") +// Recommended for authentication when using autoconfigure module +implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension:1.52.0-alpha") +``` + +#### 2. Configure the SDK + +Use the OpenTelemetry SDK Autoconfigure module to configure the SDK. You can set the following system properties or environment variables: + +```bash +# System Properties +-Dotel.exporter.otlp.endpoint=https://telemetry.googleapis.com +-Dotel.metrics.exporter=otlp +-Dotel.exporter.otlp.protocol=http/protobuf + +# Or Environment Variables +OTEL_EXPORTER_OTLP_ENDPOINT=https://telemetry.googleapis.com +OTEL_METRICS_EXPORTER=otlp +OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf +``` + +#### 3. Code Walkthrough + +##### Legacy Configuration + +In the legacy setup using `GoogleCloudMetricExporter`, you typically configured it using `MetricConfiguration` as shown in [MetricsExporterExample.java](file:///usr/local/google/home/sharmapranav/Projects/opentelemetry-operations-java/examples/metrics/src/main/java/com/google/cloud/opentelemetry/example/metrics/MetricsExporterExample.java): + +```java +MetricConfiguration configuration = MetricConfiguration.builder() + // Configure project ID, credentials, etc. + .build(); +MetricExporter metricExporter = GoogleCloudMetricExporter.createWithConfiguration(configuration); +``` + +##### OTLP Configuration + +With the OTLP exporter, you can use the `AutoConfiguredOpenTelemetrySdk` to automatically pick up configuration from environment variables or system properties. If you need to manually add authorization headers (e.g., if not using the `gcp-auth-extension`), you can customize the exporter as shown in [OTLPMetricExample.java](file:///usr/local/google/home/sharmapranav/Projects/opentelemetry-operations-java/examples/otlpmetric/src/main/java/com/google/cloud/opentelemetry/example/otlpmetric/OTLPMetricExample.java): + +```java +AutoConfiguredOpenTelemetrySdk autoConfOTelSdk = + AutoConfiguredOpenTelemetrySdk.builder() + .addMetricExporterCustomizer( + (exporter, configProperties) -> addAuthorizationHeaders(exporter, credentials)) + .build(); +``` + +The `addAuthorizationHeaders` method computes the headers required for Google Cloud, including the `Authorization` bearer token: + +```java +private static MetricExporter addAuthorizationHeaders( + MetricExporter exporter, GoogleCredentials credentials) { + if (exporter instanceof OtlpHttpMetricExporter) { + return ((OtlpHttpMetricExporter) exporter) + .toBuilder().setHeaders(() -> getRequiredHeaderMap(credentials)).build(); + } else if (exporter instanceof OtlpGrpcMetricExporter) { + return ((OtlpGrpcMetricExporter) exporter) + .toBuilder().setHeaders(() -> getRequiredHeaderMap(credentials)).build(); + } + return exporter; +} +``` + +### Mapping and Limitations + +#### Configuration Mapping + +The following table maps the configurations available in `MetricConfiguration` to their OTLP equivalents: + +| MetricConfiguration Option | OTLP Equivalent Property / Env Var | Notes | +| :--- | :--- | :--- | +| `setProjectId(String)` | Use resource attribute: `gcp.project_id` | If using the `opentelemetry-gcp-auth-extension`, the project ID can be inferred from the credentials or the environment. | +| `setCredentials(Credentials)` | Pass the bearer token as Authorization Header in the exporter | Handled automatically by `opentelemetry-gcp-auth-extension`. | +| `setMetricServiceEndpoint(String)` | `otel.exporter.otlp.endpoint` / `OTEL_EXPORTER_OTLP_ENDPOINT` | Default is `https://telemetry.googleapis.com`. | +| `setDeadline(Duration)` | `otel.exporter.otlp.timeout` / `OTEL_EXPORTER_OTLP_TIMEOUT` | Default is 10 seconds. | +| `setPrefix(String)` | N/A | The Telemetry API automatically prefixes metrics with `workload.googleapis.com/` by default. Custom prefixes are not directly supported via OTLP exporter configuration. | + +#### Unsupported Features + +The following features of the `GoogleCloudMetricExporter` are not supported by the standard OTLP exporter: + +* **Metric Descriptor Strategy (`setDescriptorStrategy`)**: OTLP exporters do not send metric descriptors separately. Metadata is handled automatically by the backend. +* **Custom Monitored Resource Mapping (`setMonitoredResourceDescription`)**: OTLP relies on standard OTel resources. GCP maps these to monitored resources automatically. +* **Predicate-based Resource Attribute Filtering (`setResourceAttributesFilter`)**: OTLP exporters send all resource attributes by default. If you need to filter them, you must do so before they reach the exporter (e.g., via resource configuration or a processor if using a collector). +* **Use Service Time Series (`setUseServiceTimeSeries`)**: This option is specific to the Cloud Monitoring API and is not available in OTLP exporters. +* **Instrumentation Library Labels Toggle (`setInstrumentationLibraryLabelsEnabled`)**: OTLP exporters send instrumentation scope information by default. Disabling it requires dropping the attributes via views or processors. +* **Custom Metric Service Settings (`setMetricServiceSettings`)**: You cannot pass `MetricServiceSettings` to OTLP exporters. If you need custom channel or client configuration, you must use programmatic configuration with `OtlpGrpcMetricExporter.builder()` or `OtlpHttpMetricExporter.builder()`. + +#### Complete Sample -TODO: Add migration guide for metrics exporter +For a complete sample demonstrating how to export metrics to Google Cloud using OTLP, see the [examples/otlpmetric](examples/otlpmetric) folder. ## Migrate from OpenTelemetry Google Cloud Auto Exporter From 33f0e97e289e5c093b2826f9cc6451652ac9359c Mon Sep 17 00:00:00 2001 From: Pranav Sharma Date: Wed, 13 May 2026 22:00:30 +0000 Subject: [PATCH 06/10] Add instructions around Metric Attributes --- MIGRATION.md | 79 +++++++++++++++++++++++++++++++++------------------- 1 file changed, 50 insertions(+), 29 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 222cb13e..34859e8c 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -50,7 +50,7 @@ The following table maps the configurations available in `TraceConfiguration` to | :--- | :--- | :--- | | `setProjectId(String)` | Use resource attribute: `gcp.project_id` | If using the `opentelemetry-gcp-auth-extension`, the project ID can be inferred from the credentials or the environment. | | `setCredentials(Credentials)` | Pass the bearer token as Authorization Header in the exporter | Handled automatically by `opentelemetry-gcp-auth-extension`. | -| `setTraceServiceEndpoint(String)` | `otel.exporter.otlp.endpoint` / `OTEL_EXPORTER_OTLP_ENDPOINT` | Default is `https://telemetry.googleapis.com`. | +| `setTraceServiceEndpoint(String)` | `otel.exporter.otlp.endpoint` / `OTEL_EXPORTER_OTLP_ENDPOINT` | Set it to `https://telemetry.googleapis.com` to send traces to Google Cloud. | | `setFixedAttributes(Map)` | `otel.resource.attributes` / `OTEL_RESOURCE_ATTRIBUTES` | Maps to Resource attributes in OTel, which are added to all telemetry data, not just spans. | | `setDeadline(Duration)` | `otel.exporter.otlp.timeout` / `OTEL_EXPORTER_OTLP_TIMEOUT` | Default is 10 seconds. | @@ -96,45 +96,66 @@ OTEL_METRICS_EXPORTER=otlp OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf ``` -#### 3. Code Walkthrough +For more information, see [OpenTelemetry environment variables and system properties](https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties). -##### Legacy Configuration +#### 3. Initialize the SDK in Code -In the legacy setup using `GoogleCloudMetricExporter`, you typically configured it using `MetricConfiguration` as shown in [MetricsExporterExample.java](file:///usr/local/google/home/sharmapranav/Projects/opentelemetry-operations-java/examples/metrics/src/main/java/com/google/cloud/opentelemetry/example/metrics/MetricsExporterExample.java): +With the OTLP exporter and the `opentelemetry-gcp-auth-extension` added to your dependencies, you can initialize the OpenTelemetry SDK using `AutoConfiguredOpenTelemetrySdk`. The extension automatically handles authentication, so you don't need to write custom code to add authorization headers. ```java -MetricConfiguration configuration = MetricConfiguration.builder() - // Configure project ID, credentials, etc. - .build(); -MetricExporter metricExporter = GoogleCloudMetricExporter.createWithConfiguration(configuration); +import io.opentelemetry.sdk.OpenTelemetrySdk; +import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk; +import java.util.concurrent.TimeUnit; + +public class MyApplication { + private static OpenTelemetrySdk openTelemetrySdk; + + public static void main(String[] args) { + // Configure the OpenTelemetry pipeline with Auto configuration + openTelemetrySdk = AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk(); + + // Application-specific logic here + + // Flush all buffered metrics on shutdown + openTelemetrySdk.getSdkMeterProvider().shutdown().join(10, TimeUnit.SECONDS); + } +} ``` -##### OTLP Configuration +#### 4. Adding Attributes -With the OTLP exporter, you can use the `AutoConfiguredOpenTelemetrySdk` to automatically pick up configuration from environment variables or system properties. If you need to manually add authorization headers (e.g., if not using the `gcp-auth-extension`), you can customize the exporter as shown in [OTLPMetricExample.java](file:///usr/local/google/home/sharmapranav/Projects/opentelemetry-operations-java/examples/otlpmetric/src/main/java/com/google/cloud/opentelemetry/example/otlpmetric/OTLPMetricExample.java): +OpenTelemetry uses **Resource Attributes** to describe the entity producing telemetry (e.g., service name, host) and **Metric Attributes** to describe the specific measurement (e.g., HTTP method, status code). -```java -AutoConfiguredOpenTelemetrySdk autoConfOTelSdk = - AutoConfiguredOpenTelemetrySdk.builder() - .addMetricExporterCustomizer( - (exporter, configProperties) -> addAuthorizationHeaders(exporter, credentials)) - .build(); +##### Resource Attributes + +You can set resource attributes using the `OTEL_RESOURCE_ATTRIBUTES` environment variable or system property. This is a good replacement for: +* `setProjectId(String)`: Use the `gcp.project_id` resource attribute. Note that if you are using `opentelemetry-gcp-auth-extension`, you do not need to set this explicitly. + +Example: +```bash +export OTEL_RESOURCE_ATTRIBUTES="service.name=my-service,gcp.project_id=my-project" +# Or pass as a system property flag to the JVM +-Dotel.resource.attributes=gcp.project_id=my-project ``` -The `addAuthorizationHeaders` method computes the headers required for Google Cloud, including the `Authorization` bearer token: +##### Metric Attributes + +Add attributes to individual metrics when recording measurements. This is the standard way to add dimensions to your metrics. ```java -private static MetricExporter addAuthorizationHeaders( - MetricExporter exporter, GoogleCredentials credentials) { - if (exporter instanceof OtlpHttpMetricExporter) { - return ((OtlpHttpMetricExporter) exporter) - .toBuilder().setHeaders(() -> getRequiredHeaderMap(credentials)).build(); - } else if (exporter instanceof OtlpGrpcMetricExporter) { - return ((OtlpGrpcMetricExporter) exporter) - .toBuilder().setHeaders(() -> getRequiredHeaderMap(credentials)).build(); - } - return exporter; -} +import io.opentelemetry.api.common.AttributeKey; +import io.opentelemetry.api.common.Attributes; +import io.opentelemetry.api.metrics.LongCounter; +import io.opentelemetry.api.metrics.Meter; + +// ... inside your method ... + +Meter meter = openTelemetrySdk.getMeter("my-instrumentation"); +LongCounter counter = meter.counterBuilder("processed_jobs").build(); + +// Add attributes to the measurement +Attributes attributes = Attributes.of(AttributeKey.stringKey("job_type"), "import"); +counter.add(1, attributes); ``` ### Mapping and Limitations @@ -147,7 +168,7 @@ The following table maps the configurations available in `MetricConfiguration` t | :--- | :--- | :--- | | `setProjectId(String)` | Use resource attribute: `gcp.project_id` | If using the `opentelemetry-gcp-auth-extension`, the project ID can be inferred from the credentials or the environment. | | `setCredentials(Credentials)` | Pass the bearer token as Authorization Header in the exporter | Handled automatically by `opentelemetry-gcp-auth-extension`. | -| `setMetricServiceEndpoint(String)` | `otel.exporter.otlp.endpoint` / `OTEL_EXPORTER_OTLP_ENDPOINT` | Default is `https://telemetry.googleapis.com`. | +| `setMetricServiceEndpoint(String)` | `otel.exporter.otlp.endpoint` / `OTEL_EXPORTER_OTLP_ENDPOINT` | Set it to `https://telemetry.googleapis.com` to send metrics to Google Cloud. | | `setDeadline(Duration)` | `otel.exporter.otlp.timeout` / `OTEL_EXPORTER_OTLP_TIMEOUT` | Default is 10 seconds. | | `setPrefix(String)` | N/A | The Telemetry API automatically prefixes metrics with `workload.googleapis.com/` by default. Custom prefixes are not directly supported via OTLP exporter configuration. | From 024361afc6164b3b8c96d8ed4e2cd738cac9453e Mon Sep 17 00:00:00 2001 From: Pranav Sharma Date: Thu, 14 May 2026 16:43:12 +0000 Subject: [PATCH 07/10] Add information about Cloud Monitoring prefix handling --- MIGRATION.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/MIGRATION.md b/MIGRATION.md index 34859e8c..b2b7c002 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -151,8 +151,15 @@ import io.opentelemetry.api.metrics.Meter; // ... inside your method ... Meter meter = openTelemetrySdk.getMeter("my-instrumentation"); + +// Metrics without prefix will be sent to the default domain - prometheus.googleapis.com +// and will be stored in Google Managed Prometheus with prometheus_target as the Monitored Resource. LongCounter counter = meter.counterBuilder("processed_jobs").build(); +// Metrics with custom prefix will be sent to the custom domain. +// In this case, Monitored Resource is determined by the attached OpenTelemetry Resource Attributes. +LongCounter customCounter = meter.counterBuilder("custom.googleapis.com/my_counter").build(); + // Add attributes to the measurement Attributes attributes = Attributes.of(AttributeKey.stringKey("job_type"), "import"); counter.add(1, attributes); @@ -170,7 +177,7 @@ The following table maps the configurations available in `MetricConfiguration` t | `setCredentials(Credentials)` | Pass the bearer token as Authorization Header in the exporter | Handled automatically by `opentelemetry-gcp-auth-extension`. | | `setMetricServiceEndpoint(String)` | `otel.exporter.otlp.endpoint` / `OTEL_EXPORTER_OTLP_ENDPOINT` | Set it to `https://telemetry.googleapis.com` to send metrics to Google Cloud. | | `setDeadline(Duration)` | `otel.exporter.otlp.timeout` / `OTEL_EXPORTER_OTLP_TIMEOUT` | Default is 10 seconds. | -| `setPrefix(String)` | N/A | The Telemetry API automatically prefixes metrics with `workload.googleapis.com/` by default. Custom prefixes are not directly supported via OTLP exporter configuration. | +| `setPrefix(String)` | N/A | The Telemetry API automatically prefixes metrics with `prometheus.googleapis.com/` by default and will be stored in Google Managed Prometheus with `prometheus_target` as the Monitored Resource. Custom prefixes are not directly supported via OTLP exporter configuration.
If you want your metric to keep appearing under your previous prefix (e.g., `workload.googleapis.com`), you must include the full prefix in the metric name you define in your OpenTelemetry instrumentation. | #### Unsupported Features From c066bea08d9a3628a47aaa8c53bba5aea5323d0b Mon Sep 17 00:00:00 2001 From: Pranav Sharma Date: Thu, 14 May 2026 17:08:06 +0000 Subject: [PATCH 08/10] Add a section for prerequisites --- MIGRATION.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/MIGRATION.md b/MIGRATION.md index b2b7c002..31ce46ff 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -5,6 +5,25 @@ This guide provides instructions on how to migrate from the custom exporters in ## Overview Google Cloud now supports native OTLP (OpenTelemetry Protocol) ingestion for Cloud Trace and Cloud Monitoring via the [Telemetry API](https://docs.cloud.google.com/stackdriver/docs/reference/telemetry/overview). This allows you to use the standard OpenTelemetry OTLP exporters for sending telemetry data to Google Cloud. +## Before you begin + +Before you migrate your application to send trace data to the OTLP endpoint, ensure you have completed the following steps: + +### Enable billing and the Telemetry API + +1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project. +2. Verify that billing is enabled for your Google Cloud project. +3. Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs. + +### Configure permissions + +Grant the following IAM roles to the service account that your application uses: + +* **Cloud Telemetry Traces Writer** (`roles/telemetry.tracesWriter`) +* **Cloud Telemetry Metrics Writer** (`roles/telemetry.metricsWriter`) +* **Logs Writer** (`roles/logging.logWriter`) +* **Monitoring Metric Writer** (`roles/monitoring.metricWriter`) + ## Migrate from OpenTelemetry Google Cloud Trace Exporter to OTLP exporter To migrate from the deprecated Google Cloud Trace exporter to the standard OpenTelemetry OTLP exporter, follow these steps: From 80971c070f093bfbba4bfeee6a612d129e5af37b Mon Sep 17 00:00:00 2001 From: Pranav Sharma Date: Fri, 15 May 2026 20:50:21 +0000 Subject: [PATCH 09/10] Add tentative archival date in warning message --- .../opentelemetry/auto/GoogleCloudMetricExporterFactory.java | 2 +- .../opentelemetry/auto/GoogleCloudSpanExporterFactory.java | 2 +- .../cloud/opentelemetry/metric/GoogleCloudMetricExporter.java | 2 +- .../com/google/cloud/opentelemetry/trace/TraceExporter.java | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudMetricExporterFactory.java b/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudMetricExporterFactory.java index 5734d4e5..54d0c160 100644 --- a/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudMetricExporterFactory.java +++ b/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudMetricExporterFactory.java @@ -31,7 +31,7 @@ public class GoogleCloudMetricExporterFactory implements ConfigurableMetricExpor static { logger.warn( - "Google Cloud OpenTelemetry Auto exporter for Java is deprecated. Please migrate to the OpenTelemetry OTLP exporters. For migration details, see https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/blob/main/MIGRATION.md"); + "Google Cloud OpenTelemetry Auto exporter for Java is deprecated and will be archived after September 30th, 2026. Please migrate to the OpenTelemetry OTLP exporters. For migration details, see https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/blob/main/MIGRATION.md"); } @Override diff --git a/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudSpanExporterFactory.java b/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudSpanExporterFactory.java index 5cd2aee3..46df3bf1 100644 --- a/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudSpanExporterFactory.java +++ b/exporters/auto/src/main/java/com/google/cloud/opentelemetry/auto/GoogleCloudSpanExporterFactory.java @@ -31,7 +31,7 @@ public class GoogleCloudSpanExporterFactory implements ConfigurableSpanExporterP static { logger.warn( - "Google Cloud OpenTelemetry Auto exporter for Java is deprecated. Please migrate to the OpenTelemetry OTLP exporters. For migration details, see https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/blob/main/MIGRATION.md"); + "Google Cloud OpenTelemetry Auto exporter for Java is deprecated and will be archived after September 30th, 2026. Please migrate to the OpenTelemetry OTLP exporters. For migration details, see https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/blob/main/MIGRATION.md"); } @Override diff --git a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/GoogleCloudMetricExporter.java b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/GoogleCloudMetricExporter.java index e3116c35..2156aec4 100644 --- a/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/GoogleCloudMetricExporter.java +++ b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/GoogleCloudMetricExporter.java @@ -35,7 +35,7 @@ public class GoogleCloudMetricExporter implements MetricExporter { static { logger.warn( - "Google Cloud OpenTelemetry Metric exporter for Java is deprecated. Please migrate to the OpenTelemetry OTLP exporters. For migration details, see https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/blob/main/MIGRATION.md"); + "Google Cloud OpenTelemetry Metric exporter for Java is deprecated and will be archived after September 30th, 2026. Please migrate to the OpenTelemetry OTLP exporters. For migration details, see https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/blob/main/MIGRATION.md"); } private final Supplier internalMetricExporterSupplier; diff --git a/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceExporter.java b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceExporter.java index bb21d8c6..12c32ad9 100644 --- a/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceExporter.java +++ b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceExporter.java @@ -34,7 +34,7 @@ public class TraceExporter implements SpanExporter { static { logger.warn( - "Google Cloud OpenTelemetry Trace exporter for Java is deprecated. Please migrate to the OpenTelemetry OTLP exporters. For migration details, see https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/blob/main/MIGRATION.md"); + "Google Cloud OpenTelemetry Trace exporter for Java is deprecated and will be archived after September 30th, 2026. Please migrate to the OpenTelemetry OTLP exporters. For migration details, see https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/blob/main/MIGRATION.md"); } private final Supplier internalTraceExporterSupplier; From ca047f42aeb750fcf4c4e8d07ec554aa72679ffe Mon Sep 17 00:00:00 2001 From: Pranav Sharma Date: Tue, 19 May 2026 20:08:47 +0000 Subject: [PATCH 10/10] Address documentation feedback --- MIGRATION.md | 6 ++---- README.md | 5 +++-- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 31ce46ff..071ed112 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -21,8 +21,6 @@ Grant the following IAM roles to the service account that your application uses: * **Cloud Telemetry Traces Writer** (`roles/telemetry.tracesWriter`) * **Cloud Telemetry Metrics Writer** (`roles/telemetry.metricsWriter`) -* **Logs Writer** (`roles/logging.logWriter`) -* **Monitoring Metric Writer** (`roles/monitoring.metricWriter`) ## Migrate from OpenTelemetry Google Cloud Trace Exporter to OTLP exporter @@ -203,9 +201,9 @@ The following table maps the configurations available in `MetricConfiguration` t The following features of the `GoogleCloudMetricExporter` are not supported by the standard OTLP exporter: * **Metric Descriptor Strategy (`setDescriptorStrategy`)**: OTLP exporters do not send metric descriptors separately. Metadata is handled automatically by the backend. -* **Custom Monitored Resource Mapping (`setMonitoredResourceDescription`)**: OTLP relies on standard OTel resources. GCP maps these to monitored resources automatically. +* **Custom Monitored Resource Mapping (`setMonitoredResourceDescription`)**: OTLP relies on standard OTel resources. GCP maps these to monitored resources automatically. This feature was added to support internal use-cases only. * **Predicate-based Resource Attribute Filtering (`setResourceAttributesFilter`)**: OTLP exporters send all resource attributes by default. If you need to filter them, you must do so before they reach the exporter (e.g., via resource configuration or a processor if using a collector). -* **Use Service Time Series (`setUseServiceTimeSeries`)**: This option is specific to the Cloud Monitoring API and is not available in OTLP exporters. +* **Use Service Time Series (`setUseServiceTimeSeries`)**: This option is specific to the Cloud Monitoring API and is not available in OTLP exporters. This feature is for supporting internal use-cases only. * **Instrumentation Library Labels Toggle (`setInstrumentationLibraryLabelsEnabled`)**: OTLP exporters send instrumentation scope information by default. Disabling it requires dropping the attributes via views or processors. * **Custom Metric Service Settings (`setMetricServiceSettings`)**: You cannot pass `MetricServiceSettings` to OTLP exporters. If you need custom channel or client configuration, you must use programmatic configuration with `OtlpGrpcMetricExporter.builder()` or `OtlpHttpMetricExporter.builder()`. diff --git a/README.md b/README.md index 2f3579b4..5bf9f247 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ -# Open-Telemetry Operations Exporters for Java +# OpenTelemetry Operations Exporters for Java > [!WARNING] -> **DEPRECATION NOTICE**: This project and all its published artifacts are deprecated. No new features will be added, and this repository may be archived in the future. +> **DEPRECATION NOTICE**: This project and all its published artifacts are deprecated. No new features will be added, and this repository may be archived in the future.\ +Please refer to [Migration Guide](MIGRATION.md) for migration instructions to move to the standard OpenTelemetry exporters. [![Maven Central][maven-image]][maven-url]