Next.js

This guide walks you through setting up Application Performance Monitoring (APM) on a Next.js application. These instructions can also be found on the Installation page in your Middleware Account. View example code here.

Prerequisites

1 Infra Agent

Infrastructure Agent (Infra Agent). To install the Infra Agent, see our Installation Guide.

Although the Infra Agent is not required for the Next.js APM, we recommend installing it for improved performance.

2 Next.js Version

Next.js version 13.4 or above. Check your Next.js version with the following command:

Shell

Shell

npx next --version

3 OpenTelemetry Version

@opentelemetry/api package version >= v1.3.0 and < v1.5.0:

Shell

Shell

npm i @opentelemetry/api@">=1.3.0 <1.5.0"

Install

Step 1: Install Next.js APM Package

Run the following command in your terminal:

Shell

Shell

npm install @middleware.io/agent-apm-nextjs

Step 2: Modify Config File

Add the following code to your next.config.js file:

NextJS 14.0+

next.config.js

JavaScript

const nextConfig = {
    // ...
    // Your existing config
     experimental: {
         instrumentationHook: true, 
         serverComponentsExternalPackages: ['@middleware.io/agent-apm-nextjs']
     }
    // ...
    // Your existing config
}

View more

NextJS <14.0

next.config.js

JavaScript

const nextConfig = {
    // ...
    // Your existing config
     experimental: {
         instrumentationHook: true
     }
    // ...
    // Your existing config
}
module.exports = nextConfig

Step 3: Container Variables

Applications running in a container require an additional environment variable. If your application is not running in a container, move to Step 4.

Docker

Add the following environment variable to your application:

Shell

Shell

MW_AGENT_SERVICE=<DOCKER_BRIDGE_GATEWAY_ADDRESS>

Kubernetes

Add the following environment variable to your application deployment YAML file:

Shell

Shell

MW_AGENT_SERVICE=mw-service.mw-agent-ns.svc.cluster.local

For Kubernetes clusters, add the following environment variable to your application:

Shell

Shell

kubectl get service --all-namespaces | grep mw-service

Step 4: Create Instrumentation File

instrumentation.ts (or .js)

Create a custom instrumentation.ts (or .js) file in your project root directory or inside the src folder

// @ts-expect-error: The NextJS APM does not currently have full type declarations
import tracker from '@middleware.io/agent-apm-nextjs';
export function register() {
    tracker.track({
        serviceName: "<SERVICE-NAME>",
        accessToken: "<MW_API_KEY>"
    });
}

// @ts-expect-error: The NextJS APM does not currently have full type declarations
import tracker from '@middleware.io/agent-apm-nextjs';
export function register() {
    tracker.track({
        serviceName: "<SERVICE-NAME>",
        accessToken: "<MW_API_KEY>",
        target: "https://<MW_UID>.middleware.io:443"
    });
}

pagesExtension

Synchronize your instrumentation filename if you are using the pagesExtension config option to add suffixes

Step 5: Enable Logging

Ingest custom logs by using the following functions based on desired log severity levels:

index.js

JavaScript

// @ts-expect-error: The NextJS APM does not currently have full type declarations
import tracker from '@middleware.io/agent-apm-nextjs';
export default async function handler(req, res) {
    // ...
    // Your existing code
    tracker.info("Info Sample");
    tracker.warn("Warn Sample", {
        "tester": "Alex",
    });
    tracker.debug("Debug Sample");

View more

Step 6: Deploy your Project

Continuous Profiling

Continuous profiling captures real-time performance insights from your application to enable rapid identification of resource allocation, bottlenecks, and more. Navigate to the Continuous Profiling section to learn more about using Continuous Profiling with the Next.js APM.