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.3.6

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',
});

Attention

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 } },
  });
});

Géographie (opt-in)

Sur un backend Node, l’IP utilisée pour le lookup est celle du serveur, pas du client final. C’est utile pour repérer un crash localisé à une région cloud (ex. eu-west-3 vs us-east-1) sans toucher aux logs d’infra.

Pionne.init({
  token: 'pio_live_…',
  sendGeography: true, // ← opt-in
});

Au boot, un seul appel HTTP vers https://ipapi.co/json/ (timeout 4 s) attache contexts.geo = { city, region, country, country_code } à tous les events suivants. Si le lookup échoue (firewall sortant, rate-limit), le SDK continue silencieusement sans géo.

Tu utilises un cluster auto-scalé ? Pense à mettre la région du pod dans tags directement (tags: { region: process.env.AWS_REGION }) — c’est plus fiable qu’un lookup IP côté SDK.

Performance monitoring

Attention

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 pinning de Bundle ID est mobile uniquement (iOS/Android/RN/Flutter) — il protège contre la décompilation d’un APK/IPA. Sur Node, ton token vit côté serveur (.env, secrets manager, EAS env vars…) et n’est jamais shippé à un client : la menace n’existe pas.

Le champ “Bundle ID” est masqué dans l’app mobile pour les projets Node — le remplir manuellement causerait un 403 sur 100 % des events (le SDK n’envoie pas de app_id). Pour distinguer plusieurs déploiements, utilise les tags :

Pionne.init({
  token: process.env.PIONNE_TOKEN,
  tags: { deployment: process.env.APP_DEPLOYMENT ?? 'prod', region: process.env.AWS_REGION },
});

Plus de détails : Bundle ID Pinning → Backends sans bundle_id.

Voir aussi

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