# Node.js

> Auto-instrument any Node.js app with one command. Sends traces, metrics, and logs to Rocketgraph.

## One command setup

```bash
export ROCKETGRAPH_API_KEY=rg_live_xxxxxx
npx @rgraph/otel-node init
```

That's it. The AI agent reads your code, writes the instrumentation, adds env vars, and installs packages.

Get your API key at [rocketgraph.app/settings](https://rocketgraph.app/settings).

### What it does

1. Reads `package.json` and your entry files
2. Writes `instrumentation.ts` (or `.js`) in the project root
3. Appends `ROCKETGRAPH_API_KEY` and `OTEL_SERVICE_NAME` to `.env.local`
4. Installs only the OTel packages your project needs
5. Configures traces, metrics, and logs → Rocketgraph
6. Bridges `console.log/warn/error` to OTel logs

### Supported

**Frameworks:** Express, Fastify, Next.js, NestJS, Koa, Hapi, Restify

**Libraries:** PostgreSQL, MySQL, MongoDB, Redis, Prisma, TypeORM, Knex, GraphQL, gRPC, AWS SDK, Pino, Winston, Bunyan

### After running

- **Next.js:** Auto-loaded. Just restart your dev server.
- **Everything else:** Import as the first line of your entry file:
  ```typescript
  import './instrumentation'
  ```

### Optional: add error handlers

```bash
npx @rgraph/otel-node instrument
```

Reads your app code and adds error-handling middleware. Separate step — `init` never modifies application code.

### Offline mode (no AI)

```bash
npx @rgraph/otel-node init --legacy
```

Template-based setup. No API key required.

## Commands

| Command | Description |
|---------|------------|
| `npx @rgraph/otel-node init` | Create instrumentation + install packages |
| `npx @rgraph/otel-node instrument` | Add error handlers (optional) |
| `npx @rgraph/otel-node init --legacy` | Template mode, no AI |
| `npx @rgraph/otel-node detect` | Show detected project info |
| `npx @rgraph/otel-node uninstall` | Remove instrumentation file |

## Manual setup

```bash
npm install @opentelemetry/sdk-node @opentelemetry/api \
  @opentelemetry/resources @opentelemetry/semantic-conventions \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http \
  @opentelemetry/exporter-metrics-otlp-http \
  @opentelemetry/exporter-logs-otlp-http \
  @opentelemetry/sdk-metrics @opentelemetry/sdk-logs
```

```bash
export ROCKETGRAPH_API_KEY="rg_live_xxxxxx"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingress.rocketlog.io"
export OTEL_SERVICE_NAME="my-service"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
node app.js
```