Log Sessions

Log sessions are a diagnostic feature that allows an operator to capture SDK activity for a specific contact or client ID in real time. A session acts as a scoped collection bucket: once created, any upstream service can publish log entry events referencing the session ID and they will be stored and made visible in the management UI.

Flow

  1. An operator creates a log session via the management UI or the REST API (POST /log-sessions). The session targets a specific contact (contactId) or SDK client (clientId), and optionally narrows the scope to a single application (appCode). An expiry time (endDate) must be provided; the session is considered active until that time is reached or until it is ended explicitly.

  2. The SDK management service stores the session and returns its UUID. That UUID is the sessionId used in all subsequent log entry events.

  3. An upstream service (e.g. the mobile SDK gateway) publishes LogEntryEvent messages to the Pub/Sub subscription configured by the LOG_ENTRIES_SUBSCRIPTION environment variable.

  4. The log-entry-writer worker subscribes to that subscription, parses and validates each message, and calls the CreateLogEntryUseCase.

  5. The use case looks up the session by sessionId and verifies it is still active. If so, the entry is persisted. If the session has expired or does not exist the message is rejected and will not be retried.

  6. Stored log entries are retrievable via GET /log-sessions/:id/log-entries and are rendered in the management UI.

sequenceDiagram participant op as Operator participant api as SDK Management
(REST API) participant ps as Pub/Sub
(log entries subscription) participant w as log-entry-writer
(worker) participant db as Database op->>api: POST /log-sessions api->>db: insert log_session api-->>op: { id, endDate, ... } note over ps: Upstream service publishes
LogEntryEvent with sessionId ps->>w: LogEntryEvent message w->>db: verify session is active w->>db: insert log_entry w->>ps: ack

Pub/Sub Subscription

Log entry events are consumed from a subscription whose name is configured at runtime via the LOG_ENTRIES_SUBSCRIPTION environment variable. The subscription must exist on the Google Cloud project identified by GOOGLE_CLOUD_PROJECT.

Messages must be JSON-encoded and conform to the LogEntryEvent schema described below. Invalid messages (failed schema validation) are not acknowledged, so they will be retried according to the subscription’s retry policy.

LogEntryEvent Schema

{
  "sessionId": "01960000-0000-7000-8000-000000000000",
  "type": "http-request",
  "timestamp": "2025-06-01T12:00:00.000Z",
  "payload": { ... }
}

Fields

Field Type Description

sessionId

string (UUIDv7)

The ID of an active log session that this entry belongs to.

type

string

Identifies the kind of event. Determines how the payload is interpreted. See Log Entry Types below.

timestamp

string (ISO 8601)

The time the logged event occurred in the upstream service.

payload

object

Arbitrary key/value data whose structure depends on type.

Log Entry Types

http-request

Records an outbound HTTP call made by the SDK, including the request details and the HTTP status code of the response.

{
  "sessionId": "01960000-0000-7000-8000-000000000000",
  "type": "http-request",
  "timestamp": "2025-06-01T12:00:00.123Z",
  "payload": {
    "request": {
      "method": "POST",
      "url": "https://example.com/api/v1/resource",
      "headers": {
        "Content-Type": "application/json",
        "X-Request-Id": "abc-123"
      },
      "body": { "key": "value" }
    },
    "response": {
      "statusCode": 200,
      "headers": {
        "Content-Type": "application/json"
      },
      "body": { "result": "ok" }
    }
  }
}

Payload Fields

Field Type Required Description

payload.request.method

string

yes

The HTTP method used (e.g. GET, POST, PUT).

payload.request.url

string

yes

The full URL of the request.

payload.request.headers

object

no

Request headers as a flat name/value map.

payload.request.body

object

no

The JSON body of the request.

payload.response.statusCode

number

yes

The HTTP status code returned by the server. Status codes in the 2xx–3xx range are shown as a success badge; 4xx and above as an error badge.

payload.response.headers

object

no

Response headers as a flat name/value map.

payload.response.body

object

no

The JSON body of the response.

Unknown Types

Any type value not listed above is accepted and stored without error. The management UI will render the raw payload as formatted JSON for unknown types.

Adding a Type of Log Entry

To add support for a new log entry type, make the following changes:

  1. Create a detail component in apps/frontend/src/components/log-entries/. Follow the pattern of HttpRequestLogEntry.vue: accept a single payload prop typed as Record<string, unknown> and render the relevant fields.

  2. Register the detail component in LogEntryDetailDialog.vue. Import the new component and add a v-if="entryType === '<your-type>'" branch above the fallback v-else <pre> block.

  3. Add a list-view renderer in render-log-entry-payload.ts. Add a new case '<your-type>': in the switch statement and return a compact HTML summary string, following the pattern of renderHttpRequestPayload.

  4. Document the new type in this page under Log Entry Types. Provide a description, a JSON example, and a payload fields table.