@saidsef/tracing-node 4.3.0 → 4.4.0

package/README.md

@@ -22,6 +22,7 @@ Effortlessly supercharge your applications with world-class distributed tracing!
 | AWS SDK | Cloud service instrumentation |
 | Pino logger | Integration with trace/span IDs |
 | Node runtime metrics | Event loop, garbage collection, heap |
+| Log export | Pino records over OTLP, correlated by trace |
 | RED metrics | Request duration histograms over OTLP |
 | DNS/FS instrumentation | Optional monitoring |
 | Resource detection | Host, OS, process, container |
@@ -47,6 +48,8 @@ The W3C Trace Context propagation this library registers is what lets Tempo pair
 
 Metrics go to the same endpoint by default and land in Mimir. They are recorded before the sampler runs, so they stay complete however far trace volume is turned down.
 
+Pino log records go to the same endpoint and land in Loki, each carrying the trace and span id of the request that wrote it. No log agent or file scraping sits in between.
+
 ## Instalation
 
 ```
@@ -86,6 +89,8 @@ setupTracing({hostname: 'hostname', serviceName: 'service_name', url: 'endpoint'
 | enableMetrics | boolean | export metrics as well as traces | No | `true` |
 | metricsUrl | string | metrics endpoint, when it differs from `url` | No | `url` |
 | metricExportIntervalMillis | number | how often metrics are exported | No | `60000` |
+| enableLogs | boolean | send Pino log records over OTLP | No | `true` |
+| logsUrl | string | logs endpoint, when it differs from `url` | No | `url` |
 
 ## Documentation
 

package/libs/index.mjs

@@ -22,7 +22,9 @@ import {HttpInstrumentation} from '@opentelemetry/instrumentation-http';
 import {DnsInstrumentation} from '@opentelemetry/instrumentation-dns';
 import {ElasticsearchInstrumentation} from 'opentelemetry-instrumentation-elasticsearch';
 import {ExpressInstrumentation} from '@opentelemetry/instrumentation-express';
+import {logs} from '@opentelemetry/api-logs';
 import {NodeTracerProvider} from '@opentelemetry/sdk-trace-node';
+import {OTLPLogExporter} from '@opentelemetry/exporter-logs-otlp-grpc';
 import {OTLPMetricExporter} from '@opentelemetry/exporter-metrics-otlp-grpc';
 import {OTLPTraceExporter} from '@opentelemetry/exporter-trace-otlp-grpc';
 import {PinoInstrumentation} from '@opentelemetry/instrumentation-pino';
@@ -31,6 +33,7 @@ import {IORedisInstrumentation} from '@opentelemetry/instrumentation-ioredis';
 import {registerInstrumentations} from '@opentelemetry/instrumentation';
 import {RuntimeNodeInstrumentation} from '@opentelemetry/instrumentation-runtime-node';
 import {MeterProvider, PeriodicExportingMetricReader} from '@opentelemetry/sdk-metrics';
+import {BatchLogRecordProcessor, LoggerProvider} from '@opentelemetry/sdk-logs';
 import {FsInstrumentation} from '@opentelemetry/instrumentation-fs';
 import {resourceFromAttributes, detectResources, envDetector, hostDetector, osDetector, processDetector, serviceInstanceIdDetector} from '@opentelemetry/resources';
 import {ATTR_SERVICE_NAME} from '@opentelemetry/semantic-conventions';
@@ -71,6 +74,7 @@ const setPeerService = (span, host) => {
 
 let tracerProvider = null; // Declare provider in module scope for access in stopTracing
 let meterProvider = null;
+let loggerProvider = null;
 
 /**
 * Sets up tracing for the application using OpenTelemetry.
@@ -95,6 +99,8 @@ let meterProvider = null;
 * @param {boolean} [options.enableMetrics=true] - Export metrics as well as traces.
 * @param {string} [options.metricsUrl=options.url] - Endpoint for metrics, when it differs from the trace endpoint.
 * @param {number} [options.metricExportIntervalMillis=60000] - How often metrics are exported.
+* @param {boolean} [options.enableLogs=true] - Send Pino log records over OTLP.
+* @param {string} [options.logsUrl=options.url] - Endpoint for logs, when it differs from the trace endpoint.
 *
 * @returns {Tracer} - The tracer for the service.
 */
@@ -115,6 +121,8 @@ export function setupTracing(options = {}) {
     enableMetrics = true,
     metricsUrl = url,
     metricExportIntervalMillis = 60000,
+    enableLogs = true,
+    logsUrl = url,
   } = options;
 
   // Validate required parameters
@@ -149,8 +157,8 @@ export function setupTracing(options = {}) {
     explicitAttributes[ATTR_CONTAINER_NAME] = hostname;
   }
 
-  // One resource for both signals. Grafana pairs a metric with a trace on
-  // service.name, so the two providers have to carry an identical resource.
+  // One resource for every signal. Grafana pairs a metric and a log line with
+  // a trace on service.name, so the providers carry an identical resource.
   const resource = detectResources({
     detectors: [envDetector, hostDetector, osDetector, processDetector, serviceInstanceIdDetector],
   }).merge(resourceFromAttributes(explicitAttributes));
@@ -173,6 +181,22 @@ export function setupTracing(options = {}) {
     metrics.setGlobalMeterProvider(meterProvider);
   }
 
+  if (enableLogs) {
+    loggerProvider = new LoggerProvider({
+      resource,
+      processors: [
+        new BatchLogRecordProcessor({
+          exporter: new OTLPLogExporter({...exportOptions, url: logsUrl}),
+          maxQueueSize: 4096,
+          maxExportBatchSize: 1024,
+          scheduledDelayMillis: 2000,
+          exportTimeoutMillis: 10000,
+        }),
+      ],
+    });
+    logs.setGlobalLoggerProvider(loggerProvider);
+  }
+
   // Register globally. With no overrides, register() installs the modern
   // AsyncLocalStorageContextManager and a CompositePropagator of
   // W3CTraceContext + W3CBaggage - identical propagation to the previous
@@ -245,6 +269,10 @@ export function setupTracing(options = {}) {
       },
     }),
     new PinoInstrumentation({
+      // Log sending is on by default, and every record is parsed and rebuilt as
+      // a LogRecord before it reaches a logger. With no logger provider that
+      // work is done for a no-op, so turn it off rather than pay for nothing.
+      disableLogSending: !enableLogs,
       logHook: (span, record) => {
         // trace_id/span_id/trace_flags are injected by the instrumentation by
         // default; only add service name for better log correlation.
@@ -329,6 +357,7 @@ export function setupTracing(options = {}) {
   registerInstrumentations({
     tracerProvider,
     meterProvider,
+    loggerProvider,
     instrumentations,
   });
 
@@ -337,11 +366,11 @@ export function setupTracing(options = {}) {
 }
 
 /**
-* Gracefully stops the tracing by shutting down the tracer and meter providers.
+* Gracefully stops the tracing by shutting down every provider it registered.
 *
-* This function ensures that all pending spans and metrics are exported and
-* resources are cleaned up properly. It is recommended to call this function
-* during the application's shutdown process.
+* This function ensures that all pending spans, metrics and log records are
+* exported and resources are cleaned up properly. It is recommended to call
+* this function during the application's shutdown process.
 *
 * @returns {Promise<void>} - A promise that resolves when shutdown is complete.
 */
@@ -372,6 +401,20 @@ export async function stopTracing() {
       diag.error('Error during metrics shutdown:', error);
     }
   }
+
+  if (loggerProvider) {
+    try {
+      await loggerProvider.shutdown();
+      diag.info('Logs have been successfully shut down.');
+    } catch (error) {
+      diag.error('Error during logs shutdown:', error);
+    } finally {
+      // A second setGlobalLoggerProvider is ignored, so unregister whatever the
+      // flush did, or a later setupTracing keeps writing to a dead provider.
+      loggerProvider = null;
+      logs.disable();
+    }
+  }
 }
 
 /**
@@ -382,4 +425,5 @@ export async function stopTracing() {
 export function __resetTracingForTesting() {
   tracerProvider = null;
   meterProvider = null;
+  loggerProvider = null;
 }

package/libs/index.test.mjs

@@ -2,7 +2,9 @@
 import { describe, it, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert';
 import { metrics } from '@opentelemetry/api';
+import { logs } from '@opentelemetry/api-logs';
 import { MeterProvider } from '@opentelemetry/sdk-metrics';
+import { LoggerProvider } from '@opentelemetry/sdk-logs';
 import { setupTracing, stopTracing, __resetTracingForTesting } from './index.mjs';
 
 describe('setupTracing', () => {
@@ -105,6 +107,53 @@ describe('setupTracing', () => {
     assert.ok(metrics.getMeterProvider() instanceof MeterProvider, 'global meter provider should be the SDK one');
   });
 
+  // The Pino instrumentation sends every log record to the Logs API whether or
+  // not a provider is registered. Without one the record is built and dropped.
+  it('should register a global logger provider by default', () => {
+    setupTracing({
+      serviceName: 'test-service',
+      url: 'http://localhost:4317',
+    });
+    assert.ok(logs.getLoggerProvider() instanceof LoggerProvider, 'global logger provider should be the SDK one');
+  });
+
+  it('should leave the no-op logger provider in place when logs are disabled', () => {
+    setupTracing({
+      serviceName: 'test-service',
+      url: 'http://localhost:4317',
+      enableLogs: false,
+    });
+    assert.ok(!(logs.getLoggerProvider() instanceof LoggerProvider), 'no logger provider should be registered');
+  });
+
+  it('should accept a separate logs endpoint', () => {
+    const tracer = setupTracing({
+      serviceName: 'test-service',
+      url: 'http://localhost:4317',
+      logsUrl: 'http://localhost:4318',
+    });
+    assert.ok(tracer, 'tracer should be defined');
+    assert.ok(logs.getLoggerProvider() instanceof LoggerProvider, 'global logger provider should be the SDK one');
+  });
+
+  // Without the unregister in stopTracing the API keeps the first provider and
+  // silently ignores the second registration.
+  it('should unregister the logger provider on shutdown', async () => {
+    setupTracing({
+      serviceName: 'test-service',
+      url: 'http://localhost:4317',
+    });
+    await stopTracing();
+    assert.ok(!(logs.getLoggerProvider() instanceof LoggerProvider), 'logger provider should be unregistered');
+
+    __resetTracingForTesting();
+    setupTracing({
+      serviceName: 'test-service',
+      url: 'http://localhost:4317',
+    });
+    assert.ok(logs.getLoggerProvider() instanceof LoggerProvider, 'a later setup should register again');
+  });
+
   // Without the unregister in stopTracing the API refuses the second
   // registration and the global keeps pointing at the shut-down provider.
   it('should unregister the meter provider on shutdown', async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saidsef/tracing-node",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "tracing NodeJS - Wrapper for OpenTelemetry instrumentation packages",
   "main": "libs/index.mjs",
   "scripts": {
@@ -33,6 +33,8 @@
   "homepage": "https://github.com/saidsef/tracing-node#readme",
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.222.0",
+    "@opentelemetry/exporter-logs-otlp-grpc": "^0.222.0",
     "@opentelemetry/exporter-metrics-otlp-grpc": "^0.222.0",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.222.0",
     "@opentelemetry/instrumentation": "^0.222.0",
@@ -47,6 +49,7 @@
     "@opentelemetry/instrumentation-runtime-node": "^0.35.0",
     "@opentelemetry/instrumentation-undici": "^0.32.0",
     "@opentelemetry/resources": "^2.11.0",
+    "@opentelemetry/sdk-logs": "^0.222.0",
     "@opentelemetry/sdk-metrics": "^2.11.0",
     "@opentelemetry/sdk-trace-base": "^2.11.0",
     "@opentelemetry/sdk-trace-node": "^2.11.0",