feat(otlp-transformer)!: remove internal types and functions from public API

experimental/CHANGELOG.md

@@ -19,6 +19,60 @@ All notable changes to experimental packages in this project will be documented
 * feat(otlp-transformer)!: accept `ResourceMetrics` in serializers instead of `ResourceMetrics[]`
   * (user-facing): `ProtobufMetricsSerializer` now only accepts `ResourceMetrics` instead of `ResourceMetrics[]` to align with `PushMetricExporter` requirements
   * (user-facing): `JsonMetricsSerializer` now only accepts `ResourceMetrics` instead of `ResourceMetrics[]` to align with `PushMetricExporter` requirements
+* feat(otlp-transformer)!: remove internal types and functions from public API @pichlermarc
+  * (user-facing): the following types and functions were intended for internal use and have been removed from exports
+    * `OtlpEncodingOptions`
+    * `IKeyValueList`
+    * `IKeyValue`
+    * `IInstrumentationScope`
+    * `IArrayValue`
+    * `LongBits`
+    * `IAnyValue`
+    * `Fixed64`
+    * `SpanContextEncodeFunction`
+    * `toLongBits`
+    * `OptionalSpanContextEncodeFunction`
+    * `getOtlpEncoder`
+    * `Encoder`
+    * `HrTimeEncodeFunction`
+    * `encodeAsLongBits`
+    * `encodeAsString`
+    * `hrTimeToNanos`
+    * `IValueAtQuantile`
+    * `ISummaryDataPoint`
+    * `ISummary`
+    * `ISum`
+    * `IScopeMetrics`
+    * `IResourceMetrics`
+    * `INumberDataPoint`
+    * `IHistogramDataPoint`
+    * `IHistogram`
+    * `IExponentialHistogramDataPoint`
+    * `IExponentialHistogram`
+    * `IMetric`
+    * `IGauge`
+    * `IExemplar`
+    * `EAggregationTemporality`
+    * `IExportMetricsServiceRequest`
+    * `IBuckets`
+    * `IResource`
+    * `IStatus`
+    * `EStatusCode`
+    * `ILink`
+    * `IEvent`
+    * `IScopeSpans`
+    * `ISpan`
+    * `IResourceSpans`
+    * `ESpanKind`
+    * `IExportTraceServiceRequest`
+    * `IScopeLogs`
+    * `IExportLogsServiceRequest`
+    * `IResourceLogs`
+    * `ILogRecord`
+    * `ESeverityNumber`
+    * `createExportTraceServiceRequest`
+    * `createExportMetricsServiceRequest`
+    * `createExportLogsServiceRequest`
 
 ### :rocket: (Enhancement)
 

experimental/packages/otlp-transformer/README.md

@@ -21,18 +21,41 @@ 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 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 {
-  createExportTraceServiceRequest,
-  createExportMetricsServiceRequest,
-  createExportLogsServiceRequest,
+  JsonLogsSerializer,
+  JsonMetricsSerializer,
+  JsonTraceSerializer,
+  ProtobufLogsSerializer,
+  ProtobufMetricsSerializer,
+  ProtobufTraceSerializer,
+  IExportLogsServiceResponse,
+  IExportMetricsServiceResponse,
+  IExportTraceServiceResponse,
 } from '@opentelemetry/otlp-transformer';
 
-const serializedSpans = createExportTraceServiceRequest(readableSpans);
-const serializedMetrics = createExportMetricsServiceRequest(readableMetrics);
-const serializedLogs = createExportLogsServiceRequest(readableLogRecords);
+// 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);
 ```
 
 ## Useful links

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

@@ -14,76 +14,19 @@
  * limitations under the License.
  */
 
-export {
-  OtlpEncodingOptions,
-  IKeyValueList,
-  IKeyValue,
-  IInstrumentationScope,
-  IArrayValue,
-  LongBits,
-  IAnyValue,
-  Fixed64,
-} from './common/types';
-export {
-  SpanContextEncodeFunction,
-  toLongBits,
-  OptionalSpanContextEncodeFunction,
-  getOtlpEncoder,
-  Encoder,
-  HrTimeEncodeFunction,
-  encodeAsLongBits,
-  encodeAsString,
-  hrTimeToNanos,
-} from './common';
 export {
   IExportMetricsPartialSuccess,
-  IValueAtQuantile,
-  ISummaryDataPoint,
-  ISummary,
-  ISum,
-  IScopeMetrics,
-  IResourceMetrics,
-  INumberDataPoint,
-  IHistogramDataPoint,
-  IHistogram,
-  IExponentialHistogramDataPoint,
-  IExponentialHistogram,
-  IMetric,
-  IGauge,
-  IExemplar,
-  EAggregationTemporality,
-  IExportMetricsServiceRequest,
   IExportMetricsServiceResponse,
-  IBuckets,
 } from './metrics/types';
-export { IResource } from './resource/types';
 export {
   IExportTracePartialSuccess,
-  IStatus,
-  EStatusCode,
-  ILink,
-  IEvent,
-  IScopeSpans,
-  ISpan,
-  IResourceSpans,
-  ESpanKind,
   IExportTraceServiceResponse,
-  IExportTraceServiceRequest,
 } from './trace/types';
 export {
   IExportLogsServiceResponse,
-  IScopeLogs,
-  IExportLogsServiceRequest,
-  IResourceLogs,
-  ILogRecord,
   IExportLogsPartialSuccess,
-  ESeverityNumber,
 } from './logs/types';
 
-export { createExportTraceServiceRequest } from './trace';
-export { createExportMetricsServiceRequest } from './metrics';
-export { createExportLogsServiceRequest } from './logs';
-
 export {
   ProtobufLogsSerializer,
   ProtobufMetricsSerializer,

experimental/packages/otlp-transformer/src/json/serializers.ts

@@ -59,6 +59,9 @@ export const JsonMetricsSerializer: ISerializer<
   },
 };
 
+/*
+ * @experimental this serializer may receive breaking changes in minor versions, pin this package's version when using this constant
+ */
 export const JsonLogsSerializer: ISerializer<
   ReadableLogRecord[],
   IExportLogsServiceResponse

experimental/packages/otlp-transformer/src/protobuf/serializers.ts

@@ -54,6 +54,9 @@ const traceResponseType = root.opentelemetry.proto.collector.trace.v1
 const traceRequestType = root.opentelemetry.proto.collector.trace.v1
   .ExportTraceServiceRequest as ExportType<IExportTraceServiceRequest>;
 
+/*
+ * @experimental this serializer may receive breaking changes in minor versions, pin this package's version when using this constant
+ */
 export const ProtobufLogsSerializer: ISerializer<
   ReadableLogRecord[],
   IExportLogsServiceResponse

experimental/packages/otlp-transformer/test/common.test.ts

@@ -15,9 +15,9 @@
  */
 
 import { hexToBinary } from '@opentelemetry/core';
-import { getOtlpEncoder } from '../src';
 import { toAnyValue } from '../src/common/internal';
 import * as assert from 'assert';
+import { getOtlpEncoder } from '../src/common';
 
 const traceId = 'abcdef01234567890000000000000000';
 const spanId = '12341234abcdabcd';

experimental/packages/otlp-transformer/test/logs.test.ts

@@ -17,18 +17,14 @@ import { HrTime, TraceFlags } from '@opentelemetry/api';
 import { InstrumentationScope, hexToBinary } from '@opentelemetry/core';
 import { Resource } from '@opentelemetry/resources';
 import * as assert from 'assert';
-import {
-  createExportLogsServiceRequest,
-  ESeverityNumber,
-  IExportLogsServiceRequest,
-  ProtobufLogsSerializer,
-  JsonLogsSerializer,
-  OtlpEncodingOptions,
-} from '../src';
+import { ProtobufLogsSerializer, JsonLogsSerializer } from '../src';
 import { ReadableLogRecord } from '@opentelemetry/sdk-logs';
 import { SeverityNumber } from '@opentelemetry/api-logs';
 import { toBase64 } from './utils';
 import * as root from '../src/generated/root';
+import { OtlpEncodingOptions } from '../src/common/types';
+import { ESeverityNumber, IExportLogsServiceRequest } from '../src/logs/types';
+import { createExportLogsServiceRequest } from '../src/logs';
 
 function createExpectedLogJson(
   options: OtlpEncodingOptions

experimental/packages/otlp-transformer/test/metrics.test.ts

@@ -26,13 +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 { ProtobufMetricsSerializer, JsonMetricsSerializer } from '../src';
 import * as root from '../src/generated/root';
+import { encodeAsLongBits, encodeAsString } from '../src/common';
 
 const START_TIME = hrTime();
 const END_TIME = hrTime();

experimental/packages/otlp-transformer/test/trace.test.ts

@@ -19,15 +19,11 @@ import { TraceState, hexToBinary } from '@opentelemetry/core';
 import { Resource } from '@opentelemetry/resources';
 import { ReadableSpan } from '@opentelemetry/sdk-trace-base';
 import * as assert from 'assert';
-import {
-  OtlpEncodingOptions,
-  createExportTraceServiceRequest,
-  ESpanKind,
-  EStatusCode,
-  ProtobufTraceSerializer,
-  JsonTraceSerializer,
-} from '../src';
+import { ProtobufTraceSerializer, JsonTraceSerializer } from '../src';
 import { toBase64 } from './utils';
+import { OtlpEncodingOptions } from '../src/common/types';
+import { ESpanKind, EStatusCode } from '../src/trace/types';
+import { createExportTraceServiceRequest } from '../src/trace';
 
 function createExpectedSpanJson(options: OtlpEncodingOptions) {
   const useHex = options.useHex ?? false;