Skip to main content
Version: Developer

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.

Report options time period dropdown

Report options

Time period options​

Time periodWindowAutomatic refresh
DefaultThe last day of data.None.
Real-TimeThe last hour of data.Refreshes every five minutes. Real-Time is the only time period with automatic refresh enabled.
CustomA specific time frame selected in the custom time menu.A configurable auto-refresh interval set in the same menu.

Custom time range modal

Custom time range selection 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.

Logging dashboard filters with exclusion rules

Application tab filters with More Filters expanded and three active exclusion rules

Application tab filter fields​

FieldMeaningDefault
Search MessageA 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
LevelThe 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
LimitThe maximum number of entries to load, newest first: 50, 100, 250, 500, or 1000.100
RefreshReloads the entries for the current filters.Not applicable
Time RangeThe 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
ApplicationThe services to include. Each option shows the number of entries in the time range. No selection includes every service.All Applications
ProcessThe logger names to include. When applications are selected, the list contains only the processes those applications log.All Processes
HostThe hosts to include.All Hosts
Search UserA 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.

Level dropdown menu with ticked levels

Level selection with Debug and Error selected

Web Filter tab filter fields​

FieldMeaningDefault
Search SiteA case-insensitive search for text in the site name.Empty
LimitThe maximum number of entries to load, newest first.100
RefreshReloads the entries for the current filters.Not applicable
Time RangeThe window to search, as on the Application tab.1 hour
Search CategoryA case-insensitive search for text in the web filter category.Empty
Search AllowedTrue returns allowed requests. False returns blocked requests. All returns both.All
Search UserA 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.

Web Filter tab filters and results

Web Filter tab with More Filters expanded

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.

RuleMatchesExample
textEntries whose message contains the text. On the Web Filter tab, entries whose site contains the text.healthcheck
field:valueEntries 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:valueEntries 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:templateEntries 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:value matches on application, process, host, user, and funcname are 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.

Logging results table with grouped entries

Application tab results with Group Similar Messages turned on

The toolbar above the results provides the following controls.

ControlAction
SearchFilters the loaded entries by message, or by site on the Web Filter tab, without a new search.
FiltersSets the sort order, the rows per page, and the visible columns for the loaded entries.
ExportDownloads 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.

Log entry details with field tiles and a traceback

Log entry details for an error entry

The details contain the following sections.

SectionContents
RequestThe requested URL. Shown only when the entry has one.
MessageThe full message. Copy Message copies it to the clipboard.
Field tilesHost, 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 StackThe exception details, when the entry has them.
Similar tabThe other loaded entries grouped with this entry. Shown only when Group Similar Messages is on and the group has more than one entry.

Similar tab listing grouped log entries

Similar tab for a grouped entry

Actions menu​

The Actions menu acts on the open entry. An action is unavailable when the entry has no value for its field.

ActionResult
Exclude Messages Like ThisAdds a like: rule for the entry's message shape.
Exclude This ApplicationAdds an application: rule for the entry's application.
Exclude This ProcessAdds a process: rule for the entry's process.
Exclude This HostAdds a host: rule for the entry's host.
Only This HostSets the Host filter to the entry's host only.
Only This ApplicationSets the Application filter to the entry's application only.
Copy JSONCopies the entry to the clipboard as JSON.

Actions menu with exclusion and filter actions

Actions menu in the log entry details

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 view with context, password, and system information options

Export view for a log entry

Export fields​

FieldMeaningDefault
Previous contextThe number of seconds of logs before the entry to include.10
Post contextThe number of seconds of logs after the entry to include.5
PasswordThe password that encrypts the archive. The same password is required to extract it.Required, no default
Include system version informationAdds system information to the archive.Selected

The archive downloads as diagnostics.zip.

Export artifacts​

The archive contains up to three files.

FileContentsCondition
export.jsonThe export window, the chosen options, the row cap, the number of entries exported, and whether the cap truncated the export.Always included.
context.jsonEvery 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.jsonSystem version information.Included only when Include system version information is selected.
note

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.

FileServiceFormat
/opt/kasm/current/log/api.logAPI ServerJSON
/opt/kasm/current/log/agent.logProvision AgentJSON
/opt/kasm/current/log/nginx/access_json.lognginx proxy (access log)JSON
/opt/kasm/current/log/nginx/error.lognginx proxy (error log)Text
note

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'.

note

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 nameEvent
kasm.provision.createA workspace provisioning operation begins.
kasm.provision.destroyA workspace provisioning operation is torn down.
kasm.provision.cast.createA Cast provisioning operation begins.
kasm.account.login.successfulA user authenticates successfully.
kasm.account.login.failed_invalid_passwordA login attempt fails because the password is invalid.
kasm.account.login.failed_ldap_errorA login attempt fails because of an LDAP error.
kasm.scaling.status.resourcesAutoScale reports current resource status.
kasm.scaling.provider.aws.statusAutoScale 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.

AttributeMeaning
messageThe log message text.
levelThe logging level (INFO, WARNING, ERROR, etc.).
client.addressThe source IP address of the request.
user_agent.originalThe user agent string of the request.
kasm.server.idThe Agent identifier.
kasm.kasm.user_idThe unique identifier of the user.
kasm.kasm.user_nameThe username of the user.
kasm.kasm.image_idThe unique identifier of the workspace image.
kasm.kasm.image_nameThe internal name of the workspace image.
kasm.kasm.image_friendly_nameThe display name of the workspace image.
kasm.kasm.idThe unique identifier of the workspace session.
note

In ClickHouse (kasm_otel.otel_logs), these attributes are accessible via LogAttributes['attribute_name']. For example: LogAttributes['kasm.kasm.user_name'].