AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

instrument-logs

Add PostHog log capture to track application logs. Use after implementing features or reviewing PRs to ensure meaningful log events are captured with structured properties. Also handles initial OTLP exporter setup if not yet configured.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--instrument-logs at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 19

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.com instead of https://us.i.posthog.com (ingestion host), and use https://eu.posthog.com instead of https://app.posthog.com (app host for links).

On this page

  1. 1

    Install OpenTelemetry packages

    Required

    npm install @opentelemetry/sdk-logs @opentelemetry/exporter-logs-otlp-http @opentelemetry/api-logs @opentelemetry/resources
    
  2. 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 with phx_).

    You can find your project token in Project Settings.

  3. 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.ts is enabled by default and the experimental.instrumentationHook option 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 (or next.config.mjs) to enable the instrumentation hook:

    /** @type {import('next').NextConfig} */
    const nextConfig = {
      experimental: {
        instrumentationHook: true,
      },
    }
    
    module.exports = nextConfig
    
  4. 4

    Create the instrumentation file

    Required

    Create an instrumentation.ts (or instrumentation.js) file in the root of your project (or inside src/ 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 loggerProvider is created outside of register() 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/json header 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. 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. The after() function from next/server runs 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 as unstable_after in 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. 6

    Test your setup

    Recommended

    Once everything is configured, test that logs are flowing into PostHog:

    1. Send a test log from your application
    2. Check the PostHog Logs interface for your log entries
    3. Verify the logs appear in your project

    View your logs in PostHog

  7. 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 passing posthogDistinctId and sessionId | | 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 |

    Troubleshoot common issues