Glossary

Observability has a lot of words for a few ideas. This page defines every term the Loggerhead documentation uses. Each entry stands on its own, so you can read one and go back to what you were doing.

The three signals

Log

One line of text that your application wrote at a moment in time, with a severity and a set of fields. A log answers “what happened”. Example: ERROR checkout payment provider timeout after 3000ms.

Metric

A number your application measured, recorded again and again over time. A metric answers “how much” or “how many”. Example: the number of requests a second, or the amount of memory in use.

Trace

The record of one request as it moves through your software. A trace answers “where did the time go”. A trace of a checkout request shows the call to the cart, the call to the payment provider, and the call to the database, each with its own start time and duration.

Span

One step inside a trace. A trace is a tree of spans. The trace above has a span for the cart call, a span for the payment call, and a span for the database call. A span that fails carries the error.

How data reaches Loggerhead

OpenTelemetry

The open standard for logs, metrics, and traces. Every major programming language has an OpenTelemetry library, and every major observability tool reads its data. Loggerhead speaks OpenTelemetry and nothing else, so it works with software you have already instrumented.

OTLP

OpenTelemetry Protocol: the format OpenTelemetry uses to send data from one place to another. OTLP travels over gRPC (port 4317 by default) or over HTTP (port 4318 by default). When this documentation says “point your app at Loggerhead”, it means “send OTLP to the Loggerhead receiver”.

Receiver

The part of Loggerhead that listens for incoming telemetry. Loggerhead runs one receiver, on 127.0.0.1, inside the app. It is the only thing that writes to the database.

Collector

A program that gathers telemetry and forwards it somewhere. The standard OpenTelemetry Collector runs in Docker or in a cluster and sends what it gathers onward.

Root and branch

Loggerhead’s word for the shape of a collector topology. The root is the receiver inside the Loggerhead app, and it is the only place data comes to rest. A branch is any other collector — one in Docker, one in a Kubernetes cluster, one on another Mac — that forwards into the root. See Collector topology.

Exporter

The part of your application, or of a collector, that sends telemetry out. You configure an exporter with an endpoint, and the endpoint is the Loggerhead receiver.

Scrape

To fetch metrics by asking for them, rather than waiting to be sent them. Some programs publish their numbers at a URL and expect a tool to read that URL on a schedule. Loggerhead can scrape such a URL every 15 seconds, which means those programs need no change at all.

Push and pull

Two directions. Push means your application sends telemetry to Loggerhead. Pull means Loggerhead goes and fetches it, which is what a scrape does.

Words that describe the data

Service name

The name your application gives itself in its telemetry, set by OTEL_SERVICE_NAME. Loggerhead groups and filters by this name, so every application you connect needs one that is different from the others.

Attribute (also called a label or a field)

A named value attached to a log, a metric, or a span. http.route, user.id, and env are attributes. They are what you filter and group by.

Cardinality

The number of different values an attribute takes. env has low cardinality: perhaps three values. user.id has high cardinality: one value per user. High cardinality on a metric label is the most common reason an observability bill grows without warning, because the tool stores one series per combination of values. Loggerhead reports high-cardinality labels as a finding.

Trace context

The two IDs — a trace ID and a span ID — that tie a log line to the request that produced it. A log with trace context can be opened from its trace, and a trace can show every log its spans emitted. A log without trace context is an orphan: you can read it, but you cannot tell which request caused it.

Counter, gauge, and histogram

The three shapes a metric takes. A counter only goes up, and counts things that happened: requests served, errors returned. A gauge goes up and down, and reports a level right now: memory in use, items in a queue. A histogram records a distribution of values, which is what lets a tool report a p95.

p95

The value that 95 percent of measurements fall below. A p95 latency of 400 ms means 95 requests in 100 finished in under 400 ms. It describes a slow request better than an average does, because a few very slow requests barely move an average.

Sampling

To keep some records and drop the rest, on purpose, to cut volume and cost. Loggerhead’s linting suggests sampling for log lines that repeat thousands of times an hour and carry no information.

Retention

How long records are kept before they are deleted. Loggerhead Free keeps a fixed window. Loggerhead Pro keeps data for as long as you choose.

Loggerhead’s own terms

Workspace

One project inside Loggerhead. A workspace owns one receiver port pair (4317/4318 for the first, 4319/4320 for the second) and holds one or more environments. The sender picks the workspace by the port it exports to.

Environment

One deployment of a project: Local, Staging, Production, or a name you choose. Every environment owns one database file, its alerts, and its lint findings. The app reads one environment at a time.

deployment.environment.name

The resource attribute that picks the environment inside a workspace. OpenTelemetry semantic conventions 1.27 gave it this name; the older deployment.environment works too, and the new key wins when a record carries both. A record tagged staging lands in the Staging database. A record with no tag lands in Local. A record whose tag matches no environment lands in Local and raises the “Unknown environment” finding.

Telemetry linting

Loggerhead reads what your application emits and reports the problems with the telemetry itself, not with the application: noise, leaked personal data, unbounded cardinality, logs with no trace context, and metrics that stopped arriving. Each finding carries a written fix. See What it checks.

Finding

One result from telemetry linting: a problem, the service it came from, the field involved, and the fix in plain words. A finding is open while its rule fires. When the rule stops firing it is resolved with a reason and stays on the page for 24 hours. A finding the user hides is ignored.

Linting page

The page in the Loggerhead app that lists the current findings, with tabs for the open, the ignored, and the recently resolved ones.

Lint rule

One check that telemetry linting runs, such as “Noisy logs” or “Stale metric”. Every finding names the rule that made it. A rule has an id (noisy_logs), a signal, a toggle, and thresholds. There are 42 rules. See Tune the rules.

Rules tab of the Linting page

The page in the Loggerhead app that lists every lint rule with its toggle and its thresholds, for the environment the app shows. It sits in the sidebar under Quality.

Threshold

One number or list a lint rule reads to decide whether to fire: a share of the volume, a count of records before the rule fires, a byte limit, a number of seconds, a rate per minute, or a list of names. Each threshold has a default, and the user can edit it per environment on the Rules tab of the Linting page.

Edited (rule)

A lint rule with at least one threshold that differs from its default. The Rules tab of the Linting page marks the rule with a chip and lists it under the Edited tab. Reset to default removes the edit.

Resolved (finding)

A finding whose rule stopped firing. Loggerhead keeps it under Recently resolved for 24 hours with the reason: “Fixed” when fresh data from the service no longer trips the rule, or “Data aged out” when the window no longer holds those records.

Ignored (finding)

A finding the user hid from the Linting page, for good or for 7 days. It does not count, and the Ignored tab takes it back. The Rules tab of the Linting page shows how many findings of each rule are ignored.

Effective port

The port the Loggerhead receiver is actually listening on right now. Loggerhead prefers 4317 and 4318, but another program may already hold one of them, so it moves along a fixed ladder. Always copy the port the app shows. See Ports and the effective port.

MCP (Model Context Protocol)

The open standard that lets an AI coding tool call tools and read data from another program. Claude Code, Cursor, Codex, and Windsurf all speak it. Loggerhead hosts an MCP server inside the app, so your coding tool can read your telemetry and act on what it finds. See Set up the MCP server.

DuckDB

The database Loggerhead stores everything in: one file on your disk, read a column at a time, which is what makes a query over a week of local traffic finish in milliseconds. One process may hold the file, and the Loggerhead app is that process.

Loopback (127.0.0.1)

The network address a machine uses to talk to itself. Traffic to it never reaches a network card, so it never leaves the Mac. The Loggerhead receiver and the MCP server both bind to loopback.