From 8ae3f546df54715be507a1a1f85d84caea09a3dc Mon Sep 17 00:00:00 2001 From: "marc.pichler" Date: Fri, 13 May 2022 13:09:41 +0200 Subject: [PATCH] feat(otlp-transformer): cleanup readme and deps. --- .../packages/otlp-transformer-base/README.md | 83 ++---------------- .../otlp-transformer-base/package.json | 1 - .../otlp-transformer-metrics/README.md | 87 ++----------------- .../otlp-transformer-metrics/package.json | 1 - .../packages/otlp-transformer-trace/README.md | 87 ++----------------- .../otlp-transformer-trace/package.json | 1 - 6 files changed, 18 insertions(+), 242 deletions(-) diff --git a/experimental/packages/otlp-transformer-base/README.md b/experimental/packages/otlp-transformer-base/README.md index 2c53ce82cac..c8eb39a70ee 100644 --- a/experimental/packages/otlp-transformer-base/README.md +++ b/experimental/packages/otlp-transformer-base/README.md @@ -3,9 +3,10 @@ [![NPM Published Version][npm-img]][npm-url] [![Apache License][license-image]][license-image] -This package provides everything needed to serialize [OpenTelemetry SDK][sdk] traces and metrics into the [OpenTelemetry Protocol][otlp] format using [protocol buffers][protobuf] or JSON. -It also contains service clients for exporting traces and metrics to the OpenTelemetry Collector or a compatible receiver using using OTLP over [gRPC][grpc]. -This module uses [`protobufjs`][protobufjs] for serialization and is compatible with [`@grpc/grpc-js`][grpc-js]. +**NOTE: This package is intended for internal use only.** + +This package provides everything needed to serialize [OpenTelemetry SDK][sdk] structures that are shared between signals +to [OpenTelemetry Protocol][otlp] format using [protocol buffers][protobuf] or JSON. ## Quick Start @@ -14,80 +15,8 @@ To get started you will need to install a compatible OpenTelemetry API. ### Install Peer Dependencies ```sh -npm install \ - @opentelemetry/api \ - @grpc/grpc-js # only required if you are using gRPC -``` - -### Serialize Traces and Metrics - -This module exports functions to serialize traces and metrics from the OpenTelemetry SDK into protocol buffers which can be sent over HTTP to the OpenTelemetry collector or a compatible receiver. - -```typescript -import { createExportTraceServiceRequest, createExportMetricsServiceRequest } from "@opentelemetry/otlp-transformer"; - -const serializedSpans = createExportTraceServiceRequest(readableSpans); -const serializedMetrics = createExportMetricsServiceRequest(readableMetrics); -``` - -### Create gRPC Service Clients - -This module also contains gRPC service clients for exporting traces and metrics to an OpenTelemetry collector or compatible receiver over gRPC. -In order to avoid bundling a gRPC module with this module, it is required to construct an RPC implementation to pass to the constructor of the service clients. -Any RPC implementation compatible with `grpc` or `@grpc/grpc-js` may be used, but `@grpc/grpc-js` is recommended. - -```typescript -import type { RPCImpl } from 'protobufjs'; -import { makeGenericClientConstructor, credentials } from '@gprc/grpc-js'; -import { MetricServiceClient, TraceServiceClient } from "@opentelemetry/otlp-transformer"; - -// Construct a RPC Implementation according to protobufjs docs -const GrpcClientConstructor = makeGenericClientConstructor({}); - -const metricGRPCClient = new GrpcClientConstructor( - "http://localhost:4317/v1/metrics", // default collector metrics endpoint - credentials.createInsecure(), -); - -const traceGRPCClient = new GrpcClientConstructor( - "http://localhost:4317/v1/traces", // default collector traces endpoint - credentials.createInsecure(), -); - -const metricRpc: RPCImpl = function(method, requestData, callback) { - metricGRPCClient.makeUnaryRequest( - method.name, - arg => arg, - arg => arg, - requestData, - callback - ); -} - -const traceRpc: RPCImpl = function(method, requestData, callback) { - traceGRPCClient.makeUnaryRequest( - method.name, - arg => arg, - arg => arg, - requestData, - callback - ); -} - -// Construct service clients to use RPC Implementations -const metricServiceClient = new MetricServiceClient({ - rpcImpl: metricRpc, - startTime: Date.now(), // exporter start time in milliseconds -}); - -const traceServiceClient = new TraceServiceClient({ - rpcImpl: traceRpc, -}); - -// Export ReadableSpan[] and ReadableMetric[] over gRPC -await metricServiceClient.export(readableMetrics); -await traceServiceClient.export(readableSpans); -``` +npm install @opentelemetry/api + ``` ## Useful links diff --git a/experimental/packages/otlp-transformer-base/package.json b/experimental/packages/otlp-transformer-base/package.json index ee17bdbbe33..f0ca2dce9ce 100644 --- a/experimental/packages/otlp-transformer-base/package.json +++ b/experimental/packages/otlp-transformer-base/package.json @@ -68,7 +68,6 @@ "mkdirp": "1.0.4", "mocha": "7.2.0", "nyc": "15.1.0", - "protobufjs": "6.11.2", "rimraf": "3.0.2", "ts-loader": "8.3.0", "ts-mocha": "9.0.2", diff --git a/experimental/packages/otlp-transformer-metrics/README.md b/experimental/packages/otlp-transformer-metrics/README.md index 2c53ce82cac..27ea6d33fe3 100644 --- a/experimental/packages/otlp-transformer-metrics/README.md +++ b/experimental/packages/otlp-transformer-metrics/README.md @@ -3,9 +3,10 @@ [![NPM Published Version][npm-img]][npm-url] [![Apache License][license-image]][license-image] -This package provides everything needed to serialize [OpenTelemetry SDK][sdk] traces and metrics into the [OpenTelemetry Protocol][otlp] format using [protocol buffers][protobuf] or JSON. -It also contains service clients for exporting traces and metrics to the OpenTelemetry Collector or a compatible receiver using using OTLP over [gRPC][grpc]. -This module uses [`protobufjs`][protobufjs] for serialization and is compatible with [`@grpc/grpc-js`][grpc-js]. +**NOTE: This package is intended for internal use only.** + +This package provides everything needed to serialize [OpenTelemetry SDK][sdk] metrics to [OpenTelemetry Protocol][otlp] +format using [protocol buffers][protobuf] or JSON. ## Quick Start @@ -14,80 +15,8 @@ To get started you will need to install a compatible OpenTelemetry API. ### Install Peer Dependencies ```sh -npm install \ - @opentelemetry/api \ - @grpc/grpc-js # only required if you are using gRPC -``` - -### Serialize Traces and Metrics - -This module exports functions to serialize traces and metrics from the OpenTelemetry SDK into protocol buffers which can be sent over HTTP to the OpenTelemetry collector or a compatible receiver. - -```typescript -import { createExportTraceServiceRequest, createExportMetricsServiceRequest } from "@opentelemetry/otlp-transformer"; - -const serializedSpans = createExportTraceServiceRequest(readableSpans); -const serializedMetrics = createExportMetricsServiceRequest(readableMetrics); -``` - -### Create gRPC Service Clients - -This module also contains gRPC service clients for exporting traces and metrics to an OpenTelemetry collector or compatible receiver over gRPC. -In order to avoid bundling a gRPC module with this module, it is required to construct an RPC implementation to pass to the constructor of the service clients. -Any RPC implementation compatible with `grpc` or `@grpc/grpc-js` may be used, but `@grpc/grpc-js` is recommended. - -```typescript -import type { RPCImpl } from 'protobufjs'; -import { makeGenericClientConstructor, credentials } from '@gprc/grpc-js'; -import { MetricServiceClient, TraceServiceClient } from "@opentelemetry/otlp-transformer"; - -// Construct a RPC Implementation according to protobufjs docs -const GrpcClientConstructor = makeGenericClientConstructor({}); - -const metricGRPCClient = new GrpcClientConstructor( - "http://localhost:4317/v1/metrics", // default collector metrics endpoint - credentials.createInsecure(), -); - -const traceGRPCClient = new GrpcClientConstructor( - "http://localhost:4317/v1/traces", // default collector traces endpoint - credentials.createInsecure(), -); - -const metricRpc: RPCImpl = function(method, requestData, callback) { - metricGRPCClient.makeUnaryRequest( - method.name, - arg => arg, - arg => arg, - requestData, - callback - ); -} - -const traceRpc: RPCImpl = function(method, requestData, callback) { - traceGRPCClient.makeUnaryRequest( - method.name, - arg => arg, - arg => arg, - requestData, - callback - ); -} - -// Construct service clients to use RPC Implementations -const metricServiceClient = new MetricServiceClient({ - rpcImpl: metricRpc, - startTime: Date.now(), // exporter start time in milliseconds -}); - -const traceServiceClient = new TraceServiceClient({ - rpcImpl: traceRpc, -}); - -// Export ReadableSpan[] and ReadableMetric[] over gRPC -await metricServiceClient.export(readableMetrics); -await traceServiceClient.export(readableSpans); -``` +npm install @opentelemetry/api + ``` ## Useful links @@ -109,7 +38,3 @@ Apache 2.0 - See [LICENSE][license-url] for more information. [otlp]: https://github.com/open-telemetry/opentelemetry-proto [protobuf]: https://developers.google.com/protocol-buffers -[grpc]: https://grpc.io/ - -[protobufjs]: https://www.npmjs.com/package/protobufjs -[grpc-js]: https://www.npmjs.com/package/@grpc/grpc-js diff --git a/experimental/packages/otlp-transformer-metrics/package.json b/experimental/packages/otlp-transformer-metrics/package.json index 6d4483bb461..4da97781cf7 100644 --- a/experimental/packages/otlp-transformer-metrics/package.json +++ b/experimental/packages/otlp-transformer-metrics/package.json @@ -68,7 +68,6 @@ "mkdirp": "1.0.4", "mocha": "7.2.0", "nyc": "15.1.0", - "protobufjs": "6.11.2", "rimraf": "3.0.2", "ts-loader": "8.3.0", "ts-mocha": "9.0.2", diff --git a/experimental/packages/otlp-transformer-trace/README.md b/experimental/packages/otlp-transformer-trace/README.md index 2c53ce82cac..27ea6d33fe3 100644 --- a/experimental/packages/otlp-transformer-trace/README.md +++ b/experimental/packages/otlp-transformer-trace/README.md @@ -3,9 +3,10 @@ [![NPM Published Version][npm-img]][npm-url] [![Apache License][license-image]][license-image] -This package provides everything needed to serialize [OpenTelemetry SDK][sdk] traces and metrics into the [OpenTelemetry Protocol][otlp] format using [protocol buffers][protobuf] or JSON. -It also contains service clients for exporting traces and metrics to the OpenTelemetry Collector or a compatible receiver using using OTLP over [gRPC][grpc]. -This module uses [`protobufjs`][protobufjs] for serialization and is compatible with [`@grpc/grpc-js`][grpc-js]. +**NOTE: This package is intended for internal use only.** + +This package provides everything needed to serialize [OpenTelemetry SDK][sdk] metrics to [OpenTelemetry Protocol][otlp] +format using [protocol buffers][protobuf] or JSON. ## Quick Start @@ -14,80 +15,8 @@ To get started you will need to install a compatible OpenTelemetry API. ### Install Peer Dependencies ```sh -npm install \ - @opentelemetry/api \ - @grpc/grpc-js # only required if you are using gRPC -``` - -### Serialize Traces and Metrics - -This module exports functions to serialize traces and metrics from the OpenTelemetry SDK into protocol buffers which can be sent over HTTP to the OpenTelemetry collector or a compatible receiver. - -```typescript -import { createExportTraceServiceRequest, createExportMetricsServiceRequest } from "@opentelemetry/otlp-transformer"; - -const serializedSpans = createExportTraceServiceRequest(readableSpans); -const serializedMetrics = createExportMetricsServiceRequest(readableMetrics); -``` - -### Create gRPC Service Clients - -This module also contains gRPC service clients for exporting traces and metrics to an OpenTelemetry collector or compatible receiver over gRPC. -In order to avoid bundling a gRPC module with this module, it is required to construct an RPC implementation to pass to the constructor of the service clients. -Any RPC implementation compatible with `grpc` or `@grpc/grpc-js` may be used, but `@grpc/grpc-js` is recommended. - -```typescript -import type { RPCImpl } from 'protobufjs'; -import { makeGenericClientConstructor, credentials } from '@gprc/grpc-js'; -import { MetricServiceClient, TraceServiceClient } from "@opentelemetry/otlp-transformer"; - -// Construct a RPC Implementation according to protobufjs docs -const GrpcClientConstructor = makeGenericClientConstructor({}); - -const metricGRPCClient = new GrpcClientConstructor( - "http://localhost:4317/v1/metrics", // default collector metrics endpoint - credentials.createInsecure(), -); - -const traceGRPCClient = new GrpcClientConstructor( - "http://localhost:4317/v1/traces", // default collector traces endpoint - credentials.createInsecure(), -); - -const metricRpc: RPCImpl = function(method, requestData, callback) { - metricGRPCClient.makeUnaryRequest( - method.name, - arg => arg, - arg => arg, - requestData, - callback - ); -} - -const traceRpc: RPCImpl = function(method, requestData, callback) { - traceGRPCClient.makeUnaryRequest( - method.name, - arg => arg, - arg => arg, - requestData, - callback - ); -} - -// Construct service clients to use RPC Implementations -const metricServiceClient = new MetricServiceClient({ - rpcImpl: metricRpc, - startTime: Date.now(), // exporter start time in milliseconds -}); - -const traceServiceClient = new TraceServiceClient({ - rpcImpl: traceRpc, -}); - -// Export ReadableSpan[] and ReadableMetric[] over gRPC -await metricServiceClient.export(readableMetrics); -await traceServiceClient.export(readableSpans); -``` +npm install @opentelemetry/api + ``` ## Useful links @@ -109,7 +38,3 @@ Apache 2.0 - See [LICENSE][license-url] for more information. [otlp]: https://github.com/open-telemetry/opentelemetry-proto [protobuf]: https://developers.google.com/protocol-buffers -[grpc]: https://grpc.io/ - -[protobufjs]: https://www.npmjs.com/package/protobufjs -[grpc-js]: https://www.npmjs.com/package/@grpc/grpc-js diff --git a/experimental/packages/otlp-transformer-trace/package.json b/experimental/packages/otlp-transformer-trace/package.json index a4be4c11b2d..d79a9d58118 100644 --- a/experimental/packages/otlp-transformer-trace/package.json +++ b/experimental/packages/otlp-transformer-trace/package.json @@ -68,7 +68,6 @@ "mkdirp": "1.0.4", "mocha": "7.2.0", "nyc": "15.1.0", - "protobufjs": "6.11.2", "rimraf": "3.0.2", "ts-loader": "8.3.0", "ts-mocha": "9.0.2",