opentelemetry-instrumentation-commander 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 k65miyazakiy
+
+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,66 @@
+# OpenTelemetry Instrumentation for Commander.js
+
+Automatic instrumentation for [Commander.js](https://github.com/tj/commander.js) CLI framework using OpenTelemetry.
+
+## Installation
+
+```bash
+npm install opentelemetry-instrumentation-commander
+```
+
+## Usage
+
+```typescript
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { registerInstrumentations } from '@opentelemetry/instrumentation';
+import { CommanderInstrumentation } from 'opentelemetry-instrumentation-commander';
+
+const provider = new NodeTracerProvider();
+provider.register();
+
+registerInstrumentations({
+  instrumentations: [
+    new CommanderInstrumentation(),
+  ],
+});
+```
+
+## What gets instrumented?
+
+This instrumentation creates a span for each command execution with the following attributes:
+
+- `command.name`: The name of the executed command
+- `command.args`: JSON-serialized command arguments
+- `command.duration_ms`: Command execution duration in milliseconds
+
+## Supported Versions
+
+- Commander.js: `>=2.0.0 <15`
+- Node.js: `>=18.0.0`
+
+## Configuration
+
+```typescript
+interface CommanderInstrumentationConfig {
+  // Currently no configuration options available
+  // Future options may be added here
+}
+```
+
+The instrumentation is enabled by default when registered. You can disable it using the standard `enabled` option inherited from `InstrumentationBase`:
+
+```typescript
+new CommanderInstrumentation({ enabled: false })
+```
+
+## Features
+
+- ✅ Automatic span creation for command execution
+- ✅ Support for both synchronous and asynchronous commands
+- ✅ Exception recording with stack traces
+- ✅ Context propagation to command handlers
+- ✅ Support for nested commands and subcommands
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { CommanderInstrumentation } from './instrumentation-commander';
+export type { CommanderInstrumentationConfig } from './instrumentation-commander';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AACvE,YAAY,EAAE,8BAA8B,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommanderInstrumentation = void 0;
+var instrumentation_commander_1 = require("./instrumentation-commander");
+Object.defineProperty(exports, "CommanderInstrumentation", { enumerable: true, get: function () { return instrumentation_commander_1.CommanderInstrumentation; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yEAAuE;AAA9D,qIAAA,wBAAwB,OAAA"}

package/dist/instrumentation-commander.d.ts

@@ -0,0 +1,11 @@
+import { InstrumentationBase, InstrumentationNodeModuleDefinition } from '@opentelemetry/instrumentation';
+export interface CommanderInstrumentationConfig {
+}
+export declare class CommanderInstrumentation extends InstrumentationBase<CommanderInstrumentationConfig> {
+    constructor(config?: CommanderInstrumentationConfig);
+    protected init(): InstrumentationNodeModuleDefinition;
+    private _patchCommander;
+    private _unpatchCommander;
+    private _patchAction;
+}
+//# sourceMappingURL=instrumentation-commander.d.ts.map

package/dist/instrumentation-commander.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation-commander.d.ts","sourceRoot":"","sources":["../src/instrumentation-commander.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,mCAAmC,EAEpC,MAAM,gCAAgC,CAAC;AASxC,MAAM,WAAW,8BAA8B;CAE9C;AAED,qBAAa,wBAAyB,SAAQ,mBAAmB,CAAC,8BAA8B,CAAC;gBACnF,MAAM,GAAE,8BAAmC;IAIvD,SAAS,CAAC,IAAI;IASd,OAAO,CAAC,eAAe;IA2BvB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,YAAY;CAkErB"}

package/dist/instrumentation-commander.js

@@ -0,0 +1,109 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommanderInstrumentation = void 0;
+const instrumentation_1 = require("@opentelemetry/instrumentation");
+const api_1 = require("@opentelemetry/api");
+const package_json_1 = __importDefault(require("../package.json"));
+const PACKAGE_NAME = package_json_1.default.name;
+const PACKAGE_VERSION = package_json_1.default.version;
+class CommanderInstrumentation extends instrumentation_1.InstrumentationBase {
+    constructor(config = {}) {
+        super(PACKAGE_NAME, PACKAGE_VERSION, config);
+    }
+    init() {
+        return new instrumentation_1.InstrumentationNodeModuleDefinition('commander', ['>=2.0.0 <15'], this._patchCommander.bind(this), this._unpatchCommander.bind(this));
+    }
+    _patchCommander(moduleExports, moduleVersion) {
+        this._diag.debug(`Patching commander@${moduleVersion}`);
+        const Command = moduleExports.Command;
+        if (!Command || !Command.prototype) {
+            this._diag.warn('Could not find Command class in commander module');
+            return moduleExports;
+        }
+        if ((0, instrumentation_1.isWrapped)(Command.prototype.action)) {
+            this._unwrap(Command.prototype, 'action');
+        }
+        this._wrap(Command.prototype, 'action', this._patchAction.bind(this));
+        this._diag.debug('commander module patched successfully');
+        return moduleExports;
+    }
+    _unpatchCommander(moduleExports, moduleVersion) {
+        this._diag.debug(`Unpatching commander@${moduleVersion}`);
+        const Command = moduleExports.Command;
+        if (Command && Command.prototype) {
+            if ((0, instrumentation_1.isWrapped)(Command.prototype.action)) {
+                this._unwrap(Command.prototype, 'action');
+            }
+        }
+    }
+    _patchAction(original) {
+        const instrumentation = this;
+        return function patchedAction(fn) {
+            const wrappedFn = function (...args) {
+                const commandName = getCommandName(this);
+                const spanName = `command ${commandName}`;
+                return instrumentation.tracer.startActiveSpan(spanName, {
+                    kind: api_1.SpanKind.INTERNAL,
+                    attributes: {
+                        'command.name': commandName,
+                        'command.args': JSON.stringify(args.slice(0, -1)),
+                    },
+                }, (span) => {
+                    const startTime = Date.now();
+                    try {
+                        const result = fn.apply(this, args);
+                        if (result && typeof result.then === 'function') {
+                            return result
+                                .then((res) => {
+                                span.setStatus({ code: api_1.SpanStatusCode.OK });
+                                span.setAttribute('command.duration_ms', Date.now() - startTime);
+                                span.end();
+                                return res;
+                            })
+                                .catch((error) => {
+                                span.setStatus({
+                                    code: api_1.SpanStatusCode.ERROR,
+                                    message: error.message,
+                                });
+                                span.recordException(error);
+                                span.setAttribute('command.duration_ms', Date.now() - startTime);
+                                span.end();
+                                throw error;
+                            });
+                        }
+                        span.setStatus({ code: api_1.SpanStatusCode.OK });
+                        span.setAttribute('command.duration_ms', Date.now() - startTime);
+                        span.end();
+                        return result;
+                    }
+                    catch (error) {
+                        span.setStatus({
+                            code: api_1.SpanStatusCode.ERROR,
+                            message: error instanceof Error ? error.message : String(error),
+                        });
+                        if (error instanceof Error) {
+                            span.recordException(error);
+                        }
+                        span.setAttribute('command.duration_ms', Date.now() - startTime);
+                        span.end();
+                        throw error;
+                    }
+                });
+            };
+            return original.call(this, wrappedFn);
+        };
+    }
+}
+exports.CommanderInstrumentation = CommanderInstrumentation;
+/**
+ * Extract command name from Commander instance, handling version differences.
+ * Commander v9+ uses _name property, earlier versions use name() method.
+ */
+function getCommandName(command) {
+    const name = command._name || command.name() || 'unknown';
+    return name;
+}
+//# sourceMappingURL=instrumentation-commander.js.map

package/dist/instrumentation-commander.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation-commander.js","sourceRoot":"","sources":["../src/instrumentation-commander.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "opentelemetry-instrumentation-commander",
+  "version": "0.1.0",
+  "description": "OpenTelemetry automatic instrumentation for Commander.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "mocha",
+    "test:watch": "mocha --watch",
+    "clean": "rm -rf dist",
+    "prepack": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "opentelemetry",
+    "instrumentation",
+    "commander",
+    "cli",
+    "tracing"
+  ],
+  "author": "k65miyazakiy",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@opentelemetry/context-async-hooks": "^2.2.0",
+    "@opentelemetry/sdk-trace-base": "^1.19.0",
+    "@opentelemetry/sdk-trace-node": "^1.19.0",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^20.10.0",
+    "commander": "^14.0.2",
+    "mocha": "^11.7.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.7.0",
+    "@opentelemetry/instrumentation": "^0.208.0",
+    "@opentelemetry/semantic-conventions": "^1.19.0"
+  },
+  "peerDependencies": {
+    "commander": ">=2.0.0 <15"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}