Shipeasy

Metrics

Define what you measure — aggregations, filters, outlier handling, and ratio metrics over your own events.

Production readyOn this page · 6 min readWorks with · Server SDK

A metric is a number computed from a set of events you log. It is the thing you watch while a flag ramps, and the thing an alert rule compares against a threshold. Get the definition right and the rest of the observability story follows.

metric
purchase_conversion5.2%▲ +8.3% vs last week
event stream · user u_42
10:07 page_view
10:09 click
10:14 purchase value=49
collapses to → 1
A metric collapses each user’s event stream into one number — here, conversion drawn over 7 days.

Aggregation functions

A metric query reads one event and reduces it with an aggregation function. Shipeasy has eleven, and the New metric form's Aggregate dropdown offers exactly these:

In the dropdownIn the DSLWhat it computesNeeds a value property
countcountNumber of eventsNo
sumsumSum of a numeric propertyYes
averageavgMean of a numeric propertyYes
minimumminSmallest value of a numeric propertyYes
maximummaxLargest value of a numeric propertyYes
std devstddevStandard deviation of a numeric propertyYes
p50p50Median of a numeric propertyYes
p75p7575th percentileYes
p90p9090th percentileYes
p95p9595th percentileYes
p99p9999th percentileYes

The dashboard says average; the query language spells it avg. Any other percentile is written p(97.5, event, property), and p999 is accepted as shorthand for the 99.9th. A rate — conversion, error rate — is not a twelfth function: it is a division of two counts, count(purchase) / count(session_start). Arithmetic, grouping and time functions on top of these are in the grammar; Aggregation functions says when to reach for which.

When there is no matching event

For a rate, a bucket with no matching numerator event contributes 0. For avg, the average runs over the events that exist, so a bucket with no events has no average rather than a zero. To answer "average among buyers only" explicitly, write it as a division (sum(purchase, revenueCents) / count(purchase)).

Creating a metric

Metrics are defined by a small query DSL — the same one the dashboard generates when you pick aggregation, source event, and filters in the "New metric" form. Run shipeasy metrics grammar for the full spec; the most common shapes:

# conversion on `purchase` — a rate
shipeasy metrics create purchase_conversion \
  --event-name purchase --query 'count(purchase) / count(session_start)'

# revenue
shipeasy metrics create revenue \
  --event-name purchase --query 'sum(purchase, value)'

# average order value
shipeasy metrics create avg_order_value \
  --event-name purchase --query 'avg(purchase, value)'

# sessions
shipeasy metrics create sessions \
  --event-name session_start --query 'count(session_start)'

Or in the dashboard: open Metrics and click New metric.

Filtering events into a metric

You can tighten what counts toward a metric with filters — written inline in the DSL selector as event{attr=value}. Filters run against the event's properties payload before the aggregation:

shipeasy metrics create organic_purchase \
  --event-name purchase \
  --query 'count(purchase{channel="organic"})'

Now organic_purchase only counts purchase events whose channel property equals "organic". Compose multiple predicates inside the same {} with commas — they're ANDed, and or groups them. The operators are =, =~ (a glob, not a regex), the order comparisons > >= < <= on numeric labels, a value set with in (...), and label:* for "the label is set at all". There is one negation and it goes in front of a predicate: not tier="free". Common shapes:

# Web purchases only (exclude mobile app)
'count(purchase{platform="web"})'

# Orders above $10 — numeric label, value written BARE
'sum(purchase{value > 10}, value)'

# Multiple conditions — commas inside {} are ANDed
'count(purchase{platform="web", country="US"})'

Outliers

For sum and avg, a single $50,000 enterprise purchase can swing the number for a whole day. Shipeasy supports two outlier handlers per metric:

  • Winsorise at a configurable percentile (1–99, default 99). Anything above is clamped to the value at that percentile. Default for sum and avg.
  • Cap at an absolute value. Use this when there's a domain-specific ceiling (e.g. a maximum plausible session length).
# Winsorise at p99 (the default; --winsorize-pct 99 is implicit)
shipeasy metrics create revenue \
  --event-name purchase --query 'sum(purchase, value)' \
  --winsorize-pct 99

# Clamp at p95 instead
shipeasy metrics create revenue \
  --event-name purchase --query 'sum(purchase, value)' \
  --winsorize-pct 95

Winsorising is the default and is rarely wrong. The trade-off: clamping reduces variance (good — a steadier series, so a threshold alert stops flapping on one big order) at the cost of slightly understating a real move in the tail (rare).

Ratio metrics

Some questions are inherently ratios — "clicks per impression", "conversion per visit". Write them as a division of two aggregates:

shipeasy metrics create click_through_rate \
  --event-name click \
  --query 'count(click) / count(impression)'

Any two expressions divide, so a ratio can mix count, sum and the rest — sum(order, amount) / count(session) draws fine. The dashboard shows the numerator and denominator alongside the ratio so the math is auditable.

API · metrics.create

Prop

Type

Where to next

▲ NEXT

Wire real events.

A metric is just an aggregation rule. The data that feeds it is your tracking calls — and there are exactly three things you need to get right.

Create a conversion metric
$shipeasy metrics create purchase_conversion --event-name purchase --query 'count(purchase) / count(session_start)'
Add an error-rate metric
$shipeasy metrics create error_rate --event-name client_error --query 'count(client_error) / count(request)'
Was this page helpful?
Updated October 27, 2026✎ Edit this page

On this page