Working with Logs

Query and create log entries via the REST API.

2log records all machine usage, transactions, and system events as log entries. You can query and filter these logs via the lab service.

Permissions

Admins (LAB_ADMIN, LAB_SERVICE, or LAB_SEE_LOGS): can query all logs.
Regular users: can only see their own logs. The server automatically adds a userID filter matching the logged-in user.

Querying logs

Use the getLogs service method with a filter object:

curl -X POST http://your-server/api/services/lab/getLogs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "match": {},
      "sort": {"timestamp": -1},
      "limit": 50
    }
  }'

The filter object

Field	Type	Description
`match`	object	MongoDB-style match criteria (see below)
`sort`	object	Sort order, e.g. `{"timestamp": -1}` for newest first, `{"timestamp": 1}` for oldest first
`from`	string	ISO 8601 datetime – start of time range
`to`	string	ISO 8601 datetime – end of time range (defaults to now if omitted)
`limit`	int	Maximum number of results (`-1` or omit for unlimited)

Match criteria

The match object filters log entries by exact field values:

Field	Type	Description
`userID`	string	Filter by user UUID
`resourceID`	string	Filter by machine / resource ID
`logType`	int	Filter by event type (see table below)

Log event types

Value	Name	Description
0	BILL	Completed session with billing
1	SWITCH_ON	Something was switched on
2	SWITCH_OFF	Something was switched off
3	START	A machine was started
4	STOP	A machine was stopped
5	EVENT	General event
6	LOGIN	User logged in
7	LOGOUT	User logged out
8	WARNING	Warning
9	ERROR	Error
10	OPEN	Something was opened (cabinet, lid)
11	CLOSED	Something was closed
12	TRANSFER	Balance transfer (top-up or deduction)
13	JOB	Job with duration
14	OFFLINE	Device went offline

Log entry format

Each log entry in the response contains these fields:

{
  "logID": "60a7b2c3d4e5f67890abcdef",
  "resourceID": "laser-cutter-01",
  "userID": "f47ac10b58cc4372a5670e02b2c3d479",
  "userName": "Max Mustermann",
  "email": "max@fablab.org",
  "cardID": "04:A3:2B:1C:D4:E5:F6",
  "logType": 0,
  "units": 120,
  "price": 600,
  "description": "Laser cutting session",
  "timestamp": "2024-01-15T14:30:00.000",
  "startTime": "2024-01-15T14:00:00.000",
  "endTime": "2024-01-15T14:30:00.000",
  "executive": "admin-user-uuid",
  "sessionID": "session-uuid",
  "extType": "",
  "extRef": ""
}

Field	Type	Description
`logID`	string	Unique log entry ID
`resourceID`	string	Machine or resource that generated this log
`userID`	string	UUID of the user involved
`userName`	string	Name of the user at the time of the event
`email`	string	Current email of the user (joined from user data)
`cardID`	string	RFID card used (if applicable)
`logType`	int	Event type (see table above)
`units`	int	Usage units (interpretation depends on machine)
`price`	int	Cost in cents
`description`	string	Human-readable description
`timestamp`	string	When the log was created
`startTime`	string	Start of the session/event
`endTime`	string	End of the session/event
`executive`	string	UUID of the user/service that triggered the event
`sessionID`	string	Session identifier (groups related log entries)
`extType`	string	External system type (e.g. `2log-paydesk`)
`extRef`	string	External reference ID

Examples

Logs for a specific user

Get the 20 most recent logs for a user:

curl -X POST http://your-server/api/services/lab/getLogs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "match": {
        "userID": "f47ac10b58cc4372a5670e02b2c3d479"
      },
      "sort": {"timestamp": -1},
      "limit": 20
    }
  }'

Logs for a specific machine

Get all logs for the laser cutter:

curl -X POST http://your-server/api/services/lab/getLogs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "match": {
        "resourceID": "laser-cutter-01"
      },
      "sort": {"timestamp": -1}
    }
  }'

Logs in a time range

Get all billing events from January 2024:

curl -X POST http://your-server/api/services/lab/getLogs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "match": {
        "logType": 0
      },
      "from": "2024-01-01T00:00:00.000",
      "to": "2024-02-01T00:00:00.000",
      "sort": {"timestamp": -1}
    }
  }'

Combining filters

Get all laser cutter sessions for a specific user in Q1 2024:

curl -X POST http://your-server/api/services/lab/getLogs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "match": {
        "userID": "f47ac10b58cc4372a5670e02b2c3d479",
        "resourceID": "laser-cutter-01"
      },
      "from": "2024-01-01T00:00:00.000",
      "to": "2024-04-01T00:00:00.000",
      "sort": {"timestamp": -1}
    }
  }'

Adding a log entry

To create a log entry programmatically, use the addLog method. Requires LAB_ADMIN or LAB_SERVICE permissions.

curl -X POST http://your-server/api/services/lab/addLog \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceID": "laser-cutter-01",
    "userID": "f47ac10b58cc4372a5670e02b2c3d479",
    "logType": 5,
    "description": "Manual maintenance note",
    "units": 0,
    "price": 0
  }'

The fields in the request body correspond to the log entry fields described above. The timestamp is set automatically to the current time.