What it checks

Telemetry linting runs on the data already in Loggerhead. It looks at the last window of logs, metrics, and spans and lists findings on the Improvements page. Each finding has an impact, a plain explanation, and an action.

The log checks

Finding	Impact	What it means
Error logs missing trace context	High	Error records carry no trace ID, so they cannot link to the request that failed.
Possible sensitive data	High	A log field looks like an email address, a token, or a card number.
Noisy log line	Medium	One log line dominates the volume. It costs money and hides the lines that matter.
Logs with no fields	Medium	The records carry no attributes. The message is the only place a value can be, so you can only do a text search.
Log records miss a field	Medium	Some records have no request.id (or another key) that the rest of the service sets. A query on that field misses them.
Values inside the log message	Medium	Almost every message is different, so the values sit in the text instead of in fields. You cannot group the records or count an event.
Very large log records	Medium	A message holds a payload or a stack trace. Large records cost storage and are slow to read.
Failure text below WARN severity	Medium	A record reads like a failure but sits at INFO. A severity filter and an alert rule both miss it.
Logs with no service name	Medium	The records set no service.name, so you cannot filter them by service.
Service writes too many logs	Medium	One service writes more than 600 records a minute.
Logs point at a trace that is not here	Medium	The record names a trace ID with no matching span, so the link leads nowhere.
Mostly low-signal logs	Low	Most records are DEBUG or TRACE with no fields. They add little in production.

Your log shape

Two checks read the shape of your logs. Logs with no fields wants records that carry attributes at all. Log records miss a field wants the records of one service to keep one shape.

You can declare that shape. Open Settings › Telemetry linting and list the attribute keys every record must carry:

service.name,env,request.id

Leave the field blank and Loggerhead works the shape out on its own. 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. So a service that sets request.id on 190 of 200 records gets one finding that names the 10 records that do not.

The trace checks

Finding	Impact	What it means
Broken traces (the parent span is missing)	High	A span names a parent that never arrived. The trace breaks there, so you cannot see the request that started the work.
Span names hold identifiers	High	Almost every span has a different name, such as GET /search?q=shoes. No platform can group these spans or chart a latency.
Sustained error rate with no alert	High	A service has kept an error rate up with no alert rule on it.
Spans with an impossible duration	Medium	A span ends at or before it starts, or it runs for hours. Latency figures over these spans are wrong.
Background call traced as one-span traces	Medium	A poller or a retry loop starts a new trace on every call. Each trace holds one client span and no request.

The metric checks

Finding	Impact	What it means
High-cardinality label	High	A label has thousands of values, such as a raw URL path. It blows up storage on any platform.
Flatlined metric	Medium	A metric is always zero. The instrument may be wired wrong.
Stale metric	Medium	A metric has no recent data points. The exporter may have stopped.
Counter goes down	Medium	A cumulative counter falls between data points, so every rate over it is wrong.
Metric points have no service name	Medium	The points carry no service.name label, so two services write into one series. A metric Loggerhead scraped itself names its pull source instead, and does not count.
Metric never changes	Low	The series reported one value and never moved. It is a constant, not a measurement.
Duplicate metrics	Low	Two metric names carry the same series. Keep one.
Metric names break the convention	Low	A name has capitals, a space, or both separator styles.

When it runs

The engine evaluates the window on a schedule and when you open the Improvements page. Findings merge across runs, so a finding keeps its state while the problem persists and clears when the problem goes away.

AI insight

AI analysis is a Pro feature. Add your own API key in Settings › AI analysis, then press Run AI analysis on the Improvements page. Loggerhead sends the rule findings and a summary of the window to the model, and adds AI findings next to the rule-based ones. The API key stays in the macOS Keychain. See Settings.