Session Recording

The Chromium Container

Browser co-browsing Sessions are replayed in a real browser. Use our upscope/chromium image:

docker run -d -e TOKEN=mytoken -p 3000:3000 upscope/chromium

Then point your Co-Browsing API instance at it with CHROMIUM_ENDPOINT=ws://yourdockerhost:3000?token=mytoken.

The container is configured through environment variables:

Requesting a Recording

Nothing is rendered until you ask for it. Once a Session has ended, POST its session_id to {BASE_ENDPOINT}/api/recordings/{visitor_short_id}, authenticated with a short-lived HS256 token signed with your SECRET_KEY. The first call starts the render, later calls report progress, and the video URL comes back once it's ready. See Requesting a Session Recording for the full request and its responses.

A Session can't be rendered if no events were stored for it, if it needs a browser and CHROMIUM_ENDPOINT is unset, or if MongoDB is disabled.

You can skip recording an individual Session with the session_properties.record parameter on the watch link and viewer token endpoints.

When a Render Fails

A render that fails reports one of a closed set of error codes, listed with the endpoint under Failed Renders. Most of them name the problem outright. recording_failed is the exception: it's the bucket for a failure we couldn't attribute, and the underlying error is only in your instance's logs.

Logging is off by default. Set DEBUG to upscope:recordings:,upscope:app:errors and restart the server: upscope:app:errors carries the stack trace of the unattributed failure, and upscope:recordings: traces the render's progress, including the stage it was in when it failed. The FFmpeg output goes straight to the server's own stdout, so a failed encode shows up in the container logs whether or not DEBUG is set.

Renders that fail on some Sessions while others on the same instance succeed usually come down to one of:

• Disk. Frames are written to /tmp before FFmpeg consolidates them, and the space a Session needs scales with how long it ran. A container whose writable layer fills up fails the long Sessions and keeps rendering the short ones.
• Memory. The encode runs alongside a headless Chromium. On a memory-capped container, a long Session's encode is the first thing the kernel kills, which surfaces as a failed FFmpeg exit rather than an out-of-memory error.
• The Chromium container. A replay that runs for longer than the container's TIMEOUT has its browser closed underneath it part-way through, and reports browser_crashed. A saturated POOL_MAX is not a failed render: the request waits for a free browser, and if none comes free it is answered with a 503 and retried later, so it costs time rather than the recording.

Session length is the thing to correlate against first: if the failures are all long Sessions, it's disk or memory rather than anything about the Session's content.

Storing Recordings

Recordings can be stored on a local volume (the default), on Amazon S3, on Azure Blob Storage, or on Google Cloud Storage:

Recording file URLs are not guessable (they contain a UUID), matching the access model of our cloud storage.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "UploadRecordings",
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::RECORDINGS_BUCKET/*"
    },
    {
      "Sid": "DeleteRecordingsOfDeletedVisitors",
      "Effect": "Allow",
      "Action": ["s3:ListBucket", "s3:DeleteObject"],
      "Resource": ["arn:aws:s3:::RECORDINGS_BUCKET", "arn:aws:s3:::RECORDINGS_BUCKET/*"]
    }
  ]
}