meter

type Client ¶

type Client struct {
	// contains filtered or unexported fields
}

Client is the module-level meter transport AND metric registry. Created eagerly at ms.Init: it POSTs each usage Event to the platform dispatch usage ingress over HTTP (mirroring ms.Emit / ms.Call), in both dev and prod — there is no separate dev sink. Declared metrics live in its registry, keyed by name, so Record resolves a metric by name (mirroring ms.Emits/ms.Emit).

The transport is dispatch-HTTP: MS_DISPATCH_URL (or the dev fallback) routes to the dispatch usage ingress, which re-derives the authoritative attribution and forwards to billing-engine. The HTTP client is ALWAYS built (never nil) — in dev it harmlessly targets the local dispatch, and a transport failure is non-fatal (returned, then logged by the caller, not propagated).

func New() (*Client, error)

func (c *Client) Declare(moduleID string, decl Decl)

func (c *Client) Record(ctx context.Context, name string, value float64) error

func (c *Client) RecordObservation(ctx context.Context, name string, value float64, observation Observation) error

func (c *Client) RecordWithID(ctx context.Context, eventID, name string, value float64) error

type Decl ¶

type Decl struct {
	Name    string
	Kind    Kind
	KindSet bool

	// AggregationKey is empty for ordinary semantics or "subject" when
	// BySubject was selected. Construct declarations through DeclFromOptions.
	AggregationKey string
	Unit           string
	UnitSet        bool
	Price          int64
	PriceSet       bool
	// Label is the metric's optional per-locale display label (ms.Text / ms.T),
	// resolved into the manifest metric entry in core.Meter (mirroring the
	// permission-label path). Zero when undeclared.
	Label i18n.Label
	// UnitLabel is the metric's optional per-locale display label for its Unit
	// (ms.Text / ms.T), resolved into the manifest metric entry in core.Meter
	// (mirroring Label). Zero when undeclared; does not affect Unit's billing
	// semantics.
	UnitLabel i18n.Label
	// contains filtered or unexported fields
}

Decl is the declared shape of a metric: name + kind + optional aggregation, unit, and price. It is what flows into the manifest (see registry.MetricDecl), so the platform can populate its metric_definitions catalog at install/publish.

KindSet / UnitSet / PriceSet report whether each option group was supplied, so Declare can enforce that a custom metric carries a kind and a reserved infra.*/platform.* metric carries price only. For a reserved price-override declaration Kind is empty (KindSet false) and the platform catalog supplies the kind/unit.

Construct a Decl via DeclFromOptions, NOT a struct literal: it has an unexported conflict-tracking field (kindDup) that a literal cannot set, so a hand-built Decl would silently skip the conflicting-kind guard.

func DeclFromOptions(name string, opts ...MetricOption) Decl

type Event ¶

type Event struct {
	V              int       `json:"v"`
	EventID        string    `json:"eventId"`
	AppIDHint      string    `json:"appIdHint,omitempty"`
	ModuleIDHint   string    `json:"moduleIdHint"`
	Metric         string    `json:"metric"`
	Value          float64   `json:"value"`
	RecordedAtHint time.Time `json:"recordedAtHint"`
}

Event is the v1 JSON wire format sent to the platform meter ingress by Record and RecordWithID. RecordObservation uses a private additive v2 envelope so this exported struct remains source-compatible.

There is deliberately NO kind field: a metric's kind (counter/gauge) is declared once via ms.Meter and travels in the manifest, so the platform's catalog is the single authoritative source — a call site can never mislabel a metric's semantic on the wire.

Fields ending in Hint are SDK-asserted values the platform uses for debugging and logging but MUST NOT trust for billing attribution. The authoritative values are re-derived platform-side from the authenticated invoker (Axis 2 of the Milestone D design).

ModuleIDHint is required (no omitempty) even though it is labeled a hint — the "Hint" suffix means "SDK-asserted, not authoritative," not "optional." AppIDHint is omitempty because system-triggered events may have no app context (e.g., cron job running without an AppID in ctx).

EventID is the at-least-once retry dedup key: the platform ingest is idempotent on it (ON CONFLICT(event_id) DO NOTHING), so the SAME logical Record call must reuse the SAME EventID across any transport retry. It is minted ONCE per Record call (before the event is handed to the transport) and the built Event is reused across any transport retry within that call, so a retried delivery is deduped rather than double-counted.

type Kind ¶

type Kind string

Kind is the billing semantic of a declared metric. It is fixed at declaration and recorded in the manifest; it does NOT travel on the wire (the platform's manifest-fed catalog is authoritative). A single Record call emits for both kinds — the kind decides how the platform aggregates.

Kind is set via the Counter / Gauge declaration OPTIONS, not as a positional argument; counterKind / gaugeKind are the internal enum values those options carry into the manifest and registry.

func (k Kind) IsValid() bool

type MetricOption ¶

type MetricOption interface {
	// contains filtered or unexported methods
}

MetricOption configures a metric at declaration time. The KIND is itself an option (Counter / Gauge), alongside BySubject, Unit, and Price. A custom metric MUST pass exactly one kind option; BySubject is valid only with Gauge. A reserved infra.*/platform.* metric may pass ONLY Price (its kind/unit/ aggregation are platform-owned). All other combinations panic at declaration (see Declare).

MetricOption is an INTERFACE, not a func type, on purpose: it lets Counter and Gauge be untyped-style package CONSTANTS rather than reassignable package vars. The SDK is a security boundary — if Counter/Gauge were exported `var`s a hostile module could execute `ms.Counter = nil` and silently break every later Meter call. As const-backed interface values they cannot be reassigned from outside (or inside) the package, while the call site stays parens-free (`ms.Meter(name, ms.Counter, ...)`).

func MetricLabel(l i18n.Label) MetricOption

func MetricUnitLabel(l i18n.Label) MetricOption

func Price(microDollars int64) MetricOption

func Unit(u string) MetricOption

type Observation ¶

type Observation struct {
	EventID    string
	Subject    string
	Metadata   json.RawMessage
	OccurredAt time.Time
}

Observation carries the caller-owned identity and occurrence evidence for a v2 meter event. EventID must be persisted with the billable state change and reused across ambiguous retries. Subject is an opaque end-user identity; Metadata is bounded diagnostic JSON and never an aggregation key. OccurredAt is the original event time, not the delivery/receipt time. The SDK requires it and normalizes it to UTC, but does not compare it with the module process clock. API and Billing own occurrence-window, replay, and billing-period decisions against authoritative server state.

type ServiceCredentialProvider ¶

type ServiceCredentialProvider interface {
	ServiceCredential(context.Context) (string, error)
}

ServiceCredentialProvider supplies renewable outbound module authority. Managed one-shot tasks install one so Record never falls back to an ambient process credential that the task runtime intentionally does not receive.