Getting Started

agent-apm-nextjs

Description: Agent APM for Next.js

Prerequisites

Make sure you have installed the latest version of Next.js or a version greater than 13.4+, as Vercel introduced their experimental feature in that release.

Before proceeding with the Next.js APM setup, make sure you have the @opentelemetry/api package installed. If it's not already installed, run the following command:

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

Guides

You can use this APM to track your project, either deployed on Vercel platform or hosted on own server. Run follow steps:

Step 1: Install Next.js APM package

Run the command below in your terminal to install Middleware’s Next.js APM package:

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

Step 2: Modify the next.config.js file

As this feature is experimental, you need to explicitly opt-in by providing below thing into your next.config.js file.

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

Step 3: Create an Instrumentation file

Create a custom instrumentation.ts file in your project root directory, and add following code as per your choice:

• If you are using Vercel platform to deploy your projects, then use the code snippet below for serverless functions:

// @ts-ignore
import tracker from '@middleware.io/agent-apm-nextjs';

export function register() {
    tracker.track({
        projectName: "<PROJECT-NAME>",
        serviceName: "<SERVICE-NAME>",
        accessToken: "<ACCESS-TOKEN>",
        target: "vercel",
    });
}

Note: You can find your <ACCOUNT-KEY> on the Installation screen for NextJs / Vercel.

Note: After Deploying your project on Vercel, you need to integrate the Middleware from the marketplace. You can find more details here. To get a better idea, you can clone the sample project from the GitHub repository.

• If you are using Middleware's Host-agent on your machine then use below code snippet:

// @ts-ignore
import tracker from '@middleware.io/agent-apm-nextjs';

export function register() {
    tracker.track({
        projectName: "<PROJECT-NAME>",
        serviceName: "<SERVICE-NAME>",
        accessToken: "<ACCESS-TOKEN>",
    });
}

• If you want to instrument your project without installing any host then use below code snippet:

// @ts-ignore
import tracker from '@middleware.io/agent-apm-nextjs';

export function register() {
    tracker.track({
        projectName: "<PROJECT-NAME>",
        serviceName: "<SERVICE-NAME>",
        accessToken: "<ACCESS-TOKEN>",
        target: "https://<ACCOUNT-UID>.middleware.io:443"
    });
}

Step 4: Enable Logging

To enable logging in your project, you need to add the following code in your file:

// @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
}

Note: You can find these details in your Middleware's Installation page.

That's it.