Description

@exisjs/telemetry is the official observability and tracing package for the Exis JS Framework.

It abstracts away all the complex boilerplate required to configure @opentelemetry/sdk-node, auto-instrumentations-node, and OTLP exporters. When enabled, it dynamically bootstraps itself before your ExisJS server binds, automatically instrumenting incoming HTTP requests, Mongoose queries, and Redis calls.

Installation

npm install @exisjs/telemetry

Quick Start

1. Enable Telemetry in your Config

Simply set telemetry: { enabled: true } in your exis.config.ts. The ExisJS server will automatically detect the package and boot it!

// exis.config.ts
import { defineConfig } from 'exisjs/config'

export default defineConfig({
  telemetry: {
    enabled: true,
    serviceName: 'my-microservice',
    exporter: process.env.NODE_ENV === 'production' ? 'otlp' : 'console',
    endpoint: 'http://localhost:4318/v1/traces' // Default OTLP endpoint
  }
})

2. Auto-Instrumentation

That's it! By default, the package will use getNodeAutoInstrumentations() to capture all incoming API requests and background processes.

If exporter is set to 'console', traces will print directly to your terminal (great for local development!). If set to 'otlp', traces will be sent to your telemetry backend (like Datadog, Jaeger, or Grafana Tempo).

Advanced Usage

You can use the exported tools from this package to manually add metadata or track specific logic within your route handlers:

import { getActiveSpan } from '@exisjs/telemetry'

app.get('/api/users/:id', async (req, res) => {
  // Grab the auto-created span for this HTTP request
  const span = getActiveSpan()
  
  // Attach custom business attributes
  span?.setAttribute('user.id', req.params.id)
  
  // Log a specific timeline event
  span?.addEvent('Processing User Request')

  res.json({ success: true })
})

Documentation

For full documentation and API references, please visit the main Exis JS Repository.