Configuration

Configuration

Configure LogNorth for your environment.

Server Configuration

Environment variables for the LogNorth server:

Variable	Description	Default
LOGNORTH_PORT	HTTP port	8080
LOGNORTH_STORAGE_PATH	Data directory	/data

Alerts

Get notified when errors occur. Choose your notification channel in Settings.

Option 1: ntfy.sh (Recommended)

Free push notifications to your phone or desktop. No account required.

1. Install the ntfy app on your phone or desktop
2. Subscribe to a topic with a random name (e.g., lognorth-abc123)
3. In LogNorth Settings, select “ntfy.sh” and paste the URL: https://ntfy.sh/lognorth-abc123

Option 2: Email (SMTP)

Use your own mail server for email alerts.

Setting	Description
SMTP Host	Your SMTP server (e.g., smtp.gmail.com)
SMTP Port	Usually 587 (TLS) or 465 (SSL)
SMTP Username	Your email or SMTP username
SMTP Password	Your email password or app password
From Address	Sender email address
To Address	Where to send alerts

API Authentication

Every API request requires an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Create API keys in the LogNorth web UI under Settings.

Event Schema

One schema for everything — HTTP requests, business events, errors, background jobs.

Field	Type	Description
message	string	Required. What happened.
timestamp	string	ISO 8601. Always set by the SDK.
duration_ms	int	How long it took (set by middleware).
trace_id	string	Groups related events. Auto-generated per request by middleware.
context	object	All metadata. Any key-value pairs you want.

Examples

HTTP request (sent by middleware automatically):

{
  "message": "POST /users → 201",
  "timestamp": "2024-01-15T10:30:00Z",
  "duration_ms": 45,
  "trace_id": "a1b2c3d4e5f67890",
  "context": {
    "method": "POST",
    "path": "/users",
    "status": 201
  }
}

Business event (your code, inside a request):

{
  "message": "User signed up",
  "timestamp": "2024-01-15T10:30:00Z",
  "trace_id": "a1b2c3d4e5f67890",
  "context": {
    "user_id": 123,
    "plan": "pro"
  }
}

Same trace_id as the HTTP request — automatic when using middleware.

Error (SDK captures everything):

{
  "message": "Checkout failed",
  "timestamp": "2024-01-15T10:30:00Z",
  "trace_id": "a1b2c3d4e5f67890",
  "context": {
    "error": "connection refused",
    "error_class": "ConnectionError",
    "error_file": "checkout.go",
    "error_line": 42,
    "error_caller": "processPayment",
    "stack_trace": "..."
  }
}

Background job (no request context):

{
  "message": "SendWeeklyDigest completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "duration_ms": 3200,
  "context": {
    "job": "SendWeeklyDigest"
  }
}

Key points

• timestamp is always set by the SDK. Never set it manually.
• trace_id is auto-generated per request by middleware. All logs within the same request share it.
• duration_ms is top-level, not in context. Set automatically by middleware.
• Background jobs don’t get a trace_id unless you’re inside middleware.

Context

Context is a flat JSON object. Put anything in it. Some keys have special meaning:

Key	Type	What it does
method	string	HTTP method. Shown in the log UI.
path	string	Request path. Shown in the log UI.
status	int	HTTP status. >= 500 marks the event as an error.
job	string	Background job name. Shown instead of method/path.
error	string	Error message. Marks the event as an error.
error_class	string	Error type (e.g. TypeError). Marks as error. Used for issue grouping.
error_file	string	Source file. Used for issue grouping.
error_line	int	Line number. Used for issue grouping.
error_caller	string	Function name. Shown on issue detail.
stack_trace	string	Full stack trace. Shown on issue detail.

Everything else (user_id, ip, order_id, whatever you send) is stored and searchable.

SDKs populate the error fields automatically when you call error(). You don’t set them manually.

Error Detection

LogNorth automatically sets is_error = true when:

• context.error exists and is not empty
• context.error_class exists and is not empty
• context.status >= 500

No need to manually flag errors.

Data Retention

Configure how long to keep events in Settings. Options: 7 days, 30 days, 90 days (default), 6 months, 1 year, or forever.

Older events are automatically deleted daily. Set to “Forever” to disable automatic deletion.

Storage

LogNorth uses SQLite. One file. Simple to backup, move, or restore.

Size per event: ~0.3 KB average

Traffic	Events/day	90 days	1 year	5 years
Low	1,000	25 MB	100 MB	500 MB
Medium	5,000	125 MB	500 MB	2.5 GB
High	20,000	500 MB	2 GB	10 GB

A $5 VPS with 25GB storage handles years of data for most apps.

Backups

Your database lives on your server. If the server dies, data dies too.

Pick one off-server strategy:

Strategy	Effort	Protection
VPS snapshots	Low	Your provider handles it. Enable weekly snapshots in your VPS dashboard.
rsync to another server	Medium	Cron job copies database nightly.
Litestream	Medium	Real-time replication to S3. Point-in-time recovery.

VPS snapshots are the simplest. Most providers (Hetzner, DigitalOcean, Linode) offer them for a few dollars/month.

Litestream streams every SQLite change to S3-compatible storage. See litestream.io.