--- title: "Settings" description: "Every setting the app stores, its key, and its default." source: "https://getloggerhead.com/docs/reference/settings/" --- # Settings > Every setting the app stores, its key, and its default. Most settings belong to one environment. They live in the database of that environment, and the **Data** tab of 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 | | `log_required_attributes` | The attribute keys every log record must carry, comma separated. Blank means Loggerhead works the shape out from your logs. The **Log shape drift** rule on the Rules tab of the Linting page edits it. | unset | | `lint_rule_` | The rule settings of an older version, per environment. The app copies them into the workspace file once. See below. | 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 settings of the Mac The AI settings belong to the whole Mac, as the AI key in the keychain does. Every workspace and every environment uses them, and a switch to another environment does not change them. Loggerhead keeps them in its own preferences, by the key names below. The **AI** tab of the **Settings** page writes them. | Key | Meaning | Default | | --- | --- | --- | | `ai_provider` | `apple` (Apple Intelligence on this Mac), `none`, `anthropic` (an Anthropic-compatible API), or `openai` (an OpenAI-compatible API). The old value `ollama` works as `openai`. | `apple` | | `ai_model` | Model name for the provider. The OpenAI-compatible type has no default, so it needs a value. | Provider default | | `ai_base_url` | The base URL of the cloud API, for example `https://openrouter.ai/api/v1`. It must use `https`, or `http` on `localhost`. See [Set up an AI provider](/docs/telemetry-linting/ai-providers/). | Default URL of the API type | | `ai_custom_masks` | The masks you add on the **AI** tab, as a JSON array of `{"name", "pattern"}` objects. Before a cloud model gets a sample of your telemetry, each match becomes ``. | unset | Older versions kept the AI settings in the database of each environment. The first start of a newer version copies the AI settings of the environment that opens first, one time. **Appearance** (`system`, `light`, or `dark`) also belongs to the Mac. It is not a database setting. ## The lint rules The lint rule settings belong to the workspace, not to one environment. They are in `lint-settings.json` in the workspace folder, `workspaces//lint-settings.json`. The file has one entry per rule that is not at its defaults, under `rules`, by the rule id from [Tune the rules](/docs/telemetry-linting/tune-the-rules/): ```json {"rules":{"noisy_logs":{"enabled":false,"overrides":{"noisyLogRatio":0.4,"minLogVolume":250}}}} ``` | Field | Meaning | | --- | --- | | `enabled` | `false` when the user switched the rule off. The rule then skips every scan. | | `overrides` | The threshold values the user changed, by config field name. A field that is absent keeps its default. A share is a number between 0 and 1, a duration is a number of seconds, and a list is a JSON array of strings. | The file also holds `exceptions`, `ignores`, and `changes`: the exceptions of each rule, the findings the workspace ignores, and the last 200 changes with their source (`mcp` or `ui`), time, reason, and the value before and after, which Undo reads. An entry with an unknown rule id, or an override on a field the rule does not read, is ignored and reported as a warning on the Rules tab of the Linting page. A file that does not parse is kept as `lint-settings.json.bad`, and the rules run with their defaults. Before the settings moved to the workspace, each environment's database kept one row per rule, `lint_rule_`, with the same JSON value. The first time the app opens a workspace with no settings file, it copies the rows of the open environment into the file. The MCP tool `list_lint_rules` reads the settings and reports the value in force next to the default. The MCP tools `set_lint_rule_enabled`, `set_lint_threshold`, `reset_lint_threshold`, `add_lint_exception`, `remove_lint_exception`, `ignore_finding`, and `unignore_finding` change them, with a reason. See the [Tools reference](/docs/mcp-server/tools-reference/). ## The log shape `log_required_attributes` drives the **Log records miss a field** check. It kept its own key when the lint rules moved to their page, so an older setting still works. Type the attribute keys every record must carry, separated by commas, in the **Required fields** threshold of the **Log shape drift** rule on the **Rules** tab of the **Linting** page: ``` service.name,env,request.id ``` The app accepts at most 32 keys of at most 128 characters each. The rule saves the list in the workspace file, and `log_required_attributes` applies only while the workspace sets no list. Leave the field blank and Loggerhead infers the shape of each message instead: a key that 90% or more of the records of one message carry counts as part of that message's shape, and the records that miss it are the drift. The numbers and ids in a message do not count, so `Batch 3 of 15 complete` and `Batch 4 of 15 complete` are one message. See [What it checks](/docs/telemetry-linting/what-it-checks/). ## The AI masks `ai_custom_masks` holds the masks that you add in **Settings › AI › Masks for cloud models**, as a JSON array: ```json [{"name":"account","pattern":"ACC-\\d{8}"}] ``` Before a cloud model gets the telemetry, each match of `pattern` becomes ``. Your masks apply before the built-in masks, which are not stored. A name is 1 to 32 characters: lower-case letters, digits, `_`, or `-`. A pattern is a regular expression of at most 500 characters, and it must not match an empty text. The app keeps at most 20 masks. See [What it checks](/docs/telemetry-linting/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** tab. 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](/docs/getting-started/ports-and-the-effective-port/).