securenow 3.0.14 → 4.0.2

package/NEXTJS-GUIDE.md

@@ -0,0 +1,379 @@
+# SecureNow for Next.js - Complete Integration Guide
+
+Send traces and logs from your Next.js app to SigNoz (or any OpenTelemetry-compatible backend) in under 2 minutes.
+
+## 🚀 Quick Start (2 Simple Steps!)
+
+### Step 1: Install SecureNow
+
+```bash
+npm install securenow
+# or
+yarn add securenow
+# or
+pnpm add securenow
+```
+
+**🎉 The installer will automatically:**
+- Detect your Next.js project
+- Offer to create `instrumentation.ts` (or `.js`)
+- Create `.env.local` template
+- **Zero webpack warnings** (uses @vercel/otel under the hood)
+
+**Just answer "Y" when prompted!**
+
+### Step 2: Configure Environment Variables
+
+Edit the `.env.local` file that was created:
+
+```bash
+# Required: Your app name (shows up in SigNoz)
+SECURENOW_APPID=my-nextjs-app
+
+# Required: Your SigNoz server endpoint
+SECURENOW_INSTANCE=http://your-signoz-server:4318
+
+# Optional: API key for authentication
+OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key-here"
+```
+
+### That's It! 🎉
+
+**No webpack warnings!** SecureNow uses `@vercel/otel` under the hood, which is specifically designed for Next.js and handles all the bundling correctly.
+
+---
+
+## 🔧 Alternative Setup Methods
+
+### If You Skipped Auto-Setup
+
+**Option 1: Use the CLI (Recommended)**
+
+```bash
+npx securenow init
+```
+
+**Option 2: Create Manually**
+
+Create `instrumentation.ts` at the **root** of your Next.js project (or inside `src/`):
+
+```typescript
+// instrumentation.ts
+import { registerSecureNow } from 'securenow/nextjs';
+
+export function register() {
+  registerSecureNow();
+}
+```
+
+**JavaScript version:**
+```javascript
+// instrumentation.js
+const { registerSecureNow } = require('securenow/nextjs');
+
+export function register() {
+  registerSecureNow();
+}
+```
+
+See [AUTO-SETUP.md](./AUTO-SETUP.md) for detailed setup options.
+
+---
+
+## ▶️ Run Your App
+
+Run your Next.js app:
+
+```bash
+npm run dev
+# or
+npm run build && npm start
+```
+
+You should see:
+```
+[securenow] Next.js integration loading
+[securenow] 🚀 Next.js App → service.name=my-nextjs-app-xxx
+[securenow] ✅ OpenTelemetry started for Next.js → http://...
+```
+
+---
+
+## 📊 What Gets Automatically Captured?
+
+SecureNow automatically captures comprehensive request data:
+
+### 🌐 User Information (Automatic!)
+- **IP Address** - From x-forwarded-for, x-real-ip, etc.
+- **User Agent** - Browser and device info
+- **Referer** - Where users came from
+- **Geographic Data** - Country, region, city (Vercel/Cloudflare)
+- **Request Metadata** - Headers, host, scheme
+- **Response Data** - Status codes, timing
+
+See [AUTOMATIC-IP-CAPTURE.md](./AUTOMATIC-IP-CAPTURE.md) for full details.
+
+### Next.js Built-in Spans
+- ✅ HTTP requests (`[http.method] [next.route]`)
+- ✅ API routes execution
+- ✅ Page rendering (App Router & Pages Router)
+- ✅ `getServerSideProps` / `getStaticProps`
+- ✅ Metadata generation
+- ✅ Server component loading
+- ✅ TTFB (Time to First Byte)
+
+### Backend Calls
+- ✅ HTTP/HTTPS requests (via `fetch`, `axios`, `node-fetch`, etc.)
+- ✅ Database queries:
+  - PostgreSQL
+  - MySQL / MySQL2
+  - MongoDB
+  - Redis
+- ✅ GraphQL queries
+- ✅ Other Node.js libraries
+
+---
+
+## ⚙️ Advanced Configuration
+
+### Option 1: Environment Variables (Recommended)
+
+```bash
+# .env.local
+
+# Required
+SECURENOW_APPID=my-nextjs-app
+
+# Optional Configuration
+SECURENOW_INSTANCE=http://your-signoz-server:4318
+SECURENOW_NO_UUID=1                         # Don't append UUID (useful for dev)
+OTEL_LOG_LEVEL=info                         # debug|info|warn|error
+SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns   # Disable specific instrumentations
+SECURENOW_TEST_SPAN=1                       # Create test span on startup
+
+# Authentication
+OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-key,authorization=Bearer token"
+
+# Alternative endpoint configuration
+OTEL_EXPORTER_OTLP_ENDPOINT=http://...      # Base endpoint
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://...  # Full traces URL
+```
+
+### Option 2: Programmatic Configuration
+
+```typescript
+// instrumentation.ts
+import { registerSecureNow } from 'securenow/nextjs';
+
+export function register() {
+  registerSecureNow({
+    serviceName: 'my-nextjs-app',
+    endpoint: 'http://your-signoz-server:4318',
+    noUuid: false,
+    disableInstrumentations: ['fs', 'dns'],
+    headers: {
+      'x-api-key': process.env.SECURENOW_API_KEY || '',
+    },
+  });
+}
+```
+
+**Options:**
+- `serviceName` (string): Service name (overrides `SECURENOW_APPID`)
+- `endpoint` (string): Base URL for OTLP collector (overrides `SECURENOW_INSTANCE`)
+- `noUuid` (boolean): Don't append UUID to service name
+- `disableInstrumentations` (string[]): List of instrumentations to disable
+- `headers` (object): Additional headers for authentication
+
+---
+
+## 🔧 Next.js Version Compatibility
+
+### Next.js 15+ (Recommended)
+✅ Works out of the box. Just create `instrumentation.ts`.
+
+### Next.js 14 and Below
+⚠️ You need to enable the instrumentation hook in `next.config.js`:
+
+```javascript
+// next.config.js
+const nextConfig = {
+  experimental: {
+    instrumentationHook: true,  // Required for Next.js 14 and below
+  },
+};
+
+module.exports = nextConfig;
+```
+
+---
+
+## 🎯 Deployment
+
+### Vercel
+
+SecureNow works seamlessly on Vercel:
+
+1. Add environment variables in Vercel dashboard
+2. Deploy normally
+
+The instrumentation runs during both build and runtime.
+
+### Docker
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci --production
+
+COPY . .
+RUN npm run build
+
+ENV SECURENOW_APPID=my-nextjs-app
+ENV SECURENOW_INSTANCE=http://signoz:4318
+
+EXPOSE 3000
+CMD ["npm", "start"]
+```
+
+### Self-Hosted / VPS
+
+Just set environment variables and run:
+
+```bash
+export SECURENOW_APPID=my-nextjs-app
+export SECURENOW_INSTANCE=http://your-signoz-server:4318
+npm start
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Not seeing traces?
+
+**Check 1: Is instrumentation loading?**
+```bash
+npm run dev
+# Look for: [securenow] Next.js integration loading
+```
+
+**Check 2: Enable debug logging**
+```bash
+OTEL_LOG_LEVEL=debug npm run dev
+```
+
+**Check 3: Create a test span**
+```bash
+SECURENOW_TEST_SPAN=1 npm run dev
+```
+
+### `Cannot find module 'securenow/nextjs'`
+
+Make sure you're on the latest version:
+```bash
+npm install securenow@latest
+```
+
+### Traces not appearing in SigNoz
+
+1. **Check endpoint:**
+   ```bash
+   curl http://your-signoz-server:4318/v1/traces
+   ```
+
+2. **Verify connectivity:** Make sure your app can reach SigNoz
+
+3. **Check authentication:** If using API keys, verify headers
+
+### Too many spans / noisy logs
+
+Disable specific instrumentations:
+```bash
+SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns,net
+```
+
+---
+
+## 📖 Comparison with Other Solutions
+
+### vs. `@vercel/otel`
+- ✅ **SecureNow**: Pre-configured for SigNoz, includes auto-instrumentations
+- ⚠️ **@vercel/otel**: Requires manual instrumentation setup
+
+### vs. Manual OpenTelemetry Setup
+- ✅ **SecureNow**: 3 lines of code, works immediately
+- ⚠️ **Manual**: 50+ lines, complex configuration
+
+### vs. Other APM Solutions (DataDog, New Relic)
+- ✅ **SecureNow**: Open-source, self-hosted, vendor-neutral
+- ⚠️ **Commercial APM**: Expensive, vendor lock-in
+
+---
+
+## 🔥 Best Practices
+
+### 1. Use Meaningful Service Names
+```bash
+# Good ✅
+SECURENOW_APPID=checkout-service
+SECURENOW_APPID=user-dashboard
+
+# Bad ❌
+SECURENOW_APPID=app
+SECURENOW_APPID=test
+```
+
+### 2. Set Deployment Environment
+```bash
+# Vercel automatically sets VERCEL_ENV
+# For other platforms:
+NODE_ENV=production
+```
+
+### 3. Use Service Instance IDs in Production
+```bash
+# Default behavior (recommended for production)
+# Each worker gets a unique instance ID
+
+# For development (easier to filter)
+SECURENOW_NO_UUID=1
+```
+
+### 4. Disable Noisy Instrumentations
+```bash
+# File system operations can be too verbose
+SECURENOW_DISABLE_INSTRUMENTATIONS=fs
+```
+
+---
+
+## 🎓 Examples
+
+Check the `examples/` folder for:
+- `nextjs-instrumentation.ts` - Basic TypeScript setup
+- `nextjs-instrumentation.js` - Basic JavaScript setup
+- `nextjs-with-options.ts` - Advanced configuration
+- `nextjs-env-example.txt` - Complete environment variables reference
+
+---
+
+## 🆘 Support
+
+- **Issues:** [GitHub Issues](https://github.com/your-repo/securenow/issues)
+- **Documentation:** [Full Documentation](https://your-docs-site.com)
+- **SigNoz Docs:** [SigNoz OpenTelemetry Docs](https://signoz.io/docs/)
+
+---
+
+## 📝 License
+
+ISC
+
+---
+
+**Made with ❤️ for the Next.js and SigNoz community**
+

package/NEXTJS-QUICKSTART.md

@@ -0,0 +1,67 @@
+# Next.js + SecureNow Quick Start
+
+## Installation (30 seconds)
+
+```bash
+npm install securenow
+```
+
+**🎉 The installer will automatically offer to create the instrumentation file!**
+
+Just answer "Y" when prompted, and it's done!
+
+---
+
+## Alternative: Manual Setup
+
+If you skipped auto-setup or want to do it manually:
+
+### Option 1: Use CLI (Recommended)
+
+```bash
+npx securenow init
+```
+
+### Option 2: Create File Manually
+
+Create `instrumentation.ts` at project root:
+
+```typescript
+import { registerSecureNow } from 'securenow/nextjs';
+export function register() { registerSecureNow(); }
+```
+
+### 2. Create `.env.local`:
+
+```bash
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=http://your-signoz:4318
+```
+
+### 3. (Next.js 14 only) Update `next.config.js`:
+
+```javascript
+module.exports = {
+  experimental: { instrumentationHook: true }
+}
+```
+
+## Run
+
+```bash
+npm run dev
+```
+
+## Verify
+
+Look for:
+```
+[securenow] ✅ OpenTelemetry started for Next.js
+```
+
+Open SigNoz → check for traces from `my-nextjs-app`
+
+---
+
+**That's it!** See [NEXTJS-GUIDE.md](./NEXTJS-GUIDE.md) for advanced configuration.
+

package/README.md

@@ -1,22 +1,145 @@
-# securenow
-[npm package for securenow] : (http://securenow.ai/)
-
-# installation
-To install SecureNow, follow these steps:
-
-1. Request your API key from [SecureNow](http://securenow.ai/).
-2. Install the package using npm:
-```
-npm i --save securenow
-```
-
-set the api key in your environement variable : 
-```bash
-export securenow=<API-KEY>
-```
-
-if you have a dedicated securenow instance : 
-
-```bash
-export securenow_instance='http://<dedicated_instance>:4318'
-```
+# SecureNow
+
+OpenTelemetry instrumentation for Node.js and Next.js applications - send traces to SigNoz or any OTLP-compatible backend.
+
+**Official npm package:** [securenow](http://securenow.ai/)
+
+---
+
+## 🚀 Quick Start
+
+### For Next.js Applications
+
+**The easiest way to add observability to Next.js!**
+
+```bash
+# Just install - setup is automatic!
+npm install securenow
+```
+
+**🎉 The installer will automatically:**
+- Detect your Next.js project
+- Create `instrumentation.ts` (or `.js`)
+- Create `.env.local` template
+
+**Just answer "Y" when prompted!**
+
+Then configure your `.env.local`:
+
+```bash
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=http://your-signoz-server:4318
+```
+
+**Alternative:** Use the CLI command
+```bash
+npx securenow init
+```
+
+**Done!** 🎉 See [Next.js Complete Guide](./NEXTJS-GUIDE.md) for details.
+
+---
+
+### For Node.js Applications (Express, Fastify, NestJS, etc.)
+
+```bash
+# 1. Install
+npm install securenow
+
+# 2. Set environment variables
+export SECURENOW_APPID=my-app
+export SECURENOW_INSTANCE=http://your-signoz-server:4318
+
+# 3. Run with preload
+NODE_OPTIONS="-r securenow/register" node app.js
+# or
+NODE_OPTIONS="-r securenow/register" npm start
+```
+
+---
+
+## 📦 Installation
+
+```bash
+npm install securenow
+# or
+yarn add securenow
+# or
+pnpm add securenow
+```
+
+---
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+```bash
+# Required: Your application identifier
+SECURENOW_APPID=my-app-name
+
+# Optional: Your SigNoz/OTLP collector endpoint
+# Default: http://46.62.173.237:4318
+SECURENOW_INSTANCE=http://your-signoz-server:4318
+
+# Optional: Additional configuration
+SECURENOW_NO_UUID=1                         # Don't append UUID to service name
+OTEL_LOG_LEVEL=info                         # debug|info|warn|error
+SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns   # Disable specific instrumentations
+OTEL_EXPORTER_OTLP_HEADERS="x-api-key=..."  # Authentication headers
+```
+
+### Legacy Environment Variables (still supported)
+
+```bash
+export securenow=<API-KEY>
+export securenow_instance='http://<dedicated_instance>:4318'
+```
+
+---
+
+## 🎯 Supported Frameworks & Libraries
+
+SecureNow automatically instruments:
+
+### Web Frameworks
+- ✅ Next.js (App Router & Pages Router)
+- ✅ Express.js
+- ✅ Fastify
+- ✅ NestJS
+- ✅ Koa
+- ✅ Hapi
+
+### Databases
+- ✅ PostgreSQL
+- ✅ MySQL / MySQL2
+- ✅ MongoDB
+- ✅ Redis
+
+### Other
+- ✅ HTTP/HTTPS requests
+- ✅ GraphQL
+- ✅ gRPC
+- ✅ And many more via OpenTelemetry auto-instrumentation
+
+---
+
+## 📚 Documentation
+
+- **[Next.js Quick Start](./NEXTJS-QUICKSTART.md)** - Get started in 30 seconds
+- **[Next.js Complete Guide](./NEXTJS-GUIDE.md)** - Full Next.js integration guide
+- **[Examples](./examples/)** - Code examples for different setups
+
+---
+
+## 🆘 Support
+
+- **Website:** [securenow.ai](http://securenow.ai/)
+- **Issues:** Report bugs and request features
+- **Documentation:** Full documentation and guides
+
+---
+
+## 📄 License
+
+ISC