SigNoz Web Toolkit – OpenTelemetry Setup (Logs, Traces, Metrics)

A command-line tool to quickly scaffold OpenTelemetry instrumentation for your front-end or Node.js apps and wire it to SigNoz. Supports both self-hosted and cloud deployments.

🚀 Quick Start

npx @signozhq/web-toolkit

• Runs an interactive CLI to select signals, file type, and more
• Generates an instrumentation/ folder with ready-to-use files

✨ Features

• Logs, Traces, Metrics: Choose any combination of signals
• Smart Package Detection: Detects npm/yarn/pnpm/bun and installs required deps
• Idempotent Merges: Detects existing setup, adds only new signals, updates index
• Boilerplate Generation: Creates per-signal instrumentation files
• Zero-Config Deploy Info: Reads SigNoz config from environment variables

🎯 What It Generates

The tool creates an instrumentation/ directory with:

• index.ts or index.js: Imports all selected signals
• logs/instrumentation.ts or .js: Logs setup
• traces/instrumentation.ts or .js: Traces setup
• metrics/instrumentation.ts or .js: Metrics setup

The exact extension depends on your selected file type.

🌐 Configuration via Environment Variables

Set these environment variables (in your .env, CI, or run command):

SIGNOZ_COLLECTION_URL=<your-otlp-endpoint>   # e.g., http://localhost:4317 or https://ingest.us.signoz.cloud:443
SIGNOZ_INGESTION_KEY=<ingestion-key-if-required>  # leave empty for most self-hosted setups

The generated code reads these at runtime to configure exporters.

📖 Usage

1. Run the setup tool:

npx @signozhq/web-toolkit

2. Follow the prompts:

• Select signals (Logs, Traces, Metrics)
• Pick file type (TypeScript/JavaScript)
• Choose package manager if dependencies need installation
• Provide a service name

3. Import in your app (example for TypeScript):

import "./instrumentation/index.ts";

Command-line flags (skip prompts)

• --lang=ts or --lang=js to select file type
• --logs, --traces, --metrics to select signals

Examples:

# TypeScript files and only logs
npx @signozhq/web-toolkit --lang=ts --logs

# JavaScript files with logs and traces
npx @signozhq/web-toolkit --lang=js --logs --traces

# Provide flags with space instead of equals also works
npx @signozhq/web-toolkit --lang ts --metrics

Adding to an existing instrumentation directory

If instrumentation/ already exists, the tool will:

• Detect existing file type (.ts/.js)
• Detect existing signals in instrumentation/{logs,traces,metrics}
• Create files only for newly selected signals
• Update instrumentation/index.(ts|js) to import all signals

🔧 Prompts Overview

• Signals: Which signals to instrument
• Package Manager: Used to install missing dependencies
• Service Name: Your application/service name
• File Type: TypeScript or JavaScript

Deployment details are not prompted; they are read from environment variables.

🚨 Troubleshooting

Permission denied when executing the CLI

If you see a permission error when running the tool:

npm cache clean --force
rm -rf ~/.npm/_npx
npx @signozhq/web-toolkit

Or manually set the executable bit on the built file (for local development):

chmod +x dist/index.js

The build scripts automatically ensure executable permissions after each build.

📦 Package Managers

Automatically detects and uses one of:

• npm
• yarn
• pnpm
• bun

🔢 Versioning and Releases (Changesets)

This project uses Changesets for versioning and publishing.

Common workflows:

# Create a changeset (select version bump type per change)
npm run changeset

# Apply versions to package.json and generate changelogs
npm run version

# Publish to npm (uses versions and changelogs from above)
npm run release

# Optional: preview published files
npm run publish:check

🔍 Common Issues

1. Missing package.json: Ensure you're in a Node.js project directory
2. Permission errors: Ensure the binary is executable or rerun the build
3. Dependency installation fails: Check your package manager configuration

🧹 Cleanup on Cancel

If you cancel during the interactive flow, the tool cleans up any partially created instrumentation/ files.

🤝 Contributing

Contributions are welcome! Please open issues and pull requests.

📄 License

MIT License - see LICENSE for details.

🔗 Links

• OpenTelemetry Documentation
• SigNoz Documentation
• Node.js OpenTelemetry