@opentelemetry/instrumentation-pino - npm Package Compare versions

Comparing version 0.40.0 to 0.41.0

build/src/instrumentation.d.ts

@@ -10,4 +10,3 @@ import { InstrumentationBase, InstrumentationNodeModuleDefinition } from '@opentelemetry/instrumentation';
     private _getMixinFunction;
-    private _combineOptions;
 }
 //# sourceMappingURL=instrumentation.d.ts.map

build/src/instrumentation.js

@@ -22,2 +22,3 @@ "use strict";
 const version_1 = require("./version");
+const log_sending_utils_1 = require("./log-sending-utils");
 const pinoVersions = ['>=5.14.0 <10'];
@@ -40,20 +41,48 @@ const DEFAULT_LOG_KEYS = {
                 const patchedPino = Object.assign((...args) => {
-                    if (args.length === 0) {
-                        return moduleExports({
-                            mixin: instrumentation._getMixinFunction(),
+                    const config = instrumentation.getConfig();
+                    const isEnabled = instrumentation.isEnabled();
+                    const logger = moduleExports(...args);
+                    // Setup "log correlation" -- injection of `trace_id` et al fields.
+                    // Note: If the Pino logger is configured with `nestedKey`, then
+                    // the `trace_id` et al fields added by `otelMixin` will be nested
+                    // as well. https://getpino.io/#/docs/api?id=mixin-function
+                    const otelMixin = instrumentation._getMixinFunction();
+                    const mixinSym = moduleExports.symbols.mixinSym;
+                    const origMixin = logger[mixinSym];
+                    if (origMixin === undefined) {
+                        logger[mixinSym] = otelMixin;
+                    }
+                    else {
+                        logger[mixinSym] = (ctx, level) => {
+                            return Object.assign(otelMixin(ctx, level), origMixin(ctx, level));
+                        };
+                    }
+                    // Setup "log sending" -- sending log records to the Logs API.
+                    // This depends on `pino.multistream`, which was added in v7.0.0.
+                    if (isEnabled &&
+                        !config.disableLogSending &&
+                        typeof moduleExports.multistream === 'function') {
+                        const otelTimestampFromTime = (0, log_sending_utils_1.getTimeConverter)(logger, moduleExports);
+                        const otelStream = new log_sending_utils_1.OTelPinoStream({
+                            messageKey: logger[moduleExports.symbols.messageKeySym],
+                            levels: logger.levels,
+                            otelTimestampFromTime,
                         });
+                        otelStream[Symbol.for('pino.metadata')] = true; // for `stream.lastLevel`
+                        // An error typically indicates a Pino bug, or logger configuration
+                        // bug. `diag.warn` *once* for the first error on the assumption
+                        // subsequent ones stem from the same bug.
+                        otelStream.once('unknown', (line, err) => {
+                            instrumentation._diag.warn('could not send pino log line (will only log first occurrence)', { line, err });
+                        });
+                        // Use pino's own `multistream` to send to the original stream and
+                        // to the OTel Logs API/SDK.
+                        // https://getpino.io/#/docs/api?id=pinomultistreamstreamsarray-opts-gt-multistreamres
+                        const origStream = logger[moduleExports.symbols.streamSym];
+                        logger[moduleExports.symbols.streamSym] = moduleExports.multistream([
+                            { level: logger.level, stream: origStream },
+                            { level: logger.level, stream: otelStream },
+                        ], { levels: logger.levels.values });
                     }
-                    if (args.length === 1) {
-                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                        const optsOrStream = args[0];
-                        if (typeof optsOrStream === 'string' ||
-                            typeof (optsOrStream === null || optsOrStream === void 0 ? void 0 : optsOrStream.write) === 'function') {
-                            args.splice(0, 0, {
-                                mixin: instrumentation._getMixinFunction(),
-                            });
-                            return moduleExports(...args);
-                        }
-                    }
-                    args[0] = instrumentation._combineOptions(args[0]);
-                    return moduleExports(...args);
+                    return logger;
                 }, moduleExports);
@@ -66,2 +95,3 @@ if (typeof patchedPino.pino === 'function') {
                 }
+                /* istanbul ignore if */
                 if (isESM) {
@@ -99,3 +129,4 @@ if (module.pino) {
             var _a;
-            if (!instrumentation.isEnabled()) {
+            if (!instrumentation.isEnabled() ||
+                instrumentation.getConfig().disableLogCorrelation) {
                 return {};
@@ -121,19 +152,4 @@ }
     }
-    _combineOptions(options) {
-        if (options === undefined) {
-            return { mixin: this._getMixinFunction() };
-        }
-        if (options.mixin === undefined) {
-            options.mixin = this._getMixinFunction();
-            return options;
-        }
-        const originalMixin = options.mixin;
-        const otelMixin = this._getMixinFunction();
-        options.mixin = (context, level) => {
-            return Object.assign(otelMixin(context, level), originalMixin(context, level));
-        };
-        return options;
-    }
 }
 exports.PinoInstrumentation = PinoInstrumentation;
 //# sourceMappingURL=instrumentation.js.map

build/src/types.d.ts

@@ -5,4 +5,24 @@ import { Span } from '@opentelemetry/api';
 export interface PinoInstrumentationConfig extends InstrumentationConfig {
+    /**
+     * Whether to disable the automatic sending of log records to the
+     * OpenTelemetry Logs SDK.
+     * @default false
+     */
+    disableLogSending?: boolean;
+    /**
+     * Whether to disable the injection trace-context fields, and possibly other
+     * fields from `logHook()`, into log records for log correlation.
+     * @default false
+     */
+    disableLogCorrelation?: boolean;
+    /**
+     * A function that allows injecting additional fields in log records. It is
+     * called, as `logHook(span, record)`, for each log record emitted in a valid
+     * span context. It requires `disableLogCorrelation` to be false.
+     */
     logHook?: LogHookFunction;
-    /** Configure the names of field injected into logs when there is span context available.  */
+    /**
+     * Configure the names of field injected into logs when there is span context
+     * available.
+     */
     logKeys?: {
@@ -9,0 +29,0 @@ traceId: string;

build/src/version.d.ts

@@ -1,3 +0,3 @@
-export declare const PACKAGE_VERSION = "0.40.0";
+export declare const PACKAGE_VERSION = "0.41.0";
 export declare const PACKAGE_NAME = "@opentelemetry/instrumentation-pino";
 //# sourceMappingURL=version.d.ts.map

build/src/version.js

@@ -20,4 +20,4 @@ "use strict";
 // this is autogenerated file, see scripts/version-update.js
-exports.PACKAGE_VERSION = '0.40.0';
+exports.PACKAGE_VERSION = '0.41.0';
 exports.PACKAGE_NAME = '@opentelemetry/instrumentation-pino';
 //# sourceMappingURL=version.js.map

package.json

 {
   "name": "@opentelemetry/instrumentation-pino",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "OpenTelemetry instrumentation for `pino` logger",
@@ -15,2 +15,3 @@ "main": "build/src/index.js",
     "lint:fix": "eslint . --ext .ts --fix",
+    "lint:readme": "node ../../../scripts/lint-readme.js",
     "precompile": "tsc --version && lerna run version:update --scope @opentelemetry/instrumentation-pino --include-dependencies",
@@ -49,6 +50,6 @@ "prewatch": "npm run precompile",
     "@opentelemetry/api": "^1.3.0",
-    "@opentelemetry/context-async-hooks": "^1.8.0",
     "@opentelemetry/contrib-test-utils": "^0.40.0",
     "@opentelemetry/sdk-trace-base": "^1.8.0",
     "@opentelemetry/sdk-trace-node": "^1.8.0",
+    "@opentelemetry/semantic-conventions": "^1.22.0",
     "@types/mocha": "7.0.2",
@@ -69,6 +70,8 @@ "@types/node": "18.6.5",
   "dependencies": {
+    "@opentelemetry/api-logs": "^0.52.0",
+    "@opentelemetry/core": "^1.25.0",
     "@opentelemetry/instrumentation": "^0.52.0"
   },
   "homepage": "https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-pino#readme",
-  "gitHead": "0af1b70f7c3c9763c85ac51fa5e334c1e1512020"
+  "gitHead": "ad8436d6a4174f2288cb939080cd4e74da94b0d7"
 }

README.md

@@ -6,3 +6,3 @@ # OpenTelemetry instrumentation for pino
 
-This module provides automatic instrumentation for injection of trace context for the [`pino`](https://www.npmjs.com/package/pino) module, which may be loaded using the [`@opentelemetry/sdk-trace-node`](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-node) package and is included in the [`@opentelemetry/auto-instrumentations-node`](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node) bundle.
+This module provides automatic instrumentation of the [`pino`](https://www.npmjs.com/package/pino) module to inject trace-context into Pino log records (log correlation) and to send Pino logging to the OpenTelemetry Logging SDK (log sending). It may be loaded using the [`@opentelemetry/sdk-trace-node`](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-node) package and is included in the [`@opentelemetry/auto-instrumentations-node`](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node) bundle.
 
@@ -19,42 +19,51 @@ If total installation size is not constrained, it is recommended to use the [`@opentelemetry/auto-instrumentations-node`](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node) bundle with [@opentelemetry/sdk-node](`https://www.npmjs.com/package/@opentelemetry/sdk-node`) for the most seamless instrumentation experience.
 
+## Supported Versions
+
+- [`pino`](https://www.npmjs.com/package/pino) versions `>=5.14.0 <10`
+  - The "log sending" feature is only supported in pino v7 and later.
+
 ## Usage
 
 ```js
-const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
+const { NodeSDK, tracing, logs, api } = require('@opentelemetry/sdk-node');
 const { PinoInstrumentation } = require('@opentelemetry/instrumentation-pino');
-const { registerInstrumentations } = require('@opentelemetry/instrumentation');
-
-const provider = new NodeTracerProvider();
-provider.register();
-
-registerInstrumentations({
+const sdk = new NodeSDK({
+  spanProcessor: new tracing.SimpleSpanProcessor(new tracing.ConsoleSpanExporter()),
+  logRecordProcessor: new logs.SimpleLogRecordProcessor(new logs.ConsoleLogRecordExporter()),
   instrumentations: [
     new PinoInstrumentation({
-      // Optional hook to insert additional context to log object.
-      logHook: (span, record, level) => {
-        record['resource.service.name'] =
-          provider.resource.attributes['service.name'];
-      },
-      // Log span context under custom keys
-      // This is optional, and will default to "trace_id", "span_id" and "trace_flags" as the keys
-      logKeys: {
-        traceId: 'traceId',
-        spanId: 'spanId',
-        traceFlags: 'traceFlags',
-      },
+      // See below for Pino instrumentation options.
     }),
-    // other instrumentations
-  ],
-});
+  ]
+})
+sdk.start();
 
 const pino = require('pino');
 const logger = pino();
-logger.info('foobar');
-// {"msg":"foobar","trace_id":"fc30029f30df383a4090d3189fe0ffdf","span_id":"625fa861d19d1056","trace_flags":"01", ...}
+
+logger.info('hi');
+// 1. Log records will be sent to the SDK-registered log record processor, if any.
+//    This is called "log sending".
+
+const tracer = api.trace.getTracer('example');
+tracer.startActiveSpan('manual-span', span => {
+  logger.info('in a span');
+  // 2. Fields identifying the current span will be added to log records:
+  //    {"level":30,...,"msg":"in a span","trace_id":"d61b4e4af1032e0aae279d12f3ab0159","span_id":"d140da862204f2a2","trace_flags":"01"}
+  //    This feature is called "log correlation".
+});
 ```
 
-### Fields added to pino log objects
+### Log sending
 
-For the current active span, the following fields are injected. These field names can be optionally configured via `logKeys` in the PinoInstrumentation config:
+Creation of a Pino Logger will automatically add a [Pino destination](https://getpino.io/#/docs/api?id=pinooptions-destination-gt-logger) that sends log records to the OpenTelemetry Logs SDK. The OpenTelemetry SDK can be configured to handle those records -- for example, sending them on to an OpenTelemetry collector for log archiving and processing. The example above shows a minimal configuration that emits OpenTelemetry log records to the console for debugging.
 
+If the OpenTelemetry SDK is not configured with a Logger provider, then this added destination will be a no-op.
+
+Log sending can be disabled with the `disableLogSending: true` option.
+
+### Log correlation
+
+Pino logger calls in the context of a tracing span will have fields identifying the span added to the log record. This allows [correlating](https://opentelemetry.io/docs/specs/otel/logs/#log-correlation) log records with tracing data. The added fields are ([spec](https://opentelemetry.io/docs/specs/otel/compatibility/logging_trace_context/)):
+
 - `trace_id`
@@ -64,7 +73,33 @@ - `span_id`
 
+These field names can optionally be configured via the `logKeys` option. For example:
+
+```js
+    new PinoInstrumentation({
+      logKeys: {
+        traceId: 'myTraceId',
+        spanId: 'mySpanId',
+        traceFlags: 'myTraceFlags',
+      },
+    }),
+```
+
+After adding these fields, the optional `logHook` is called to allow injecting additional fields. For example:
+
+```js
+  logHook: (span, record) => {
+    record['resource.service.name'] = provider.resource.attributes['service.name'];
+  }
+```
+
 When no span context is active or the span context is invalid, injection is skipped.
+Log injection can be disabled with the `disableLogCorrelation: true` option.
 
-### Supported versions
+### Pino instrumentation options
 
-`>=5.14.0 <10`
+| Option                  | Type              | Description |
+| ----------------------- | ----------------- | ----------- |
+| `disableLogSending`     | `boolean`         | Whether to disable [log sending](#log-sending). Default `false`. |
+| `disableLogCorrelation` | `boolean`         | Whether to disable [log correlation](#log-correlation). Default `false`. |
+| `logKeys`               | record            | A record with keys `traceId`, `spanId`, and `traceFlags` string fields giving the field names to use for log-correlation span data. |
+| `logHook`               | `LogHookFunction` | An option hook to inject additional context to a log record after trace-context has been added. This requires `disableLogCorrelation` to be false. |
 
@@ -75,2 +110,12 @@ ## Semantic Conventions
 
+## Alternative log sending with `pino-opentelemetry-transport`
+
+A possible alternative to the "log sending" support provided by this instrumentation is the [`pino-opentelemetry-transport` package](https://github.com/pinojs/pino-opentelemetry-transport).
+
+Every Pino logger has an output ["destination"](https://getpino.io/#/docs/api?id=destination), for example, a file or stdout.  Since v7, Pino includes support for ["transports"](https://getpino.io/#/docs/transports), a type of destination that uses a [worker thread](https://nodejs.org/api/worker_threads.html) to run the transport code. When calling `logger.info("hi")`, Pino serializes the log record to a JSON string, [sends that string to the worker](https://nodejs.org/api/worker_threads.html#workerpostmessagevalue-transferlist) for it to be handled.
+
+The `pino-opentelemetry-transport` package uses this mechanism. It starts an OpenTelemetry SDK `LoggerProvider` in the worker thread, parses each log record string, translates it into the OpenTelemetry Logs data model and sends it. Note that this `LoggerProvider` is independent of any OpenTelemetry SDK components in the main thread.
+
+The log sending support in this instrumentation works on the main thread and uses the OpenTelemetry SDK configured in the main thread. Otherwise the two mechanisms are very similar. Note that because they are maintained separately, there might be small differences in how Pino log records are translated into the OpenTelemetry Logs data model.
+
 ## Useful links
@@ -77,0 +122,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

72994

increased by88.88%

Number of package files

18

increased by20%

Lines of code

523

increased by130.4%

Number of lines in readme file

132

increased by51.72%

Worsened metrics

Dependency count

4

increased by100%

Dependency changes

• + Added@opentelemetry/api-logs@^0.52.0

• + Added@opentelemetry/core@^1.25.0

• + Added@opentelemetry/core@1.26.0(transitive)

• + Added@opentelemetry/semantic-conventions@1.27.0(transitive)