securenow 3.0.14 → 4.0.1

package/AUTO-SETUP.md

@@ -0,0 +1,414 @@
+# SecureNow Auto-Setup Guide
+
+SecureNow can automatically create the instrumentation file for your Next.js project! Choose the method that works best for you.
+
+---
+
+## 🎯 Three Ways to Setup
+
+### 1. ✨ Automatic Setup (Recommended)
+
+**Happens automatically when you install:**
+
+```bash
+npm install securenow
+```
+
+**What happens:**
+1. Installer detects Next.js project
+2. Asks: "Would you like to automatically create instrumentation file? (Y/n)"
+3. Creates `instrumentation.ts` (or `.js`) in the right location
+4. Creates `.env.local` template
+5. Shows next steps
+
+**Example output:**
+```
+┌─────────────────────────────────────────────────┐
+│  🎉 SecureNow installed successfully!          │
+│  Next.js project detected                       │
+└─────────────────────────────────────────────────┘
+
+Would you like to automatically create instrumentation file? (Y/n) Y
+
+✅ Created instrumentation.ts
+✅ Created .env.local template
+
+┌─────────────────────────────────────────────────┐
+│  🚀 Next Steps:                                 │
+│                                                 │
+│  1. Edit .env.local and set:                   │
+│     SECURENOW_APPID=your-app-name              │
+│     SECURENOW_INSTANCE=http://signoz:4318      │
+│                                                 │
+│  2. Run your app: npm run dev                  │
+│                                                 │
+│  3. Check SigNoz for traces!                   │
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+### 2. 🛠️ CLI Command (Manual but Easy)
+
+**If you skipped auto-setup or want to setup later:**
+
+```bash
+npx securenow init
+```
+
+**Options:**
+
+```bash
+# Force TypeScript
+npx securenow init --typescript
+
+# Force JavaScript
+npx securenow init --javascript
+
+# Create in src/ folder
+npx securenow init --src
+
+# Create in root folder
+npx securenow init --root
+
+# Overwrite existing files
+npx securenow init --force
+
+# Combine options
+npx securenow init --typescript --src
+```
+
+**Example:**
+```bash
+$ npx securenow init
+
+🚀 SecureNow Setup
+
+✅ Created instrumentation.ts
+✅ Created .env.local template
+
+┌─────────────────────────────────────────────────┐
+│  🎉 Setup Complete!                             │
+│                                                 │
+│  Next steps:                                    │
+│  1. Edit .env.local and configure               │
+│  2. Start your app: npm run dev                 │
+│  3. Check SigNoz dashboard for traces!          │
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+### 3. 📝 Manual Creation
+
+**Create the file yourself:**
+
+```typescript
+// instrumentation.ts (at project root)
+import { registerSecureNow } from 'securenow/nextjs';
+
+export function register() {
+  registerSecureNow();
+}
+```
+
+```bash
+# .env.local
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=http://your-signoz:4318
+```
+
+---
+
+## 🤖 Auto-Setup Behavior
+
+### Detection Logic
+
+The postinstall script checks:
+
+1. **Is this a Next.js project?**
+   - Looks for `next` in package.json dependencies
+   
+2. **Does instrumentation file already exist?**
+   - Checks for: `instrumentation.ts`, `instrumentation.js`
+   - Checks in: root and `src/` folder
+   
+3. **Is this an interactive environment?**
+   - Skips in CI/CD environments
+   - Skips if stdin is not a TTY
+
+### Smart Defaults
+
+- **TypeScript vs JavaScript**
+  - Detects `tsconfig.json` → creates `.ts` file
+  - No tsconfig → creates `.js` file
+
+- **Root vs src/ folder**
+  - If `src/` folder exists → creates file there
+  - Otherwise → creates in root
+
+- **.env.local handling**
+  - Only creates if it doesn't exist
+  - Never overwrites existing `.env.local`
+
+### Non-Interactive Environments
+
+In CI/CD or non-interactive environments:
+
+```bash
+[securenow] ℹ️  Non-interactive environment detected
+[securenow] 💡 To complete setup, run: npx securenow init
+```
+
+---
+
+## 🎛️ CLI Reference
+
+### Commands
+
+```bash
+npx securenow init      # Initialize setup
+npx securenow help      # Show help
+npx securenow version   # Show version
+```
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--typescript`, `--ts` | Force TypeScript file |
+| `--javascript`, `--js` | Force JavaScript file |
+| `--src` | Create in src/ folder |
+| `--root` | Create in root folder |
+| `--force`, `-f` | Overwrite existing files |
+
+### Examples
+
+**Basic setup:**
+```bash
+npx securenow init
+```
+
+**TypeScript in src folder:**
+```bash
+npx securenow init --typescript --src
+```
+
+**JavaScript in root:**
+```bash
+npx securenow init --javascript --root
+```
+
+**Force overwrite:**
+```bash
+npx securenow init --force
+```
+
+**Not a Next.js project but want to proceed:**
+```bash
+npx securenow init --force
+```
+
+---
+
+## 🔧 Configuration
+
+### Disable Auto-Setup
+
+If you never want auto-setup to run:
+
+**Option 1: Environment variable**
+```bash
+SECURENOW_NO_POSTINSTALL=1 npm install securenow
+```
+
+**Option 2: npm config**
+```bash
+npm install securenow --ignore-scripts
+```
+
+**Option 3: Answer "n" when prompted**
+```
+Would you like to automatically create instrumentation file? (Y/n) n
+
+[securenow] No problem! To setup later, run: npx securenow init
+```
+
+---
+
+## 📂 File Locations
+
+The installer chooses locations automatically:
+
+### TypeScript Projects
+
+```
+my-nextjs-app/
+├── instrumentation.ts     ← Created here (no src/)
+└── .env.local            ← Created here
+```
+
+or with src/ folder:
+
+```
+my-nextjs-app/
+├── src/
+│   └── instrumentation.ts  ← Created here (with src/)
+└── .env.local             ← Created here
+```
+
+### JavaScript Projects
+
+```
+my-nextjs-app/
+├── instrumentation.js     ← Created here
+└── .env.local            ← Created here
+```
+
+---
+
+## 🚨 Troubleshooting
+
+### Auto-setup didn't run
+
+**Possible reasons:**
+
+1. **Not a Next.js project**
+   - Install `next` first, then install `securenow`
+   - Or use: `npx securenow init --force`
+
+2. **CI/CD environment**
+   - Run manually: `npx securenow init`
+
+3. **File already exists**
+   - Auto-setup skips if file exists
+   - Use: `npx securenow init --force` to overwrite
+
+4. **Installation with --ignore-scripts**
+   - Run: `npx securenow init`
+
+### CLI command not found
+
+```bash
+# Make sure securenow is installed
+npm list securenow
+
+# Run with npx
+npx securenow init
+```
+
+### Permission errors
+
+```bash
+# On Unix systems, the CLI should be executable
+chmod +x node_modules/securenow/cli.js
+
+# Or use npx
+npx securenow init
+```
+
+---
+
+## 🎯 Comparison
+
+| Method | Speed | Flexibility | Best For |
+|--------|-------|-------------|----------|
+| **Auto-setup** | ⚡ Instant | Basic | First-time users |
+| **CLI** | 🚀 Fast | High | Custom setups |
+| **Manual** | 📝 Slow | Full | Advanced users |
+
+---
+
+## 💡 Best Practices
+
+### For Development
+
+1. **Let auto-setup run**
+   - Fastest way to get started
+   - Creates everything you need
+
+2. **Review generated files**
+   - Check `instrumentation.ts`
+   - Verify `.env.local` settings
+
+3. **Use CLI for adjustments**
+   - `npx securenow init --force` to regenerate
+
+### For Teams
+
+1. **Add to documentation**
+   ```md
+   ## Setup Observability
+   npm install securenow
+   # Answer "Y" when prompted
+   ```
+
+2. **Share .env.local template**
+   - Commit `.env.local.example`
+   - Team copies to `.env.local`
+
+3. **CI/CD setup**
+   ```bash
+   # In CI, skip auto-setup
+   npm install --ignore-scripts
+   
+   # Or set env var
+   SECURENOW_NO_POSTINSTALL=1 npm install
+   ```
+
+### For Monorepos
+
+```bash
+# In each Next.js app
+cd apps/web
+npx securenow init
+
+cd apps/admin
+npx securenow init
+```
+
+---
+
+## 🆘 Need Help?
+
+```bash
+# Get help
+npx securenow help
+
+# Check version
+npx securenow version
+
+# Re-run setup
+npx securenow init --force
+```
+
+**Documentation:**
+- [Quick Start](./NEXTJS-QUICKSTART.md)
+- [Complete Guide](./NEXTJS-GUIDE.md)
+- [Customer Guide](./CUSTOMER-GUIDE.md)
+
+---
+
+## ✨ Summary
+
+**Simplest way:**
+```bash
+npm install securenow
+# Press Y when asked
+```
+
+**If you need control:**
+```bash
+npm install securenow
+npx securenow init --typescript --src
+```
+
+**For CI/CD:**
+```bash
+npm install --ignore-scripts
+npx securenow init
+```
+
+**That's it!** 🎉
+
+

package/CUSTOMER-GUIDE.md

@@ -0,0 +1,326 @@
+# 🚀 Add Observability to Your Next.js App in 2 Minutes
+
+**Send traces to SigNoz with just 1-2 steps. No webpack warnings!**
+
+---
+
+## Step 1: Install SecureNow
+
+```bash
+npm install securenow
+```
+
+**🎉 That's it!** The installer will automatically:
+- Detect your Next.js project
+- Offer to create `instrumentation.ts` (or `.js`)
+- Create `.env.local` template
+- **No webpack bundling warnings** (uses @vercel/otel)
+
+Just answer **"Y"** when prompted!
+
+---
+
+## Step 2: Configure Environment Variables
+
+The installer created `.env.local` for you. Just edit it:
+
+```typescript
+import { registerSecureNow } from 'securenow/nextjs';
+
+export function register() {
+  registerSecureNow();
+}
+```
+
+**Using JavaScript?** Create `instrumentation.js` instead:
+
+```javascript
+const { registerSecureNow } = require('securenow/nextjs');
+
+export function register() {
+  registerSecureNow();
+}
+```
+
+---
+
+## Step 3: Add Environment Variables
+
+Create or update `.env.local`:
+
+```bash
+# Just update these two values:
+SECURENOW_APPID=my-nextjs-app              # Your app name
+SECURENOW_INSTANCE=http://your-signoz:4318 # Your SigNoz URL
+```
+
+---
+
+## That's It! 🎉
+
+---
+
+## 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 project root:
+
+```typescript
+import { registerSecureNow } from 'securenow/nextjs';
+export function register() { registerSecureNow(); }
+```
+
+Then create `.env.local`:
+
+```bash
+SECURENOW_APPID=my-nextjs-app
+SECURENOW_INSTANCE=http://your-signoz:4318
+```
+
+---
+
+## Run Your App
+
+Run your app:
+
+```bash
+npm run dev
+```
+
+You should see:
+
+```
+[securenow] Next.js integration loading
+[securenow] 🚀 Next.js App → service.name=my-nextjs-app
+[securenow] ✅ OpenTelemetry started for Next.js
+```
+
+Open your **SigNoz dashboard** and you'll see traces immediately!
+
+---
+
+## 📊 What You Get Automatically
+
+### ✅ Next.js Built-in Spans
+- HTTP requests
+- API routes
+- Page rendering
+- Server-side props
+- Metadata generation
+- Time to First Byte (TTFB)
+
+### ✅ Backend Instrumentation
+- **Databases:** PostgreSQL, MySQL, MongoDB, Redis
+- **HTTP Calls:** fetch, axios, http/https
+- **GraphQL** queries
+- **gRPC** calls
+- **And 30+ more libraries**
+
+No additional code needed!
+
+---
+
+## ⚙️ Optional: Add Authentication
+
+If your SigNoz server requires an API key:
+
+```bash
+# Add to .env.local
+OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key-here"
+```
+
+---
+
+## 🔧 Optional: Advanced Configuration
+
+Want more control? You can pass options:
+
+```typescript
+import { registerSecureNow } from 'securenow/nextjs';
+
+export function register() {
+  registerSecureNow({
+    serviceName: 'my-app',
+    endpoint: 'http://signoz:4318',
+    headers: {
+      'x-api-key': process.env.SIGNOZ_API_KEY || '',
+    },
+    disableInstrumentations: ['fs'],  // Optional: disable specific instrumentations
+  });
+}
+```
+
+---
+
+## 🚨 Troubleshooting
+
+### Not seeing traces?
+
+**1. Check the console output**
+```bash
+npm run dev
+# Look for: [securenow] ✅ OpenTelemetry started
+```
+
+**2. Enable debug mode**
+```bash
+# Add to .env.local
+OTEL_LOG_LEVEL=debug
+```
+
+**3. Create a test span**
+```bash
+# Add to .env.local
+SECURENOW_TEST_SPAN=1
+```
+
+**4. Verify SigNoz is accessible**
+```bash
+curl http://your-signoz-server:4318/v1/traces
+```
+
+---
+
+## 🎯 Next.js Version Requirements
+
+| Next.js Version | Setup Required |
+|----------------|----------------|
+| **Next.js 15+** | ✅ Just create `instrumentation.ts` |
+| **Next.js 14 and below** | ⚠️ Also add to `next.config.js`: |
+
+For Next.js 14 and below, update `next.config.js`:
+
+```javascript
+const nextConfig = {
+  experimental: {
+    instrumentationHook: true,  // Required for Next.js 14 and below
+  },
+};
+
+module.exports = nextConfig;
+```
+
+---
+
+## ☁️ Deployment
+
+### Vercel
+
+1. Go to your Vercel project settings
+2. Add environment variables:
+   - `SECURENOW_APPID=my-nextjs-app`
+   - `SECURENOW_INSTANCE=http://your-signoz:4318`
+3. Redeploy
+
+**Done!** Traces will appear in SigNoz.
+
+### 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
+
+```bash
+export SECURENOW_APPID=my-nextjs-app
+export SECURENOW_INSTANCE=http://your-signoz:4318
+npm start
+```
+
+---
+
+## 🎓 Environment Variables Reference
+
+```bash
+# ===== REQUIRED =====
+SECURENOW_APPID=my-app-name           # Your app identifier
+SECURENOW_INSTANCE=http://host:4318   # SigNoz endpoint
+
+# ===== OPTIONAL =====
+OTEL_EXPORTER_OTLP_HEADERS="key=val"  # API keys/headers
+SECURENOW_NO_UUID=1                   # Don't append UUID
+OTEL_LOG_LEVEL=info                   # debug|info|warn|error
+SECURENOW_DISABLE_INSTRUMENTATIONS=fs # Comma-separated
+SECURENOW_TEST_SPAN=1                 # Test span on startup
+```
+
+---
+
+## 💡 Best Practices
+
+### ✅ DO
+- Use descriptive app names: `checkout-service`, `user-api`
+- Set `SECURENOW_APPID` in production
+- Keep UUID enabled in production (unique per deployment)
+- Use `OTEL_LOG_LEVEL=info` or `warn` in production
+
+### ❌ DON'T
+- Use generic names: `app`, `test`, `api`
+- Hardcode API keys in code
+- Disable important instrumentations without reason
+- Use `OTEL_LOG_LEVEL=debug` in production (too verbose)
+
+---
+
+## 📚 More Resources
+
+- **[Complete Guide](./NEXTJS-GUIDE.md)** - In-depth documentation
+- **[Quick Start](./NEXTJS-QUICKSTART.md)** - Condensed version
+- **[Examples](./examples/)** - Code examples
+- **[Architecture](./ARCHITECTURE.md)** - How it works
+
+---
+
+## 🆘 Need Help?
+
+- **Documentation:** [Full guides](./NEXTJS-GUIDE.md)
+- **Examples:** See `examples/` folder
+- **SigNoz Docs:** [signoz.io/docs](https://signoz.io/docs/)
+
+---
+
+## ✨ Why SecureNow?
+
+| Feature | SecureNow | Manual Setup | @vercel/otel |
+|---------|-----------|--------------|--------------|
+| Lines of code | 3 | 100+ | 20+ |
+| Setup time | 2 min | 1-2 hours | 30 min |
+| Auto-instrumentation | 30+ libs | Manual | Limited |
+| Configuration | Env vars | Complex | Medium |
+| Production ready | ✅ Yes | Depends | ✅ Yes |
+
+**Choose SecureNow for the easiest setup!**
+
+---
+
+<div align="center">
+
+**Made with ❤️ for Next.js and SigNoz**
+
+[Website](http://securenow.ai/) • [NPM](https://www.npmjs.com/package/securenow) • [Documentation](./NEXTJS-GUIDE.md)
+
+</div>
+