references/nextjs.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
Next.js Logs installation
Canonical URL: https://posthog.com/docs/logs/installation/nextjs
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Install OpenTelemetry packages
- Get your project token
- Enable instrumentation in Next.js
- Create the instrumentation file
- Use OpenTelemetry logging
- Test your setup
- Next steps
-
1
Install OpenTelemetry packages
Required
npm install @opentelemetry/sdk-logs @opentelemetry/exporter-logs-otlp-http @opentelemetry/api-logs @opentelemetry/resources -
2
Get your project token
Required
You'll need your PostHog project token to authenticate log requests. This is the same key you use for capturing events and exceptions with the PostHog SDK.
Important: Use your project token which starts with
phc_. Do not use a personal API key (which starts withphx_).You can find your project token in Project Settings.
-
3
Enable instrumentation in Next.js
Required
Note: This step is only needed on Next.js 13.2–14.x. For Next.js 15 and later,
instrumentation.tsis enabled by default and theexperimental.instrumentationHookoption is deprecated — remove it from your config if it's set.On Next.js 14 and earlier, add the following to your
next.config.js(ornext.config.mjs) to enable the instrumentation hook:/** @type {import('next').NextConfig} */ const nextConfig = { experimental: { instrumentationHook: true, }, } module.exports = nextConfig -
4
Create the instrumentation file
Required
Create an
instrumentation.ts(orinstrumentation.js) file in the root of your project (or insidesrc/if you use that folder).import { BatchLogRecordProcessor, LoggerProvider } from '@opentelemetry/sdk-logs' import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http' import { logs } from '@opentelemetry/api-logs' import { resourceFromAttributes } from '@opentelemetry/resources' // Create LoggerProvider outside register() so it can be exported and flushed in route handlers export const loggerProvider = new LoggerProvider({ resource: resourceFromAttributes({ 'service.name': 'my-nextjs-app' }), processors: [ new BatchLogRecordProcessor({ exporter: new OTLPLogExporter({ url: 'https://us.i.posthog.com/i/v1/logs', headers: { Authorization: 'Bearer <ph_project_token>', 'Content-Type': 'application/json', }, }), }), ], }) export function register() { if (process.env.NEXT_RUNTIME === 'nodejs') { logs.setGlobalLoggerProvider(loggerProvider) } }Note: The
loggerProvideris created outside ofregister()so it can be exported and used to flush logs in route handlers. This pattern is necessary because Route Handlers complete execution before batched logs have a chance to be sent to the collector. By exporting the provider, we can manually flush logs at the end of each request.Important: The
Content-Type: application/jsonheader is required.Alternatively, you can pass the API key as a query parameter:
new OTLPLogExporter({ url: 'https://us.i.posthog.com/i/v1/logs?token=<ph_project_token>', headers: { 'Content-Type': 'application/json', }, }) -
5
Use OpenTelemetry logging
Required
Now you can use OpenTelemetry logging in your server-side code (API routes, Server Components, etc.):
import { SeverityNumber } from '@opentelemetry/api-logs' import { after } from 'next/server' import { loggerProvider } from '@/instrumentation' const logger = loggerProvider.getLogger('my-nextjs-app') export async function GET() { logger.emit({ body: 'API request received', severityNumber: SeverityNumber.INFO, attributes: { endpoint: '/api/example', method: 'GET', }, }) // Ensure logs are flushed before the serverless function freezes after(async () => { await loggerProvider.forceFlush() }) return Response.json({ success: true }) }Important: Without calling
forceFlush(), your logs may not be sent. Route Handlers complete execution before the OpenTelemetry batch processor has a chance to send logs to the collector. Theafter()function fromnext/serverruns code after the response is sent, ensuring logs are flushed before the serverless function freezes.Note:
after()is stable in Next.js 15.1+ (available asunstable_afterin 15.0). On Next.js 14 and earlier, it doesn't exist — flush before returning instead:await loggerProvider.forceFlush() return Response.json({ success: true }) -
6
Test your setup
Recommended
Once everything is configured, test that logs are flowing into PostHog:
- Send a test log from your application
- Check the PostHog Logs interface for your log entries
- Verify the logs appear in your project
-
Next steps
Checkpoint
What you can do with your logs
| Action | Description | | --- | --- | | Why you need logs | What logs show you that nothing else does | | Search logs | Use the search interface to find specific log entries | | Filter by level | Filter by
INFO,WARN,ERROR, etc. | | Link session replay | Connect logs to users and session replays by passingposthogDistinctIdandsessionId| | Link logs to a person | Surface every log emitted on behalf of a user on their PostHog person profile | | Logging best practices | Learn what to log, how to structure logs, and patterns that make logs useful in production |