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/link-session-replay.md

AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

Link session replay

Canonical URL: https://posthog.com/docs/logs/link-session-replay

Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use https://eu.posthog.com instead of https://app.posthog.com (app host for links).

On this page

Connecting your backend logs to frontend session replays provides complete visibility into the user journey, helping you understand the full context around issues in your application.

Why link to session replay?

By including session IDs and user identity in your logs, you can:

  • See the full user journey: Navigate from a log entry directly to the session replay to see what the user was doing
  • Debug issues faster: Quickly find and watch the exact session where an error or issue occurred
  • Correlate logs with user actions: Match backend log events with actual user experience
  • View related errors: See Error Tracking issues that occurred during the same session directly in the log details

Prerequisites

Logs captured client-side: When you call posthog.captureLog / posthog.logger.* directly from the JavaScript web SDK or React Native SDK, the current distinct_id and session_id are attached to every log record automatically. You only need the manual setup below when your backend emits the logs.

Implementation

To link logs to session replays, you need to pass the session ID and user identity from your frontend to your backend, then include them as log attributes.

Frontend: Get the session ID

In your frontend code, retrieve the current session ID and send it with your API requests:

JavaScript

import posthog from 'posthog-js'

// Get the current session ID
const sessionId = posthog.get_session_id()

// Send it with your API request
const response = await fetch('/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: userInput,
    sessionId: sessionId  // Include session ID
  })
})

"React

import { posthog } from './posthog'

// Get the current session ID
const sessionId = posthog.get_session_id()

// Send it with your API request
const response = await fetch('https://api.example.com/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: userInput,
    sessionId,  // Include session ID
  }),
})

Backend: Include session ID and user identity in logs

Once you have the session ID, include it along with the user's identity using the sessionId and posthogDistinctId attributes. These examples assume you've already set up a logging client for your language.

JavaScript

import { logs } from '@opentelemetry/api-logs'

const logger = logs.getLogger('my-app')

app.post('/api/chat', async (req, res) => {
  const { message, sessionId } = req.body
  const userId = req.userId // ... get your user ID

  logger.emit({
    severityText: 'info',
    body: 'Chat request received',
    attributes: {
      posthogDistinctId: userId,       // Links to PostHog user
      sessionId: sessionId,            // Links to session replay
      endpoint: '/api/chat',
    },
  })

  // ... handle the request

  res.json({ success: true })
})

Python

import logging

logger = logging.getLogger(__name__)

@app.route('/api/chat', methods=['POST'])
def chat():
    data = request.json
    message = data['message']
    session_id = data.get('sessionId')
    user_id = current_user.id

    logger.info(
        "Chat request received",
        extra={
            "posthogDistinctId": user_id,     # Links to PostHog user
            "sessionId": session_id,           # Links to session replay
            "endpoint": "/api/chat",
        }
    )

    # ... handle the request

    return jsonify({"success": True})

Note: If you don't include posthogDistinctId, logs won't be linked to a user. If you don't include sessionId, logs won't be linked to a session replay. You can use either or both independently.

Viewing linked replays

Once you've set up session linking, you can navigate from logs to their corresponding session replays:

From the logs list:

  1. Hover over a log entry in the logs view
  2. Click the View recording button in the floating action menu to open the session replay at the log timestamp

From log details:

  1. Click on a log entry to open log details
  2. Click the View recording button to open the session replay

The recording button only appears for log entries that have an associated session ID.

View related errors

When you click on a log entry that has a session ID, you can view related errors in the Related errors tab. This tab shows Error Tracking issues that occurred within the same session (within ±6 hours of the log timestamp).

This helps you debug issues by showing errors that happened around the same time as your log entry, giving you a more complete picture of what went wrong.

If no session ID is found in the log entry, the tab displays a message prompting you to link your logs to sessions.

See also