Traces	Metrics	App Logs	Custom Logs	Profiling
✅	✖️	✖️	✅	✅

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

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.

Next.js Version

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

Shell

npx next --version

OpenTelemetry Version

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

Shell

npm install @opentelemetry/api”>=1.3.0 <1.5.0”

Install

Step 1: Install `Next.js` APM Package

Run the following command in your terminal:

Shell

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

Step 2: Modify Config File

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

Next.js

const nextConfig = {
    experimental: {
        instrumentationHook: true,
        serverComponentsExternalPackages: ['@middleware.io/agent-apm-nextjs']
    }
}
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

MW_AGENT_SERVICE=<DOCKER_BRIDGE_GATEWAY_ADDRESS>

The DOCKER_BRIDGE_GATEWAY_ADDRESS is the IP address of the gateway between the Docker host and bridge network. This is 172.17.0.1 by default. Learn more about Docker bridge networking here

Kubernetes

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

Shell

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

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

Shell

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

Step 4: Create Instrumentation File

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

The instrumentation.ts file must be located at the root of your project unless you are using the src directory. If you are using the src directory, ensure the instrumentation.ts file is placed within the src directory, alongside the pages and app directories.

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

Example: If you use pagesExtension: ['ts'], the instrumentation file should be named instrumentation.ts.

Add the below code snippet depending on your current setup:

Infra Agent Installed
Infra Agent NOT Installed

Next.js

    // @ts-ignore
    import tracker from '@middleware.io/agent-apm-nextjs';
    export function register() {
        tracker.track({
            serviceName: "<SERVICE-NAME>",
            accessToken: "<xxxxxxxxxx>"
        });
    }

Next.js

    // @ts-ignore
    import tracker from '@middleware.io/agent-apm-nextjs';
    export function register() {
        tracker.track({
            serviceName: "<SERVICE-NAME>",
            accessToken: "<ACCESS-TOKEN>",
            target: "https://{ACCOUNT-UID}.middleware.io"
        });
    }

Step 5: Enable Logging

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

Next.js

// @ts-ignore
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");
    tracker.error("Error Sample");
    // ...
    // Your existing code
}

Step 6: Deploy your Project

If you’re looking to set up a sample Next.js project with API routes, you can use the following command in your terminal: npx create-next-app@latest --example api-routes

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.

Need assistance or want to learn more about Middleware? Contact us at support[at]middleware.io.

​Prerequisites

​Install

​Step 1: Install Next.js APM Package

​Step 2: Modify Config File

​Step 3: Container Variables

​Docker

​Kubernetes

​Step 4: Create Instrumentation File

​Step 5: Enable Logging

​Step 6: Deploy your Project

​Continuous Profiling

Prerequisites

Install

Step 1: Install `Next.js` APM Package

Step 2: Modify Config File

Step 3: Container Variables

Docker

Kubernetes

Step 4: Create Instrumentation File

Step 5: Enable Logging

Step 6: Deploy your Project

Continuous Profiling