Available since 2.2

The request log records a sample of the Content API requests of selected projects. Its purpose is a replay check before a project switches its GraphQL engine: the recorded requests run against a copy of the database through both engines, and their responses are compared.

The sample contains client data

The log records every query with its variables, and variables carry the data clients send: names, e-mails, texts and anything else stored in the project. Treat the file like a database dump:

  • Write it to a location only the operators of the check can read, never to shared log storage or stdout.
  • Do not copy it outside the environment where the check runs.
  • Delete it as soon as the check is done.

The log is off by default. It records only the projects it lists, until a set time and at most a set number of requests.

Configuration

CONTEMBER_CONTENT_API_REQUEST_LOG_PROJECTS=blog
CONTEMBER_CONTENT_API_REQUEST_LOG_FILE=/var/lib/contember/request-log/blog.jsonl
CONTEMBER_CONTENT_API_REQUEST_LOG_MAX_REQUESTS=5000
CONTEMBER_CONTENT_API_REQUEST_LOG_UNTIL=2026-01-02T18:00:00Z

or in the server config:

server:
  contentApi:
    requestLog:
      projects: [blog]
      file: /var/lib/contember/request-log/blog.jsonl
      maxRequests: 5000
      until: '2026-01-02T18:00:00Z' # quoted, or YAML reads it as a date
OptionMeaning
projectsSlugs of the projects to record, as a list or a comma-separated string. There is no wildcard. Without projects, the log is off. A slug matches that project in every project group.
fileThe file the Engine appends to, one JSON object per line. A new file is readable by its owner only. Required when projects are listed.
maxRequestsThe number of requests recorded per project slug by one Engine process, at most 100 000. Required when projects are listed.
untilAn ISO timestamp with a time zone. Nothing is recorded after it. It may lie at most 7 days ahead when the Engine starts. Required when projects are listed.

until is the hard bound: it holds for every Engine process and after any restart, so a forgotten configuration stops recording by itself. maxRequests counts per process: a cluster of workers can record up to the number of workers times maxRequests, and a restarted process counts from zero again and appends to the same file. To stop recording earlier, remove the configuration and restart the Engine.

Recorded entries

{"time":"2026-01-02T03:04:05.000Z","projectGroup":null,"project":"blog","stage":"live","roles":["editor"],"method":"POST","operationName":"Articles","query":"query Articles($limit: Int) { listArticle(limit: $limit) { id } }","variables":{"limit":10},"status":200}
FieldMeaning
timeWhen the request finished.
projectGroupThe project group of the request, or null when the Engine serves a single one.
project, stageThe project and stage of the request URL.
rolesThe effective project roles of the identity. The identity itself and the variables of its memberships are not recorded, so a replay with other membership variables can return other rows.
methodThe HTTP method of the request, usually POST or GET.
operationName, query, variablesThe GraphQL request as the client sent it: from the body of a POST, from the query string of a GET. In a GET request, and in a form-encoded POST, variables is the raw string the client sent.
statusThe HTTP status of the GraphQL response; a failed request is recorded too. It is taken before X-Contember-Force-Ok turns an error status into 200, so it can differ from what such a client received.

Only requests that reach GraphQL execution are recorded. A request refused before it, for example without authentication, for an unknown stage or answered with 304 Not Modified, is not.

If the file cannot be written, the Engine logs an error and stops recording; requests are not affected. On shutdown the Engine waits at most 5 seconds for the file to be flushed.