Settings

Settings live in the app’s own database. The Settings page writes them. The key names below are the names in the database, so a support answer and a log line agree with this page.

Key	Meaning	Default
retention_days	Days to keep telemetry before cleanup.	7
theme	system, light, or dark.	system
ai_provider	none, anthropic, openai, or ollama.	none
ai_model	Model name for the provider.	Provider default
log_required_attributes	The attribute keys every log record must carry, comma separated. Blank means Loggerhead works the shape out from your logs.	unset
ingest_require_auth	Require a bearer token on ingest that does not come from loopback.	false
ingest_token	The accepted bearer token.	unset
ingest_tls_cert_file	PEM certificate for the receiver.	unset
ingest_tls_key_file	PEM key for the receiver.	unset

The log shape

log_required_attributes drives the Log records miss a field check. Type the attribute keys every record must carry, separated by commas, in Settings › Telemetry linting:

service.name,env,request.id

The app accepts at most 32 keys of at most 128 characters each. Leave the field blank and Loggerhead infers the shape of each service instead: a key that 90% or more of a service’s records carry counts as part of that service’s shape, and the records that miss it are the drift. See What it checks.

The AI key

The AI provider key is not a setting. The app stores it in the macOS Keychain, and it never enters the database or a log line. Add it on the Settings › AI analysis page. AI analysis is a Pro feature.

The receiver ports

The receiver prefers 4317 for gRPC and 4318 for HTTP. When another program holds a port, the app moves along a fixed ladder and shows the port in use on the Collectors page. See Ports and the effective port.