Events and metrics

Everything in Unimeter revolves around two ideas. An event is something that happened in your application, and a metric is a rule that tells Unimeter what to do with events of a certain kind. Once you understand these two, the rest of the system falls into place.

What an event is

An event is a record of one thing happening to one customer at one moment. A user made an API call. A virtual machine ran for another minute. Someone uploaded a file. Your service returned a response containing a certain number of bytes. Each of these is one event.

When your application sends an event, it is telling Unimeter four things. Who did this, what did they do, how much of it was there, and when did it happen. The who is represented by an account identifier, which is a number you choose to mean a specific customer or workspace in your system. The what is a metric code, a short string like api_calls or compute_seconds that picks out which metric this event belongs to. The how much is a value, a whole number that means whatever the metric says it means. For counting API calls the value is usually one. For measuring bytes transferred the value is the number of bytes. The when is a timestamp in nanoseconds since the Unix epoch, though Unimeter fills this in automatically if you leave it blank.

Events are append-only. Once stored, they are not edited or deleted. If you made a mistake and want to correct usage for a customer, you send a compensating event rather than going back and changing history. This makes auditing simple and keeps the system honest.

What a metric is

A metric is the definition of a thing you want to measure and the rule for how to measure it. Before you can send events with a certain metric code, you register that metric with Unimeter so it knows what the events mean.

A metric schema has a few fields. The code is the identifier your events reference, like api_calls. The aggregation type tells Unimeter how to combine events for the same customer over a billing period; it might count them, sum their values, remember the maximum, and so on. Optional pieces include filters, which let you break usage down by tag, and alert thresholds, which let you notice when a customer crosses a line.

Billing periods

Every metric has a period that defines how wide each billing window is. Unimeter supports two modes.

Fixed periods divide time into equal-length windows. You choose a duration like 30 days, and Unimeter computes which window an event belongs to by simple division. This is the default and works well for testing or for billing models that do not align with calendar months.

Calendar periods follow the actual calendar. Each month is its own period regardless of whether it has 28, 30, or 31 days. You can also set a custom billing cycle day between 1 and 28. For example, if your billing cycle starts on the 15th of each month, an event on April 20 belongs to the April 15 – May 14 period, while an event on April 10 belongs to the March 15 – April 14 period. Calendar periods are the right choice for most production billing because they match what customers expect to see on an invoice.

When you register a metric, Unimeter remembers it across restarts. The same metric is available to every node in your cluster. If you change the metric definition later by registering it again with different settings, future events use the new rules while past events stay as they were.

How they fit together

Think of a metric as a column heading on a spreadsheet and events as rows you add over time. The metric decides what kind of number goes in the column and whether new values add up, replace, or track the largest. When you ask Unimeter how much a customer has used, it looks at every event that matches the account and metric for the period you care about, applies the aggregation rule, and hands you back the result.

A concrete walkthrough makes this clearer. Imagine a metric called api_calls set to count events with a monthly period. Customer 42 makes a hundred API calls on the first day of the month, so your application sends a hundred events each with account 42, metric api_calls, value 1. Unimeter counts them and remembers that customer 42 is at 100 for this month. Customer 42 makes another fifty calls on the second day, and the total moves to 150. When the billing system asks for customer 42’s api_calls usage for the current month, Unimeter returns 150 immediately. At the start of the next month the counter resets to zero because it is a new billing period.

What comes next

The aggregation types cover more than just counting. Head to Metric types to see the five available modes and when to use each. If you want to break totals down by things like region or feature, read Filters and dimensions. And to get warned when a customer crosses a free-tier boundary or a usage cap, see Alerts.