otlp-logger 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Vladimir Adamić
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# otlp-logger
+[![npm version](https://img.shields.io/npm/v/otlp-logger)](https://www.npmjs.com/package/otlp-logger)
+[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)
+
+Sends logs in the [OpenTelemetry Log Data Model](https://github.com/open-telemetry/opentelemetry-specification/blob/fc8289b8879f3a37e1eba5b4e445c94e74b20359/specification/logs/data-model.md) to an OTLP logs collector.
+
+## Install
+
+```
+npm i otlp-logger
+```
+
+## Configuration
+### Protocol
+can be set to `http/protobuf`, `grpc`, `http` or `console` by using 
+
+* env var `OTEL_EXPORTER_OTLP_PROTOCOL` 
+* env var `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL`
+* setting the exporterProtocol option
+
+Settings configured programmatically take precedence over environment variables. Per-signal environment variables take precedence over non-per-signal environment variables. This principle applies to all the configurations in this module.
+
+If no protocol is specified, `http/protobuf` is used as a default.
+
+### Exporter settings
+
+#### Collector URL
+
+Set either of the following environment variables:
+`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`,
+`OTEL_EXPORTER_OTLP_ENDPOINT`
+
+#### Protocol-specific exporter configuration
+
+#### `http/protobuf`
+[Env vars in README](https://github.com/open-telemetry/opentelemetry-js/blob/d4a41bd815dd50703f692000a70c59235ad71959/experimental/packages/exporter-trace-otlp-proto/README.md#exporter-timeout-configuration)
+
+#### `grpc`
+[Environment Variable Configuration](https://github.com/open-telemetry/opentelemetry-js/blob/d4a41bd815dd50703f692000a70c59235ad71959/experimental/packages/exporter-logs-otlp-grpc/README.md#environment-variable-configuration)
+
+#### `http`
+[Env vars in README](https://github.com/open-telemetry/opentelemetry-js/blob/d4a41bd815dd50703f692000a70c59235ad71959/experimental/packages/exporter-trace-otlp-http/README.md#configuration-options-as-environment-variables)
+
+
+#### Processor-specific configuration
+If batch log processor is selected (is default), it can be configured using env vars described in the [OpenTelemetry specification](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#batch-logrecord-processor)
+
+### Options
+When using the transport, the following options can be used to configure the transport programmatically:
+
+* `loggerName`: name to be used by the OpenTelemetry logger
+* `serviceVersion`: name to be used by the OpenTelemetry logger
+* `resourceAttributes`: Object containing [resource attributes](https://opentelemetry.io/docs/instrumentation/js/resources/). Optional
+* `logRecordProcessorOptions`: a single object or an array of objects specifying the LogProcessor and LogExporter types and constructor params. Optional
+
+
+## Usage
+
+### Minimalistic example
+
+Make sure you have access to an OTEL collector.
+
+To start quickly, create a minimal configuration for OTEL collector in the `otel-collector-config.yaml` file:
+
+```
+receivers:
+  otlp:
+    protocols:
+      grpc:
+
+exporters:
+  file:
+    path: ./etc/test-logs/otlp-logs.log
+    flush_interval: 1
+
+  logging:
+    verbosity: basic
+  
+processors:
+  batch:
+
+service:
+  pipelines:
+    logs:
+      receivers: [otlp]
+      processors: []
+      exporters: [logging, file]
+```
+
+The collector can then be ran with:
+
+```
+docker run --volume=$(pwd)/otel-collector-config.yaml:/etc/otel-collector-config.yaml:rw --volume=/tmp/test-logs:/etc/test-logs:rw -p 4317:4317 -d otel/opentelemetry-collector-contrib:latest --config=/etc/otel-collector-config.yaml
+```
+
+Create an index.js file containing
+
+```js
+const { getOtlpLogger } = require('otlp-logger')
+
+const logger = getOtlpLogger({
+  loggerName: 'test',
+  serviceVersion: '1.0.0'
+})
+
+logger.emit({
+  severityNumber: 1,
+  severityText: 'TRACE',
+  body: 'test',
+  timestamp: Date.now()
+})
+```
+
+Run the service setting the `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` and `OTEL_RESOURCE_ATTRIBUTES` env vars
+
+```
+OTEL_EXPORTER_OTLP_LOGS_PROTOCOL='grpc' OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://localhost:4317 OTEL_RESOURCE_ATTRIBUTES="service.name=my-service,service.version=1.2.3" node index.js
+```
+
+## License
+
+MIT

package/commitlint.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  // We need this until https://github.com/dependabot/dependabot-core/issues/2445
+  // is resolved.
+  ignores: [msg => /Signed-off-by: dependabot\[bot]/m.test(msg)]
+}

package/lib/create-log-processor.js

@@ -0,0 +1,94 @@
+'use strict'
+
+const {
+  SimpleLogRecordProcessor,
+  BatchLogRecordProcessor,
+  ConsoleLogRecordExporter
+} = require('@opentelemetry/sdk-logs')
+
+const { MultiLogRecordProcessor } = require('./multi-log-processor')
+
+/**
+ * @param {LogRecordProcessorOptions | LogRecordProcessorOptions[]} [logRecordProcessorOptions]
+ */
+function createLogProcessor (logRecordProcessorOptions) {
+  return Array.isArray(logRecordProcessorOptions)
+    ? new MultiLogRecordProcessor(
+      logRecordProcessorOptions.map(createLogRecordProcessor)
+    )
+    : createLogRecordProcessor(logRecordProcessorOptions)
+}
+
+/**
+ * @typedef {"batch" | "simple"} RecordProcessorType
+ * @typedef {Object} LogRecordProcessorOptions
+ * @property {RecordProcessorType} recordProcessorType = "batch"
+ * @property {ExporterOptions} [exporterOptions]
+ * @property {import('@opentelemetry/sdk-logs').BufferConfig} [processorConfig]
+ *
+ * @param {LogRecordProcessorOptions} [opts]
+ * @returns {import('@opentelemetry/sdk-logs').LogRecordProcessor}
+ */
+function createLogRecordProcessor (opts) {
+  const exporter = createExporter(opts?.exporterOptions)
+
+  if (opts?.recordProcessorType === 'simple') {
+    return new SimpleLogRecordProcessor(exporter)
+  }
+
+  return new BatchLogRecordProcessor(exporter, opts?.processorConfig)
+}
+
+/**
+ * @typedef {Object} GrpcExporterOptions
+ * @property {"grpc"} protocol
+ * @property {import('@opentelemetry/otlp-grpc-exporter-base').OTLPGRPCExporterConfigNode} [grpcExporterOptions]
+ *
+ * @typedef {Object} HttpExporterOptions
+ * @property {"http"} protocol
+ * @property {import('@opentelemetry/otlp-exporter-base').OTLPExporterNodeConfigBase} [httpExporterOptions]
+ *
+ * @typedef {Object} ProtobufExporterOptions
+ * @property {"http/protobuf"} protocol
+ * @property {import('@opentelemetry/otlp-exporter-base').OTLPExporterNodeConfigBase} [protobufExporterOptions]
+ *
+ * @typedef {Object} ConsoleExporterOptions
+ * @property {"console"} protocol
+ *
+ * @typedef {GrpcExporterOptions | HttpExporterOptions | ProtobufExporterOptions | ConsoleExporterOptions } ExporterOptions
+ *
+ * @param {ExporterOptions} exporterOptions
+ * @returns {import('@opentelemetry/sdk-logs').LogRecordExporter}
+ */
+function createExporter (exporterOptions) {
+  const exporterProtocol =
+    exporterOptions?.protocol ??
+    process.env.OTEL_EXPORTER_OTLP_LOGS_PROTOCOL ??
+    process.env.OTEL_EXPORTER_OTLP_PROTOCOL
+
+  if (exporterProtocol === 'grpc') {
+    const {
+      OTLPLogExporter
+    } = require('@opentelemetry/exporter-logs-otlp-grpc')
+    return new OTLPLogExporter(exporterOptions?.grpcExporterOptions)
+  }
+
+  if (exporterProtocol === 'http') {
+    const {
+      OTLPLogExporter
+    } = require('@opentelemetry/exporter-logs-otlp-http')
+    return new OTLPLogExporter(exporterOptions?.httpExporterOptions)
+  }
+
+  if (exporterProtocol === 'console') {
+    return new ConsoleLogRecordExporter()
+  }
+
+  const { OTLPLogExporter } = require('@opentelemetry/exporter-logs-otlp-proto')
+
+  return new OTLPLogExporter(exporterOptions?.protobufExporterOptions)
+}
+
+module.exports = {
+  createLogProcessor
+}

package/lib/multi-log-processor.js

@@ -0,0 +1,38 @@
+'use_strict'
+
+const { callWithTimeout } = require('@opentelemetry/core')
+
+// taken from https://github.com/open-telemetry/opentelemetry-js/blob/5fcd8cf136e2235903dde3df9ba03ced594f0e95/experimental/packages/sdk-logs/src/types.ts#L27C3-L27C26
+const FORCE_FLUSH_TIMEOUT_MILLIS = 30000
+/**
+ * Using the MultiLogRecordProcessor from the sdk-logs package is currently not possible because it is not exported.
+ * This should work as a drop-in replacement.
+ */
+class MultiLogRecordProcessor {
+  constructor (processors, forceFlushTimeoutMillis) {
+    this.processors = processors
+    this.forceFlushTimeoutMillis = forceFlushTimeoutMillis
+  }
+
+  async forceFlush () {
+    const timeout = this.forceFlushTimeoutMillis
+    await Promise.all(
+      this.processors.map(processor =>
+        (FORCE_FLUSH_TIMEOUT_MILLIS, callWithTimeout)(
+          processor.forceFlush(),
+          timeout
+        )
+      )
+    )
+  }
+
+  onEmit (logRecord) {
+    this.processors.forEach(processors => processors.onEmit(logRecord))
+  }
+
+  async shutdown () {
+    await Promise.all(this.processors.map(processor => processor.shutdown()))
+  }
+}
+
+exports.MultiLogRecordProcessor = MultiLogRecordProcessor

package/lib/otlp-logger.js

@@ -0,0 +1,102 @@
+'use strict'
+
+const { LoggerProvider } = require('@opentelemetry/sdk-logs')
+const { logs } = require('@opentelemetry/api-logs') // TODO: optional import
+const api = require('@opentelemetry/api')
+const {
+  Resource,
+  detectResourcesSync,
+  envDetectorSync,
+  hostDetectorSync,
+  osDetectorSync,
+  processDetector
+} = require('@opentelemetry/resources')
+const { createLogProcessor } = require('./create-log-processor')
+
+/**
+ * @typedef {Object} Options
+ * @property {string} loggerName
+ * @property {string} serviceVersion
+ * @property {import('./create-log-processor').LogRecordProcessorOptions | import('./create-log-processor').LogRecordProcessorOptions[]} [logRecordProcessorOptions]
+ * @property {Object} [resourceAttributes={}]
+ *
+ * @param {Options} opts
+ */
+function getOtlpLogger (opts) {
+  const detectedResource = detectResourcesSync({
+    detectors: [
+      envDetectorSync,
+      hostDetectorSync,
+      osDetectorSync,
+      processDetector
+    ]
+  })
+  const loggerProvider = new LoggerProvider({
+    resource: detectedResource.merge(
+      new Resource({ ...opts.resourceAttributes })
+    )
+  })
+
+  loggerProvider.addLogRecordProcessor(
+    createLogProcessor(opts.logRecordProcessorOptions)
+  )
+
+  logs.setGlobalLoggerProvider(loggerProvider)
+
+  const logger = logs.getLogger(opts.loggerName, opts.serviceVersion)
+
+  return {
+    /**
+     * @param {import('@opentelemetry/api-logs').LogRecord} obj
+     */
+    emit (obj) {
+      logger.emit(loadContext(obj))
+    },
+    async shutdown () {
+      return loggerProvider.shutdown()
+    }
+  }
+}
+
+/**
+ * load context from attributes and set it to logRecord.context
+ *
+ * @param {import('@opentelemetry/api-logs').LogRecord} logRecord
+ * @returns {import('@opentelemetry/api-logs').LogRecord}
+ */
+function loadContext (logRecord) {
+  let context = api.context.active()
+  let attributes = logRecord.attributes
+
+  if (typeof attributes !== 'undefined') {
+    /* eslint-disable camelcase */
+    const { trace_id, span_id, trace_flags, ...otherAttributes } =
+      logRecord.attributes
+
+    if (
+      typeof trace_id !== 'undefined' &&
+      typeof span_id !== 'undefined' &&
+      typeof trace_flags !== 'undefined'
+    ) {
+      context = api.trace.setSpanContext(context, {
+        traceId: trace_id,
+        spanId: span_id,
+        traceFlags: trace_flags,
+        isRemote: true
+      })
+    }
+
+    attributes = otherAttributes
+    /* eslint-enable camelcase */
+  }
+
+  return {
+    ...logRecord,
+    attributes,
+    context
+  }
+}
+
+module.exports = {
+  getOtlpLogger
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "otlp-logger",
+  "version": "1.1.1",
+  "description": "Exports logs to OpenTelemetry Collector using OTLP protocol",
+  "main": "lib/otlp-logger.js",
+  "scripts": {
+    "validate-and-test": "standard | snazzy && tap test/**/*.test.js --coverage-report=lcovonly && tsd",
+    "test": "npm run validate-and-test",
+    "docker-run": "docker compose up",
+    "generate-types": "tsc",
+    "pretest-ci": "npm run generate-types",
+    "pretest": "npm run generate-types",
+    "prepack": "npm run generate-types",
+    "prepare": "husky install"
+  },
+  "author": "Vladimir Adamic <vladimir.adamic@gmail.com>",
+  "repository": "github:Vunovati/otlp-logger",
+  "license": "MIT",
+  "dependencies": {
+    "@opentelemetry/api-logs": "^0.48.0",
+    "@opentelemetry/core": "^1.17.0",
+    "@opentelemetry/exporter-logs-otlp-grpc": "^0.48.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.48.0",
+    "@opentelemetry/exporter-logs-otlp-proto": "^0.48.0",
+    "@opentelemetry/resources": "^1.17.0",
+    "@opentelemetry/sdk-logs": "^0.48.0"
+  },
+  "types": "./types/otlp-logger.d.ts",
+  "devDependencies": {
+    "@commitlint/cli": "^18.2.0",
+    "@commitlint/config-conventional": "^18.1.0",
+    "@opentelemetry/api": "^1.4.1",
+    "@opentelemetry/instrumentation-http": "^0.48.0",
+    "@opentelemetry/sdk-node": "^0.48.0",
+    "@tapjs/sinon": "^1.1.16",
+    "@types/node": "^20.8.2",
+    "husky": "^9.0.10",
+    "require-inject": "^1.4.4",
+    "snazzy": "^9.0.0",
+    "standard": "^17.1.0",
+    "tap": "^18.5.8",
+    "tar-stream": "^3.1.6",
+    "testcontainers": "^10.2.1",
+    "tsd": "^0.30.3",
+    "typescript": "^5.2.2"
+  },
+  "standard": {
+    "ignore": [
+      "node_modules/"
+    ]
+  },
+  "tsd": {
+    "directory": "./test/types"
+  },
+  "files": [
+    "types",
+    "*.js"
+  ],
+  "tap": {
+    "plugin": [
+      "@tapjs/sinon"
+    ]
+  }
+}

package/types/create-log-processor.d.ts

@@ -0,0 +1,30 @@
+export type RecordProcessorType = "batch" | "simple";
+export type LogRecordProcessorOptions = {
+    /**
+     * = "batch"
+     */
+    recordProcessorType: RecordProcessorType;
+    exporterOptions?: ExporterOptions;
+    processorConfig?: import('@opentelemetry/sdk-logs').BufferConfig;
+};
+export type GrpcExporterOptions = {
+    protocol: "grpc";
+    grpcExporterOptions?: import('@opentelemetry/otlp-grpc-exporter-base').OTLPGRPCExporterConfigNode;
+};
+export type HttpExporterOptions = {
+    protocol: "http";
+    httpExporterOptions?: import('@opentelemetry/otlp-exporter-base').OTLPExporterNodeConfigBase;
+};
+export type ProtobufExporterOptions = {
+    protocol: "http/protobuf";
+    protobufExporterOptions?: import('@opentelemetry/otlp-exporter-base').OTLPExporterNodeConfigBase;
+};
+export type ConsoleExporterOptions = {
+    protocol: "console";
+};
+export type ExporterOptions = GrpcExporterOptions | HttpExporterOptions | ProtobufExporterOptions | ConsoleExporterOptions;
+/**
+ * @param {LogRecordProcessorOptions | LogRecordProcessorOptions[]} [logRecordProcessorOptions]
+ */
+export function createLogProcessor(logRecordProcessorOptions?: LogRecordProcessorOptions | LogRecordProcessorOptions[]): import("@opentelemetry/sdk-logs").LogRecordProcessor;
+//# sourceMappingURL=create-log-processor.d.ts.map

package/types/create-log-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-log-processor.d.ts","sourceRoot":"","sources":["../lib/create-log-processor.js"],"names":[],"mappings":"kCAsBa,OAAO,GAAG,QAAQ;;;;;yBAEjB,mBAAmB;sBACnB,eAAe;sBACf,OAAO,yBAAyB,EAAE,YAAY;;;cAiB9C,MAAM;0BACN,OAAO,wCAAwC,EAAE,0BAA0B;;;cAG3E,MAAM;0BACN,OAAO,mCAAmC,EAAE,0BAA0B;;;cAGtE,eAAe;8BACf,OAAO,mCAAmC,EAAE,0BAA0B;;;cAGtE,SAAS;;8BAEV,mBAAmB,GAAG,mBAAmB,GAAG,uBAAuB,GAAG,sBAAsB;AA/CzG;;GAEG;AACH,+DAFW,yBAAyB,GAAG,yBAAyB,EAAE,wDAQjE"}

package/types/multi-log-processor.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Using the MultiLogRecordProcessor from the sdk-logs package is currently not possible because it is not exported.
+ * This should work as a drop-in replacement.
+ */
+export class MultiLogRecordProcessor {
+    constructor(processors: any, forceFlushTimeoutMillis: any);
+    processors: any;
+    forceFlushTimeoutMillis: any;
+    forceFlush(): Promise<void>;
+    onEmit(logRecord: any): void;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=multi-log-processor.d.ts.map

package/types/multi-log-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-log-processor.d.ts","sourceRoot":"","sources":["../lib/multi-log-processor.js"],"names":[],"mappings":"AAMA;;;GAGG;AACH;IACE,2DAGC;IAFC,gBAA4B;IAC5B,6BAAsD;IAGxD,4BAUC;IAED,6BAEC;IAED,0BAEC;CACF"}

package/types/otlp-logger.d.ts

@@ -0,0 +1,23 @@
+export type Options = {
+    loggerName: string;
+    serviceVersion: string;
+    logRecordProcessorOptions?: import('./create-log-processor').LogRecordProcessorOptions | import('./create-log-processor').LogRecordProcessorOptions[];
+    resourceAttributes?: any;
+};
+/**
+ * @typedef {Object} Options
+ * @property {string} loggerName
+ * @property {string} serviceVersion
+ * @property {import('./create-log-processor').LogRecordProcessorOptions | import('./create-log-processor').LogRecordProcessorOptions[]} [logRecordProcessorOptions]
+ * @property {Object} [resourceAttributes={}]
+ *
+ * @param {Options} opts
+ */
+export function getOtlpLogger(opts: Options): {
+    /**
+     * @param {import('@opentelemetry/api-logs').LogRecord} obj
+     */
+    emit(obj: import('@opentelemetry/api-logs').LogRecord): void;
+    shutdown(): Promise<void>;
+};
+//# sourceMappingURL=otlp-logger.d.ts.map

package/types/otlp-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otlp-logger.d.ts","sourceRoot":"","sources":["../lib/otlp-logger.js"],"names":[],"mappings":";gBAiBc,MAAM;oBACN,MAAM;gCACN,OAAO,wBAAwB,EAAE,yBAAyB,GAAG,OAAO,wBAAwB,EAAE,yBAAyB,EAAE;;;AAJvI;;;;;;;;GAQG;AACH,oCAFW,OAAO;IA0Bd;;OAEG;cADQ,OAAO,yBAAyB,EAAE,SAAS;;EASzD"}