@bluealba/opentelemetry-tracer 1.0.4-develop-1171

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @bluealba/opentelemetry-tracer@1.0.4-develop-1171 build
+> tsc
+

package/.turbo/turbo-test.log

@@ -0,0 +1,24 @@
+
+> @bluealba/opentelemetry-tracer@1.0.4-develop-1171 test
+> jest --detectOpenHandles --forceExit
+
+PASS __tests__/tracing.test.ts
+  ● Console
+
+    console.log
+      [Tracing] Disabled
+
+      at Object.log (src/tracing.ts:54:33)
+
+    console.log
+      [Tracing] Enabled: Publishing traces to http://localhost:4318/v1/traces with service test-service
+
+      at Object.log (src/tracing.ts:54:33)
+
+PASS __tests__/with-tracing.test.ts
+
+Test Suites: 2 passed, 2 total
+Tests:       4 passed, 4 total
+Snapshots:   0 total
+Time:        4.694 s
+Ran all test suites.

package/CHANGELOG.md

@@ -0,0 +1,186 @@
+# @bluealba-public/opentelemetry-tracer
+
+## 1.0.4
+
+### Patch Changes
+
+- Root dependency changes:
+
+  ## devDependencies
+
+  ### Added
+
+  - Added @faker-js/faker@9.2.0
+  - Added autocannon@^8.0.0
+
+- Root dependency changes:
+
+  ## devDependencies
+
+  ### Added
+
+  - Added @faker-js/faker@9.2.0
+  - Added autocannon@^8.0.0
+
+## 1.0.3
+
+### Patch Changes
+
+- Root dependency changes:
+
+  ## dependencies
+
+  ### Added
+
+  - Added pino-nestjs@^0.1.3
+
+- fd6d8c7: Root dependency changes:
+
+  ## dependencies
+
+  ### Removed
+
+  - Removed pino-pretty@^13.0.0
+
+## 1.0.2
+
+### Patch Changes
+
+- b3e2c49: Forcing bump to build the packages (previous versions didn't get build/published)
+
+## 1.0.1
+
+### Patch Changes
+
+- 602f1c8: Root dependency changes:
+
+  ## dependencies
+
+  ### Updated
+
+  - Updated cache-manager from ^6.4.0 to ^5.5.2
+  - Updated prettier from ~3.4.2 to ~3.0.3
+  - Updated reflect-metadata from ^0.2.2 to ^0.2.0
+
+  ### Removed
+
+  - Removed @autotelic/fastify-opentelemetry@^0.22.1
+  - Removed @aws-sdk/client-secrets-manager@^3.744.0
+  - Removed @bluealba/microservices-toolkit@^1.9.5
+  - Removed @faker-js/faker@9.5.0
+  - Removed @fastify/cookie@^11.0.2
+  - Removed @fastify/express@^4.0.2
+  - Removed @fastify/reply-from@^12.0.2
+  - Removed @fastify/static@^8.1.0
+  - Removed @fastify/swagger@^9.4.2
+  - Removed @fastify/swagger-ui@^5.2.1
+  - Removed @nestjs/axios@^4.0.0
+  - Removed @nestjs/cache-manager@^3.0.0
+  - Removed @nestjs/common@^11.0.9
+  - Removed @nestjs/config@^4.0.0
+  - Removed @nestjs/core@^11.0.9
+  - Removed @nestjs/devtools-integration@^0.2.0
+  - Removed @nestjs/jwt@^11.0.0
+  - Removed @nestjs/mapped-types@2.1.0
+  - Removed @nestjs/passport@^11.0.5
+  - Removed @nestjs/platform-express@^11.0.9
+  - Removed @nestjs/platform-fastify@^11.0.12
+  - Removed @nestjs/platform-ws@^11.0.9
+  - Removed @nestjs/schematics@^11.0.0
+  - Removed @nestjs/swagger@^11.0.3
+  - Removed @nestjs/testing@^11.0.9
+  - Removed @nestjs/websockets@^11.0.9
+  - Removed @nestjs/event-emitter@^3.0.0
+  - Removed @opentelemetry/api@^1.9.0
+  - Removed @opentelemetry/auto-instrumentations-node@^0.56.0
+  - Removed @opentelemetry/exporter-trace-otlp-http@^0.57.2
+  - Removed @opentelemetry/resources@^1.30.1
+  - Removed @opentelemetry/sdk-node@^0.57.2
+  - Removed @opentelemetry/semantic-conventions@^1.30.0
+  - Removed @radix-ui/react-dialog@^1.1.6
+  - Removed @testing-library/jest-dom@^6.6.3
+  - Removed @testing-library/react@^16.2.0
+  - Removed @types/express-serve-static-core@4.19.6
+  - Removed @types/react@18.3.18
+  - Removed @types/react-dom@^18.3.5
+  - Removed @types/supertest@^6.0.0
+  - Removed @types/systemjs@^6.15.0
+  - Removed axios@^1.6.8
+  - Removed ba-db-postgres@^6.0.0
+  - Removed basic-auth@^2.0.1
+  - Removed bcryptjs@^3.0.2
+  - Removed body-parser@^1.20.2
+  - Removed class-validator@^0.14.1
+  - Removed clsx@^2.1.1
+  - Removed co@~4.6.0
+  - Removed compression@~1.7.4
+  - Removed cookie-parser@^1.4.6
+  - Removed cross-spawn@7.0.3
+  - Removed dayjs@^1.11.13
+  - Removed dotenv@^8.6.0
+  - Removed ejs@^3.1.9
+  - Removed esbuild@0.20.2
+  - Removed express@^4.18.2
+  - Removed fastify@^5.2.1
+  - Removed husky@9.1.7
+  - Removed identity-obj-proxy@^3.0.0
+  - Removed jest@^29.7.0
+  - Removed jest-environment-jsdom@^29.7.0
+  - Removed jest-html-reporter@^3.10.2
+  - Removed jsonwebtoken@9.0.2
+  - Removed kafkajs@~1.11.0
+  - Removed knex@^3.1.0
+  - Removed lodash@^4.17.15
+  - Removed moment@^2.30.1
+  - Removed morgan@^1.10.0
+  - Removed negotiator@^0.6.3
+  - Removed nestjs-cls@^5.0.1
+  - Removed node-cache@^5.1.2
+  - Removed nodemon@^3.1.4
+  - Removed path-to-regexp@6.3.0
+  - Removed pino@^9.6.0
+  - Removed pino-http@^10.4.0
+  - Removed ramda@^0.30.1
+  - Removed react@^18.3.1
+  - Removed react-dom@18.3.1
+  - Removed react-hook-form@^7.54.2
+  - Removed rxjs@^7.8.1
+  - Removed single-spa@^6.0.3
+  - Removed swagger-jsdoc@^6.2.8
+  - Removed swagger-ui-express@^5.0.1
+  - Removed underscore@^1.13.7
+  - Removed url-join@^4.0.1
+  - Removed winston@^2.4.7
+  - Removed @bluealba-public/from-env@\*
+
+  ## devDependencies
+
+  ### Added
+
+  - Added jest-environment-jsdom@^29.7.0
+  - Added jest-html-reporter@^3.10.2
+  - Added nodemon@^3.1.4
+  - Added ts-jest@^29.2.5
+  - Added ts-loader@9.5.1
+  - Added ts-node@10.9.2
+  - Added tsconfig-paths@^4.2.0
+  - Added typescript@5.8.3
+  - Added identity-obj-proxy@^3.0.0
+  - Added @types/express-serve-static-core@4.19.6
+  - Added @types/ramda@^0.30.2
+  - Added @types/react@18.3.3
+  - Added @types/react-dom@^18.3.0
+  - Added @types/supertest@^6.0.0
+  - Added @types/systemjs@^6.15.0
+  - Added @nestjs/cli@^11.0.6
+  - Added @testing-library/jest-dom@^6.5.0
+  - Added glob@^11.0.1
+  - Added husky@^9.1.7
+  - Added lint-staged@^15.5.0
+  - Added syncpack@^13.0.3
+
+  ### Updated
+
+  - Updated @types/jsonwebtoken from ^9.0.8 to ^9.0.9
+
+- d1a9ccb: Add NestJS Gateway

package/LICENSE

@@ -0,0 +1,134 @@
+Required Notice: Copyright Blue Alba LLC 2025 (https://bluealba.com)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you
+must agree to them as both strict obligations and
+conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the
+software that would otherwise infringe the licensor's
+copyright in it for any permitted purpose. However,
+you may only distribute the software according to
+[Distribution License](#distribution-license) and make
+changes or new works based on the software according to
+[Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software. Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or
+the URL for them above, as well as copies of any plain-text
+lines beginning with `Required Notice:` that the licensor
+provided with the software. For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software
+that covers patent claims the licensor can license, as well
+as patent claims that the licensor becomes able to license.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization, or
+government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice. Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms, including any portion of the
+software.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,55 @@
+# OpenTelemetry Tracer
+
+
+## Overview
+OpenTelemetry Tracer provides a robust tracing utility built on OpenTelemetry, enabling seamless instrumentation of asynchronous operations in your application. It supports auto-instrumentation and custom tracer configuration to effectively monitor performance and troubleshoot issues.
+
+## Installation
+Install the package from npm:
+```bash
+npm install @bluealba/opentelemetry-tracer
+```
+
+## Usage
+Initialize tracing in your application by importing and calling the `initTracing` function:
+```typescript
+import { initTracing } from '@bluealba/opentelemetry-tracer';
+
+const tracing = initTracing({
+  enabled: true,
+  url: process.env.TRACE_URL,
+  serviceName: 'your-service-name'
+});
+
+// Wrap asynchronous operations with tracing
+const tracedOperation = tracing.withTracing('operation-span', async () => {
+  // ... your code ...
+});
+```
+
+
+### For Fastify Applications >5.x
+For Fastify applications, use the provided Fastify plugin to automatically trace incoming requests and responses:
+```
+npm install @autotelic/fastify-opentelemetry
+```
+
+```typescript
+import fastify from 'fastify';
+import fastifyOpenTelemetry from '@autotelic/fastify-opentelemetry';
+
+const app = fastify();
+
+app.register(fastifyOpenTelemetry);
+
+// ... existing code ...
+```
+
+
+## Configuration
+Customize the tracer with the following options:
+- **enabled**: Toggle tracing on or off.
+- **url**: Specify the OTLP trace exporter endpoint.
+- **serviceName**: Name your service for trace identification.
+- **logger**: (Optional) Custom logger for additional logging.
+- **instrumentations**: (Optional) List of instrumentations to enable.

package/__tests__/tracing.test.ts

@@ -0,0 +1,77 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { trace, context } from '@opentelemetry/api';
+import { initTracing, Tracing } from '../src/tracing';
+
+trace.setSpan = jest.fn().mockImplementation((ctx, span) => ctx);
+
+jest.mock('@opentelemetry/sdk-node', () => {
+  return {
+    NodeSDK: jest.fn().mockImplementation(() => ({
+      start: jest.fn(),
+      shutdown: jest.fn().mockResolvedValue(undefined),
+    })),
+  };
+});
+
+jest.mock('@opentelemetry/auto-instrumentations-node', () => ({
+  getNodeAutoInstrumentations: jest.fn().mockReturnValue([]),
+}));
+
+jest.mock('@opentelemetry/exporter-trace-otlp-http', () => ({
+  OTLPTraceExporter: jest.fn(),
+}));
+
+jest.mock('@opentelemetry/resources', () => ({
+  Resource: jest.fn(),
+}));
+
+jest.mock('@opentelemetry/api', () => {
+  const originalModule = jest.requireActual('@opentelemetry/api');
+  return {
+    ...originalModule,
+    trace: {
+      getTracer: jest.fn().mockReturnValue({
+        startSpan: jest.fn().mockReturnValue({
+          setStatus: jest.fn(),
+          recordException: jest.fn(),
+          end: jest.fn(),
+        }),
+      }),
+    },
+  };
+});
+
+describe('initTracing', () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+    delete process.env.TRACE_URL;
+    delete process.env.npm_package_name;
+  });
+
+  it('should return the disabled implementation when tracing is not enabled', () => {
+    const tracing: Tracing = initTracing({ enabled: false });
+    const fakeFn = jest.fn().mockResolvedValue('result');
+    const wrappedFn = tracing.withTracing('span-test', fakeFn);
+    expect(wrappedFn).toBe(fakeFn);
+  });
+
+  it('should initialize tracing when it is enabled', async () => {
+    process.env.TRACE_URL = 'http://localhost:4318/v1/traces';
+    process.env.npm_package_name = 'test-service';
+    const tracing: Tracing = initTracing();
+    expect(NodeSDK).toHaveBeenCalled();
+    expect(trace.getTracer).toHaveBeenCalledWith('test-service');
+
+    // We verify that withTracing wraps the function correctly
+    const fakeFn = jest.fn().mockResolvedValue('result');
+    const wrappedFn = tracing.withTracing('span-test', fakeFn);
+    const result = await wrappedFn('argument');
+    expect(result).toBe('result');
+    expect(fakeFn).toHaveBeenCalledWith('argument');
+
+    // We verify shutdown
+    await tracing.shutdown?.();
+    const sdkInstance = (NodeSDK as jest.Mock).mock.results[0].value;
+    expect(sdkInstance.shutdown).toHaveBeenCalled();
+  });
+});

package/__tests__/with-tracing.test.ts

@@ -0,0 +1,41 @@
+import { SpanStatusCode } from '@opentelemetry/api';
+import { withTracing } from '../src/with-tracing';
+
+describe('withTracing', () => {
+  let fakeSpan: any;
+  let fakeTracer: any;
+  let fakeFn: jest.Mock;
+
+  beforeEach(() => {
+    fakeSpan = {
+      setStatus: jest.fn(),
+      recordException: jest.fn(),
+      end: jest.fn(),
+    };
+
+    fakeTracer = {
+      startSpan: jest.fn().mockReturnValue(fakeSpan),
+    };
+
+    fakeFn = jest.fn().mockResolvedValue('result');
+  });
+
+  it('should execute the function and mark the span as OK on success', async () => {
+    const wrappedFn = withTracing(fakeTracer, 'span-test', fakeFn);
+    const result = await wrappedFn('arg1');
+    expect(result).toBe('result');
+    expect(fakeTracer.startSpan).toHaveBeenCalledWith('span-test');
+    expect(fakeSpan.setStatus).toHaveBeenCalledWith({ code: SpanStatusCode.OK });
+    expect(fakeSpan.end).toHaveBeenCalled();
+  });
+
+  it('should record the exception and mark the span as ERROR on failure', async () => {
+    const error = new Error('failed');
+    fakeFn.mockRejectedValue(error);
+    const wrappedFn = withTracing(fakeTracer, 'span-test', fakeFn);
+    await expect(wrappedFn('arg1')).rejects.toThrow('failed');
+    expect(fakeSpan.recordException).toHaveBeenCalledWith(error);
+    expect(fakeSpan.setStatus).toHaveBeenCalledWith({ code: SpanStatusCode.ERROR });
+    expect(fakeSpan.end).toHaveBeenCalled();
+  });
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { initTracing, Tracing, TracingOptions, Logger } from './tracing';
+export { withTracing, TracingFunction } from './with-tracing';

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTracing = exports.initTracing = void 0;
+var tracing_1 = require("./tracing");
+Object.defineProperty(exports, "initTracing", { enumerable: true, get: function () { return tracing_1.initTracing; } });
+var with_tracing_1 = require("./with-tracing");
+Object.defineProperty(exports, "withTracing", { enumerable: true, get: function () { return with_tracing_1.withTracing; } });

package/dist/tracing.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Provides a tracing utility built on top of OpenTelemetry to instrument and monitor asynchronous operations.
+ *
+ * @remarks
+ * The tracing module conditionally initializes the OpenTelemetry Node SDK with the OTLP trace exporter.
+ * Tracing is enabled if the provided options flag "enabled" is true or if the TRACE_URL environment variable is defined.
+ * If not enabled or the trace exporter URL is not provided, the module returns a no-op implementation that simply executes
+ * the provided function without instrumentation.
+ *
+ * The module exposes two primary interfaces:
+ *
+ * - {@link Tracing}: Defines an API for wrapping asynchronous functions with tracing spans using the {withTracing} method.
+ *   Optionally, it also provides a {shutdown} method to gracefully terminate the OpenTelemetry SDK.
+ *
+ * - {@link TracingOptions}: Allows configuration of the tracing behavior. It supports:
+ *   - `enabled`: A boolean flag to explicitly enable or disable tracing.
+ *   - `url`: The endpoint URL for the OTLP trace exporter.
+ *   - `serviceName`: The name of the service, defaulting to the npm package name or 'anonymous-service' if unspecified.
+ *
+ * The tracing spans are created using a tracer instance from the OpenTelemetry API, which is configured with
+ * automatic instrumentation via {@link getNodeAutoInstrumentations}, and the service resource is tagged with
+ * the provided service name.
+ *
+ * @packageDocumentation
+ */
+import * as opentelemetry from '@opentelemetry/sdk-node';
+export interface Tracing {
+    withTracing: <T extends (...args: any[]) => Promise<any>>(spanName: string, fn: T) => T;
+    shutdown?: () => Promise<void>;
+}
+export interface Logger {
+    log: (msg: string) => void;
+    error: (msg: string) => void;
+}
+export interface TracingOptions {
+    enabled?: boolean;
+    url?: string;
+    serviceName?: string;
+    logger?: Logger;
+    instrumentations?: opentelemetry.NodeSDKConfiguration["instrumentations"];
+}
+/**
+ * Initializes tracing for the application using OpenTelemetry.
+ *
+ * @remarks
+ * This function configures and starts the OpenTelemetry NodeSDK with the OTLP trace exporter.
+ * It determines whether tracing is enabled based on the provided options or the environment variable `TRACE_URL`.
+ * If tracing is disabled or the `url` is not specified, a no-operation version of the tracing interface is returned.
+ *
+ * @param options - Optional configuration settings for tracing. If not provided, values are inferred from environment variables:
+ *                  - `enabled`: Boolean flag to enable tracing. Defaults to true if `TRACE_URL` is defined.
+ *                  - `url`: The endpoint URL for the trace exporter.
+ *                  - `serviceName`: The service name used for tracing. Defaults to the value of `npm_package_name` or a predefined anonymous service name.
+ *
+ * @returns An object with:
+ *          - `withTracing`: A function that wraps a given function execution with a tracing span.
+ *          - `shutdown`: An async function to gracefully shutdown the tracing SDK.
+ *
+ * @example
+ * const tracing = initTracing({ enabled: true, url: 'http://localhost:4318', serviceName: 'my-service' });
+ * tracing.withTracing('my-span', () => {
+ *   // ... code to be traced ...
+ * });
+ */
+export declare function initTracing(options?: TracingOptions): Tracing;

package/dist/tracing.js

@@ -0,0 +1,132 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initTracing = initTracing;
+/**
+ * Provides a tracing utility built on top of OpenTelemetry to instrument and monitor asynchronous operations.
+ *
+ * @remarks
+ * The tracing module conditionally initializes the OpenTelemetry Node SDK with the OTLP trace exporter.
+ * Tracing is enabled if the provided options flag "enabled" is true or if the TRACE_URL environment variable is defined.
+ * If not enabled or the trace exporter URL is not provided, the module returns a no-op implementation that simply executes
+ * the provided function without instrumentation.
+ *
+ * The module exposes two primary interfaces:
+ *
+ * - {@link Tracing}: Defines an API for wrapping asynchronous functions with tracing spans using the {withTracing} method.
+ *   Optionally, it also provides a {shutdown} method to gracefully terminate the OpenTelemetry SDK.
+ *
+ * - {@link TracingOptions}: Allows configuration of the tracing behavior. It supports:
+ *   - `enabled`: A boolean flag to explicitly enable or disable tracing.
+ *   - `url`: The endpoint URL for the OTLP trace exporter.
+ *   - `serviceName`: The name of the service, defaulting to the npm package name or 'anonymous-service' if unspecified.
+ *
+ * The tracing spans are created using a tracer instance from the OpenTelemetry API, which is configured with
+ * automatic instrumentation via {@link getNodeAutoInstrumentations}, and the service resource is tagged with
+ * the provided service name.
+ *
+ * @packageDocumentation
+ */
+const opentelemetry = __importStar(require("@opentelemetry/sdk-node"));
+const auto_instrumentations_node_1 = require("@opentelemetry/auto-instrumentations-node");
+const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const api_1 = require("@opentelemetry/api");
+const with_tracing_1 = require("./with-tracing");
+const ANONYMOUS_SERVICE_NAME = 'anonymous-service';
+const defaultLogger = {
+    log: (msg) => console.log(msg),
+    error: (msg) => console.error(msg),
+};
+/**
+ * Initializes tracing for the application using OpenTelemetry.
+ *
+ * @remarks
+ * This function configures and starts the OpenTelemetry NodeSDK with the OTLP trace exporter.
+ * It determines whether tracing is enabled based on the provided options or the environment variable `TRACE_URL`.
+ * If tracing is disabled or the `url` is not specified, a no-operation version of the tracing interface is returned.
+ *
+ * @param options - Optional configuration settings for tracing. If not provided, values are inferred from environment variables:
+ *                  - `enabled`: Boolean flag to enable tracing. Defaults to true if `TRACE_URL` is defined.
+ *                  - `url`: The endpoint URL for the trace exporter.
+ *                  - `serviceName`: The service name used for tracing. Defaults to the value of `npm_package_name` or a predefined anonymous service name.
+ *
+ * @returns An object with:
+ *          - `withTracing`: A function that wraps a given function execution with a tracing span.
+ *          - `shutdown`: An async function to gracefully shutdown the tracing SDK.
+ *
+ * @example
+ * const tracing = initTracing({ enabled: true, url: 'http://localhost:4318', serviceName: 'my-service' });
+ * tracing.withTracing('my-span', () => {
+ *   // ... code to be traced ...
+ * });
+ */
+function initTracing(options) {
+    var _a, _b, _c, _d, _e;
+    const enabled = (_a = options === null || options === void 0 ? void 0 : options.enabled) !== null && _a !== void 0 ? _a : process.env.TRACE_URL !== undefined;
+    const url = (_b = options === null || options === void 0 ? void 0 : options.url) !== null && _b !== void 0 ? _b : process.env.TRACE_URL;
+    const serviceName = (_d = (_c = options === null || options === void 0 ? void 0 : options.serviceName) !== null && _c !== void 0 ? _c : process.env.npm_package_name) !== null && _d !== void 0 ? _d : ANONYMOUS_SERVICE_NAME;
+    const logger = (options === null || options === void 0 ? void 0 : options.logger) || defaultLogger;
+    const instrumentations = (_e = options === null || options === void 0 ? void 0 : options.instrumentations) !== null && _e !== void 0 ? _e : [];
+    if (!enabled || !url) {
+        logger.log('[Tracing] Disabled');
+        return { withTracing: (_spanName, fn) => fn };
+    }
+    const sdk = new opentelemetry.NodeSDK({
+        autoDetectResources: true,
+        traceExporter: new exporter_trace_otlp_http_1.OTLPTraceExporter({ url }),
+        instrumentations: [
+            (0, auto_instrumentations_node_1.getNodeAutoInstrumentations)(),
+            ...instrumentations
+        ],
+        resource: new resources_1.Resource({
+            [semantic_conventions_1.SemanticResourceAttributes.SERVICE_NAME]: serviceName
+        })
+    });
+    sdk.start();
+    logger.log(`[Tracing] Enabled: Publishing traces to ${url} with service ${serviceName}`);
+    process.on('SIGTERM', () => {
+        sdk.shutdown()
+            .then(() => logger.log('Tracing terminated'))
+            .catch((error) => logger.error('Error terminating tracing: ' + error))
+            .finally(() => process.exit(0));
+    });
+    const tracer = api_1.trace.getTracer(serviceName);
+    return {
+        withTracing: (spanName, fn) => (0, with_tracing_1.withTracing)(tracer, spanName, fn),
+        shutdown: async () => { await sdk.shutdown(); }
+    };
+}

package/dist/with-tracing.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Wraps an asynchronous function with tracing instrumentation using OpenTelemetry.
+ *
+ * This function creates a new trace span and executes the provided function within this span's context.
+ * Upon completion, the span status is set based on the execution's outcome:
+ * - If the function completes successfully, the span status is set to OK.
+ * - If an error is thrown, the error is recorded and the span status is set to ERROR, and the error is rethrown.
+ *
+ * @template T - A function type extending a function that returns a Promise.
+ *
+ * @param tracer - An OpenTelemetry Tracer used to start a new trace span.
+ * @param spanName - The name to assign to the newly created span.
+ * @param fn - The asynchronous function to be wrapped with tracing.
+ *
+ * @returns A new function that returns the same promise as the original function, but with tracing applied.
+ */
+import { Tracer } from '@opentelemetry/api';
+export type TracingFunction<T> = (...args: any[]) => Promise<T>;
+export declare function withTracing<T extends TracingFunction<T>>(tracer: Tracer, spanName: string, fn: T): T;

package/dist/with-tracing.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTracing = withTracing;
+/**
+ * Wraps an asynchronous function with tracing instrumentation using OpenTelemetry.
+ *
+ * This function creates a new trace span and executes the provided function within this span's context.
+ * Upon completion, the span status is set based on the execution's outcome:
+ * - If the function completes successfully, the span status is set to OK.
+ * - If an error is thrown, the error is recorded and the span status is set to ERROR, and the error is rethrown.
+ *
+ * @template T - A function type extending a function that returns a Promise.
+ *
+ * @param tracer - An OpenTelemetry Tracer used to start a new trace span.
+ * @param spanName - The name to assign to the newly created span.
+ * @param fn - The asynchronous function to be wrapped with tracing.
+ *
+ * @returns A new function that returns the same promise as the original function, but with tracing applied.
+ */
+const api_1 = require("@opentelemetry/api");
+function withTracing(tracer, spanName, fn) {
+    const wrapped = async (...args) => {
+        const span = tracer.startSpan(spanName);
+        try {
+            return await api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), async () => {
+                const result = await fn(...args);
+                span.setStatus({ code: api_1.SpanStatusCode.OK });
+                return result;
+            });
+        }
+        catch (error) {
+            span.recordException(error);
+            span.setStatus({ code: api_1.SpanStatusCode.ERROR });
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    };
+    return wrapped;
+}

package/jest.config.js

@@ -0,0 +1,6 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} **/
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/__tests__/**/*.test.ts']
+};

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@bluealba/opentelemetry-tracer",
+  "version": "1.0.4-develop-1171",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest"
+  },
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "publishConfig": {
+    "@bluealba:registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { initTracing, Tracing, TracingOptions, Logger } from './tracing';
+export { withTracing, TracingFunction } from './with-tracing';

package/src/tracing.ts

@@ -0,0 +1,122 @@
+/**
+ * Provides a tracing utility built on top of OpenTelemetry to instrument and monitor asynchronous operations.
+ *
+ * @remarks
+ * The tracing module conditionally initializes the OpenTelemetry Node SDK with the OTLP trace exporter.
+ * Tracing is enabled if the provided options flag "enabled" is true or if the TRACE_URL environment variable is defined.
+ * If not enabled or the trace exporter URL is not provided, the module returns a no-op implementation that simply executes
+ * the provided function without instrumentation.
+ *
+ * The module exposes two primary interfaces:
+ *
+ * - {@link Tracing}: Defines an API for wrapping asynchronous functions with tracing spans using the {withTracing} method.
+ *   Optionally, it also provides a {shutdown} method to gracefully terminate the OpenTelemetry SDK.
+ *
+ * - {@link TracingOptions}: Allows configuration of the tracing behavior. It supports:
+ *   - `enabled`: A boolean flag to explicitly enable or disable tracing.
+ *   - `url`: The endpoint URL for the OTLP trace exporter.
+ *   - `serviceName`: The name of the service, defaulting to the npm package name or 'anonymous-service' if unspecified.
+ *
+ * The tracing spans are created using a tracer instance from the OpenTelemetry API, which is configured with
+ * automatic instrumentation via {@link getNodeAutoInstrumentations}, and the service resource is tagged with
+ * the provided service name.
+ *
+ * @packageDocumentation
+ */
+import * as opentelemetry from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { Resource } from '@opentelemetry/resources';
+import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
+import { trace, Tracer } from '@opentelemetry/api';
+import { withTracing as createWithTracing } from './with-tracing';
+
+const ANONYMOUS_SERVICE_NAME = 'anonymous-service';
+
+export interface Tracing {
+  withTracing: <T extends (...args: any[]) => Promise<any>>(spanName: string, fn: T) => T;
+  shutdown?: () => Promise<void>;
+}
+
+export interface Logger {
+  log: (msg: string) => void;
+  error: (msg: string) => void;
+}
+export interface TracingOptions {
+  enabled?: boolean;
+  url?: string;
+  serviceName?: string;
+  logger?: Logger;
+  instrumentations?: opentelemetry.NodeSDKConfiguration["instrumentations"];
+}
+
+const defaultLogger: Logger = {
+  log: (msg: string) => console.log(msg),
+  error: (msg: string) => console.error(msg),
+};
+
+/**
+ * Initializes tracing for the application using OpenTelemetry.
+ *
+ * @remarks
+ * This function configures and starts the OpenTelemetry NodeSDK with the OTLP trace exporter.
+ * It determines whether tracing is enabled based on the provided options or the environment variable `TRACE_URL`.
+ * If tracing is disabled or the `url` is not specified, a no-operation version of the tracing interface is returned.
+ *
+ * @param options - Optional configuration settings for tracing. If not provided, values are inferred from environment variables:
+ *                  - `enabled`: Boolean flag to enable tracing. Defaults to true if `TRACE_URL` is defined.
+ *                  - `url`: The endpoint URL for the trace exporter.
+ *                  - `serviceName`: The service name used for tracing. Defaults to the value of `npm_package_name` or a predefined anonymous service name.
+ *
+ * @returns An object with:
+ *          - `withTracing`: A function that wraps a given function execution with a tracing span.
+ *          - `shutdown`: An async function to gracefully shutdown the tracing SDK.
+ *
+ * @example
+ * const tracing = initTracing({ enabled: true, url: 'http://localhost:4318', serviceName: 'my-service' });
+ * tracing.withTracing('my-span', () => {
+ *   // ... code to be traced ...
+ * });
+ */
+export function initTracing(options?: TracingOptions): Tracing {
+  const enabled = options?.enabled ?? process.env.TRACE_URL !== undefined;
+  const url = options?.url ?? process.env.TRACE_URL;
+  const serviceName = options?.serviceName ?? process.env.npm_package_name ?? ANONYMOUS_SERVICE_NAME;
+  const logger = options?.logger || defaultLogger;
+  const instrumentations = options?.instrumentations ?? [];
+
+  if (!enabled || !url) {
+    logger.log('[Tracing] Disabled');
+    return { withTracing: (_spanName, fn) => fn };
+  }
+
+  const sdk = new opentelemetry.NodeSDK({
+    autoDetectResources: true,
+    traceExporter: new OTLPTraceExporter({ url }),
+    instrumentations: [
+      getNodeAutoInstrumentations(),
+      ...instrumentations
+    ],
+    resource: new Resource({
+      [SemanticResourceAttributes.SERVICE_NAME]: serviceName
+    })
+  });
+
+  sdk.start();
+
+  logger.log(`[Tracing] Enabled: Publishing traces to ${url} with service ${serviceName}`);
+
+  process.on('SIGTERM', () => {
+    sdk.shutdown()
+      .then(() => logger.log('Tracing terminated'))
+      .catch((error: any) => logger.error('Error terminating tracing: ' + error))
+      .finally(() => process.exit(0));
+  });
+
+  const tracer: Tracer = trace.getTracer(serviceName);
+
+  return {
+    withTracing: (spanName, fn) => createWithTracing(tracer, spanName, fn),
+    shutdown: async () => { await sdk.shutdown(); }
+  };
+}

package/src/with-tracing.ts

@@ -0,0 +1,44 @@
+/**
+ * Wraps an asynchronous function with tracing instrumentation using OpenTelemetry.
+ *
+ * This function creates a new trace span and executes the provided function within this span's context.
+ * Upon completion, the span status is set based on the execution's outcome:
+ * - If the function completes successfully, the span status is set to OK.
+ * - If an error is thrown, the error is recorded and the span status is set to ERROR, and the error is rethrown.
+ *
+ * @template T - A function type extending a function that returns a Promise.
+ * 
+ * @param tracer - An OpenTelemetry Tracer used to start a new trace span.
+ * @param spanName - The name to assign to the newly created span.
+ * @param fn - The asynchronous function to be wrapped with tracing.
+ *
+ * @returns A new function that returns the same promise as the original function, but with tracing applied.
+ */
+import { context, trace, Tracer, SpanStatusCode } from '@opentelemetry/api';
+
+export type TracingFunction<T> = (...args: any[]) => Promise<T>;
+
+export function withTracing<T extends TracingFunction<T>>(
+  tracer: Tracer,
+  spanName: string,
+  fn: T
+): T {
+  const wrapped = async (...args: Parameters<T>) => {
+    const span = tracer.startSpan(spanName);
+    try {
+      return await context.with(trace.setSpan(context.active(), span), async () => {
+        const result = await fn(...args);
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+      });
+    } catch (error) {
+      span.recordException(error as Error);
+      span.setStatus({ code: SpanStatusCode.ERROR });
+      throw error;
+    } finally {
+      span.end();
+    }
+  };
+  return wrapped as T;
+}
+

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2019",
+    "module": "CommonJS",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src"]
+}

package/version.json

@@ -0,0 +1 @@
+{"version": "1.0.4-develop-1171", "name": "bluealba-opentelemetry-tracer", "displayName": "null"}