Reporting and Logging
Kasm Workspaces reporting and logging form the evidence layer that makes workspace delivery auditable and operationally visible. The built-in dashboards present usage, session activity, and security-relevant events, while enriched JSON logs from each role service can be ingested into an external Security Information and Event Management (SIEM) solution. File-based logs complement an external SIEM rather than replacing it.
Logging behavior is configured in the Settings dashboard. For configuration options, see the logging settings.
Log retention
Logs, traces, and metrics are stored in ClickHouse with per-signal retention periods: 30 days (general logs), 365 days (audit logs), 7 days (traces), 90 days (metrics). For configuration and customization, see Observability Configuration.
Dashboard
The reporting dashboard shows session, user, and infrastructure data over a selected time period. By default it displays the last day of data. The Time Period dropdown menu changes the window.
Most dashboard reports read from ClickHouse. When observability is disabled, only the current sessions, agents, image usage, and user session usage reports return data. See Running without observability.

Time period options
| Time period | Window | Automatic refresh |
|---|---|---|
| Default | The last day of data. | None. |
| Real-Time | The last hour of data. | Refreshes every five minutes. Real-Time is the only time period with automatic refresh enabled. |
| Custom | A specific time frame selected in the custom time menu. | A configurable auto-refresh interval set in the same menu. |

Logging dashboard
The logging dashboard (Admin > Diagnostics > Logging) searches the logs that every Kasm Workspaces service sends to ClickHouse (the kasm_otel database). Viewing it requires the Reports View permission. When ClickHouse is unavailable, the logging dashboard warns and returns no data. The dashboard has two tabs:
- Application shows log entries from the Kasm Workspaces services.
- Web Filter shows the URL access decisions made by the web filter.
The filters and exclusion rules are applied by the server across the whole time range before the entry limit. The total in the results summary counts every matching entry, including entries beyond the limit. For step-by-step use, see Find the cause of an error with the logging dashboard.

Application tab filter fields
| Field | Meaning | Default |
|---|---|---|
| Search Message | A case-insensitive search for text anywhere in the log message. Every character matches literally, including % and _. The search applies after a short pause in typing. Enter applies it immediately and Escape clears it. | Empty |
| Level | The log levels to return: Debug, Info, Warning, Error, and Critical. Any combination can be selected, including non-adjacent levels such as Debug and Error. No selection returns every level. | Info and above |
| Limit | The maximum number of entries to load, newest first: 50, 100, 250, 500, or 1000. | 100 |
| Refresh | Reloads the entries for the current filters. | Not applicable |
| Time Range | The window to search: the last 15 minutes, 1 hour, 6 hours, 24 hours, or 7 days. Custom adds Start Date and End Date fields for a fixed window. | 1 hour |
| Application | The services to include. Each option shows the number of entries in the time range. No selection includes every service. | All Applications |
| Process | The logger names to include. When applications are selected, the list contains only the processes those applications log. | All Processes |
| Host | The hosts to include. | All Hosts |
| Search User | A case-insensitive search for text in the username attached to the entry. | Empty |
Application, Process, Host, and Search User are under More Filters. Reset restores every filter to its default. Reset does not change exclusion rules or Group Similar Messages. The filters and exclusion rules are saved in the browser until logout, so they persist across page reloads. Logging out clears them because they can contain usernames. The Group Similar Messages setting persists across logins.
Web Filter tab filter fields
| Field | Meaning | Default |
|---|---|---|
| Search Site | A case-insensitive search for text in the site name. | Empty |
| Limit | The maximum number of entries to load, newest first. | 100 |
| Refresh | Reloads the entries for the current filters. | Not applicable |
| Time Range | The window to search, as on the Application tab. | 1 hour |
| Search Category | A case-insensitive search for text in the web filter category. | Empty |
| Search Allowed | True returns allowed requests. False returns blocked requests. All returns both. | All |
| Search User | A case-insensitive search for text in the username attached to the entry. | Empty |
The Web Filter tab lists each entry's timestamp, user, allowed status, category, and site.

Exclusion rules
Exclusion rules hide matching entries. Each rule is a chip in the Exclusions field. Type a rule and press Enter or type a comma to add it. Select a chip to turn the rule off or back on. A rule that is off appears struck through. The x on a chip removes the rule, and Clear All removes every rule. The Actions menu in the log entry details also adds rules.
The following table lists the rule syntax.
| Rule | Matches | Example |
|---|---|---|
text | Entries whose message contains the text. On the Web Filter tab, entries whose site contains the text. | healthcheck |
field:value | Entries where the field exactly equals the value (application, process, host, level, user, funcname). The match is case-sensitive, except for level. | user:alice@example.com |
field:value | Entries where the field contains the value (message, site, category, url). | site:example.com |
/pattern/ | Entries whose message matches the regular expression. On the Web Filter tab, entries whose site matches it. | /^Checking for/ |
field:/pattern/ | Entries where the field matches the regular expression. | url:/status$/ |
like:template | Entries whose message has the same shape as the template. The placeholders <n>, <hex>, <uuid>, <ip>, and <ts> match any number, hexadecimal ID, UUID, IP address, and timestamp. Exclude Messages Like This creates this rule. | like:Pruned <n> unused images from kasm-host-<n> |
Rules follow these limits:
- Substring matches and regular expressions ignore letter case. Exact
field:valuematches onapplication,process,host,user, andfuncnameare case-sensitive. - Regular expressions use RE2 syntax. Lookarounds, such as
(?=...), and backreferences, such as\1, are not supported. - A rule can be up to 500 characters long.
- The enabled rules share a combined size limit.
like:rules for long messages use the most space. A rule that does not fit is not applied until other rules are turned off or removed. - A
like:rule for a long message matches only the start of the message.
A rule that breaks a limit or has invalid syntax appears in red and is not applied. Hover over the chip to see the reason.
Results
The summary line under the filters reports how many entries are shown and loaded. When more entries match than the limit allows, the summary also shows the total number of matching entries. Raise the limit or narrow the filters to load older matches.
Group Similar Messages combines loaded entries that share a level, an application, and a message shape into one row. The row shows the newest entry and a count such as ×22. Grouping applies to the loaded entries only.

The toolbar above the results provides the following controls.
| Control | Action |
|---|---|
| Search | Filters the loaded entries by message, or by site on the Web Filter tab, without a new search. |
| Filters | Sets the sort order, the rows per page, and the visible columns for the loaded entries. |
| Export | Downloads every loaded entry as a JSON file, including the entries inside groups. |
Selecting an entry opens its details.
Log entry details
The log entry details show every populated field of one entry. The title shows the entry's level, timestamp, and application.

The details contain the following sections.
| Section | Contents |
|---|---|
| Request | The requested URL. Shown only when the entry has one. |
| Message | The full message. Copy Message copies it to the clipboard. |
| Field tiles | Host, Level, Timestamp, and Application always appear, with - when the entry has no value. Process, service, function, wrapped function, user, client IP, user agent, allowed, category, site, domain, session ID, server ID, connection proxy, trace ID, and span ID appear when the entry has a value. |
| Traceback and Error Stack | The exception details, when the entry has them. |
| Similar tab | The other loaded entries grouped with this entry. Shown only when Group Similar Messages is on and the group has more than one entry. |

Actions menu
The Actions menu acts on the open entry. An action is unavailable when the entry has no value for its field.
| Action | Result |
|---|---|
| Exclude Messages Like This | Adds a like: rule for the entry's message shape. |
| Exclude This Application | Adds an application: rule for the entry's application. |
| Exclude This Process | Adds a process: rule for the entry's process. |
| Exclude This Host | Adds a host: rule for the entry's host. |
| Only This Host | Sets the Host filter to the entry's host only. |
| Only This Application | Sets the Application filter to the entry's application only. |
| Copy JSON | Copies the entry to the clipboard as JSON. |

Export
Export in the log entry details packages the logs around the entry into an AES256-encrypted ZIP archive. The export window runs from Previous context seconds before the entry to Post context seconds after it. Exporting requires the System Export Data permission. Back returns to the entry details without exporting.

Export fields
| Field | Meaning | Default |
|---|---|---|
| Previous context | The number of seconds of logs before the entry to include. | 10 |
| Post context | The number of seconds of logs after the entry to include. | 5 |
| Password | The password that encrypts the archive. The same password is required to extract it. | Required, no default |
| Include system version information | Adds system information to the archive. | Selected |
The archive downloads as diagnostics.zip.
Export artifacts
The archive contains up to three files.
| File | Contents | Condition |
|---|---|---|
export.json | The export window, the chosen options, the row cap, the number of entries exported, and whether the cap truncated the export. | Always included. |
context.json | Every log entry in the export window, including the selected entry, up to 5,000 entries. The dashboard filters and exclusion rules do not apply. | Always included. |
system_info.json | System version information. | Included only when Include system version information is selected. |
The archive uses AES256 encryption. Older built-in operating system extractors on Windows and macOS may not support AES256 ZIP files, in which case a utility such as 7-Zip is required to extract the contents. Verify support against the current operating system version.
File-based logs
Each service writes logs to disk at /opt/kasm/current/log/. These files can be ingested into a SIEM solution directly using Filebeat, the Splunk Universal Forwarder, or similar agents.
| File | Service | Format |
|---|---|---|
/opt/kasm/current/log/api.log | API Server | JSON |
/opt/kasm/current/log/agent.log | Provision Agent | JSON |
/opt/kasm/current/log/nginx/access_json.log | nginx proxy (access log) | JSON |
/opt/kasm/current/log/nginx/error.log | nginx proxy (error log) | Text |
The nginx access log (access_json.log) is written to disk by nginx and also collected by the OTel Collector's filelog receiver. Both destinations receive the same data. In ClickHouse, nginx records appear with ResourceAttributes['service.name'] = 'kasm-proxy'.
Application service log files changed in 1.20.0. Each service writes one JSON file: the API server, including the manager, writes api.log, and the agent writes agent.log. The api_server.log, *_json.log, and per-API text files from earlier releases are no longer written. The JSON field names also changed: levelname is now level, name is now logger, and lineno is now line. The timestamp, module, and message fields are unchanged. For the complete mapping, see Observability migration.
Metrics
Important application log events include a kasm.metric_name attribute. Each value identifies an event useful for visualization and analysis.
| Metric name | Event |
|---|---|
kasm.provision.create | A workspace provisioning operation begins. |
kasm.provision.destroy | A workspace provisioning operation is torn down. |
kasm.provision.cast.create | A Cast provisioning operation begins. |
kasm.account.login.successful | A user authenticates successfully. |
kasm.account.login.failed_invalid_password | A login attempt fails because the password is invalid. |
kasm.account.login.failed_ldap_error | A login attempt fails because of an LDAP error. |
kasm.scaling.status.resources | AutoScale reports current resource status. |
kasm.scaling.provider.aws.status | AutoScale reports AWS provider status. |
Many metric logs contain additional data useful for analysis. Administrators can inspect the logs for further detail.
For the full catalog of metrics emitted by Kasm services (counters, gauges, histograms), see Observability Metrics.
Common attributes
Where applicable, the application logs emit additional attributes that provide context for analysis.
| Attribute | Meaning |
|---|---|
message | The log message text. |
level | The logging level (INFO, WARNING, ERROR, etc.). |
client.address | The source IP address of the request. |
user_agent.original | The user agent string of the request. |
kasm.server.id | The Agent identifier. |
kasm.kasm.user_id | The unique identifier of the user. |
kasm.kasm.user_name | The username of the user. |
kasm.kasm.image_id | The unique identifier of the workspace image. |
kasm.kasm.image_name | The internal name of the workspace image. |
kasm.kasm.image_friendly_name | The display name of the workspace image. |
kasm.kasm.id | The unique identifier of the workspace session. |
In ClickHouse (kasm_otel.otel_logs), these attributes are accessible via LogAttributes['attribute_name']. For example: LogAttributes['kasm.kasm.user_name'].