Getting Started

OwlMetry is designed to be set up by your coding agent. Install the CLI, give your agent a prompt, and it handles authentication, project creation, and SDK integration.

You can also set everything up manually if you prefer.

Install the CLI

npm install -g @owlmetry/cli

Requires Node.js 20+. The CLI ships with built-in skill files that teach your agent the full command reference and SDK integration patterns.

Tell Your Agent to Set Up OwlMetry

Give your coding agent a prompt like this:

Set up OwlMetry in this project. Run `owlmetry skills` to get the
skill file paths, then install the CLI and relevant SDK skill files.
Use the CLI skill to authenticate and create a project/app, then use
the SDK skill to instrument the code.

That's it. Your agent reads the skill files and takes it from there. The only thing you'll need to do is provide a 6-digit verification code — the agent will ask for your email, OwlMetry sends you a code, and you paste it back. This creates your account, generates an API key, and the agent handles the rest: creating a project, setting up an app, installing the SDK, and wiring up event tracking.

Tip: Add this line to your project's CLAUDE.md, AGENTS.md, or whatever default instructions file your coding agent uses:

### OwlMetry
Load `/owlmetry-cli` before running any `owlmetry` CLI commands or doing analytics work — it links to the appropriate SDK skill for your platform.

This ensures every future session knows OwlMetry is integrated and loads the right skill files automatically — including the full API reference, funnel design rules, and lifecycle metric patterns.

Choose Your Deployment

• Hosted — Use the instance at owlmetry.com. No server setup required.
• Self-hosted — Run OwlMetry on your own server. Full control over your data, deployed in under 30 minutes.

Manual Setup

Prefer to set things up yourself? Here's what to do.

1. Sign Up

Go to owlmetry.com and enter your email. You'll receive a 6-digit verification code — enter it to sign in. No password needed. Your account is created automatically on first verification.

If you're self-hosting, use your own instance URL instead.

2. Create a Project

In the dashboard sidebar, go to Projects and click Create Project. A project groups related apps across platforms (e.g., an iOS app and a backend service under one project).

3. Create an App

From your project's detail page, click Create App. Choose the platform that matches your target:

For Apple, Android, and Web platforms, provide a bundle ID (e.g., com.example.myapp). Backend apps don't need one.

When you create the app, a client API key (owl_client_...) is generated automatically. Copy this key — you'll need it to configure the SDK.

4. Install and Configure Your SDK

Swift Quickstart

For iOS, iPadOS, and macOS apps. Requires an Apple-platform app and client key from OwlMetry.

1. Add the Swift Package

In Xcode: File > Add Package Dependencies, enter the repository URL, select branch main, and add OwlMetry to your target.

Or in Package.swift:

dependencies: [
    .package(url: "https://github.com/Jasonvdb/owlmetry.git", branch: "main")
]

Add to your target:

.target(name: "YourApp", dependencies: [
    .product(name: "OwlMetry", package: "owlmetry")
])

Minimum platforms: iOS 16.0, macOS 13.0. Zero external dependencies.

2. Configure

Call Owl.configure() as early as possible -- in your @main App init() or AppDelegate didFinishLaunching:

import OwlMetry

@main
struct MyApp: App {
    init() {
        do {
            try Owl.configure(
                endpoint: "https://ingest.owlmetry.com",
                apiKey: "owl_client_your_key_here"
            )
        } catch {
            print("OwlMetry configuration failed: \(error)")
        }
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

3. Log an Event

Owl.info("App launched")
Owl.error("Failed to load profile", screenName: "ProfileView")
Owl.warn("Slow network response", customAttributes: ["latency_ms": "1200"])

Events are buffered and flushed automatically in batches. They appear in the OwlMetry dashboard within seconds.

Node.js Quickstart

For API servers, job workers, and serverless functions. Requires a backend-platform app and client key from OwlMetry.

1. Install

npm install @owlmetry/node

Zero runtime dependencies. Node.js 20+. ESM only.

2. Configure

Call Owl.configure() in your main entry point, before any other Owl calls:

import { Owl } from '@owlmetry/node';

Owl.configure({
  endpoint: 'https://ingest.owlmetry.com',
  apiKey: 'owl_client_your_key_here',
  serviceName: 'my-api',
  appVersion: '1.0.0',
});

3. Log an Event

Owl.info('Server started', { port: 4000 });
Owl.error('Database connection failed', { host: 'db.example.com' });
Owl.warn('Rate limit approaching', { current: 95, limit: 100 });

Events are buffered in memory and flushed every 5 seconds or when 20 events accumulate. A beforeExit handler auto-flushes on graceful shutdown.

4. Scoped Logging (Optional)

In multi-user backends, create a scoped logger to automatically tag events with a user ID:

const owl = Owl.withUser('user_42');
owl.info('Order placed', { order_id: 'ord_123' });
owl.error('Payment failed', { reason: 'insufficient_funds' });

What's Next

Once events are flowing, explore these areas:

• Events -- Understand log levels, sessions, and timestamps
• Metrics -- Track operation durations and success rates
• Funnels -- Measure conversion across multi-step flows
• CLI -- Query and manage everything from the terminal
• API Reference -- Full REST API documentation