diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 00000000..22c199d2 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,487 @@ +# 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 + +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 +``` + +#### 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: + +| 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` | 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. | + +#### 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()`. + +#### Complete Sample + +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 + +> [!WARNING] +> **Breaking Change Warning:** Migrating from the legacy Google Cloud Monitoring exporter to the standard OTLP exporter introduces breaking changes to your metric names. +> +> * **Legacy Exporter:** Ingests metrics under the `workload.googleapis.com/` domain (unless a custom prefix was configured). +> * **OTLP Exporter:** Ingests metrics under the `prometheus.googleapis.com/` domain by default. +> +> Because of this domain change, your metric names in Cloud Monitoring will change. **This will break any existing dashboards, alerting policies, and will cause data discontinuity** between your historical and new metrics. + +### Why Migrate? + +While this migration introduces breaking changes, transitioning to the standard OTLP exporter is highly recommended for the following reasons: +* **Standardization:** Aligns your application with the industry-standard OpenTelemetry Protocol (OTLP), ensuring vendor neutrality and compatibility with the broader OpenTelemetry ecosystem. +* **Google Managed Prometheus (GMP):** Standard OTLP metrics are ingested into Google Managed Prometheus. GMP offers a robust, scalable, and cost-effective solution for monitoring (~20x cheaper than the Cloud Monitoring API ingestion), with long-term support and compatibility. +* **Future-proofing:** The legacy Google Cloud Monitoring exporter is deprecated and will be archived after September 30th, 2026. Migrating now ensures your monitoring pipeline remains supported. + +--- + +### Migration Strategies + +We recommend three paths for migration, depending on your operational requirements: + +1. **Direct Migration (Recommended):** Migrate fully to the OTLP exporter and update your dashboards and alerts to use the new metric names under the `prometheus.googleapis.com/` domain. +2. **Transition via Double-Writing (Alternative):** Run both the legacy exporter and the OTLP exporter in parallel. This allows you to validate the new OTLP pipeline and update dashboards/alerts without any monitoring downtime, at the cost of temporary double-ingestion charges. +3. **Custom Wrapped Exporter (Alternative):** Wrap the standard OTLP exporter in-code to automatically prepend a prefix (like `workload.googleapis.com/`) to all metrics. This allows you to keep your existing dashboards and alerts working without changing your application's metric instrumentation code. + +--- + +### Strategy 1: Direct Migration (Recommended) + +Follow these steps to fully transition to the standard OTLP exporter. + +#### 1. Update Dependencies + +Replace the legacy Google Cloud metrics exporter dependency with the standard OTLP exporter and the GCP auth extension in your `build.gradle` file: + +```groovy +// Remove: implementation("com.google.cloud:opentelemetry-operations-exporter-metrics:") + +// Add: +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 +``` + +For more information, see [OpenTelemetry environment variables and system properties](https://opentelemetry.io/docs/languages/java/configuration/#environment-variables-and-system-properties). + +#### 3. Initialize the SDK in Code + +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 +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); + } +} +``` + +#### 4. Adding Attributes + +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). + +##### 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 +``` + +##### Metric Attributes + +Add attributes to individual metrics when recording measurements. This is the standard way to add dimensions to your metrics. + +```java +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"); + +// 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); +``` + +#### 5. Update Dashboards and Alerts + +Once you deploy the OTLP exporter, your metrics will be ingested under the `prometheus.googleapis.com/` domain. You must update your Cloud Monitoring dashboards and alerting policies: +* Identify all queries referencing `workload.googleapis.com/`. +* Update them to reference `prometheus.googleapis.com/_` or the corresponding Prometheus metric name format. + +--- + +### Strategy 2: Transition via Double-Writing (Alternative) + +To avoid gaps in monitoring and validate the OTLP pipeline before making it the source of truth, you can export metrics to both destinations simultaneously. + +> [!IMPORTANT] +> **Cost Warning:** Double-writing metrics will double your metric ingestion volume, which will increase your Google Cloud Monitoring costs during the transition period. It also increases CPU and memory usage on your application. + +#### 1. Keep Legacy and Add OTLP Dependencies + +Keep your existing dependency on `opentelemetry-operations-exporter-metrics` and add the OTLP exporter dependencies to your `build.gradle`: + +```groovy +// Keep your existing legacy exporter dependency +implementation("com.google.cloud:opentelemetry-operations-exporter-metrics:") + +// Add standard OTLP dependencies +implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.56.0") +// Recommended for authentication +implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension:1.52.0-alpha") +``` + +#### 2. Configure SDK for Dual Export in Code + +When double-writing, you cannot rely solely on the Autoconfigure module for metrics, as you need to register multiple metric readers. You must configure the SDK programmatically: + +```java +import io.opentelemetry.api.OpenTelemetry; +import io.opentelemetry.sdk.OpenTelemetrySdk; +import io.opentelemetry.sdk.metrics.SdkMeterProvider; +import io.opentelemetry.sdk.metrics.export.MetricExporter; +import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader; +import io.opentelemetry.exporter.otlp.metrics.OtlpGrpcMetricExporter; +import com.google.cloud.opentelemetry.metric.GoogleCloudMetricExporter; +import java.time.Duration; +import java.util.concurrent.TimeUnit; + +public class MyApplication { + private static OpenTelemetrySdk openTelemetrySdk; + + public static void main(String[] args) { + // 1. Create the legacy Google Cloud exporter (writes to workload.googleapis.com) + MetricExporter gcpExporter = GoogleCloudMetricExporter.createWithDefaultConfiguration(); + + // 2. Create the standard OTLP exporter (writes to prometheus.googleapis.com) + // Note: Assumes OTEL_EXPORTER_OTLP_ENDPOINT and other configuration env vars are set, + // or defaults to standard OTLP endpoints. + MetricExporter otlpExporter = OtlpGrpcMetricExporter.builder().build(); + + // 3. Register both exporters as MetricReaders in the SdkMeterProvider + SdkMeterProvider meterProvider = SdkMeterProvider.builder() + .registerMetricReader( + PeriodicMetricReader.builder(gcpExporter) + .setInterval(Duration.ofSeconds(60)) + .build()) + .registerMetricReader( + PeriodicMetricReader.builder(otlpExporter) + .setInterval(Duration.ofSeconds(60)) + .build()) + .build(); + + // 4. Build and register the OpenTelemetry SDK + openTelemetrySdk = OpenTelemetrySdk.builder() + .setMeterProvider(meterProvider) + .buildAndRegisterGlobal(); + + // Application-specific logic here + + // Flush and shutdown on exit + openTelemetrySdk.getSdkMeterProvider().shutdown().join(10, TimeUnit.SECONDS); + } +} +``` + +#### 3. Validate and Cutover + +1. **Verify Dual Ingestion:** Ensure metrics are appearing in Cloud Monitoring under both the old name (`workload.googleapis.com/...`) and the new name (`prometheus.googleapis.com/...`). +2. **Migrate Dashboards/Alerts:** Create duplicates of your dashboards and alerts, updating them to use the new `prometheus.googleapis.com` metrics. Verify they show identical trends and trigger correctly. +3. **Decommission Legacy Exporter:** Once validated, remove the legacy exporter dependency and the programmatic initialization code, reverting to the standard OTLP-only configuration (Strategy 1). + +--- + +### Strategy 3: Custom Wrapped Exporter (Alternative) + +If you want to use the standard OTLP exporter and the Autoconfigure module, but still need to prepend a prefix (e.g., `workload.googleapis.com/`) to all your metrics to keep your existing dashboards and alerts working *without* changing your individual metric instrumentation code, you can implement a custom wrapped exporter. + +This approach intercepts the metrics just before they are exported, wraps them to prepend the prefix to their names, and then delegates the actual export to the standard OTLP exporter. + +#### How it Works + +1. **Create a Wrapper Exporter**: Implement the `MetricExporter` interface to wrap the standard OTLP exporter and prepend the prefix to metric names. +2. **Use OpenTelemetry SPI (AutoConfigurationCustomizerProvider)**: Register a customizer that automatically wraps the default OTLP exporter during SDK autoconfiguration. + +#### Implementation Steps (Java) + +##### 1. Create the `PrefixedMetricData` Wrapper + +This class wraps standard `MetricData` and overrides `getName()` to prepend the desired prefix. + +```java +import io.opentelemetry.sdk.common.InstrumentationScopeInfo; +import io.opentelemetry.sdk.metrics.data.Data; +import io.opentelemetry.sdk.metrics.data.MetricData; +import io.opentelemetry.sdk.metrics.data.MetricDataType; +import io.opentelemetry.sdk.resources.Resource; + +public class PrefixedMetricData implements MetricData { + private final MetricData delegate; + private final String prefix; + + public PrefixedMetricData(MetricData delegate, String prefix) { + this.delegate = delegate; + this.prefix = prefix; + } + + @Override + public Resource getResource() { return delegate.getResource(); } + + @Override + public InstrumentationScopeInfo getInstrumentationScopeInfo() { return delegate.getInstrumentationScopeInfo(); } + + @Override + public String getName() { return prefix + delegate.getName(); } + + @Override + public String getDescription() { return delegate.getDescription(); } + + @Override + public String getUnit() { return delegate.getUnit(); } + + @Override + public MetricDataType getType() { return delegate.getType(); } + + @Override + public Data getData() { return delegate.getData(); } +} +``` + +##### 2. Create the `PrefixedMetricExporter` Wrapper + +This class wraps the standard `MetricExporter` and maps the incoming metrics to `PrefixedMetricData` before exporting. + +```java +import io.opentelemetry.sdk.common.CompletableResultCode; +import io.opentelemetry.sdk.common.export.MemoryMode; +import io.opentelemetry.sdk.metrics.Aggregation; +import io.opentelemetry.sdk.metrics.InstrumentType; +import io.opentelemetry.sdk.metrics.data.MetricData; +import io.opentelemetry.sdk.metrics.export.MetricExporter; +import java.util.Collection; +import java.util.List; +import java.util.stream.Collectors; + +public class PrefixedMetricExporter implements MetricExporter { + private final MetricExporter delegate; + private final String prefix; + + public PrefixedMetricExporter(MetricExporter delegate, String prefix) { + this.delegate = delegate; + this.prefix = prefix; + } + + @Override + public CompletableResultCode export(Collection metrics) { + List prefixedMetrics = + metrics.stream() + .map(metric -> new PrefixedMetricData(metric, prefix)) + .collect(Collectors.toList()); + return delegate.export(prefixedMetrics); + } + + @Override + public CompletableResultCode flush() { return delegate.flush(); } + + @Override + public CompletableResultCode shutdown() { return delegate.shutdown(); } + + @Override + public void close() { delegate.close(); } + + @Override + public Aggregation getDefaultAggregation(InstrumentType instrumentType) { + return delegate.getDefaultAggregation(instrumentType); + } + + @Override + public io.opentelemetry.sdk.metrics.data.AggregationTemporality getAggregationTemporality( + InstrumentType instrumentType) { + return delegate.getAggregationTemporality(instrumentType); + } + + @Override + public MemoryMode getMemoryMode() { return delegate.getMemoryMode(); } +} +``` + +##### 3. Register the Customizer via SPI + +Create a customizer class that implements `AutoConfigurationCustomizerProvider` to intercept and wrap the OTLP exporter. + +```java +import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizer; +import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider; + +public class OtlpMetricCustomizer implements AutoConfigurationCustomizerProvider { + + @Override + public void customize(AutoConfigurationCustomizer autoConfigurationCustomizer) { + autoConfigurationCustomizer.addMetricExporterCustomizer( + (metricExporter, configProperties) -> { + // Wrap only the OTLP exporter + if (metricExporter.getClass().getName().contains("Otlp")) { + // Replace "workload.googleapis.com/" with your desired prefix + return new PrefixedMetricExporter(metricExporter, "workload.googleapis.com/"); + } + return metricExporter; + }); + } + + @Override + public int order() { + return Integer.MAX_VALUE; // Apply towards the end + } +} +``` + +Register this customizer by creating a file named `io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider` in your project's `src/main/resources/META-INF/services/` directory. + +Add the fully qualified name of your customizer class to this file: +``` +com.yourpackage.OtlpMetricCustomizer +``` + +#### Pros & Cons + +* **Pros:** + * **No Instrumentation Changes:** You don't need to change the names of metrics in your application code. + * **Compatible with Autoconfigure:** Works seamlessly with the standard OpenTelemetry Autoconfigure module. + * **No Infrastructure Overhead:** Avoids the need to deploy and manage an OpenTelemetry Collector just for renaming metrics. +* **Cons:** + * **Code Maintenance:** Requires adding and maintaining wrapper classes in your application codebase. + * **Language Specific:** You must implement this wrapper for each language used in your services (the example above is for Java). + +Note: A complete implementation of this strategy can be found in [this example](https://github.com/GoogleCloudPlatform/opentelemetry-samples/tree/main/java/otlpmetric-exporter-wrapper). + +--- + +### 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` | 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 `prometheus.googleapis.com/` by default. Custom prefixes are not supported via OTLP exporter configuration. If you must keep a custom prefix during transition, you must include it in the metric name in your instrumentation, or use the double-writing strategy. | + +#### 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`)**: OTel 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. 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()`. + +#### Complete Sample + +For a complete sample demonstrating how to export metrics to Google Cloud using OTLP, see the [otlpmetric sample](https://github.com/GoogleCloudPlatform/opentelemetry-samples/tree/main/java/otlpmetric). + +## 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/README.md b/README.md index 511bc190..5bf9f247 100644 --- a/README.md +++ b/README.md @@ -1,4 +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.\ +Please refer to [Migration Guide](MIGRATION.md) for migration instructions to move to the standard OpenTelemetry exporters. [![Maven Central][maven-image]][maven-url] 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/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/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..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 @@ -20,9 +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 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 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 578161cf..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 @@ -20,9 +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 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 public SpanExporter createExporter(ConfigProperties config) { 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/GoogleCloudMetricExporter.java b/exporters/metrics/src/main/java/com/google/cloud/opentelemetry/metric/GoogleCloudMetricExporter.java index 86445582..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 @@ -29,9 +29,15 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; +@Deprecated 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 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; private GoogleCloudMetricExporter(MetricConfiguration configuration) { @@ -64,6 +70,7 @@ private GoogleCloudMetricExporter(MetricConfiguration configuration) { * which gets initialized lazily once {@link GoogleCloudMetricExporter#export(Collection)} is * called. */ + @Deprecated public static MetricExporter createWithDefaultConfiguration() { return new GoogleCloudMetricExporter(MetricConfiguration.builder().build()); } @@ -81,6 +88,7 @@ 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) { return new GoogleCloudMetricExporter(configuration); } 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/TraceExporter.java b/exporters/trace/src/main/java/com/google/cloud/opentelemetry/trace/TraceExporter.java index cab668b9..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 @@ -27,10 +27,16 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; +@Deprecated 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 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; private TraceExporter(TraceConfiguration configuration) { @@ -62,6 +68,7 @@ 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() { return new TraceExporter(TraceConfiguration.builder().build()); } @@ -79,6 +86,7 @@ public static SpanExporter createWithDefaultConfiguration() { * for trace. * @return An instance of {@link TraceExporter} as a {@link SpanExporter} object */ + @Deprecated public static SpanExporter createWithConfiguration(TraceConfiguration configuration) { return new TraceExporter(configuration); } 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(); 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";