journal

Journal

The Journal service listens to the platform event stream, persists each event to PostgreSQL for auditability and exposes HTTP endpoints to query journals or view per-client telemetry (first/last seen, subscriptions, in/out message counters).

Configuration

The service is configured with the following environment variables (unset values fall back to defaults).

Deployment

The service is distributed as a Docker container. Check the journals for the journal and journal-db services and how they are wired into the base stack.

To start the service outside of the container, execute the following shell script:

git clone https://github.com/absmach/supermq
cd supermq

# build and install the binary
make journal
make install

# run with the essentials; requires Postgres, Auth gRPC, Domains gRPC, and NATS running
SMQ_JOURNAL_HTTP_HOST=localhost \
SMQ_JOURNAL_HTTP_PORT=9021 \
SMQ_JOURNAL_DB_HOST=localhost \
SMQ_JOURNAL_DB_PORT=5432 \
SMQ_JOURNAL_DB_USER=supermq \
SMQ_JOURNAL_DB_PASS=supermq \
SMQ_JOURNAL_DB_NAME=journal \
SMQ_AUTH_GRPC_URL=localhost:7001 \
SMQ_DOMAINS_GRPC_URL=localhost:7003 \
SMQ_ES_URL=nats://localhost:4222 \
$GOBIN/supermq-journal

HTTP API

Base URL defaults to http://localhost:9021. All journal and telemetry endpoints require Authorization: Bearer <token> (health is public).

Usage

API examples

List user journals

curl -X GET "http://localhost:9021/journal/user/${USER_ID}?limit=5&with_attributes=true&dir=desc" \
  -H "Authorization: Bearer $TOKEN"

Expected response:

{
  "journals": [
    {
      "operation": "user.create",
      "occurred_at": "2024-01-11T12:05:07.449053Z",
      "attributes": {
        "created_at": "2024-06-12T11:34:32.991591Z",
        "id": "29d425c8-542b-4614-8a4d-a5951945d720",
        "identity": "Gawne-Havlicek@email.com",
        "name": "Newgard-Frisina",
        "status": "enabled",
        "updated_at": "2024-06-12T11:34:33.116795Z",
        "updated_by": "ad228f20-4741-47c5-bef7-d871b541c019"
      },
      "metadata": {
        "Update": "Calvo-Felkins"
      }
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 5
}

List entity journals in a domain

Retrieves telemetry data for a specific client within a domain. This includes connection status, messages sent/received, and other metrics.

curl -X GET "http://localhost:9021/${DOMAIN_ID}/journal/client/${CLIENT_ID}?operation=client.create&with_metadata=true&dir=desc&limit=10" \
  -H "Authorization: Bearer $TOKEN"

Expected response:

{
  "total": 2,
  "offset": 0,
  "limit": 10,
  "journals": [
    {
      "operation": "client.create",
      "occurred_at": "2024-06-12T11:34:33Z",
      "domain": "29d425c8-542b-4614-8a4d-a5951945d720",
      "attributes": {
        "id": "bb7edb32-2eac-4aad-aebe-ed96fe073879",
        "domain": "29d425c8-542b-4614-8a4d-a5951945d720",
        "name": "clientName",
        "status": "enabled"
      },
      "metadata": {
        "trace_id": "6efb4c24b1b4a684"
      }
    }
  ]
}

View client telemetry

Retrieves telemetry data for a specific client within a domain. This includes connection status, messages sent/received, and other metrics.

curl -X GET "http://localhost:9021/${DOMAIN_ID}/journal/client/${CLIENT_ID}/telemetry" \
  -H "Authorization: Bearer $TOKEN"

Expected response:

{
  "client_id": "bb7edb32-2eac-4aad-aebe-ed96fe073879",
  "domain_id": "29d425c8-542b-4614-8a4d-a5951945d720",
  "subscriptions": 5,
  "inbound_messages": 1234567,
  "outbound_messages": 987654,
  "first_seen": "2024-01-11T10:00:00Z",
  "last_seen": "2024-01-11T12:05:07.449053Z"
}

Health check

curl "http://localhost:9021/health"

Expected response:

{
  "status": "pass",
  "version": "0.18.0",
  "commit": "ffffffff",
  "description": "journal service",
  "build_time": "1970-01-01_00:00:00",
  "instance_id": "b4f1d5d2-4f24-4c2a-9a40-123456789abc"
}