Events

Log events at different levels (info, debug, warn, error) with custom attributes and screen context.

Events are the core unit of data in OwlMetry. The Swift SDK provides four log levels, each designed for a different class of information. For a broader overview of the event model, see Events.

Log Levels

Info

Normal operations worth recording: user actions, feature usage, successful completions. This is the default level for most instrumentation.

Owl.info("User tapped checkout", screenName: "Cart")

Debug

Verbose detail useful only during development: cache hits, state transitions, intermediate values. Debug events are filtered out when viewing production data.

Owl.debug("Cache hit for user preferences", screenName: "Home", customAttributes: ["key": "user_prefs"])

Warn

Something unexpected that the app recovered from: slow responses, fallback paths, retries needed.

Owl.warn("Slow network response", customAttributes: ["latency_ms": "1200", "endpoint": "/api/feed"])

Error

Something failed: network errors, parse failures, missing data, caught exceptions.

Owl.error("Failed to load profile image", screenName: "Profile", customAttributes: ["error": error.localizedDescription])

Method Signature

All four methods share the same signature:

Owl.info(
    _ message: String,
    screenName: String? = nil,
    customAttributes: [String: String]? = nil,
    file: String = #file,
    function: String = #function,
    line: Int = #line
)

Parameter	Description
`message`	A descriptive string for the event. Choose messages that are specific and searchable.
`screenName`	The screen where the event occurred. Ties the event to a location in the UI.
`customAttributes`	Key-value pairs of additional structured data. Values must be strings.
`file`, `function`, `line`	Automatically captured from the call site. Do not pass these manually.

The SDK automatically captures the source file, function name, and line number of every log call. This metadata is included on the event and visible in the dashboard, making it straightforward to trace an event back to the code that emitted it.

Automatic Lifecycle Events

The SDK emits several events automatically without any manual calls:

Event	Level	When
`sdk:session_started`	info	On `Owl.configure()`. Includes `_launch_ms` (time from process start to configure).
`sdk:app_foregrounded`	info	When the app enters the foreground.
`sdk:app_backgrounded`	info	When the app enters the background.
`sdk:screen_appeared`	info	When a view with `.owlScreen()` appears. See Screen Tracking.
`sdk:screen_disappeared`	debug	When a view with `.owlScreen()` disappears. Includes `_duration_ms`.
`sdk:network_request`	info/warn/error	On URLSession HTTP request completion. See below.

Network Request Tracking

The SDK automatically instruments URLSession completion-handler-based requests. This is enabled by default and requires no code beyond Owl.configure().

Each tracked request emits a sdk:network_request event with these attributes:

Attribute	Description
`_http_method`	GET, POST, PUT, etc.
`_http_url`	Sanitized URL (scheme + host + path only; query parameters stripped for privacy).
`_http_status`	HTTP status code.
`_http_duration_ms`	Request duration in milliseconds.
`_http_response_size`	Response body size in bytes.
`_http_error`	Error description (network failures only).

Log levels are assigned based on the response: info for 2xx/3xx, warn for 4xx/5xx, and error for network failures with no response.

The SDK's own requests to the OwlMetry ingest endpoint are automatically excluded. To disable network request tracking entirely:

try Owl.configure(
    endpoint: "https://ingest.owlmetry.com",
    apiKey: "owl_client_...",
    networkTrackingEnabled: false
)

Best Practices

Be specific with messages. Prefer "Failed to load profile image" over "error". Specific messages are easier to search and filter.
Use screenName for UI events. It ties events to where they happened, making dashboard filtering more useful.
Use customAttributes for structured data. Anything you might want to filter, group, or search on later should be an attribute rather than embedded in the message string.
Avoid logging PII. Do not include emails, phone numbers, passwords, or authentication tokens in events.
Avoid high-frequency events. Do not log on every frame, scroll position change, or timer tick. Focus on meaningful actions and outcomes.

Ready to get started?

Install the CLI and let your agent handle the rest.

Get Started GitHub