maqpna usage report
Write a signed usage report and its FOCUS cost export
Synopsis#
maqpna usage report (--period 2027-01 | --from DATE --to DATE) --key KEYURI [--tenant T] [--out DIR]
[--price-file prices.yaml] [--ledger FILE | --gateway URL] [--no-sessions]
[--installation-id ID] [--license FILE] [--default-vcpu 1] [-o json]
signed report.json + report.focus.csv (FOCUS 1.2, list price × quantity) + summaryDescription#
From the help of maqpna usage:
Sandbox seconds come from AgentSessions (status.readyAt to status.outcome.finishedAt, or now while running; sessions that never became ready are not billed). Calls, tokens and approval requests come from the audit ledger (--ledger FILE offline, or the gateway's /v1/audit/records). Namespaces map to tenants through Tenant.spec.namespaces; usage outside any tenant has an empty tenant. Buckets carry counts only.
Finished sessions' sandbox time is also recorded by the gateway in the ledger (usageReporting, decision "usage"), so it survives AgentSession garbage collection; sessions found in the ledger are not counted twice.
Flags#
| Flag | Type | Description | Default |
|---|---|---|---|
--default-vcpu | float | vCPU for sandbox time without CPU data (the report is then flagged estimated) | 1 |
--from | string | period start (RFC3339 or YYYY-MM-DD; with --to) | none |
--gateway | string | gateway base URL (env MAQPNA_GATEWAY_URL; default: the context's gateway) | none |
--installation-id | string | installation id (env MAQPNA_INSTALLATION_ID; default: the kube-system namespace UID) | none |
--key | string | signing key: the audit-checkpoint key (file path or file:///…; pkcs11: and kms:// need a custom build with a backend) | none |
--ledger | string | read the audit ledger from FILE instead of the gateway | none |
--license | string | licence file whose id the report carries (verified against the built-in keys) | none |
--no-sessions | switch | skip the cluster (calls, tokens, approvals and ledger-recorded sandbox time only) | none |
--oidc-token-file | string | file holding an OIDC access token for the admin API (env MAQPNA_OIDC_TOKEN_FILE); wins over --token | none |
--out | string | output directory (report; default .) or file (export; default usage-<period>.json) | none |
--period | string | calendar month YYYY-MM (UTC) | none |
--price-file | string | per-SKU list prices (YAML; default: the Operator edition prices) | none |
--tenant | string | report only this tenant | none |
--to | string | period end, exclusive (RFC3339 or YYYY-MM-DD) | none |
--token | string | static admin token (env MAQPNA_ADMIN_TOKEN; dev/break-glass) | none |
The global flags (--context, -o, --no-color, ...) work with every command.
Examples#
maqpna usage report --period 2027-01 --key checkpoint.key --out reports/What happens when you run it#
- Talks to the gateway:
--gateway, elseMAQPNA_GATEWAY_URL, else the current context's gateway (maqpna context). - Authenticates to the admin API with the token stored by
maqpna login,--oidc-token-file, or a static--token(MAQPNA_ADMIN_TOKEN). - Reads the audit ledger offline with
--ledger FILE: read the audit ledger from FILE instead of the gateway. - Prints a table by default;
-o jsonor-o yamlprint the data, and--jq EXPRfilters the JSON.
Exit codes#
| Code | Meaning |
|---|---|
0 | success |
1 | error (the message says what failed, with a hint when there is one) |
2 | usage error: unknown flag, missing argument or bad value; the synopsis is printed |
3 | a check failed, a change is blocked, or a result did not match (tamper, policy mismatch) (not used by this command) |