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.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Why link to session replay?
- Prerequisites
- Implementation
- Viewing linked replays
- View related errors
- See also
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 web frontend, or the React Native SDK in your mobile app
- Session replay enabled if you want to link to replays (you can still pass
posthogDistinctIdwithout session replay to link logs to a user profile)
Logs captured client-side: When you call
posthog.captureLog/posthog.logger.*directly from the JavaScript web SDK or React Native SDK, the currentdistinct_idandsession_idare 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 includesessionId, 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:
- Hover over a log entry in the logs view
- Click the View recording button in the floating action menu to open the session replay at the log timestamp
From log details:
- Click on a log entry to open log details
- 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
- Link logs to a person: same
posthogDistinctIdattribute, surfaced on the person profile's Logs tab. - Session replay installation
- Logs installation
- Search logs
- Error Tracking