diff --git a/experimental/CHANGELOG.md b/experimental/CHANGELOG.md index 83471e2416..fb1383cb57 100644 --- a/experimental/CHANGELOG.md +++ b/experimental/CHANGELOG.md @@ -31,6 +31,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) diff --git a/experimental/packages/otlp-transformer/README.md b/experimental/packages/otlp-transformer/README.md index b91b6d06d7..9f592812ba 100644 --- a/experimental/packages/otlp-transformer/README.md +++ b/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 diff --git a/experimental/packages/otlp-transformer/src/index.ts b/experimental/packages/otlp-transformer/src/index.ts index 12c1cadc87..18cc064bbc 100644 --- a/experimental/packages/otlp-transformer/src/index.ts +++ b/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, diff --git a/experimental/packages/otlp-transformer/src/json/serializers.ts b/experimental/packages/otlp-transformer/src/json/serializers.ts index d21070d98c..c187d6309b 100644 --- a/experimental/packages/otlp-transformer/src/json/serializers.ts +++ b/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 diff --git a/experimental/packages/otlp-transformer/src/protobuf/serializers.ts b/experimental/packages/otlp-transformer/src/protobuf/serializers.ts index ff73ab67f2..95b475695d 100644 --- a/experimental/packages/otlp-transformer/src/protobuf/serializers.ts +++ b/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; +/* + * @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 diff --git a/experimental/packages/otlp-transformer/test/common.test.ts b/experimental/packages/otlp-transformer/test/common.test.ts index 1925ee1283..9ab639c602 100644 --- a/experimental/packages/otlp-transformer/test/common.test.ts +++ b/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'; diff --git a/experimental/packages/otlp-transformer/test/logs.test.ts b/experimental/packages/otlp-transformer/test/logs.test.ts index b279ae75da..b3c606d1b7 100644 --- a/experimental/packages/otlp-transformer/test/logs.test.ts +++ b/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 diff --git a/experimental/packages/otlp-transformer/test/metrics.test.ts b/experimental/packages/otlp-transformer/test/metrics.test.ts index 06d357102e..6c8d332321 100644 --- a/experimental/packages/otlp-transformer/test/metrics.test.ts +++ b/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(); diff --git a/experimental/packages/otlp-transformer/test/trace.test.ts b/experimental/packages/otlp-transformer/test/trace.test.ts index b740430dc3..dd6354ea4d 100644 --- a/experimental/packages/otlp-transformer/test/trace.test.ts +++ b/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;