feat(otlp-transformer)!: add new entrypoints for non-core features

chancancode · chancancode · commit 380d5572415f · 2024-12-12T13:27:50.000-08:00
In preparation of stabilizing `@opentelemetry/otlp-transformer`, this commit introduces some new entrypoints for the package: * `@opentelemetry/otlp-transformer/proto`: utilities for working with the OTLP binary protobuf format * `@opentelemetry/otlp-transformer/json`: utilities for working with the OTLP JSON format * `@opentelemetry/otlp-transformer/experimental`: features to remain in experimental status post-stabilization The intent of separating out the first two entrypoints is to both aid bundlers with tree-shaking, but also to prevent the irrelevant code from running at all, since the generated prtobuf code is known to cause problems in certain environments (e.g. see #4987, #5096). The last of those entrypoints is currently empty, but expected to be utilized in future commits as features are triaged as part of the stabilization effort. Fixes #5216
diff --git a/experimental/CHANGELOG.md b/experimental/CHANGELOG.md
@@ -19,6 +19,10 @@ All notable changes to experimental packages in this project will be documented
 
 ### :boom: Breaking Change
 
+* feat(otlp-transformer)!: add new entrypoints for non-core features [#5259](https://github.com/open-telemetry/opentelemetry-js/pull/5259/)
+  * (user-facing): OTLP (binary protobuf) utilities now located at `@opentelemetry/otlp-transformer/proto`
+  * (user-facing): OTLP (json) utilities now located at `@opentelemetry/otlp-transformer/json`
+  * (internal): features to remain experimental post-stabilization now located at `@opentelemetry/otlp-transformer/experimental` (empty for now)
 * feat(otlp-exporter-base)!: collapse base classes into one [#5031](https://github.com/open-telemetry/opentelemetry-js/pull/5031) @pichlermarc
   * `OTLPExporterNodeBase` has been removed in favor of a platform-agnostic implementation (`OTLPExporterBase`)
   * `OTLPExporterBrowserBase` has been removed in favor of a platform-agnostic implementation (`OTLPExporterBase`)
diff --git a/experimental/packages/exporter-logs-otlp-grpc/src/OTLPLogExporter.ts b/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';
+import { ProtobufLogsSerializer } from '@opentelemetry/otlp-transformer/protobuf';
 import { OTLPExporterBase } from '@opentelemetry/otlp-exporter-base';
 
 /**
diff --git a/experimental/packages/exporter-logs-otlp-http/src/platform/browser/OTLPLogExporter.ts b/experimental/packages/exporter-logs-otlp-http/src/platform/browser/OTLPLogExporter.ts
@@ -20,7 +20,7 @@ import type {
 } from '@opentelemetry/sdk-logs';
 import type { OTLPExporterConfigBase } from '@opentelemetry/otlp-exporter-base';
 import { OTLPExporterBase } from '@opentelemetry/otlp-exporter-base';
-import { JsonLogsSerializer } from '@opentelemetry/otlp-transformer';
+import { JsonLogsSerializer } from '@opentelemetry/otlp-transformer/json';
 import { createLegacyOtlpBrowserExportDelegate } from '@opentelemetry/otlp-exporter-base/browser-http';
 
 /**
diff --git a/experimental/packages/exporter-logs-otlp-http/src/platform/node/OTLPLogExporter.ts b/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';
+import { JsonLogsSerializer } from '@opentelemetry/otlp-transformer/json';
 import { VERSION } from '../../version';
 import {
   convertLegacyHttpOptions,
diff --git a/experimental/packages/exporter-logs-otlp-proto/src/platform/browser/OTLPLogExporter.ts b/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';
+import { ProtobufLogsSerializer } from '@opentelemetry/otlp-transformer/protobuf';
 
 import { ReadableLogRecord, LogRecordExporter } from '@opentelemetry/sdk-logs';
 import { createLegacyOtlpBrowserExportDelegate } from '@opentelemetry/otlp-exporter-base/browser-http';
diff --git a/experimental/packages/exporter-logs-otlp-proto/src/platform/node/OTLPLogExporter.ts b/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';
+import { ProtobufLogsSerializer } from '@opentelemetry/otlp-transformer/protobuf';
 import {
   convertLegacyHttpOptions,
   createOtlpHttpExportDelegate,
diff --git a/experimental/packages/exporter-trace-otlp-grpc/src/OTLPTraceExporter.ts b/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';
+import { ProtobufTraceSerializer } from '@opentelemetry/otlp-transformer/protobuf';
 import { OTLPExporterBase } from '@opentelemetry/otlp-exporter-base';
 
 /**
diff --git a/experimental/packages/exporter-trace-otlp-http/src/platform/browser/OTLPTraceExporter.ts b/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';
+import { JsonTraceSerializer } from '@opentelemetry/otlp-transformer/json';
 import { createLegacyOtlpBrowserExportDelegate } from '@opentelemetry/otlp-exporter-base/browser-http';
 
 /**
diff --git a/experimental/packages/exporter-trace-otlp-http/src/platform/node/OTLPTraceExporter.ts b/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';
+import { JsonTraceSerializer } from '@opentelemetry/otlp-transformer/json';
 import {
   convertLegacyHttpOptions,
   createOtlpHttpExportDelegate,
diff --git a/experimental/packages/exporter-trace-otlp-proto/src/platform/browser/OTLPTraceExporter.ts b/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';
+import { ProtobufTraceSerializer } from '@opentelemetry/otlp-transformer/protobuf';
 import { createLegacyOtlpBrowserExportDelegate } from '@opentelemetry/otlp-exporter-base/browser-http';
 
 const DEFAULT_COLLECTOR_RESOURCE_PATH = 'v1/traces';
diff --git a/experimental/packages/exporter-trace-otlp-proto/src/platform/node/OTLPTraceExporter.ts b/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';
+import { ProtobufTraceSerializer } from '@opentelemetry/otlp-transformer/protobuf';
 import { VERSION } from '../../version';
 import {
   createOtlpHttpExportDelegate,
diff --git a/experimental/packages/opentelemetry-exporter-metrics-otlp-grpc/src/OTLPMetricExporter.ts b/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';
+import { ProtobufMetricsSerializer } from '@opentelemetry/otlp-transformer/protobuf';
 
 /**
  * OTLP-gRPC metric exporter
diff --git a/experimental/packages/opentelemetry-exporter-metrics-otlp-http/src/platform/browser/OTLPMetricExporter.ts b/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';
+import { JsonMetricsSerializer } from '@opentelemetry/otlp-transformer/json';
 import { createLegacyOtlpBrowserExportDelegate } from '@opentelemetry/otlp-exporter-base/browser-http';
 
 /**
diff --git a/experimental/packages/opentelemetry-exporter-metrics-otlp-http/src/platform/node/OTLPMetricExporter.ts b/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';
+import { JsonMetricsSerializer } from '@opentelemetry/otlp-transformer/json';
 import { VERSION } from '../../version';
 import {
   convertLegacyHttpOptions,
diff --git a/experimental/packages/opentelemetry-exporter-metrics-otlp-proto/src/OTLPMetricExporter.ts b/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';
+import { ProtobufMetricsSerializer } from '@opentelemetry/otlp-transformer/protobuf';
 import { VERSION } from './version';
 import {
   convertLegacyHttpOptions,
diff --git a/experimental/packages/otlp-transformer/README.md b/experimental/packages/otlp-transformer/README.md
@@ -21,7 +21,7 @@ npm install @opentelemetry/api
 
 ### Serialize Traces/Metrics/Logs
 
-This module exports functions to serialize traces, metrics and logs from the OpenTelemetry SDK into protocol buffers which can be sent over HTTP to the OpenTelemetry collector or a compatible receiver.
+This package exports functions to serialize traces, metrics and logs from the OpenTelemetry SDK into OTLP JSON format, which can be sent over HTTP to the OpenTelemetry collector or a compatible receiver.
 
 ```typescript
 import {
@@ -30,11 +30,86 @@ import {
   createExportLogsServiceRequest,
 } from '@opentelemetry/otlp-transformer';
 
-const serializedSpans = createExportTraceServiceRequest(readableSpans);
-const serializedMetrics = createExportMetricsServiceRequest(readableMetrics);
-const serializedLogs = createExportLogsServiceRequest(readableLogRecords);
+const serializableSpans = createExportTraceServiceRequest(readableSpans);
+const serializableMetrics = createExportMetricsServiceRequest(readableMetrics);
+const serializableLogs = createExportLogsServiceRequest(readableLogRecords);
 ```
 
+Note that these functions return JSON-serializable objects (i.e. JavaScript objects that can be passed into `JSON.stringify(...)`) adhering to the OTLP JSON format, not the serialized JSON-text payload themselves.
+
+### Protobuf (Binary) Serializers
+
+Additionally, this package also exports serializers to serialize traces, metrics and logs into the export requests using the OTLP binary protobuf format, as well as deserializing the corresponding binary response payloads.
+
+```typescript
+import {
+  ProtobufTraceSerializer,
+  ProtobufMetricsSerializer,
+  ProtobufLogsSerializer,
+} from '@opentelemetry/otlp-transformer/protobuf';
+
+const serializedSpans: Uint8Array =
+  ProtobufTraceSerializer.serializeRequest(readableSpans);
+const serializedMetrics: Uint8Array =
+  ProtobufMetricsSerializer.serializeRequest(readableMetrics);
+const serializedLogs: Uint8Array =
+  ProtobufLogsSerializer.serializeRequest(readableLogRecords);
+
+// ...
+
+const deserializedTraceResponse = ProtobufTraceSerializer.deserializeResponse(
+  serializedTraceResponse /* Uint8Array */
+);
+const deserializedMetricsResponse =
+  ProtobufMetricsSerializer.deserializeResponse(
+    serializedTraceResponse /* Uint8Array */
+  );
+const deserializedLogsResponse = ProtobufLogsSerializer.deserializeResponse(
+  serializedTraceResponse /* Uint8Array */
+);
+```
+
+### JSON Serializers
+
+For feature parity, this package also exports JSON serializers with the same interfaces:
+
+```typescript
+import {
+  JsonTraceSerializer,
+  JsonMetricsSerializer,
+  JsonLogsSerializer,
+} from '@opentelemetry/otlp-transformer/json';
+
+const serializedSpans: Uint8Array =
+  JsonTraceSerializer.serializeRequest(readableSpans);
+const serializedMetrics: Uint8Array =
+  JsonMetricsSerializer.serializeRequest(readableMetrics);
+const serializedLogs: Uint8Array =
+  JsonLogsSerializer.serializeRequest(readableLogRecords);
+
+// ...
+
+const deserializedTraceResponse = JsonTraceSerializer.deserializeResponse(
+  serializedTraceResponse /* Uint8Array */
+);
+const deserializedMetricsResponse = JsonMetricsSerializer.deserializeResponse(
+  serializedTraceResponse /* Uint8Array */
+);
+const deserializedLogsResponse = JsonLogsSerializer.deserializeResponse(
+  serializedTraceResponse /* Uint8Array */
+);
+```
+
+Unlike the `createExport*Request` functions (and similar to the binary protobuf serializers), these serializer methods returns the _serialized_ bytes directly, skipping the need to further serialize them with `JSON.stringify(...)`.
+
+Among other things, the `Uint8Array` can be used directly as the `body` of a `fetch()` request. Likewise, a `Uint8Array` of the response body can be obtained from `await response.bytes()`.
+
+### Experimental Features
+
+As we iterate towards the stabilization of this package, certain features are expected to remain in experimental status. These features are subject to changes and breakages between minor versions of the package, even after the package itself reaches version `1.0`.
+
+These features are exported from the `@opentelemetry/otlp-transformer/experimental` entrypoint. Currently, this entrypoint is empty, as the entire package is considered experimental at the moment. It is expected to be utilized as part of upcoming stabilization efforts.
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
diff --git a/experimental/packages/otlp-transformer/package.json b/experimental/packages/otlp-transformer/package.json
@@ -6,10 +6,48 @@
   },
   "version": "0.56.0",
   "description": "Transform OpenTelemetry SDK data into OTLP",
-  "module": "build/esm/index.js",
-  "esnext": "build/esnext/index.js",
-  "types": "build/src/index.d.ts",
-  "main": "build/src/index.js",
+  "exports": {
+    ".": {
+      "module": "./build/esm/index.js",
+      "esnext": "./build/esnext/index.js",
+      "types": "./build/src/index.d.ts",
+      "default": "./build/src/index.js"
+    },
+    "./experimental": {
+      "module": "./build/esm/experimental/index.js",
+      "esnext": "./build/esnext/experimental/index.js",
+      "types": "./build/src/experimental/index.d.ts",
+      "default": "./build/src/experimental/index.js"
+    },
+    "./json": {
+      "module": "./build/esm/json/index.js",
+      "esnext": "./build/esnext/json/index.js",
+      "types": "./build/src/json/index.d.ts",
+      "default": "./build/src/json/index.js"
+    },
+    "./protobuf": {
+      "module": "./build/esm/protobuf/index.js",
+      "esnext": "./build/esnext/protobuf/index.js",
+      "types": "./build/src/protobuf/index.d.ts",
+      "default": "./build/src/protobuf/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./build/src/index.d.ts"
+      ],
+      "experimental": [
+        "./build/src/experimental/index.d.ts"
+      ],
+      "json": [
+        "./build/src/json/index.d.ts"
+      ],
+      "protobuf": [
+        "./build/src/protobuf/index.d.ts"
+      ]
+    }
+  },
   "repository": "open-telemetry/opentelemetry-js",
   "scripts": {
     "prepublishOnly": "npm run compile",
diff --git a/experimental/packages/otlp-transformer/src/experimental/index.ts b/experimental/packages/otlp-transformer/src/experimental/index.ts
@@ -0,0 +1,17 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export default {};
diff --git a/experimental/packages/otlp-transformer/src/index.ts b/experimental/packages/otlp-transformer/src/index.ts
@@ -84,16 +84,4 @@ export { createExportTraceServiceRequest } from './trace';
 export { createExportMetricsServiceRequest } from './metrics';
 export { createExportLogsServiceRequest } from './logs';
 
-export {
-  ProtobufLogsSerializer,
-  ProtobufMetricsSerializer,
-  ProtobufTraceSerializer,
-} from './protobuf/serializers';
-
-export {
-  JsonTraceSerializer,
-  JsonLogsSerializer,
-  JsonMetricsSerializer,
-} from './json/serializers';
-
 export { ISerializer } from './common/i-serializer';
diff --git a/experimental/packages/otlp-transformer/src/json/index.ts b/experimental/packages/otlp-transformer/src/json/index.ts
@@ -0,0 +1,21 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export {
+  JsonTraceSerializer,
+  JsonMetricsSerializer,
+  JsonLogsSerializer,
+} from './serializers';
diff --git a/experimental/packages/otlp-transformer/src/protobuf/index.ts b/experimental/packages/otlp-transformer/src/protobuf/index.ts
@@ -0,0 +1,21 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export {
+  ProtobufTraceSerializer,
+  ProtobufMetricsSerializer,
+  ProtobufLogsSerializer,
+} from './serializers';
diff --git a/experimental/packages/otlp-transformer/test/logs.test.ts b/experimental/packages/otlp-transformer/test/logs.test.ts
@@ -21,10 +21,10 @@ import {
   createExportLogsServiceRequest,
   ESeverityNumber,
   IExportLogsServiceRequest,
-  ProtobufLogsSerializer,
-  JsonLogsSerializer,
   OtlpEncodingOptions,
 } from '../src';
+import { JsonLogsSerializer } from '../src/json';
+import { ProtobufLogsSerializer } from '../src/protobuf';
 import { ReadableLogRecord } from '@opentelemetry/sdk-logs';
 import { SeverityNumber } from '@opentelemetry/api-logs';
 import { toBase64 } from './utils';
diff --git a/experimental/packages/otlp-transformer/test/metrics.test.ts b/experimental/packages/otlp-transformer/test/metrics.test.ts
@@ -26,12 +26,9 @@ import * as assert from 'assert';
 import { createExportMetricsServiceRequest } from '../src/metrics';
 import { EAggregationTemporality } from '../src/metrics/types';
 import { hrTime, hrTimeToNanoseconds } from '@opentelemetry/core';
-import {
-  encodeAsString,
-  encodeAsLongBits,
-  ProtobufMetricsSerializer,
-  JsonMetricsSerializer,
-} from '../src';
+import { encodeAsString, encodeAsLongBits } from '../src';
+import { JsonMetricsSerializer } from '../src/json';
+import { ProtobufMetricsSerializer } from '../src/protobuf';
 import * as root from '../src/generated/root';
 
 const START_TIME = hrTime();
diff --git a/experimental/packages/otlp-transformer/test/trace.test.ts b/experimental/packages/otlp-transformer/test/trace.test.ts
