--- title: "Glossary" description: "Every term this documentation uses, in plain words: OTLP, span, collector, cardinality, MCP, and the rest." source: "https://getloggerhead.com/docs/reference/glossary/" --- # Glossary > Every term this documentation uses, in plain words: OTLP, span, collector, cardinality, MCP, and the rest. 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](/docs/collectors/topology-root-and-branches/). ### 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](/docs/telemetry-linting/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](/docs/telemetry-linting/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](/docs/getting-started/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](/docs/mcp-server/setup/). ### 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.