Introduction
Honeycomb est une plateforme d'observabilité moderne qui excelle dans l'analyse de données haute cardinalité. Contrairement aux solutions traditionnelles, elle permet d'explorer rapidement les traces distribuées et d'identifier les goulots d'étranglement sans indexer toutes les métriques à l'avance. En 2026, l'intégration via OpenTelemetry est devenue le standard. Ce tutoriel vous guide pas à pas pour instrumenter une application Node.js, envoyer des traces et créer des dashboards pertinents. Vous apprendrez à configurer le SDK, à gérer les attributs et à analyser les données en conditions réelles.
Prérequis
- Node.js 20+ et TypeScript
- Compte Honeycomb avec clé API
- Connaissances de base en OpenTelemetry
- Application Express ou Next.js existante
Installation des dépendances
npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-httpCes packages installent le SDK OpenTelemetry, les instrumentations automatiques et l'exporter compatible Honeycomb. Évitez les versions incompatibles en utilisant des versions récentes.
Configuration du traceur
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
const exporter = new OTLPTraceExporter({
url: 'https://api.honeycomb.io/v1/traces',
headers: { 'x-honeycomb-team': process.env.HONEYCOMB_API_KEY || '' }
});
const sdk = new NodeSDK({
traceExporter: exporter,
instrumentations: [getNodeAutoInstrumentations()]
});
sdk.start();Ce fichier initialise le SDK et envoie les traces vers Honeycomb. La variable d'environnement HONEYCOMB_API_KEY doit être définie. Ne jamais hardcoder la clé dans le code source.
Instrumentation manuelle d'une route
import { trace } from '@opentelemetry/api';
const tracer = trace.getTracer('my-service');
app.get('/api/users', async (req, res) => {
const span = tracer.startSpan('get-users');
try {
const users = await fetchUsers();
span.setAttribute('user.count', users.length);
res.json(users);
} catch (error) {
span.recordException(error);
res.status(500).send('Error');
} finally {
span.end();
}
});L'instrumentation manuelle ajoute des attributs métier comme le nombre d'utilisateurs. Cela enrichit les traces Honeycomb et facilite le filtrage par cardinalité élevée.
Configuration Docker pour production
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
ENV HONEYCOMB_API_KEY=${HONEYCOMB_API_KEY}
ENV OTEL_SERVICE_NAME=my-app
CMD ["node", "--require", "./tracing.js", "dist/index.js"]Ce Dockerfile injecte la clé API et le nom du service au runtime. Utilisez toujours des variables d'environnement pour les secrets en production.
Création d'un dataset Honeycomb
curl -X POST https://api.honeycomb.io/1/datasets \
-H "X-Honeycomb-Team: $HONEYCOMB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "production-traces"}'Cette commande crée un dataset dédié aux traces. Organisez vos environnements (prod, staging) dans des datasets séparés pour une meilleure isolation des données.
Bonnes pratiques
- Toujours utiliser des attributs sémantiques standards OpenTelemetry
- Limiter la cardinalité des attributs à moins de 1000 valeurs distinctes
- Configurer des sampling rates adaptés à votre volume de trafic
- Ajouter des spans pour les appels externes critiques
- Documenter les noms de services et versions dans les attributs
Erreurs courantes à éviter
- Oublier d'appeler span.end() ce qui laisse des traces incomplètes
- Ne pas propager le contexte dans les appels asynchrones
- Exposer la clé API dans le frontend
- Ignorer les erreurs de connexion à l'exporter Honeycomb
Pour aller plus loin
Découvrez nos formations avancées sur l'observabilité moderne et Honeycomb sur Learni Group.