Querying and Summary

The usage query surface exposed by @downcity/services, and how product-side and admin-side callers read it.

The service exposed by the usage service is usually just usage.

The core idea on this page

The same usage facts are read from two different points of view:

user-side: how much did I use?
admin-side: which cities, models, and users are consuming resources?

Common admin-side reads

const events = await admin.service("usage").get("events");
const summary = await admin.service("usage").get("summary");

Typical roles:

events: detailed debugging or auditing
summary: dashboards, operations overviews, cost snapshots

Common user-side reads

const me = await user.service("usage").get("me");

Typical uses:

usage pages
account settings
plan quota displays

A common admin-side pattern

const summary = await admin.service("usage").get("summary");

return {
  usageSummary: summary,
};

A common user-side pattern

const me = await user.service("usage").get("me");

return {
  currentUsage: me,
};

Why not only expose raw events

Most consumers do not want to aggregate everything themselves. Admin tools often want summary first, and end users usually only want their own usage view.

Common API surface

admin.service("usage").get("events")
admin.service("usage").get("summary")
user.service("usage").get("me")

Common misunderstandings

`summary` is not optional sugar

Aggregated answers are exactly what many dashboards and operations tools need.

Downcity-side callers can read usage too

Usage is not only internal operational data. It can be part of the downcity experience.

Raw events and summary should not be treated as the same thing

Debugging, operations, and end-user UX care about different shapes of the same facts.