> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.
# Activity log monitoring
> Capture, visualize, and query application events and screenshots from devices
Activity log monitoring captures application events and screenshots from [BRICKS Foundation](/foundation) devices and stores them in a cloud time-series database. Use it to analyze device behavior, track user interactions, monitor application health, and visually review what your devices were displaying at any point in time.
Activity log monitoring is available on Business plan workspaces.
## Enable logging
Enable activity log on a device from [BRICKS Controller](/controller/devices):
1. Open the device detail page
2. Go to **Settings** > **Activity Log**
3. Toggle **Enabled** on
You can also enable logging for all devices in a group by deploying activity log settings from the **Device Group** tab.
### Event ID filter
Use the **Event ID Filter** field to set a regex pattern that controls which events are logged. Only events with IDs matching the pattern are captured. Leave empty to log all events.
## What is logged
### Events
Each log entry contains:
| Field | Description |
| --------------- | ------------------------------------------ |
| **Event name** | Identifier for the event type |
| **Timestamp** | When the event occurred |
| **Payload** | Custom event-specific content |
| **Device ID** | Which device produced the event |
| **Subspace ID** | Canvas subspace context (if applicable) |
| **Sender** | Component or module that emitted the event |
Events are grouped into three categories:
| Category | Event names | Description |
| -------------- | -------------------------------------------------------------- | ---------------------------------------------------------------- |
| **General** | `BRICK_*`, `GENERATOR_*`, `CANVAS_*`, `SUBSPACE_*`, and others | UI interactions, lifecycle events, and custom application events |
| **Data** | `PROPERTY_BANK_*` | Property bank state updates |
| **Local Sync** | `LOCAL_SYNC_INFO` | Device discovery and sync activity on the local network |
### Screenshots
When screenshot capture is enabled, screenshots can be triggered from [BRICKS Controller](/controller/devices) and are uploaded as JPEG images to the activity log server. Screenshots are timestamped and stored per device, letting you visually review what was displayed on screen at any given moment.
Screenshots are useful for:
* **Visual auditing** — Confirm the correct content was shown during a campaign or time window
* **Incident investigation** — See exactly what the device was displaying when an anomaly occurred
* **Remote monitoring** — Get a visual check on deployed devices without physical access
## How events are uploaded
Events are captured on-device, cached locally, and uploaded in batches to the activity log server at regular intervals (default: every 2 minutes). On browsers, a final upload is triggered automatically when the page unloads to minimize data loss.
## Screenshots
### How screenshot capture works
When enabled, screenshots can be triggered from BRICKS Controller and are uploaded as JPEG images to the activity log server, tagged with the capture timestamp. The server stores one image per device per timestamp — re-uploading at the same timestamp replaces the previous image.
Each image must be under 5 MB.
### Viewing screenshots
Screenshots can be retrieved by timestamp via [BRICKS Controller](/controller/devices) or the GraphQL API. The screenshots query returns a list of available timestamps; fetch the image for any timestamp using the download API or the BRICKS CLI.
```bash theme={null}
# List available screenshots for a device
bricks activity-log screenshots --device --start-time 2024-01-01T00:00:00Z
# Download a specific screenshot
bricks activity-log screenshot --device --ts 2024-01-15T10:30:00Z -o screenshot.jpg --open
```
## Query with GraphQL
The activity log server exposes a GraphQL API for querying events and screenshots. Use it to build custom dashboards, integrate with external analytics tools, or automate log analysis.
### Authentication
All GraphQL queries require a workspace token with the `query_activity_log` permission. Create one in **BRICKS Controller** → **Workspace Settings** → **Tokens**.
### Endpoint
```
https://activity-log.bricks.tools/api/graphql
```
Include your token as a Bearer token:
```
Authorization: Bearer
```
### Queries
#### Query events
The API provides category-specific queries (`general_events`, `data_events`, `local_sync_stats`) and a unified `events` query for cross-category retrieval. Use the GraphQL explorer at the [endpoint URL](#endpoint) to browse the full schema.
```graphql theme={null}
query {
general_events(filter: {
device_id: "your-device-id"
start_time: "2024-01-15T00:00:00Z"
end_time: "2024-01-15T23:59:59Z"
}) @stream {
timestamp
event_name
payload
}
}
```
#### Available filter fields
| Field | Applies to | Description |
| ------------- | ------------- | ---------------------------------- |
| `device_id` | All | Filter by device |
| `event_type` | `events` only | `general`, `data`, or `local_sync` |
| `event_name` | All | Filter by specific event name |
| `subspace_id` | All | Filter by canvas subspace |
| `sender` | All | Filter by emitting component |
| `start_time` | All | Range start (ISO 8601) |
| `end_time` | All | Range end (ISO 8601) |
Time range queries are limited to **30 days** per request.
#### Query screenshots
```graphql theme={null}
query {
screenshots(filter: {
device_id: "your-device-id"
start_time: "2024-01-15T00:00:00Z"
end_time: "2024-01-15T23:59:59Z"
}) @stream {
timestamp
}
}
```
### Using the BRICKS CLI
The BRICKS CLI wraps the GraphQL API for common query patterns:
```bash theme={null}
# Query events with filters
bricks activity-log events \
--start-time 2024-01-15T00:00:00Z \
--device your-device-id \
--type general \
--event-name BRICK_CLICK \
--limit 100
# Output as JSON
bricks activity-log events --start-time 2024-01-15T00:00:00Z --device your-device-id -f json
```
### Prometheus-compatible API
For metrics dashboards (Grafana, etc.), activity logs are also queryable via a Prometheus-compatible API. See the **Query Activity Log** guide in **Workspace Settings** for the endpoint URL and usage examples.
## Data retention
### Screenshots
Screenshot retention is determined by the workspace plan at the time of upload:
| Plan | Screenshot retention |
| -------- | -------------------- |
| Free | 7 days |
| Basic | 90 days |
| Pro | 90 days |
| Business | 90 days |
Screenshots older than the retention period are automatically deleted. Upgrading your plan does not extend retention on screenshots already uploaded under a lower tier.
### Events
Events do not have a fixed retention limit.
## Use cases
* **User behavior analysis** — Track how users interact with bricks and navigate canvases
* **Troubleshooting** — Investigate what happened before an error or unexpected behavior
* **Fleet monitoring** — Monitor event patterns across multiple deployed devices
* **Visual auditing** — Review screenshots to confirm correct content was displayed
* **Performance tracking** — Analyze generator response times and event frequency
## Next steps
Inspect runtime state in real time on the device.
Run end-to-end automation tests on devices.