Events
Query and filter events from the CLI with flexible date ranges, levels, and output formats.
Events are the raw log records emitted by SDKs — every Owl.info(), Owl.error(), Owl.step(), etc. Filter by app, level, user, session, environment, screen, or time range. Defaults to the last 24 hours.
Query events
owlmetry events [options]| Flag | Required | Description |
|---|---|---|
--project-id <id> | No | Filter by project UUID |
--app-id <id> | No | Filter by app UUID |
--since <time> | No | Start time (default: 24h) |
--until <time> | No | End time (default: now) |
--level <levels> | No | Filter by log level: info, debug, warn, error. Accepts a single value or a comma-separated list (e.g. --level info,warn) |
--user-id <id> | No | Filter by user ID |
--session-id <id> | No | Filter by session UUID |
--screen-name <name> | No | Filter by screen name |
--limit <n> | No | Max events to return |
--cursor <cursor> | No | Pagination cursor (from previous response) |
--data-mode <mode> | No | production (default), development, or all |
--order <direction> | No | Sort by timestamp: desc (default, newest first) or asc (oldest first) |
Time formats
The --since and --until flags accept two formats:
Relative — a number followed by a unit suffix:
| Suffix | Unit |
|---|---|
s | Seconds |
m | Minutes |
h | Hours |
d | Days |
w | Weeks |
Absolute — ISO 8601 timestamps:
2025-01-15T10:00:00Z
2025-01-15Examples
# Events from the last hour
owlmetry events --since 1h
# Errors from a specific app in the last 7 days
owlmetry events --app-id 550e8400-... --level error --since 7d
# Warnings and errors only
owlmetry events --level warn,error --since 7d
# Events for a specific user session
owlmetry events --session-id a1b2c3d4-...
# Development events only
owlmetry events --since 1h --data-mode development
# Walk a session chronologically (oldest first)
owlmetry events --session-id a1b2c3d4-... --order ascPagination
When there are more results, the response includes a next_cursor value. Pass it with --cursor to fetch the next page:
owlmetry events --since 7d --limit 50
# Output includes: "More results available. Use --cursor <value>"
owlmetry events --since 7d --limit 50 --cursor eyJsYXN0...View a single event
owlmetry events view <id>Shows full event details including custom attributes, device info, and experiment assignments.
| Argument | Description |
|---|---|
<id> | Event UUID |
Investigate an event
owlmetry investigate <eventId> [--window <minutes>]Builds the best possible breadcrumb trail around a specific event. If the target has a session_id, pulls the full session from that app; otherwise falls back to a --window time window. Then enriches with cross-app events for the same user in the same project (bounded by the session/window's time range) so backend and client events appear together even without a shared session_id. Results are merged, deduped by event id, and shown ascending by timestamp.
| Argument / Flag | Required | Description |
|---|---|---|
<eventId> | Yes | Target event UUID |
--window <minutes> | No | Fallback window, used only when the target has no session_id (default: 5) |
The target event is highlighted in the output. The default output format is log (even when --format table is set).
# Investigate a session-linked event (pulls the full session + cross-app user events)
owlmetry investigate a1b2c3d4-...
# Backend/no-session event: widen the fallback window
owlmetry investigate a1b2c3d4-... --window 30Output formats
Events support all three output formats:
# Table (default) — columnar summary
owlmetry events --since 1h
# Log — chronological log-style view
owlmetry events --since 1h --format log
# JSON — raw data for scripting
owlmetry events --since 1h --format jsonThe log format is particularly useful for reading event streams chronologically, similar to tailing a log file. The investigate command defaults to log format.
The table output colours each event's app_version green when it matches the app's latest_app_version, amber when it's older — see Latest Version Detection.