SDK Node.js

🎫 Récupère ton token

Pionne est mobile-first : tu génères ton token depuis l’app mobile Pionne.

1. Télécharge sur App Store (à venir) / Google Play (à venir)
2. Crée ton compte (30 jours gratuits, carte non requise)
3. + Nouveau projet → choisis Node.js → copie le pio_live_…

Le SDK Pionne pour Node.js. Auto-capture les uncaughtException et unhandledRejection, enrichit chaque event avec le contexte runtime (Node version, OS, hostname, PID, mémoire).

Version actuelle : 0.1.0

Installation

npm install @pionne/node

Quickstart

ESM

index.ts

import { Pionne } from '@pionne/node';

Pionne.init({
  token: 'pio_live_…',
  release: '1.0.0',
  environment: 'production',
});

CommonJS

index.js

const { Pionne } = require('@pionne/node');

Pionne.init({
  token: 'pio_live_…',
  release: '1.0.0',
  environment: 'production',
});

Caution

Après un uncaughtException, le SDK envoie l’event puis appelle process.exit(1). C’est la bonne pratique : ton process est dans un état indéterminé, il faut le redémarrer (via PM2, systemd, ton orchestrateur). Si tu veux désactiver ce comportement, passe exitOnUncaught: false dans init().

Auto-capture

• process.on('uncaughtException') — exceptions sync non capturées
• process.on('unhandledRejection') — promises rejetées sans .catch()

Auto-context

• process.version — version Node
• os.platform(), os.release() — OS et release
• os.hostname() — nom de la machine
• process.pid — PID
• process.memoryUsage() — RSS, heap used, heap total

Auto-breadcrumbs

• console.log / console.warn / console.error
• Requêtes HTTP sortantes via http/https (instrumentation de request)

Note

Pas de breadcrumbs fetch dans le SDK actuel — fetch global n’est dispo qu’à partir de Node 18. Si tu veux les capturer, instrumente manuellement via addBreadcrumb() ou utilise un wrapper.

API

Pionne.init(options);
Pionne.captureException(error, { tags, contexts });
Pionne.captureMessage('Cache miss', { level: 'info' });
Pionne.setUser({ id: 'user_42' });
Pionne.setTags({ region: 'eu-west-1' });
Pionne.setEnabled(false);
Pionne.addBreadcrumb({ category: 'db', message: 'SELECT * FROM users' });

Frameworks

Express

import express from 'express';
import { Pionne } from '@pionne/node';

Pionne.init({ token: 'pio_live_…' });

const app = express();

// ... tes routes ...

// Le middleware d'erreur DOIT être enregistré en dernier
app.use(Pionne.expressErrorHandler());

app.listen(3000);

Fastify

import Fastify from 'fastify';
import { Pionne } from '@pionne/node';

Pionne.init({ token: 'pio_live_…' });

const fastify = Fastify();

fastify.setErrorHandler((error, request, reply) => {
  Pionne.captureException(error, {
    contexts: { request: { url: request.url, method: request.method } },
  });
  reply.status(500).send({ error: 'Internal Server Error' });
});

fastify.listen({ port: 3000 });

NestJS

main.ts

import { NestFactory } from '@nestjs/core';
import { Pionne } from '@pionne/node';
import { AppModule } from './app.module';
import { PionneExceptionFilter } from './pionne.filter';

Pionne.init({ token: 'pio_live_…' });

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalFilters(new PionneExceptionFilter());
  await app.listen(3000);
}
bootstrap();

pionne.filter.ts

import { ExceptionFilter, Catch, ArgumentsHost } from '@nestjs/common';
import { Pionne } from '@pionne/node';

@Catch()
export class PionneExceptionFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    Pionne.captureException(exception as Error);
    throw exception; // re-throw pour que Nest gère la réponse
  }
}

Vanilla

import { Pionne } from '@pionne/node';

Pionne.init({ token: 'pio_live_…' });

async function main() {
  try {
    await doSomething();
  } catch (err) {
    Pionne.captureException(err as Error);
  }
}

main();

Background jobs

Pour BullMQ, Bee-Queue, Agenda, Worker Threads ou tout job runner, wrap chaque handler dans un try/catch :

worker.on('failed', (job, err) => {
  Pionne.captureException(err, {
    tags: { job: job.name },
    contexts: { job: { id: job.id, data: job.data } },
  });
});

Performance monitoring

Caution

Le tracing distribué (spans, transactions, latences DB) arrive en V1.1. Pour l’instant, le SDK Node se concentre sur la capture d’exceptions.

Anti-token-theft

Le hostname (os.hostname()) est auto-pinné côté serveur au premier event. Si ton token fuite et qu’il est utilisé depuis un autre serveur, les events sont rejetés.

Voir aussi

• SDK Web — frontend browser
• API Ingest — protocole HTTP brut
• Source maps — symbolication