The @axiomhq/nextjs library is currently in public preview. For more information, see Features states.
-
The two options can collect different event types.
- If you already use Vercel for deployments, the Axiom Vercel app can be easier to integrate into your existing experience.
- The cost of these options can differ widely depending on the volume of data you transfer. The Axiom Vercel app depends on Vercel Log Drains, a feature that’s only available on paid plans. For more information, see the blog post on the changes to Vercel Log Drains.
Prerequisites
- Create an Axiom account.
- Create a dataset in Axiom where you send your data.
- Create an API token in Axiom with permissions to update the dataset you have created.
Use next-axiom library
The next-axiom library is an open-source project and welcomes your contributions. For more information, see the GitHub repository.Install next-axiom
-
In your terminal, go to the root folder of your Next.js app and run the following command:
-
Add the following environment variables to your Next.js app:
NEXT_PUBLIC_AXIOM_DATASETis the name of the Axiom dataset where you want to send data.NEXT_PUBLIC_AXIOM_TOKENis the Axiom API token you have generated.
-
In the
next.config.tsfile, wrap your Next.js configuration inwithAxiom:
Capture traffic requests
To capture traffic requests, create amiddleware.ts file in the root folder of your Next.js app:
Web Vitals
To send Web Vitals to Axiom, add theAxiomWebVitals component from next-axiom to the app/layout.tsx file:
Logs
Send logs to Axiom from different parts of your app. Each log function call takes a message and an optionalfields object.
Route handlers
Wrap your route handlers inwithAxiom to add a logger to your request and log exceptions automatically:
Client components
To send logs from client components, adduseLogger from next-axiom to your component:
Server components
To send logs from server components, addLogger from next-axiom to your component, and call flush before returning:
Log levels
The log level defines the lowest level of logs sent to Axiom. Choose one of the following levels (from lowest to highest):debugis the default setting. It means that you send all logs to Axiom.infowarnerrormeans that you only send the highest-level logs to Axiom.offmeans that you don’t send any logs to Axiom.
Capture errors
To capture routing errors, use the error handling mechanism of Next.js:- Go to the
appfolder. - Create an
error.tsxfile. - Inside your component function, add
useLoggerfrom next-axiom to send the error to Axiom. For example:
Extend logger
To extend the logger, uselog.with to create an intermediate logger. For example:
Use @axiomhq/nextjs library
The @axiomhq/nextjs library is part of the Axiom JavaScript SDK, an open-source project and welcomes your contributions. For more information, see the GitHub repository.Install @axiomhq/nextjs
-
In your terminal, go to the root folder of your Next.js app and run the following command:
-
Create the folder
lib/axiomto store configurations for Axiom. -
Create a
axiom.tsfile in thelib/axiomfolder with the following content:lib/axiom/axiom.ts -
In the
lib/axiomfolder, create aserver.tsfile with the following content:Thelib/axiom/server.tscreateAxiomRouteHandleris a builder function that returns a wrapper for your route handlers. The wrapper handles successful responses and errors thrown within the route handler. For more information on the logger, see the @axiomhq/logging library. -
In the
lib/axiomfolder, create aclient.tsfile with the following content:lib/axiom/client.ts
Capture traffic requests
To capture traffic requests, create amiddleware.ts file in the root folder of your Next.js app with the following content:
middleware.ts
Web Vitals
To capture Web Vitals, add theWebVitals component to the app/layout.tsx file:
/app/layout.tsx
Logs
Send logs to Axiom from different parts of your app. Each log function call takes a message and an optionalfields object.
Route handlers
You can use thewithAxiom function exported from the setup file in lib/axiom/server.ts to wrap your route handlers.
Client components
To send logs from client components, adduseLogger to your component:
Server components
To send logs from server components, use the following:Capture errors
Capture errors on Next 15 or later
To capture errors on Next 15 or later, use theonRequestError option. Create an instrumentation.ts file in the src or root folder of your Next.js app (depending on your configuration) with the following content:
instrumentation.ts
onRequestError function:
Capture errors on Next 14 or earlier
To capture routing errors on Next 14 or earlier, use the error handling mechanism of Next.js:-
Create an
error.tsxfile in theappfolder. -
Inside your component function, add
useLoggerto send the error to Axiom. For example:
Advanced customizations
This section describes some advanced customizations.Proxy for client-side usage
Instead of sending logs directly to Axiom, you can send them to a proxy endpoint in your Next.js app. This is useful if you don’t want to expose the Axiom API token to the client or if you want to send the logs from the client to transports on your server.-
Create a
client.tsfile in thelib/axiomfolder with the following content:lib/axiom/client.ts -
In the
/app/api/axiomfolder, create aroute.tsfile with the following content. This example uses/api/axiomas the Axiom proxy path./app/api/axiom/route.ts
Customize data reports sent to Axiom
To customize the reports sent to Axiom, use theonError and onSuccess functions that the createAxiomRouteHandler function accepts in the configuration object.
In the lib/axiom/server.ts file, use the transformRouteHandlerErrorResult and transformRouteHandlerSuccessResult functions to customize the data sent to Axiom by adding fields to the report object:
transformSuccessResult() or transformErrorResult() functions:
Change the log level from Next.js built-in function errors
By default, Axiom uses the following log levels:- Errors thrown by the
redirect()function are logged asinfo. - Errors thrown by the
forbidden(),notFound()andunauthorized()functions are logged aswarn.
logLevelByStatusCode() function when logging errors from your route handler:
transformErrorResult() function using a getNextErrorStatusCode() function. To compose these functions yourself, create your own getNextErrorStatusCode() function and inject the result into the transformErrorResult() report.
Server execution context
TheserverContextFieldsFormatter function adds the server execution context to the logs, this is useful to have information about the scope where the logs were generated.
By default, the createAxiomRouteHandler function adds a request_id field to the logs using this server context and the server context fields formatter.
Route handlers server context
ThecreateAxiomRouteHandler accepts a store field in the configuration object. The store can be a map, an object, or a function that accepts a request and context. It returns a map or an object.
The fields in the store are added to the fields object of the log report. For example, you can use this to add a trace_id field to every log report within the same function execution in the route handler.
Sever context on arbitrary functions
You can also add the server context to any function that runs in the server. For example, server actions, middleware, and server components.middleware.ts