Link session replay

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

• A logging client installed on your backend
• The PostHog JavaScript SDK on your frontend
• Session replay enabled if you want to link to replays (you can still pass posthogDistinctId without session replay to link logs to a user profile)

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:

// In your frontend code
import posthog from 'posthog-js'

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

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

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.

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 })
})

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:

1. In the logs view, click on the log entry you're interested in to open log details
2. In the log details view, click the View recording button to open the session replay
3. Watch the user's interaction in context alongside the backend logs

You can only view recordings for log entries that have an associated session ID.

This linking helps you correlate backend log events with actual frontend user behavior, enabling faster debugging and better understanding of issues as they occur in your application.

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

• Session replay installation
• Logs installation
• Search logs
• Error Tracking