feat(otlp-transformer)!: use factory functions over constants to bett…

…er allow keeping state in the future

experimental/CHANGELOG.md

@@ -9,6 +9,24 @@ All notable changes to experimental packages in this project will be documented
 
 ### :rocket: (Enhancement)
 
+* feat(oltp-transformer)!: move each serializer to its own entrypoint
+  * This package depends on all signals, as well as `protobuf.js`, so some bundlers like rollup would issue warnings even if the user made a conscious decision to not use a protobuf exporter
+  * (user-facing) All types except for `ISerializer` were removed from the main entrypoint, to get previously exported types, use the following entrypoints
+    * `@opentelemetry/otlp-transformer/metrics`: metrics export service return types
+    * `@opentelemetry/otlp-transformer/metrics/json`: metrics json serializer
+    * `@opentelemetry/otlp-transformer/metrics/protobuf`: metrics protobuf serializer
+    * `@opentelemetry/otlp-transformer/trace`: trace export service return types
+    * `@opentelemetry/otlp-transformer/trace/trace`: trace json serializer
+    * `@opentelemetry/otlp-transformer/trace/protobuf`: trace protobuf serializer
+    * `@opentelemetry/otlp-transformer/logs`: logs export service return types
+    * `@opentelemetry/otlp-transformer/logs/trace`: logs export service return types
+    * `@opentelemetry/otlp-transformer/logs/protobuf`: logs export service return types
+* feat(otlp-transformer)!: change serializer acquisition from constant to factory function
+  * (user-facing) serializer constant export have now been removed and replaced by factory functions
+    * to acquire a serializer, replace `<ExportType><Signal>Serializer` with `create<ExportType><Signal>Serializer()`
+      * example: `ProtobufMetricsSerializer` -> `createProtobufMetricsSerializer()`
+    * this was done to simplify future performance improvements without having to introduce additional APIs
+
 ### :bug: (Bug Fix)
 
 ### :books: (Refine Doc)

experimental/packages/exporter-logs-otlp-grpc/src/OTLPLogExporter.ts

@@ -20,7 +20,7 @@ import {
   createOtlpGrpcExportDelegate,
   OTLPGRPCExporterConfigNode,
 } from '@opentelemetry/otlp-grpc-exporter-base';
-import { ProtobufLogsSerializer } from '@opentelemetry/otlp-transformer/experimental/logs/protobuf';
+import { createProtobufLogsSerializer } from '@opentelemetry/otlp-transformer/experimental/logs/protobuf';
 import { OTLPExporterBase } from '@opentelemetry/otlp-exporter-base';
 
 /**
@@ -34,7 +34,7 @@ export class OTLPLogExporter
     super(
       createOtlpGrpcExportDelegate(
         convertLegacyOtlpGrpcOptions(config, 'LOGS'),
-        ProtobufLogsSerializer,
+        createProtobufLogsSerializer(),
         'LogsExportService',
         '/opentelemetry.proto.collector.logs.v1.LogsService/Export'
       )

experimental/packages/exporter-logs-otlp-http/src/platform/browser/OTLPLogExporter.ts

@@ -21,7 +21,7 @@ import type {
 import type { OTLPExporterConfigBase } from '@opentelemetry/otlp-exporter-base';
 import { OTLPExporterBase } from '@opentelemetry/otlp-exporter-base';
 import { createLegacyOtlpBrowserExportDelegate } from '@opentelemetry/otlp-exporter-base/browser-http';
-import { JsonLogsSerializer } from '@opentelemetry/otlp-transformer/experimental/logs/json';
+import { createJsonLogsSerializer } from '@opentelemetry/otlp-transformer/experimental/logs/json';
 
 /**
  * Collector Logs Exporter for Web
@@ -34,7 +34,7 @@ export class OTLPLogExporter
     super(
       createLegacyOtlpBrowserExportDelegate(
         config,
-        JsonLogsSerializer,
+        createJsonLogsSerializer(),
         'v1/logs',
         { 'Content-Type': 'application/json' }
       )

experimental/packages/exporter-logs-otlp-http/src/platform/node/OTLPLogExporter.ts

@@ -20,7 +20,7 @@ import type {
 } from '@opentelemetry/sdk-logs';
 import type { OTLPExporterNodeConfigBase } from '@opentelemetry/otlp-exporter-base';
 import { OTLPExporterBase } from '@opentelemetry/otlp-exporter-base';
-import { JsonLogsSerializer } from '@opentelemetry/otlp-transformer/experimental/logs/json';
+import { createJsonLogsSerializer } from '@opentelemetry/otlp-transformer/experimental/logs/json';
 import { VERSION } from '../../version';
 import {
   convertLegacyHttpOptions,
@@ -41,7 +41,7 @@ export class OTLPLogExporter
           'User-Agent': `OTel-OTLP-Exporter-JavaScript/${VERSION}`,
           'Content-Type': 'application/json',
         }),
-        JsonLogsSerializer
+        createJsonLogsSerializer()
       )
     );
   }

experimental/packages/exporter-logs-otlp-proto/src/platform/browser/OTLPLogExporter.ts

@@ -18,7 +18,7 @@ import {
   OTLPExporterConfigBase,
   OTLPExporterBase,
 } from '@opentelemetry/otlp-exporter-base';
-import { ProtobufLogsSerializer } from '@opentelemetry/otlp-transformer/experimental/logs/protobuf';
+import { createProtobufLogsSerializer } from '@opentelemetry/otlp-transformer/experimental/logs/protobuf';
 
 import { ReadableLogRecord, LogRecordExporter } from '@opentelemetry/sdk-logs';
 import { createLegacyOtlpBrowserExportDelegate } from '@opentelemetry/otlp-exporter-base/browser-http';
@@ -34,7 +34,7 @@ export class OTLPLogExporter
     super(
       createLegacyOtlpBrowserExportDelegate(
         config,
-        ProtobufLogsSerializer,
+        createProtobufLogsSerializer(),
         'v1/logs',
         { 'Content-Type': 'application/x-protobuf' }
       )

experimental/packages/exporter-logs-otlp-proto/src/platform/node/OTLPLogExporter.ts

@@ -18,7 +18,7 @@ import {
   OTLPExporterBase,
   OTLPExporterNodeConfigBase,
 } from '@opentelemetry/otlp-exporter-base';
-import { ProtobufLogsSerializer } from '@opentelemetry/otlp-transformer/experimental/logs/protobuf';
+import { createProtobufLogsSerializer } from '@opentelemetry/otlp-transformer/experimental/logs/protobuf';
 import {
   convertLegacyHttpOptions,
   createOtlpHttpExportDelegate,
@@ -41,7 +41,7 @@ export class OTLPLogExporter
           'User-Agent': `OTel-OTLP-Exporter-JavaScript/${VERSION}`,
           'Content-Type': 'application/x-protobuf',
         }),
-        ProtobufLogsSerializer
+        createProtobufLogsSerializer()
       )
     );
   }

experimental/packages/exporter-trace-otlp-grpc/src/OTLPTraceExporter.ts

@@ -20,7 +20,7 @@ import {
   createOtlpGrpcExportDelegate,
   OTLPGRPCExporterConfigNode,
 } from '@opentelemetry/otlp-grpc-exporter-base';
-import { ProtobufTraceSerializer } from '@opentelemetry/otlp-transformer/trace/protobuf';
+import { createProtobufTraceSerializer } from '@opentelemetry/otlp-transformer/trace/protobuf';
 import { OTLPExporterBase } from '@opentelemetry/otlp-exporter-base';
 
 /**
@@ -34,7 +34,7 @@ export class OTLPTraceExporter
     super(
       createOtlpGrpcExportDelegate(
         convertLegacyOtlpGrpcOptions(config, 'TRACES'),
-        ProtobufTraceSerializer,
+        createProtobufTraceSerializer(),
         'TraceExportService',
         '/opentelemetry.proto.collector.trace.v1.TraceService/Export'
       )

experimental/packages/exporter-trace-otlp-http/src/platform/browser/OTLPTraceExporter.ts

@@ -19,7 +19,7 @@ import {
   OTLPExporterConfigBase,
   OTLPExporterBase,
 } from '@opentelemetry/otlp-exporter-base';
-import { JsonTraceSerializer } from '@opentelemetry/otlp-transformer/trace/json';
+import { createJsonTraceSerializer } from '@opentelemetry/otlp-transformer/trace/json';
 import { createLegacyOtlpBrowserExportDelegate } from '@opentelemetry/otlp-exporter-base/browser-http';
 
 /**
@@ -33,7 +33,7 @@ export class OTLPTraceExporter
     super(
       createLegacyOtlpBrowserExportDelegate(
         config,
-        JsonTraceSerializer,
+        createJsonTraceSerializer(),
         'v1/traces',
         { 'Content-Type': 'application/json' }
       )

experimental/packages/exporter-trace-otlp-http/src/platform/node/OTLPTraceExporter.ts

@@ -20,7 +20,7 @@ import {
   OTLPExporterBase,
 } from '@opentelemetry/otlp-exporter-base';
 import { VERSION } from '../../version';
-import { JsonTraceSerializer } from '@opentelemetry/otlp-transformer/trace/json';
+import { createJsonTraceSerializer } from '@opentelemetry/otlp-transformer/trace/json';
 import {
   convertLegacyHttpOptions,
   createOtlpHttpExportDelegate,
@@ -40,7 +40,7 @@ export class OTLPTraceExporter
           'User-Agent': `OTel-OTLP-Exporter-JavaScript/${VERSION}`,
           'Content-Type': 'application/json',
         }),
-        JsonTraceSerializer
+        createJsonTraceSerializer()
       )
     );
   }

experimental/packages/exporter-trace-otlp-proto/src/platform/browser/OTLPTraceExporter.ts

@@ -19,7 +19,7 @@ import {
   OTLPExporterConfigBase,
   OTLPExporterBase,
 } from '@opentelemetry/otlp-exporter-base';
-import { ProtobufTraceSerializer } from '@opentelemetry/otlp-transformer/trace/protobuf';
+import { createProtobufTraceSerializer } from '@opentelemetry/otlp-transformer/trace/protobuf';
 import { createLegacyOtlpBrowserExportDelegate } from '@opentelemetry/otlp-exporter-base/browser-http';
 
 const DEFAULT_COLLECTOR_RESOURCE_PATH = 'v1/traces';
@@ -35,7 +35,7 @@ export class OTLPTraceExporter
     super(
       createLegacyOtlpBrowserExportDelegate(
         config,
-        ProtobufTraceSerializer,
+        createProtobufTraceSerializer(),
         DEFAULT_COLLECTOR_RESOURCE_PATH,
         { 'Content-Type': 'application/x-protobuf' }
       )

experimental/packages/exporter-trace-otlp-proto/src/platform/node/OTLPTraceExporter.ts

@@ -19,7 +19,7 @@ import {
   OTLPExporterNodeConfigBase,
   OTLPExporterBase,
 } from '@opentelemetry/otlp-exporter-base';
-import { ProtobufTraceSerializer } from '@opentelemetry/otlp-transformer/trace/protobuf';
+import { createProtobufTraceSerializer } from '@opentelemetry/otlp-transformer/trace/protobuf';
 import { VERSION } from '../../version';
 import {
   createOtlpHttpExportDelegate,
@@ -40,7 +40,7 @@ export class OTLPTraceExporter
           'User-Agent': `OTel-OTLP-Exporter-JavaScript/${VERSION}`,
           'Content-Type': 'application/x-protobuf',
         }),
-        ProtobufTraceSerializer
+        createProtobufTraceSerializer()
       )
     );
   }

experimental/packages/opentelemetry-exporter-metrics-otlp-grpc/src/OTLPMetricExporter.ts

@@ -23,7 +23,7 @@ import {
   createOtlpGrpcExportDelegate,
   OTLPGRPCExporterConfigNode,
 } from '@opentelemetry/otlp-grpc-exporter-base';
-import { ProtobufMetricsSerializer } from '@opentelemetry/otlp-transformer/metrics/protobuf';
+import { createProtobufMetricsSerializer } from '@opentelemetry/otlp-transformer/metrics/protobuf';
 
 /**
  * OTLP-gRPC metric exporter
@@ -33,7 +33,7 @@ export class OTLPMetricExporter extends OTLPMetricExporterBase {
     super(
       createOtlpGrpcExportDelegate(
         convertLegacyOtlpGrpcOptions(config ?? {}, 'METRICS'),
-        ProtobufMetricsSerializer,
+        createProtobufMetricsSerializer(),
         'MetricsExportService',
         '/opentelemetry.proto.collector.metrics.v1.MetricsService/Export'
       ),

experimental/packages/opentelemetry-exporter-metrics-otlp-http/src/platform/browser/OTLPMetricExporter.ts

@@ -17,7 +17,7 @@
 import { OTLPMetricExporterOptions } from '../../OTLPMetricExporterOptions';
 import { OTLPMetricExporterBase } from '../../OTLPMetricExporterBase';
 import { OTLPExporterConfigBase } from '@opentelemetry/otlp-exporter-base';
-import { JsonMetricsSerializer } from '@opentelemetry/otlp-transformer/metrics/json';
+import { createJsonMetricsSerializer } from '@opentelemetry/otlp-transformer/metrics/json';
 import { createLegacyOtlpBrowserExportDelegate } from '@opentelemetry/otlp-exporter-base/browser-http';
 
 /**
@@ -28,7 +28,7 @@ export class OTLPMetricExporter extends OTLPMetricExporterBase {
     super(
       createLegacyOtlpBrowserExportDelegate(
         config ?? {},
-        JsonMetricsSerializer,
+        createJsonMetricsSerializer(),
         'v1/metrics',
         { 'Content-Type': 'application/json' }
       )

experimental/packages/opentelemetry-exporter-metrics-otlp-http/src/platform/node/OTLPMetricExporter.ts

@@ -17,7 +17,7 @@
 import { OTLPMetricExporterOptions } from '../../OTLPMetricExporterOptions';
 import { OTLPMetricExporterBase } from '../../OTLPMetricExporterBase';
 import { OTLPExporterNodeConfigBase } from '@opentelemetry/otlp-exporter-base';
-import { JsonMetricsSerializer } from '@opentelemetry/otlp-transformer/metrics/json';
+import { createJsonMetricsSerializer } from '@opentelemetry/otlp-transformer/metrics/json';
 import { VERSION } from '../../version';
 import {
   convertLegacyHttpOptions,
@@ -39,7 +39,7 @@ export class OTLPMetricExporter extends OTLPMetricExporterBase {
           ...USER_AGENT,
           'Content-Type': 'application/json',
         }),
-        JsonMetricsSerializer
+        createJsonMetricsSerializer()
       ),
       config
     );

experimental/packages/opentelemetry-exporter-metrics-otlp-proto/src/OTLPMetricExporter.ts

@@ -17,7 +17,7 @@
 import { OTLPMetricExporterOptions } from '@opentelemetry/exporter-metrics-otlp-http';
 import { OTLPMetricExporterBase } from '@opentelemetry/exporter-metrics-otlp-http';
 import { OTLPExporterNodeConfigBase } from '@opentelemetry/otlp-exporter-base';
-import { ProtobufMetricsSerializer } from '@opentelemetry/otlp-transformer/metrics/protobuf';
+import { createProtobufMetricsSerializer } from '@opentelemetry/otlp-transformer/metrics/protobuf';
 import { VERSION } from './version';
 import {
   convertLegacyHttpOptions,
@@ -32,7 +32,7 @@ export class OTLPMetricExporter extends OTLPMetricExporterBase {
           'User-Agent': `OTel-OTLP-Exporter-JavaScript/${VERSION}`,
           'Content-Type': 'application/x-protobuf',
         }),
-        ProtobufMetricsSerializer
+        createProtobufMetricsSerializer()
       ),
       config
     );

experimental/packages/otlp-transformer/README.md

@@ -19,59 +19,66 @@ To get started you will need to install a compatible OpenTelemetry API.
 npm install @opentelemetry/api
 ```
 
-### Entrypoints
-
-Since this package depends on all signals, and protobuf.js for serialization,
-this package offers multiple entrypoints to avoid polluting the app during bundling.
-
-- `@opentelmetry/otlp-transformer` interfaces used by every signal
-- `@opentelmetry/otlp-transformer/metrics` interfaces used by metrics
-- `@opentelmetry/otlp-transformer/metrics/protobuf` OTLP protobuf serialization for metrics
-- `@opentelmetry/otlp-transformer/metrics/json` OTLP JSON serialization for metrics
-- `@opentelmetry/otlp-transformer/trace` interfaces used by trace
-- `@opentelmetry/otlp-transformer/trace/protobuf` OTLP protobuf serialization for trace
-- `@opentelmetry/otlp-transformer/trace/json` OTLP JSON serialization for trace
-- `@opentelmetry/otlp-transformer/experimental/logs` interfaces used by logs
-- `@opentelmetry/otlp-transformer/experimental/logs/protobuf` OTLP protobuf serialization for logs
-- `@opentelmetry/otlp-transformer/experimental/logs/json` OTLP JSON serialization for logs
+### Experimental Features and Entrypoint
+
+This package is currently marked as experimental. New minor versions may include breaking changes, regardless of
+the entrypoint used. Once the package is marked as stable, only the `experimental/` entrypoint will break in
+minor versions of the package. If you use experimental features it is therefore recommended to pin the package or use
+to depend on a tilde-version.
 
 ### Serialize Traces/Metrics/Logs
 
 This module exports serializers to serialize traces, metrics and logs from the OpenTelemetry SDK into protocol buffers
 or JSON which can be sent over HTTP or gRPC (protobuf-only) to the OpenTelemetry collector or a compatible receiver.
 
 ```typescript
-import {
-  JsonLogsSerializer,
-  JsonMetricsSerializer,
-  JsonTraceSerializer,
-  ProtobufLogsSerializer,
-  ProtobufMetricsSerializer,
-  ProtobufTraceSerializer,
-  IExportLogsServiceResponse,
-  IExportMetricsServiceResponse,
-  IExportTraceServiceResponse,
-} from '@opentelemetry/otlp-transformer';
-
-// serialize to JSON export requests
-const serializedJsonLogs: Uint8Array = JsonLogsSerializer.serializeRequest(readableLogRecords);
-const serializedJsonMetrics: Uint8Array = JsonMetricsSerializer.serializeRequest(resourceMetrics);
-const serializedJsonTraces: Uint8Array = JsonTraceSerializer.serializeRequest(readableSpans);
-
-// serialize to Protobuf export requests
-const serializedProtobufLogs: Uint8Array = ProtobufLogsSerializer.serializeRequest(readableLogRecords);
-const serializedProtobufMetrics: Uint8Array = ProtobufMetricsSerializer.serializeRequest(resourceMetrics);
-const serializedProtobufTraces: Uint8Array = ProtobufTraceSerializer.serializeRequest(readableSpans);
-
-// deserialize JSON export responses
-const deserializedJsonLogResponse: IExportLogsServiceResponse = JsonLogsSerializer.deserializeResponse(jsonLogResponse);
-const deserializedJsonMetricsResponse: IExportMetricsServiceResponse = JsonMetricsSerializer.deserializeResponse(jsonMetricsResponse);
-const deserializedJsonTraceResponse: IExportTraceServiceResponse = JsonTraceSerializer.deserializeResponse(jsonTraceResponse);
-
-// deserialize Protobuf export responses
-const deserializedProtobufLogResponse: IExportLogsServiceResponse = ProtobufLogsSerializer.deserializeResponse(protobufLogResponse);
-const deserializedProtobufMetricsResponse: IExportMetricsServiceResponse = ProtobufMetricsSerializer.deserializeResponse(protobufMetricsResponse);
-const deserializedProtobufTraceResponse: IExportTraceServiceResponse = ProtobufTraceSerializer.deserializeResponse(protobufTraceResponse);
+// Logs (protobuf) - experimental
+import {IExportLogsServiceResponse} from '@opentelemetry/otlp-transformer/experimental/logs';
+import {createProtobufLogsSerializer} from '@opentelemetry/otlp-transformer/experimental/logs/protobuf';
+
+const protobufLogsSerializer = createProtobufTraceSerializer();
+const serializedProtobufLogs: Uint8Array = protobufLogsSerializer.serializeRequest(readableLogRecords);
+const deserializedProtobufLogResponse: IExportLogsServiceResponse = protobufLogsSerializer.deserializeResponse(protobufLogResponse);
+
+// Logs (json) - experimental
+import {IExportLogsServiceResponse} from '@opentelemetry/otlp-transformer/experimental/logs';
+import {createJsonLogsSerializer} from '@opentelemetry/otlp-transformer/experimental/logs/json';
+
+const jsonLogsSerializer = createJsonLogsSerializer();
+const serializedJsonLogs: Uint8Array = jsonLogsSerializer.serializeRequest(readableLogRecords);
+const deserializedJsonLogResponse: IExportLogsServiceResponse = jsonLogsSerializer.deserializeResponse(jsonLogResponse);
+
+// Metrics (protobuf)
+import {IExportMetricsServiceResponse} from '@opentelemetry/otlp-transformer/metrics'
+import {createProtobufMetricsSerializer} from '@opentelemetry/otlp-transformer/metrics/protobuf';
+
+const protobufMetricsSerializer = createProtobufMetricsSerializer();
+const serializedProtobufMetrics: Uint8Array = protobufMetricsSerializer.serializeRequest(resourceMetrics);
+const deserializedProtobufMetricsResponse: IExportMetricsServiceResponse = protobufMetricsSerializer.deserializeResponse(protobufMetricsResponse);
+
+// Metrics (json)
+import {IExportMetricsServiceResponse} from '@opentelemetry/otlp-transformer/metrics'
+import {createJsonMetricsSerializer} from '@opentelemetry/otlp-transformer/metrics/json';
+
+const jsonMetricsSerializer = createJsonMetricsSerializer();
+const serializedJsonMetrics: Uint8Array = jsonMetricsSerializer.serializeRequest(resourceMetrics);
+const deserializedJsonMetricsResponse: IExportMetricsServiceResponse = jsonMetricsSerializer.deserializeResponse(jsonMetricsResponse);
+
+// Traces (protobuf)
+import {IExportTraceServiceResponse} from '@opentelemetry/otlp-transformer/trace'
+import {createProtobufTraceSerializer} from '@opentelemetry/otlp-transformer/trace/protobuf';
+
+const protobufTraceSerializer = createProtobufTraceSerializer();
+const serializedProtobufTraces: Uint8Array = protobufTraceSerializer.serializeRequest(readableSpans);
+const deserializedProtobufTraceResponse: IExportTraceServiceResponse = protobufTraceSerializer.deserializeResponse(protobufTraceResponse);
+
+// Traces (json)
+import {IExportTraceServiceResponse} from '@opentelemetry/otlp-transformer/trace'
+import {createJsonTraceSerializer} from '@opentelemetry/otlp-transformer/trace/json';
+
+const jsonTraceSerializer = createJsonTraceSerializer();
+const deserializedJsonTraceResponse: IExportTraceServiceResponse = jsonTraceSerializer.deserializeResponse(jsonTraceResponse);
+const serializedJsonTraces: Uint8Array = jsonTraceSerializer.serializeRequest(readableSpans);
 ```
 
 ## Useful links

experimental/packages/otlp-transformer/src/index.ts

@@ -14,4 +14,5 @@
  * limitations under the License.
  */
 
+// IMPORTANT: exports added here are public
 export { ISerializer } from './i-serializer';