docs(otlp-transformer): add entrypoints to readme.md

Author: pichlermarc

experimental/CHANGELOG.md

@@ -10,6 +10,18 @@ All notable changes to experimental packages in this project will be documented
 ### :rocket: (Enhancement)
 
 * feat(opentelemetry-sdk-node): automatically configure metrics exporter based on environment variables [#5168](https://github.com/open-telemetry/opentelemetry-js/pull/5168) @bhaskarbanerjee
+* feat(oltp-transformer)!: move each serializer to its own entrypoint [#5263](https://github.com/open-telemetry/opentelemetry-js/pull/5263) @pichlermarc
+  * 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
 
 ### :bug: (Bug Fix)
 

experimental/packages/otlp-transformer/README.md

@@ -19,45 +19,63 @@ To get started you will need to install a compatible OpenTelemetry API.
 npm install @opentelemetry/api
 ```
 
+### 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);
+// Logs (protobuf) - experimental
+import { IExportLogsServiceResponse } from '@opentelemetry/otlp-transformer/experimental/logs';
+import { ProtobufLogsSerializer } from '@opentelemetry/otlp-transformer/experimental/logs/protobuf';
 
-// serialize to Protobuf export requests
 const serializedProtobufLogs: Uint8Array = ProtobufLogsSerializer.serializeRequest(readableLogRecords);
-const serializedProtobufMetrics: Uint8Array = ProtobufMetricsSerializer.serializeRequest(resourceMetrics);
-const serializedProtobufTraces: Uint8Array = ProtobufTraceSerializer.serializeRequest(readableSpans);
+const deserializedProtobufLogResponse: IExportLogsServiceResponse = ProtobufLogsSerializer.deserializeResponse(protobufLogResponse);
+
+// Logs (json) - experimental
+import { IExportLogsServiceResponse } from '@opentelemetry/otlp-transformer/experimental/logs';
+import { JsonLogsSerializer } from '@opentelemetry/otlp-transformer/experimental/logs/json';
 
-// deserialize JSON export responses
+const serializedJsonLogs: Uint8Array = JsonLogsSerializer.serializeRequest(readableLogRecords);
 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);
+// Metrics (protobuf)
+import { IExportMetricsServiceResponse } from '@opentelemetry/otlp-transformer/metrics'
+import { ProtobufMetricsSerializer } from '@opentelemetry/otlp-transformer/metrics/protobuf';
+
+const serializedProtobufMetrics: Uint8Array = ProtobufMetricsSerializer.serializeRequest(resourceMetrics);
 const deserializedProtobufMetricsResponse: IExportMetricsServiceResponse = ProtobufMetricsSerializer.deserializeResponse(protobufMetricsResponse);
+
+// Metrics (json)
+import { IExportMetricsServiceResponse } from '@opentelemetry/otlp-transformer/metrics'
+import { JsonMetricsSerializer } from '@opentelemetry/otlp-transformer/metrics/json';
+
+const serializedJsonMetrics: Uint8Array = JsonMetricsSerializer.serializeRequest(resourceMetrics);
+const deserializedJsonMetricsResponse: IExportMetricsServiceResponse = JsonMetricsSerializer.deserializeResponse(jsonMetricsResponse);
+
+// Traces (protobuf)
+import { IExportTraceServiceResponse } from '@opentelemetry/otlp-transformer/trace'
+import { ProtobufTraceSerializer } from '@opentelemetry/otlp-transformer/trace/protobuf';
+
+const serializedProtobufTraces: Uint8Array = ProtobufTraceSerializer.serializeRequest(readableSpans);
 const deserializedProtobufTraceResponse: IExportTraceServiceResponse = ProtobufTraceSerializer.deserializeResponse(protobufTraceResponse);
+
+// Traces (json)
+import { IExportTraceServiceResponse } from '@opentelemetry/otlp-transformer/trace'
+import { JsonTraceSerializer } from '@opentelemetry/otlp-transformer/trace/json';
+
+const deserializedJsonTraceResponse: IExportTraceServiceResponse = JsonTraceSerializer.deserializeResponse(jsonTraceResponse);
+const serializedJsonTraces: Uint8Array = JsonTraceSerializer.serializeRequest(readableSpans);
 ```
 
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

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';

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

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+// IMPORTANT: exports added here are public
 export {
   IExportLogsServiceResponse,
   IExportLogsPartialSuccess,

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

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

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

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+// IMPORTANT: exports added here are public
 export {
   IExportMetricsPartialSuccess,
   IExportMetricsServiceResponse,

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

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

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

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

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

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+// IMPORTANT: exports added here are public
 export {
   IExportTracePartialSuccess,
   IExportTraceServiceResponse,

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

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