> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingest rules

> Drop or sample logs, spans, and metrics before Squasher stores them. Dropped data is not billed.

Ingest rules remove telemetry that you do not need before Squasher stores it: health-check spans,
debug logs, or a noisy metric. A rule can drop all the rows it matches, or keep a sample of them.

**Dropped data is not billed.** Squasher applies the rules before the usage meter and before
storage. Rows that a rule drops do not count toward your telemetry allowance or overage, and they
are never stored, so they add nothing to storage either.

## How a rule works

Each project can have up to 100 rules. Squasher checks them in order for each row. The first
enabled rule whose signal and conditions match the row decides what happens to it. A row that no
rule matches is kept.

| Field | Description |
| - | - |
| Signal | `logs` (log records), `traces` (spans), or `metrics` (metric points). |
| Action | `drop`: the matching rows are not stored. `sample`: keep a share of them. |
| Sample percent | For `sample`: the share of matching rows to keep, from 0 to 100. |
| Conditions | All the conditions that the rule sets must match. A rule without conditions matches every row of its signal. |
| Include errors | Off by default: error spans and error logs are kept, also when the rule matches them. |

AI observations, agent scores, and product events are never changed by ingest rules.

## Conditions

| Condition | Signal | Matches |
| - | - | - |
| Service | all | The exact `service.name`. |
| Severities | logs | One of `trace`, `debug`, `info`, `warn`, `error`, `fatal`. |
| Span name | traces | The exact route (`http.route`, normalized) or the exact span name. |
| Metric name | metrics | The exact metric name, or a prefix when the value ends with `*` (`http.server.*`). |
| Attributes | all | Up to 10 attribute tests. Each is `eq` (exact text) or `regex` (an RE2 pattern search). |

Squasher looks up an attribute key in the resource attributes first, then in the attributes of the
log record, span, or metric point. A row without the key does not match. Numbers and booleans are
compared as text.

Attribute patterns use RE2 syntax and can have up to 256 characters. Lookahead, lookbehind,
backreferences, and possessive quantifiers are not supported, so a pattern always runs in linear
time.

## Sampling

A `sample` rule keeps about the sample percent of the rows it matches. The choice is
deterministic:

* Traces: by trace ID, so Squasher keeps or drops a whole trace.
* Logs: by trace ID when the log has one, so logs stay with their trace.
* Metrics: by series, so a series is kept or dropped as a whole.

## Error protection

When **include errors** is off (the default), a rule never drops an error span (status `ERROR`) or
an error log (severity `error` or `fatal`). Squasher counts these rows as matched and kept. Turn on
include errors only when you also want to drop the errors that the rule matches.

## When a change applies

Ingest reads the rules of a project with its other ingest settings. A new rule, a change, or a
deleted rule applies within about 60 seconds. Rules change only data that arrives after that.
Data that Squasher already stored stays.

## See the saving before you save

The preview shows what a rule would do, and writes nothing:

* the rows and bytes that the rule matches over the last 7 days,
* the share of those bytes that it would drop (after sampling and error protection),
* the monthly saving: the telemetry charge it removes, plus an estimate of the storage it saves.

Squasher computes the saving from your plan's current prices and allowance. When your telemetry
stays within the plan allowance, the telemetry saving is 0, and the preview says so. The dropped
data still keeps room in your allowance. The preview works on every plan.

After a rule is saved, each rule shows what it matched, dropped, and kept over the last 7 days, and
the monthly saving of the data it dropped.

## Manage rules from the API, CLI, or MCP

```bash theme={null}
squasher ingest-rules preview --name "Health checks" --signal traces --action drop \
  --span-name /health
squasher ingest-rules create --name "Health checks" --signal traces --action drop \
  --span-name /health
squasher ingest-rules create --name "Debug logs" --signal logs --action sample \
  --sample-percent 10 --severity debug
squasher ingest-rules list
```

For the request and response fields, see the [Ingest rules API](https://docs.squasher.ai/api-reference/ingest-rules.md).

## Next steps

> [card] [Usage and budgets](https://docs.squasher.ai/features/usage-and-budgets.md)
>
> See the telemetry you use and set a budget.

> [card] [Ingest rules API](https://docs.squasher.ai/api-reference/ingest-rules.md)
>
> Create, change, order, and preview rules.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.