Metric types
Every metric in Unimeter has an aggregation type that tells the system how to turn a stream of events into one number you can put on an invoice. There are five of them, and each answers a slightly different business question. Most real products use more than one.
Count is the simplest type and the one you reach for first. It looks at all the events for a customer in a period and returns how many there were. The value field of each event is ignored. If you send ten events, the count is ten.
This is the right choice when you charge per occurrence. Per API request, per message sent, per document processed, per notification delivered. Anything where each event represents one billable thing and they all cost the same. If you want to charge different prices for different kinds of requests, you split them into separate metrics rather than trying to make count do more than it was meant to.
A small trap to avoid: count ignores the value you send, so putting anything other than 1 in there is meaningless. Send events with value 1, or leave it zero, and let the count do its job.
Sum adds up the value of every event in the period. If one customer sends events with values 100, 250, and 50, the sum for that period is 400. This is the workhorse when your unit of billing is not a whole event but a quantity inside the event.
Use sum when you charge by volume. Bytes transferred, tokens consumed, seconds of compute, cents of revenue, grams of coffee shipped. Your application measures the quantity, and sum gives you the total for the period.
A subtle point that matters at scale. The running total is a 128-bit number under the hood, which means even if each event value is as large as a 64-bit integer can hold, summing billions of them will not overflow. You do not need to worry about this boundary.
Max keeps only the largest value it has seen in the period. If you send events with values 10, 50, 30, 50 for a customer, the max is 50. Later events with smaller values do not change the result. Only an event with a value greater than the current maximum moves the needle.
This is how you measure peaks. Peak number of concurrent users in the hour. Highest bandwidth seen in the day. Largest file uploaded in the month. Anything where the business cares about the top of the curve and not the average or total.
Max is useful for tiered pricing where customers pay based on which band their peak fell into. You send a measurement event whenever a potential new peak happens and Unimeter keeps only the highest, which is exactly what you query at the end of the period.
Latest
Section titled “Latest”Latest keeps only the most recent value, where most recent is decided by the event timestamp rather than the arrival order. If events arrive out of order for any reason, Unimeter compares timestamps and holds on to the one with the newest time. Events with older timestamps are stored in history but do not overwrite a newer reading.
Use latest for gauges that describe the current state. Current seat count on a workspace. Current level of a prepaid credit balance. Current active plan tier. When you want to know what the state is right now rather than how much happened in total, latest is the type that fits.
Because latest depends on event ordering by time, it is important that your timestamps are correct. If your application has clock drift between servers, consider having Unimeter assign the timestamp by sending a zero value. Unimeter stamps events at the moment of ingestion, which gives you a consistent ordering even when the originating services disagree on time.
Count unique
Section titled “Count unique”Count unique is count with a twist. Instead of counting every event, it counts how many distinct values it has seen. If you send events with values 1, 2, 2, 3, 3, 3, the count is 3 because there are three distinct values. This is what you want for questions like how many unique users logged in this month or how many distinct machines connected to the service.
Count unique has one extra wrinkle. Each event carries an operation type that says whether it is adding a value to the set or removing one. An add event with a value you have already seen does nothing because the set already contains it. A remove event with a value you have seen takes it out of the set and the count goes down by one. This lets you model things like active seats, where users come and go and you need the current count to reflect departures as well as arrivals.
A pattern that comes up often is this. When a user logs in, send a count unique add with their user id as the value. When they cancel or are removed, send a remove event with the same id. Ask Unimeter how many unique users are active, and the answer reflects both joins and leaves.
Choosing the right type
Section titled “Choosing the right type”Think of it this way. If you want to know how many times something happened, use count. If you want to know how much of something was used, use sum. If you want the biggest single occurrence, use max. If you want the current state, use latest. If you want how many different things, use count unique.
Most real products combine several types. An API product might count successful calls with one metric, sum the megabytes transferred with another, track peak concurrent connections with max, and count unique active API keys with count unique. Each metric is independent, and customers can have many metrics at once. You pick the right tool for each number you need.