How to Implement OpenTelemetry in Next.js

OpenTelemetry is an open-source observability framework designed to instrument, generate, collect, and export telemetry data, including traces, metrics, and logs. It is vendor-agnostic, allowing developers to send data to multiple backend services like Last9, Prometheus, Datadog, or Jaeger without vendor lock-in.

For Next.js applications, OpenTelemetry is particularly useful due to the framework’s hybrid rendering approach. Since Next.js supports server-side rendering (SSR), static site generation (SSG), API routes, and Edge functions, tracking performance across these layers can be complex. OpenTelemetry helps by providing:

• End-to-end tracing to understand the flow of requests within the application.
• Performance monitoring to identify slow database queries, API responses, and server-side rendering delays.
• Error detection to quickly debug failing API routes or external service integrations.
• Real-time monitoring using metrics and logs to optimize the application.

Step-by-Step Process to SetUp OpenTelemetry in a Next.js Project

1. Installing the Required Dependencies

To begin using OpenTelemetry, install the necessary packages:

npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http

If you intend to send traces to a specific backend such as Jaeger or Prometheus, install the appropriate exporter package.

2. Configuring OpenTelemetry in a Custom Server

Since Next.js does not provide a default server, you need to create a custom server configuration to integrate OpenTelemetry.

Create a new file named otel.js in the project’s root directory:

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');

const provider = new NodeTracerProvider();
const exporter = new OTLPTraceExporter({ url: 'http://localhost:4317/v1/traces' });

provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
provider.register();

3. Adding Tracing to API Routes in Next.js

To track API routes effectively, you need to wrap your API handlers with OpenTelemetry’s tracing capabilities.

For instance, consider a basic Next.js API route:

import { trace } from '@opentelemetry/api';

export default async function handler(req, res) {
  const tracer = trace.getTracer('nextjs-api');
  const span = tracer.startSpan('api-handler');

  try {
    // Simulating a delay to observe tracing
    await new Promise((resolve) => setTimeout(resolve, 100));
    res.status(200).json({ message: 'Success' });
  } catch (error) {
    span.recordException(error);
    res.status(500).json({ error: 'Internal Server Error' });
  } finally {
    span.end();
  }
}

4. Tracing Database Queries in Next.js Applications

Database interactions can be a major source of latency. OpenTelemetry helps in tracking database query performance.

For example, if using PostgreSQL with pg:

const { Pool } = require('pg');
const { trace } = require('@opentelemetry/api');

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

async function getUser(id) {
  const tracer = trace.getTracer('nextjs-db');
  const span = tracer.startSpan('fetch-user');

  try {
    const result = await pool.query('SELECT * FROM users WHERE id = $1', [id]);
    return result.rows[0];
  } finally {
    span.end();
  }
}

5. Implementing OpenTelemetry with Edge Functions

Since Next.js supports Edge functions for low-latency responses, OpenTelemetry needs a different approach as Edge functions run in restricted environments.

A lightweight OpenTelemetry Web SDK can be used to trace requests in Edge functions:

import { trace } from '@opentelemetry/api';

export default async function handler(req) {
  const tracer = trace.getTracer('nextjs-edge');
  const span = tracer.startSpan('edge-function');

  try {
    const response = new Response(JSON.stringify({ message: 'Edge function traced' }), {
      headers: { 'Content-Type': 'application/json' },
    });
    return response;
  } finally {
    span.end();
  }
}

Instrumentation Techniques in Next.js Applications

Instrumentation is the process of adding observability to your application by collecting traces, metrics, and logs. There are different methods for instrumenting a Next.js application using OpenTelemetry:

1. Automatic Instrumentation

OpenTelemetry provides automatic instrumentation for certain libraries, reducing the need for manual setup. For example, if you are using express or http inside a Next.js custom server, you can enable automatic tracing with:

const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');

registerInstrumentations({
  instrumentations: [new HttpInstrumentation(), new ExpressInstrumentation()],
});

2. Creating Custom Spans

For greater control over what gets traced, you can manually create spans. This is useful for capturing specific operations within your application:

import { trace } from '@opentelemetry/api';

async function fetchData() {
  const tracer = trace.getTracer('nextjs-custom-span');
  const span = tracer.startSpan('fetch-data-operation');

  try {
    await fetch('https://api.example.com/data');
  } catch (error) {
    span.recordException(error);
  } finally {
    span.end();
  }
}

3. Integrating with Popular Libraries

Some libraries, like mongoose for MongoDB and knex for SQL queries, provide OpenTelemetry integrations for automatic tracing. For instance, with knex:

const { KnexInstrumentation } = require('@opentelemetry/instrumentation-knex');
registerInstrumentations({
  instrumentations: [new KnexInstrumentation()],
});

With these techniques, you can ensure that your Next.js application captures meaningful telemetry data while maintaining performance efficiency.

Sending Traces to a Backend for Visualization and Analysis

After setting up tracing, you need a backend system to store and visualize the traces. Some popular options include:

• Last9 – A telemetry data platform platform with rich visualization capabilities.
• Jaeger – An open-source distributed tracing tool.
• Prometheus – Primarily used for monitoring and alerting.

To send traces to Last9, modify your OpenTelemetry configuration:

const exporter = new OTLPTraceExporter({ url: 'https://api.last9.io/v1/traces' });
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

Data Collection and Export

OpenTelemetry provides a flexible way to collect and export telemetry data, including traces, metrics, and logs. This data helps monitor application performance and detect issues in real time.

Collecting Telemetry Data

To collect telemetry data, OpenTelemetry SDKs provide auto-instrumentation for frameworks, as well as manual instrumentation methods. The collected data includes:

• Traces – Capturing request-response cycles across services.
• Metrics – Recording application performance indicators like response time and error rates.
• Logs – Storing event details to debug issues effectively.

Exporting Data to Observability Tools

After collecting telemetry data, it needs to be exported to an observability tool or backend system for analysis. OpenTelemetry supports various exporters:

• OTLP (OpenTelemetry Protocol) Exporter – Sends data to observability platforms like Last9, Jaeger, or Prometheus.
• Console Exporter – Logs data to the console for debugging purposes.
• File Exporter – Saves traces and logs in files for local analysis.

Configuring an Exporter

For instance, to export telemetry data to Last9, configure the OTLP exporter in your OpenTelemetry setup:

const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const exporter = new OTLPTraceExporter({
    url: 'https://api.last9.io/v1/traces'
});
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

If you are using Prometheus, install and configure the Prometheus exporter accordingly:

const { PrometheusExporter } = require('@opentelemetry/exporter-prometheus');
const exporter = new PrometheusExporter({ startServer: true });
provider.addMetricExporter(exporter);

Visualizing Data in Observability Tools

Once the data is exported, you can visualize traces and metrics using dashboards provided by observability platforms like Last9, Jaeger, or Datadog. These tools help in identifying performance bottlenecks and improving application efficiency.

Conclusion

Adding OpenTelemetry to your Next.js application provides valuable performance insights, making debugging and optimization easier.

Start with basic tracing on a single API route, then expand to database interactions, external API calls, and frontend performance tracking.

With OpenTelemetry in place, you’ll have the data you need to improve user experience and ensure your Next.js app runs efficiently.