@atrim/instrument-node 0.1.0-7603d70-20251119002755

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Atrim AI
+
+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,351 @@
+# @atrim/instrument-node
+
+**One-line OpenTelemetry for Node.js**
+
+[![npm version](https://badge.fury.io/js/%40atrim%2Finstrument-node.svg)](https://www.npmjs.com/package/@atrim/instrument-node)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+OpenTelemetry instrumentation for Node.js with centralized YAML configuration. Works with any Node.js framework (Express, Fastify, Koa, Hono) and runtime (Node.js, Bun, Deno).
+
+## Quick Start
+
+**1. Install**
+
+```bash
+npm install @atrim/instrument-node
+```
+
+**2. Initialize** (at the top of your app)
+
+### Promise API (Traditional)
+
+```typescript
+import { initializeInstrumentation } from '@atrim/instrument-node'
+
+await initializeInstrumentation()
+```
+
+### Effect API (Recommended)
+
+```typescript
+import { Effect } from 'effect'
+import { initializeInstrumentationEffect } from '@atrim/instrument-node'
+
+await Effect.runPromise(initializeInstrumentationEffect())
+```
+
+**3. Done!** Your app is now sending traces to OpenTelemetry.
+
+By default, traces go to `http://localhost:4318`. To send to a remote collector:
+
+```typescript
+await initializeInstrumentation({
+  otlp: { endpoint: 'https://otel-collector.company.com:4318' }
+})
+```
+
+### What just happened?
+
+Auto-detected and configured:
+- ✅ Service name from `package.json`
+- ✅ OTLP endpoint (local or remote)
+- ✅ Auto-instrumentation for Express, HTTP, Fastify, etc.
+- ✅ Graceful shutdown on SIGTERM/SIGINT
+
+## Optional: Control What Gets Traced
+
+Create `instrumentation.yaml` in your project root:
+
+```yaml
+version: "1.0"
+instrumentation:
+  enabled: true
+  instrument_patterns:
+    - pattern: "^app\\."      # ✅ Trace application operations
+  ignore_patterns:
+    - pattern: "^health\\."   # ❌ Skip health checks
+```
+
+That's it!
+
+## Features
+
+- **Zero-config** - Works out of the box with sensible defaults
+- **Universal** - Node.js 20+, Bun 1.0+, Deno 1.40+
+- **Framework-agnostic** - Express, Fastify, Koa, Hono, vanilla HTTP
+- **Effect-TS first** - Typed error handling with Effect (optional)
+- **Pattern-based filtering** - Control which spans are created via YAML
+- **HTTP filtering** - Prevent noisy health checks and metrics endpoints
+- **Centralized config** - YAML file, URL, or environment variable
+- **Production-ready** - Graceful shutdown, error handling, performance optimized
+
+## Documentation
+
+Full documentation is available in the [main repository](https://github.com/atrim-ai/instrumentation):
+
+### Core Docs
+
+- 📖 [Getting Started](../../docs/getting-started.md) - 5-minute setup guide
+- ⚙️ [Configuration](../../docs/configuration.md) - YAML configuration reference
+- 📋 [Examples](../../docs/EXAMPLES.md) - 8+ working examples
+- 🔧 [Troubleshooting](../../docs/TROUBLESHOOTING.md) - Common issues and solutions
+- 📚 [API Reference](../../docs/api-reference.md) - Complete API documentation
+
+### Specialized Guides
+
+- 🌐 [HTTP Filtering](../../docs/HTTP_FILTERING_INVESTIGATION.md) - Prevent noisy traces
+- 🔄 [Effect Integration](../../examples/effect-ts/README.md) - Effect-TS patterns
+- 🧪 [Testing Guide](../../docs/TESTING.md) - How to test instrumented apps
+
+## Installation
+
+### npm
+
+```bash
+npm install @atrim/instrument-node
+```
+
+### yarn
+
+```bash
+yarn add @atrim/instrument-node
+```
+
+### pnpm
+
+```bash
+pnpm add @atrim/instrument-node
+```
+
+### Bun
+
+```bash
+bun add @atrim/instrument-node
+```
+
+## Usage Examples
+
+### Express Application
+
+```typescript
+import express from 'express'
+import { initializeInstrumentation } from '@atrim/instrument-node'
+
+// Initialize at startup
+await initializeInstrumentation()
+
+const app = express()
+
+app.get('/users', async (req, res) => {
+  // Automatically traced!
+  const users = await fetchUsers()
+  res.json(users)
+})
+
+app.listen(3000)
+```
+
+### Effect-TS Application
+
+```typescript
+import { Effect, Layer } from 'effect'
+import { EffectInstrumentationLive } from '@atrim/instrument-node/effect'
+
+const program = Effect.gen(function* () {
+  // Automatically traced with Effect.withSpan()
+  yield* myOperation.pipe(Effect.withSpan('app.operation'))
+}).pipe(
+  Effect.provide(EffectInstrumentationLive)
+)
+
+await Effect.runPromise(program)
+```
+
+### Bun Runtime
+
+```typescript
+import { initializeInstrumentation } from '@atrim/instrument-node'
+
+// Works exactly the same as Node.js
+await initializeInstrumentation()
+
+Bun.serve({
+  port: 3000,
+  fetch(req) {
+    return new Response('Hello from Bun!')
+  }
+})
+```
+
+### Remote Configuration
+
+```typescript
+import { initializeInstrumentation } from '@atrim/instrument-node'
+
+await initializeInstrumentation({
+  configUrl: 'https://config.company.com/instrumentation.yaml',
+  cacheTimeout: 300_000 // 5 minutes
+})
+```
+
+## Configuration
+
+### Priority Order (Highest to Lowest)
+
+1. **Explicit Config Object** - Passed programmatically
+2. **Environment Variable** - `ATRIM_INSTRUMENTATION_CONFIG`
+3. **Project Root File** - `./instrumentation.yaml`
+4. **Default Config** - Built-in defaults
+
+### instrumentation.yaml Example
+
+```yaml
+version: "1.0"
+
+instrumentation:
+  enabled: true
+  logging: "on"
+
+  # Pattern-based span filtering
+  instrument_patterns:
+    - pattern: "^app\\."
+      enabled: true
+      description: "Application operations"
+    - pattern: "^storage\\."
+      enabled: true
+      description: "Storage layer"
+
+  ignore_patterns:
+    - pattern: "^health\\."
+      description: "Health checks"
+    - pattern: "^metrics\\."
+      description: "Metrics endpoints"
+
+# Effect-TS specific (optional)
+effect:
+  auto_extract_metadata: true
+```
+
+See [Configuration Guide](../../docs/configuration.md) for complete reference.
+
+## HTTP Request Filtering
+
+**IMPORTANT:** HTTP filtering requires explicit configuration to prevent noisy traces.
+
+### Add HTTP Filtering Patterns
+
+```yaml
+# instrumentation.yaml
+instrumentation:
+  http_filtering:
+    enabled: true
+    ignore_routes:
+      - pattern: "^/health$"
+      - pattern: "^/metrics$"
+      - pattern: "^/api/internal/"
+      - pattern: "http://.*:4318/v1/traces"  # Prevent OTLP trace loops!
+```
+
+See [HTTP Filtering Guide](../../docs/HTTP_FILTERING_INVESTIGATION.md) for details.
+
+## API Reference
+
+### Standard API (Promise-based)
+
+```typescript
+// Main initialization
+initializeInstrumentation(options?: SdkInitializationOptions): Promise<NodeSDK | null>
+
+// Pattern matching only (skip SDK)
+initializePatternMatchingOnly(options?: ConfigLoaderOptions): Promise<void>
+
+// Configuration
+loadConfig(options?: ConfigLoaderOptions): Promise<InstrumentationConfig>
+
+// Service detection
+detectServiceInfo(): Promise<ServiceInfo>
+getServiceName(): Promise<string>
+getServiceVersion(): Promise<string>
+```
+
+### Effect API
+
+```typescript
+// Main initialization (Effect)
+initializeInstrumentationEffect(options?: SdkInitializationOptions): Effect.Effect<NodeSDK | null, InitializationError | ConfigError>
+
+// Effect-TS Layer
+EffectInstrumentationLive: Layer.Layer<Tracer.Tracer, ConfigError, never>
+
+// Service detection (Effect)
+detectServiceInfoEffect: Effect.Effect<ServiceInfo, ServiceDetectionError>
+getServiceNameEffect: Effect.Effect<string, ServiceDetectionError>
+getServiceVersionEffect: Effect.Effect<string, never>
+```
+
+See [API Reference](../../docs/api-reference.md) for complete documentation.
+
+## Runtimes Supported
+
+- ✅ **Node.js** 20.0.0+
+- ✅ **Bun** 1.0.0+
+- ✅ **Deno** 1.40.0+ (via npm compatibility)
+
+## Frameworks Supported
+
+- ✅ **Express** - Auto-instrumentation included
+- ✅ **Fastify** - Auto-instrumentation included
+- ✅ **Koa** - Auto-instrumentation included
+- ✅ **Hono** - Works with manual spans
+- ✅ **Vanilla HTTP** - Works with any Node.js HTTP server
+- ✅ **Effect-TS** - First-class integration with Effect.withSpan()
+
+## Examples
+
+See the [examples directory](../../examples/) for complete working examples:
+
+- [Express](../../examples/express/) - Basic Express app
+- [Effect-TS](../../examples/effect-ts/) - Advanced Effect patterns
+- [Effect Platform](../../examples/effect-platform/) - Pure Effect HTTP server
+- [Vanilla TypeScript](../../examples/vanilla/) - Standard Node.js
+- [Bun Runtime](../../examples/bun/) - Bun-specific example
+- [Remote Config](../../examples/remote-config/) - Load config from URL
+- [Multi-Service](../../examples/multi-service/) - Distributed tracing
+
+## Troubleshooting
+
+See [Troubleshooting Guide](../../docs/TROUBLESHOOTING.md) for common issues and solutions.
+
+### Quick Fixes
+
+**No traces appearing?**
+- Check collector is running: `docker run -p 4318:4318 otel/opentelemetry-collector`
+- Check endpoint: `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318`
+
+**Too many traces?**
+- Add HTTP filtering patterns (health checks, metrics, OTLP exports)
+- See [HTTP Filtering Guide](../../docs/HTTP_FILTERING_INVESTIGATION.md)
+
+**Effect-TS spans not appearing?**
+- Make sure you're using `Effect.withSpan()`
+- Provide `EffectInstrumentationLive` layer
+
+## Contributing
+
+Contributions welcome! See [main repository](https://github.com/atrim-ai/instrumentation) for guidelines.
+
+## License
+
+MIT © Atrim AI
+
+## Related Packages
+
+- [@atrim/instrument-core](../core) - Internal shared logic (private)
+- @atrim/instrument-web - Browser/web support _(Phase 1)_
+
+## Links
+
+- 📦 [npm package](https://www.npmjs.com/package/@atrim/instrument-node)
+- 🐙 [GitHub repository](https://github.com/atrim-ai/instrumentation)
+- 🐛 [Issue tracker](https://github.com/atrim-ai/instrumentation/issues)
+- 📖 [Documentation](https://github.com/atrim-ai/instrumentation#readme)

package/package.json

@@ -0,0 +1,131 @@
+{
+  "name": "@atrim/instrument-node",
+  "version": "0.1.0-7603d70-20251119002755",
+  "description": "OpenTelemetry instrumentation for Node.js with centralized YAML configuration",
+  "type": "module",
+  "license": "MIT",
+  "author": "Atrim AI",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/atrim-ai/instrumentation.git",
+    "directory": "packages/node"
+  },
+  "bugs": {
+    "url": "https://github.com/atrim-ai/instrumentation/issues"
+  },
+  "homepage": "https://github.com/atrim-ai/instrumentation#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "opentelemetry",
+    "instrumentation",
+    "tracing",
+    "observability",
+    "nodejs",
+    "bun",
+    "deno",
+    "effect",
+    "express",
+    "fastify"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./target/dist/index.d.ts",
+      "import": "./target/dist/index.js",
+      "require": "./target/dist/index.cjs"
+    },
+    "./effect": {
+      "types": "./target/dist/integrations/effect/index.d.ts",
+      "import": "./target/dist/integrations/effect/index.js",
+      "require": "./target/dist/integrations/effect/index.cjs"
+    }
+  },
+  "main": "./target/dist/index.js",
+  "module": "./target/dist/index.js",
+  "types": "./target/dist/index.d.ts",
+  "files": [
+    "target/dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@effect/opentelemetry": "^0.59.0",
+    "@effect/platform": "^0.93.0",
+    "@effect/platform-node": "latest",
+    "@opentelemetry/auto-instrumentations-node": "^0.67.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.208.0",
+    "@opentelemetry/instrumentation": "^0.208.0",
+    "@opentelemetry/sdk-node": "^0.208.0",
+    "@opentelemetry/sdk-trace-base": "^2.2.0",
+    "effect": "^3.19.0",
+    "yaml": "^2.3.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/resources": "^2.2.0",
+    "@opentelemetry/sdk-logs": "^0.208.0",
+    "@opentelemetry/sdk-metrics": "^2.2.0",
+    "@opentelemetry/sdk-trace-node": "^2.2.0",
+    "@opentelemetry/sdk-trace-web": "^2.2.0",
+    "@opentelemetry/semantic-conventions": "^1.38.0",
+    "@types/node": "^20.10.0",
+    "@vitest/coverage-v8": "^4.0.8",
+    "effect": "^3.19.0",
+    "testcontainers": "^11.8.1",
+    "tsup": "^8.0.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.8",
+    "@atrim/instrument-core": "0.4.0"
+  },
+  "peerDependencies": {
+    "@effect/opentelemetry": ">=0.40.0",
+    "@effect/platform": ">=0.70.0",
+    "@opentelemetry/api": "^1.0.0",
+    "@opentelemetry/sdk-trace-base": "^1.0.0",
+    "effect": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": false
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    },
+    "effect": {
+      "optional": true
+    },
+    "@effect/opentelemetry": {
+      "optional": true
+    },
+    "@effect/platform": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:integration": "OTEL_BSP_SCHEDULE_DELAY=500 vitest run --config vitest.integration.config.ts",
+    "test:all": "pnpm test && pnpm test:integration",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
+    "clean": "rm -rf target",
+    "publish:dev:version": "npm version $(git describe --tags --abbrev=0 | sed 's/^.*@//' | sed 's/^v//')-$(git rev-parse --short HEAD)-$(date -u +%Y%m%d%H%M%S) --no-git-tag-version",
+    "publish:dev:save": "node -p \"require('./package.json').version\" > .version",
+    "publish:dev:publish": "pnpm build && pnpm publish --tag dev --access public --no-git-checks",
+    "publish:dev:reset": "npm version 1.0.0 --no-git-tag-version",
+    "publish:dev": "pnpm publish:dev:version && pnpm publish:dev:save && pnpm publish:dev:publish && pnpm publish:dev:reset"
+  }
+}