Maple Harness home

Maple Harness 2.6.2 released! What's new in 2.6.2

Single userTeams & hubs

One person, one machine: the agent, the proxy and your own usage.

Several people, from one shared proxy up to a hub of hubs.

Your usage data #

On this page
  1. In plain words
  2. Where the files are
  3. How long it is kept
  4. Turn it off
  5. From the setup page
  6. Query it directly with DuckDB
  7. Named views
  8. Lots of history? Use the DuckDB file or monthly Parquet
  9. Several pods? Query Postgres
  10. Cost and savings
  11. The usage record schema
  12. The events log
  13. Export to CSV or Parquet
  14. Filter your data
    1. Requests with no person
  15. Keep it tidy: prune
  16. Wire it into Grafana

The usage log is on by default: one JSON object per request, in your own files — not locked inside Maple. It holds counts and labels only (model, tokens, cache figures, AI units, timing), never prompts or answers. This page is about where it lives, how long it is kept, and actually using that data: querying it directly, exporting it for another tool, and wiring it into Grafana. The settings are server.usage_ledger and server.usage_retention_days — see The usage log.

New to it? See and filter your usage is the guide: what is recorded, usage query with examples, filtered exports, the DuckDB views and the events log. This page is the reference. For where the data can live (the daily files, PostgreSQL, a lake) see Your data, and for tested recipes Query your usage.

In plain words #

  • What it is. The reference for the usage log: where the files are, how long they are kept, every column, and how to export them or wire them into Grafana.
  • What to do. On the setup page, Data & storage, the Usage data card moves, keeps, exports or prunes the log without a terminal. The guide for first questions is See and filter your usage.

Where the files are #

By default the log is in the usage folder of your Maple Harness config folder (~/.config/maple-harness/usage/ on Linux and macOS), one file per UTC day with a name nothing else uses: maple_harness_proxy_usage_ledger-2026-09-28.jsonl, maple_harness_proxy_usage_ledger-2026-09-29.jsonl, and so on. The folder is created private to you the first time the proxy writes to it.

To put it somewhere else, set server.usage_ledger to a path, or use Move on the setup page's Usage data card: usage_ledger: /data/maple/usage.jsonl writes usage-2026-09-28.jsonl and the rest next to it: the daily files are always named after the path, with the day before the extension. A path you set yourself, including the usage.jsonl in your config folder that the earlier Turn on button chose, keeps working exactly where it is, with the same names; nothing is moved or renamed. Moving the log starts new daily files in the new place and leaves the files already written where they are. If you have a plain, undated usage.jsonl from before daily files existed, it is left exactly where it is: still readable, just not written to going forward.

How much disk it takes, as an estimate: about 0.25 KB for a request with no cost or savings figures and about 0.65 KB for a priced one (measured on sample lines), so 1,000 requests a day for 90 days is roughly 22 to 58 MB. The Usage data card and maple-proxy usage status show what your own files take.

Each line is one request: the model, provider, tokens, cache figures, AI units, timing, who asked (a client label, and the session it belongs to), and what the proxy estimates it saved and cost — never prompt or answer content. The exact field list is in Files and environment.

How long it is kept #

server.usage_retention_days (Keep on the Usage data card) is how many days of daily files to keep. Older daily files are deleted when the proxy starts and then once a day, the proxy logs one line saying what it removed, and each cleanup that deletes files is recorded in the audit log (how many, and the folder). 0 keeps everything.

Left unset, it is 90 days in the default place (in the usage folder the proxy created, only files named exactly maple_harness_proxy_usage_ledger-YYYY-MM-DD.jsonl). For a path you chose yourself, nothing is deleted automatically until you set Keep; the card says so ("Automatic cleanup is off for a custom location"). Only the log's own dated files next to the configured path are ever deleted, and only when they are empty or start with a usage record: never today's file, never the plain undated file from earlier releases, never any other file in the folder, never a link, and never a file that also has another name (a hard link). If the folder you chose is itself a link (to a synced folder, say), cleanup follows it, as the log does; the default folder is never a link. Budgets count only today, so a shorter retention does not change them. A change on the card applies without a restart, from the next cleanup.

A path you give for the log must be a full path, or start with ~/ for your home folder.

Turn it off #

Press Turn off on the Usage data card (or on the one-time notice the setup page shows after upgrading), or set usage_ledger: off in config.yaml. For one run of the proxy, CCH_USAGE_LEDGER=off in its environment does the same (and CCH_USAGE_LEDGER=/some/path sends that run's log elsewhere). Nothing already written is deleted. Only off turns it off: an empty usage_ledger: "", which earlier releases saved while the log was off, now means the default place, so an upgraded install starts logging. With the log off, budgets restart from zero whenever the proxy restarts.

After upgrading, the setup page shows a one-time notice (at the top of the page and on the Usage data card) while the log is on because of the default: OK keeps it on, Turn off turns it off. Either answer is saved in config.yaml, so no other browser shows it again, and the proxy logs one line at start saying the log is on by default.

From the setup page #

The proxy's setup page has, on its Data & storage tab, a Usage data card with everything below without a terminal: whether the log is on and where; how much disk the daily files take, how many there are and the days they cover, with an estimate at the retention limit once there is a whole day of data; Location (Move, Use the default place, Turn off); Keep, the retention in days; an Export button that downloads CSV or Parquet for an optional range of days; and Remove old days, which shows you exactly which files would go and deletes them only after you confirm that list. It uses the same code as maple-proxy usage, so the card and the command always agree on which requests a range covers and which files a prune removes. If the usage log is off, the card says so and has a Turn on button.

The Usage data card on the Data & storage tab: where the log is kept, its size on disk, Location, Keep (days), Analytics files, Export and Remove old daysThe Usage data card on the Data & storage tab: where the log is kept, its size on disk, Location, Keep (days), Analytics files, Export and Remove old days
The Usage data card on the setup page's Data & storage tab after a first day of use.

Query it directly with DuckDB #

This is the fastest way to ask a real question of your own data — no export step, no code. DuckDB reads JSON Lines natively. Start by creating a typed view named usage:

maple-proxy usage schema --format sql > usage.sql
duckdb -c ".read usage.sql" -c "SELECT model, count(*) AS requests, sum(ai_units) AS ai_units FROM usage GROUP BY model ORDER BY ai_units DESC"

usage schema --format sql prints a CREATE OR REPLACE VIEW usage AS ... statement over every daily file (it finds them the same way usage export does; --path names the log directly). The view declares every column and its type, so it has the same shape on every day: a day with only local models, which report no AI units, has ai_units as 0, not a missing column. Keep usage.sql somewhere fixed and add .read /full/path/to/usage.sql to ~/.duckdbrc, and every duckdb session has the view.

Why not read_json_auto: it guesses the columns from the data it samples. A field the log leaves out when it is empty (ai_units for a local model, error when nothing failed, the labels) is simply not a column on a day that never has it, so a query naming it fails with Referenced column "ai_units" not found. Declaring the columns avoids that.

With the view in place, queries are plain SQL:

SELECT model, count(*) AS requests, sum(ai_units) AS ai_units
FROM usage
GROUP BY model
ORDER BY ai_units DESC;
SELECT date_trunc('day', "at") AS day, provider,
       sum(input_tokens) AS input_tokens, sum(cached_tokens) AS cached_tokens, sum(ai_units) AS ai_units
FROM usage
WHERE "at" >= TIMESTAMPTZ '2026-09-20'
GROUP BY ALL
ORDER BY day, provider;

at is a reserved word in DuckDB, so write it in double quotes. In the view it is a timestamp; in the files it is ISO-8601 text in UTC. To narrow by file instead, name fewer files: --path still takes the base path, but a hand-written query can use a narrower glob built the same way from your log's name, such as maple_harness_proxy_usage_ledger-2026-09-2*.jsonl in the default place (or usage-2026-09-2*.jsonl for a log you named usage.jsonl).

Without maple-proxy at hand (on another machine, say), declare the columns you use yourself and give the ones a line may leave out a default:

SELECT model, count(*) AS requests, sum(COALESCE(ai_units, 0)) AS ai_units
FROM read_json('~/.config/maple-harness/usage/maple_harness_proxy_usage_ledger-*.jsonl',
               format = 'newline_delimited', ignore_errors = true,
               columns = {'at': 'VARCHAR', 'model': 'VARCHAR', 'ai_units': 'DOUBLE'})
WHERE "at" IS NOT NULL
GROUP BY model
ORDER BY ai_units DESC;

ignore_errors and the WHERE skip a line cut short when the proxy was stopped mid-write, as the proxy's own readers do. maple-proxy usage schema --format duckdb prints the full columns value for every field.

Named views #

For the questions most people ask, --views adds ready-made views to the usage view:

maple-proxy usage schema --format sql --views > maple.sql
duckdb -cmd ".read maple.sql"

The output starts with exactly what usage schema --format sql prints without --views, then makes a schema named maple (CREATE SCHEMA IF NOT EXISTS maple) and the views inside it. Nothing outside that schema is created or replaced, so a view of yours named requests or sessions stays as it is, and --format sql without --views prints the same as before. The views read maple.usage, a copy of the usage view, so they keep working if you change your own usage view. --source csv or --source parquet with --path FILE makes the same views over an export; --source parquet-monthly and --source postgres are below.

ViewOne row perWhat it has
maple.requestsrequestevery column of usage, plus day (the UTC day), outcome (warming, cached, error, fallback or ok), and person reading unattributed where the line names nobody
maple.daily_spendUTC day, provider, model, person and teamrequests, the four token counts, AI units, and the list-price estimate with its currency; the proxies that recorded them and the account sources
maple.sessionssession idfirst and last request, requests, the models that answered, AI units, the list-price estimate, and cache_hit_rate: the share of the requests the prompt cache classified that were a hit
maple.peopleperson and teamrequests, AI units, the list-price estimate, the days active, first and last request; the first proxies they asked and the account sources
maple.provider_healthprovider, model and UTC hourrequests that reached a provider, errors and the error rate, errors_by_class (a map from error_class to a count), and the median and 95th percentile of the duration, the time spent waiting on the provider and the time to the first token
maple.alertsalert eventwhen, state (fired or resolved), scope, rule, level and the measured value, from the events log
maple.eventseventevery line of the events log
maple.child_usageline sent up by a proxy belowthe same columns as usage, for a hub; empty otherwise
maple.hopslineusage and child_usage together: one line for each proxy a request passed through
maple.client_requestsclient requestits first try on the proxy where it was asked, with ai_units_spent and cost_estimated_spent counted once, where they were spent, and lines
maple.proxiesproxy and how its lines arrivedlines, client requests that started there, lines of requests that came through other proxies, the first proxies, running copies, and spend counted where it was spent
maple.originsfirst proxy, person and teamclient requests and their spend, counted once

Things to know when reading them:

  • Each try of a request that fell back to another model is its own line, so requests counts tries.
  • A column added in a later schema version is NULL on older lines, never 0: lines before version 4 have no time to the first token or time on the provider, so provider_health reports those percentiles from version 4 lines only, and ttft_measured says how many requests each one comes from. The time to the first token is measured for streamed requests only.
  • person reads unattributed where no person was recorded (see Requests with no person), so maple.people has an unattributed row once any request has none.
  • The list-price estimate (cost_estimated) is an estimate from published prices, not a bill, and is separate from AI units: never add the two together.
  • maple.alerts and maple.events read the events files next to the usage log. An export holds no events, so over an export they are empty, and they are empty until the proxy has written an events file (print the views again after that).

What each one is for, as a query:

-- How did requests end, day by day?
SELECT day, outcome, count(*) AS requests
FROM maple.requests
GROUP BY ALL
ORDER BY day, outcome;
-- Spend by day and provider.
SELECT day, provider, sum(requests) AS requests, sum(ai_units) AS ai_units, sum(cost_estimated) AS cost_estimated
FROM maple.daily_spend
GROUP BY ALL
ORDER BY day, provider;
-- The ten sessions that used the most AI units.
SELECT session, first_at, last_at, requests, models, ai_units, cache_hit_rate
FROM maple.sessions
ORDER BY ai_units DESC
LIMIT 10;
-- Who used what.
SELECT person, team, requests, ai_units, days_active
FROM maple.people
ORDER BY ai_units DESC;
-- Hours when a provider's error rate was above 5%, with the classes of error.
SELECT provider, model, hour, requests, errors, round(error_rate, 3) AS error_rate, errors_by_class,
       ttft_p50_ms, ttft_p95_ms, ttft_measured
FROM maple.provider_health
WHERE error_rate > 0.05
ORDER BY hour DESC, provider;
-- Alerts, newest first.
SELECT "at", state, scope, rule, level, value
FROM maple.alerts
ORDER BY "at" DESC;
-- Settings changed, newest first (key paths only).
SELECT "at", subject AS setting, code, value, detail
FROM maple.events
WHERE kind = 'config.change'
ORDER BY "at" DESC;

Lots of history? Use the DuckDB file or monthly Parquet #

A view over the daily files reads one file for every day. That is quick for weeks of data; over months or years, and on a hub that also keeps what the proxies below it send up, it gets slower. Two ways to read far fewer files:

Monthly Parquet files. maple-proxy usage compact packs each month's closed UTC days into one Parquet file (usage-2026-09.parquet, plus events-2026-09.parquet and children-2026-09.parquet when there are events or lines from below), in a folder named analytics inside the usage log's folder. Today's file is never packed. Run it again whenever you like: only a month whose daily files changed is written again (--rebuild writes them all, --month 2026-09 only one).

maple-proxy usage compact
maple-proxy usage schema --format sql --views --source parquet-monthly > maple.sql
duckdb -cmd ".read maple.sql"

The views read the monthly files plus every daily file they do not cover (today's, and a day that changed since it was packed), so they hold exactly what the views over the daily files hold. The list of files is the one there was when the SQL was printed: print it again after the next compaction, or the next day.

A DuckDB file. maple-proxy usage duckdb loads your usage into one file, maple_usage.duckdb in the same analytics folder, with two tables, usage and events, and every named view inside it. It runs your own duckdb command line (install it; nothing is downloaded for you, and --duckdb names one that is not on your PATH). Run it again to refresh it: only what the daily files gained since the last run is read.

maple-proxy usage duckdb
duckdb ~/.config/maple-harness/usage/analytics/maple_usage.duckdb
SELECT * FROM maple.daily_spend ORDER BY day DESC LIMIT 20;
  • The usage table holds this proxy's lines and, on a hub, those its children sent up (source is child); maple.usage and maple.child_usage split them as the views over the files do. Both tables have two more columns, loaded_from (the daily file a row came from) and loaded_at; the views leave them out.
  • The file follows the log: rows of a daily file that the cleanup deleted leave at the next refresh, and a file replaced under its own name is read again from the start.
  • A refresh works on a copy and puts it in place only when it is complete: a run that fails leaves the file as it was, and a session that has it open keeps reading what it opened. --dry-run says what a refresh would load.
  • It is named maple_usage.duckdb because DuckDB names a database after its file, and a database named maple would make maple.daily_spend ambiguous.

Or let the proxy keep them. Analytics files on the Usage data card (server.usage_analytics) refreshes them once a day, after the cleanup: parquet the monthly files; duckdb those and the DuckDB file; lake those and a DuckLake. It is off unless you choose it, and the DuckDB file and the lake need the duckdb command line installed.

The monthly files and the DuckDB file are copies, private to you like the daily files. A monthly file is deleted as soon as a day it was made from is deleted (by the cleanup, usage prune or Remove old days), and a month whose daily files changed is not read until it is packed again. Nothing that lists or deletes the daily files ever looks inside analytics. To stop, set Analytics files to off and delete the analytics folder.

Too many open files? DuckDB keeps a few files open for each thread it runs, however many daily files there are. If a query stops with that error, lower its threads (SET threads = 4;), raise the limit in the shell that starts duckdb (ulimit -n 4096), or query the DuckDB file, which is one file.

Several pods? Query Postgres #

In central mode (Kubernetes) every replica writes to one PostgreSQL, so there are no daily files on any one machine. --source postgres prints the same named views over the shared tables, through DuckDB's postgres extension:

export MAPLE_PG_DSN='host=postgres.maple.svc dbname=maple user=analyst'
maple-proxy usage schema --format sql --views --source postgres --dsn-env MAPLE_PG_DSN > maple-pg.sql
duckdb -cmd ".read maple-pg.sql"

The connection string is read from the variable each time a view is queried; it is never written into the SQL. Use a role that can only read, and keep its password out of the string (in PGPASSWORD or a .pgpass file): DuckDB prints the connection string when it cannot connect. (Maple's own commands hide it in the errors they show.) The views read the stored lines the way the views over the files read the daily files, so the two agree; --pg-schema names a schema other than public. For history beyond what PostgreSQL keeps (storage.retention_days), move it into a lake.

Cost and savings #

Each line carries what the request cost and, as estimates, what the proxy's techniques saved and cost on it: the same figures the setup page's Savings card and maple-proxy savings show, per request. The card adds them up; the log keeps them one request at a time, so you can add them up your own way. A sum over a day matches the card's figures for that day (the card's "today" starts at your local midnight, while at is in UTC; see below).

  • What a request cost. ai_units is what the provider billed, when it reports it (measured). cost_estimated is an estimate at a provider's published list prices, in the currency named in cost_currency, for a provider set up to give one. A request has one or the other: keep them in separate columns, never add them together.
  • What the techniques saved. Every *_estimated column is an estimate, never a measurement. A saving is measured against what the same request would likely have cost without that technique, valued at prices estimated from your own requests' costs; costs of the techniques are in their own columns so you can subtract them. priced says whether a value could be put on the request at all: when it is false the AI-unit columns are 0 because nothing was valued, not because nothing was saved.
  • The headline. The Savings card's headline counts only the prompt cache and trimming: cache_saved_estimated + trim_saved_estimated, minus cache_write_surcharge_estimated + trim_cost_estimated, minus the ai_units of the proxy's own cache-warming requests (warming = true; the query's warming_ai_units). The other techniques are on their own lines, not in the headline. What you would have spent without them is ai_units plus that net. A sum of these columns over a day is exactly the card's headline for that day.
  • Cache warming. A request the proxy sent itself to keep a cache alive has warming = true; what it cost is its ai_units, and warming_expected_saved_estimated is the saving expected when it was sent, not a confirmed one.
  • Response cache. A request answered from the proxy's response cache (response_cache: on) has cached_response = true and 0 tokens and 0 ai_units: nothing was sent to the provider. response_cache_saved_estimated is an estimate of what the repeat would have cost, the lower of what the original request cost and what it would have cost with all of its input read from the prompt cache. It is on its own line on the Savings card, not in the headline.
  • Sessions. session groups a Maple Harness session with its subagents (they send the session's id), the same grouping as the setup page's Sessions card. conv is narrower: it groups the requests of one conversation, so a subagent is its own conv. Other clients can send the same header; lines from a client that does not, and cache-warming requests, have no session.

A request for a model no provider here serves has a line too: an error (error_class model_not_found) with no provider, tokens or AI units. fallback is true on every fallback attempt, answered or not; the query's fallbacks metric counts them all, while its outcome names one per line, an error first.

A request that failed but still reported AI units was billed for them: the Savings card's "You spent" and the AI units tile count them, as a plain sum(ai_units) does. The techniques' estimates are only ever on requests that completed.

Cost per day, in AI units and in list-price estimates:

SELECT date_trunc('day', "at") AS day,
       sum(ai_units) AS ai_units,
       sum(cost_estimated) AS cost_estimated, any_value(cost_currency) AS currency
FROM usage
WHERE error IS NULL
GROUP BY ALL
ORDER BY day;

Cost per model:

SELECT provider, model, count(*) AS requests,
       sum(ai_units) AS ai_units, sum(cost_estimated) AS cost_estimated
FROM usage
WHERE error IS NULL
GROUP BY ALL
ORDER BY ai_units DESC;

Cache saved per day (estimated), next to what the cache writes cost and what was spent:

SELECT date_trunc('day', "at") AS day,
       sum(ai_units) AS spent,
       sum(cache_saved_estimated) AS cache_saved_estimated,
       sum(cache_write_surcharge_estimated) AS cache_write_cost_estimated,
       count(*) FILTER (WHERE NOT priced) AS requests_not_valued
FROM usage
WHERE schema_version >= 2 AND error IS NULL
GROUP BY ALL
ORDER BY day;

What trimming saved against what it cost (estimated):

SELECT date_trunc('day', "at") AS day,
       sum(trim_saved_tokens_estimated) AS tokens_left_out,
       sum(trim_saved_estimated) AS saved_estimated,
       sum(trim_cost_estimated) AS cost_estimated,
       sum(trim_saved_estimated) - sum(trim_cost_estimated) AS net_estimated
FROM usage
WHERE schema_version >= 2 AND error IS NULL
GROUP BY ALL
ORDER BY day;

How often the response cache would have answered: requests identical to one sent within the last five minutes (the same request_hash: the same request, from the same client, to the same provider account), by client and model. maple-proxy usage cache-potential answers the same question without DuckDB, following exactly what the cache would do; this query is the simpler version, which compares each request with the one just before it:

WITH r AS (
  SELECT client, provider, model, request_hash, "at", ai_units, cached_response,
         lag("at") OVER (PARTITION BY request_hash ORDER BY "at") AS previous
  FROM usage
  WHERE request_hash IS NOT NULL AND NOT warming
)
SELECT client, provider, model, count(*) AS requests,
       count(*) FILTER (WHERE previous >= "at" - INTERVAL 5 MINUTE) AS repeats,
       count(*) FILTER (WHERE cached_response) AS answered_from_cache,
       sum(ai_units) FILTER (WHERE previous >= "at" - INTERVAL 5 MINUTE) AS repeats_ai_units
FROM r
GROUP BY ALL
ORDER BY repeats DESC;

Only requests recorded by a release with version 3 of the schema carry request_hash, and a request with images or whose last message is a tool call or a tool result never does. The count is an upper bound: the cache also needs the request to be repeatable and the earlier answer to have finished normally, which the log does not record.

Spend per conversation and per session:

SELECT session, conv, count(*) AS requests, min("at") AS first, max("at") AS last,
       sum(ai_units) AS ai_units, sum(cost_estimated) AS cost_estimated
FROM usage
WHERE error IS NULL
GROUP BY ALL
ORDER BY ai_units DESC
LIMIT 20;

session is a random id, not the name you gave the session. Each saved Maple Harness session keeps its id in its own file, in the folder maple-harness sessions path prints, so you can put the names next to it:

SELECT coalesce(s.name, u.session) AS session, count(*) AS requests, sum(u.ai_units) AS ai_units
FROM usage u
LEFT JOIN read_json('~/.config/maple-harness/sessions/*.json',
                    columns = {'name': 'VARCHAR', 'session_id': 'VARCHAR'},
                    maximum_object_size = 268435456) s
       ON s.session_id = u.session
WHERE u.session IS NOT NULL AND u.error IS NULL
GROUP BY ALL
ORDER BY ai_units DESC;

Only the name and the id are read from those files. Lines written before version 2 have no session (NULL).

The Savings card's day starts at local midnight; to match it exactly, group by your local day, for example date_trunc('day', "at" AT TIME ZONE 'Europe/Lisbon') with your own time zone.

The usage record schema #

Every line of the log, and every row of an export, is one usage record. The schema is versioned; this is version 8. Later versions may add columns at the end, and never rename, remove, reorder or retype one. Version 2 added the columns from schema_version on: the session, the cache-warming flag, a list-price estimate, and the cost and savings figures the Savings card shows, per request. Version 3 added the last three: request_hash, cached_response and response_cache_saved_estimated. Version 4 added the columns from person on: the client's version, the time to the first token and the time spent waiting on the provider, a fixed error class, how the request was routed (the attempts, the first choice, a short reason, the auto weight), fingerprints of the tools and the system prompt, and which budget counted the request. Version 5 added the columns from proxy_id on: which proxy wrote the line and which running copy of it, where the request came from when proxies are chained (origin_proxy, hops, via), why the account that served it was used, and an id for the line. Version 6 added the columns from cache_write_1h_tokens on: what the provider reported beyond the token counts (the cache writes kept for an hour, the thinking share of the output, the service tier, where inference ran, the speed, web searches), and the request priced at the provider's published list prices (list_cost_usd, an estimate, with the price list it came from and how it was priced), which monthly dollar budgets count. Version 7 added price_source: where the prices a request's savings were valued with came from. Version 8 added the columns from list_ai_units on: what the request cost at the model's published list price and the discount taken off it, its cost at the discount you configured for the sign-in, its part in a Copilot Fusion turn (which turn, the tier, how the turn was worked, the step, the review's score and how the turn ended), and who the provider was told started it. Lines written by earlier releases stay readable and have none of the columns added after their version: the view, CSV and Parquet show them as NULL on those lines, never as a 0 that would read as "nothing saved".

request_hash never holds content. It is a keyed hash of the request, salted with a random value made once for your install and kept in the proxy's secret store, so the same request gives the same value on your install only: it cannot be matched with another install's, or worked out from a known prompt without that value. tools_hash and system_hash are made the same way, from the tool definitions and from the system prompt alone, so you can see when a client changed either without either being stored.

A request that fell back to another model is one line per try: the failed try has the error and error_class, and the line of the model that answered has attempts 2 or more, first_choice and route_reason. cache_detail is in the schema already but not filled in by this release. Through chained proxies, each proxy writes its own line for the same request, and person and team name the original requester on every one of them. ttft_ms and upstream_ms are only from this version on; older lines have them NULL.

ColumnTypeUnitAlways in a log line?Meaning
attimestamp (text)—yesWhen the request was recorded (UTC, RFC 3339 text).
duration_msintegermillisecondsyesHow long the request took.
requestedtext—yesThe model name the client asked for (may be a routing alias such as auto).
modeltext—yesThe model that answered.
providertext—yesThe provider that answered.
streamedboolean—yesWhether the answer was streamed.
toolsintegercountyesTool definitions sent with the request.
messagesintegercountyesMessages in the request.
input_tokensintegertokensyesInput tokens, as the provider reported them.
output_tokensintegertokensyesOutput tokens, as the provider reported them.
cached_tokensintegertokensyesInput tokens read from the provider's prompt cache (0 when the provider reports none).
cache_write_tokensintegertokensyesInput tokens written to the provider's prompt cache (0 when the provider reports none).
ai_unitsdecimalAI unitsno: absent means 0What the request cost in the provider's own units, when it reports them. Local models report none.
errortext—no: absent means no errorWhy the request failed, if it did.
clienttext—no: absent means unknownThe access token's label, or local for a caller on this machine without one (never the token itself).
agenttext—no: absent means unknownThe kind of client, from its User-Agent: claude-code, opencode, maple-harness, hermes or other.
surfacetext—no: absent means unknownThe API the caller used: chat (OpenAI-compatible) or messages (Anthropic-compatible).
prefixtext—no: absent means unknownAn opaque grouping label (never content).
setuptext—no: absent means unknownAn opaque grouping label (never content).
convtext—no: absent means unknownAn opaque label grouping the requests of one conversation (never content).
fallbackboolean—no: absent means falseWhether the request was answered by a fallback after the first choice failed.
cache_classtext—no: absent means not classifiedHow the provider's prompt cache did: hit, partial, miss, lost or n/a.
cache_reasontext—no: absent means no reason givenFor a miss or a loss, a short reason.
schema_versioninteger—no (version 2): absent means 1The schema version the line was written with.
sessiontext—no (version 2): absent means unknownAn opaque id a client sends to group its requests into one session; Maple Harness sends its session's id (never content).
warmingboolean—no (version 2): absent means falseWhether the proxy sent this request itself, to keep a provider's prompt cache from expiring while a conversation was idle. What it cost is in ai_units.
cost_estimateddecimalthe currency in cost_currencyno (version 2): absent means no estimateAn estimate of what the request cost at the provider's published list prices, from a provider set up to give one. Not a bill, and separate from ai_units: never add the two together.
cost_currencytext—no (version 2): absent means no estimateThe currency of cost_estimated, such as USD.
pricedboolean—no (version 2): absent means falseWhether the proxy could put an AI-unit value on this request's savings, which needs a few earlier requests to the same model. When false, the AI-unit savings columns are 0 because nothing was valued, not because nothing was saved.
cache_saved_estimateddecimalAI unitsno (version 2): absent means 0Estimated: what the provider's prompt cache saved on this request, against paying for the same tokens without the cache.
cache_write_surcharge_estimateddecimalAI unitsno (version 2): absent means 0Estimated: what writing to the prompt cache cost on this request above that same price.
trim_saved_tokens_estimatedintegertokensno (version 2): absent means 0Estimated from their length: tokens that trimming left out of this request.
trim_saved_estimateddecimalAI unitsno (version 2): absent means 0Estimated: what trimming saved on this request, valued at the price of a cached token, the lowest a resent token can cost. Negative when the model asked again for a trimmed result and an earlier saving was taken back.
trim_cost_estimateddecimalAI unitsno (version 2): absent means 0Estimated: what trimming cost on this request: rewriting the prompt cache after a batch of trimming, and a request that only repeated a call whose result was trimmed.
images_saved_tokens_estimatedintegertokensno (version 2): absent means 0Estimated from each provider's published image formula: image tokens avoided by resizing or replacing images in this request.
images_saved_estimateddecimalAI unitsno (version 2): absent means 0Estimated: what sending fewer image tokens saved on this request.
images_cost_estimateddecimalAI unitsno (version 2): absent means 0Estimated: the prompt-cache rewrite a newly replaced image cost on this request.
snapshots_saved_tokens_estimatedintegertokensno (version 2): absent means 0Estimated (characters divided by four): tokens left out of browser page snapshots in this request.
snapshots_saved_estimateddecimalAI unitsno (version 2): absent means 0Estimated: what leaving those snapshot tokens out saved on this request.
snapshots_cost_estimateddecimalAI unitsno (version 2): absent means 0Estimated: a request that only asked again for a snapshot straight after a trimmed one.
stabiliser_saved_estimateddecimalAI unitsno (version 2): absent means 0Estimated: what the prefix stabiliser saved on this request. Shown on the Savings card on its own line, not in its headline.
warming_expected_saved_estimateddecimalAI unitsno (version 2): absent means 0Estimated, on a cache-warming request: the saving expected when it was sent, not a confirmed outcome. Shown on the Savings card on its own line, not in its headline.
request_hashtext—no (version 3): absent means no valueAn opaque value, the same for identical requests from the same client to the same provider account, and never content. Absent for a request the response cache could never answer (images, a tool turn).
cached_responseboolean—no (version 3): absent means falseWhether the proxy answered from its response cache. Nothing was sent to the provider, so the token and cost columns are 0.
response_cache_saved_estimateddecimalAI unitsno (version 3): absent means 0Estimated, on a request answered from the response cache: what the repeat would have cost. Shown on the Savings card on its own line, not in its headline.
persontext—no (version 4): absent means unattributedWho sent the request: the person their access token belongs to, or local for a caller on this machine without one, once people are set up. Through chained proxies, the original requester, as the proxy where they asked named them.
teamtext—no (version 4): absent means no teamThe team of the person who sent the request. Through chained proxies, the original requester's team.
agent_versiontext—no (version 4): absent means unknownThe client's version as major.minor, from its User-Agent, when it gives one.
ttft_msintegermillisecondsno (version 4): absent means not measuredStreamed requests only: the time from sending the request to the provider until its first output (text, thinking or a tool call) arrived.
upstream_msintegermillisecondsno (version 4): absent means not measuredThe time spent waiting on the provider for this request, apart from the proxy's own work and from waiting on the client to read a streamed answer.
error_classtext—no (version 4): absent means no errorA fixed class for error: quota exhausted, rate limited, overloaded, server error, not authorised, unreachable, request too large, daily budget spent, canceled, repeat guard, or status and the HTTP code.
attemptsintegercountno (version 4): absent means 1How many requests went to a provider for one client request, up to and including this one: 2 or more when fallbacks were tried before it. Each try is its own line. Empty for an answer from the response cache, which went to no provider.
first_choicetext—no (version 4): absent means the same as provider and modelThe provider/model the request would have gone to first, when another one served this line.
route_reasontext—no (version 4): absent means directA short code for why this line's provider and model were used: alias, auto, fallback:<class>, exhausted-order, health-demoted, person-policy or budget. Absent when the model asked for was used directly.
auto_weighttext—no (version 4): absent means not autoheavy, medium or light, for a request to auto or to auto-heavy, auto-medium or auto-light.
auto_basistext—no (version 4): absent means not autoA short code for what decided the auto weight, or what a provider's own router (Copilot Auto) did. Never content.
cache_detailtext—no (version 4): absent means noneA finer reason under cache_reason. Not filled in by this release.
tools_hashtext—no (version 4): absent means no valueAn opaque value, the same for the same tool definitions on this install, and never content: a keyed hash salted per install. Absent for a request without tools.
system_hashtext—no (version 4): absent means no valueAn opaque value, the same for the same system prompt on this install, and never content: a keyed hash salted per install. Absent for a request without a system prompt.
budget_scopetext—no (version 4): absent means noneWhich configured budget counted the request: provider, person or team. Absent when none did.
proxy_idtext—no (version 5): absent means unknownThe proxy that wrote the line: an id it made for itself when first started, the same for as long as its configuration folder is kept. Never a host name or address.
proxy_nametext—no (version 5): absent means no name setThe name given to that proxy (server.proxy_name), when one is set.
proxy_instancetext—no (version 5): absent means unknownWhich running copy of that proxy wrote the line, when several share one proxy_id (replicas behind one address): the pod name when it runs in one, else an id made when the proxy started.
origin_proxytext—no (version 5): absent means unknownThe first proxy the request reached, by its name (or its id when it has none): this proxy for a request sent to it directly, the one the person used for a request passed on through chained proxies.
hopsintegercountno (version 5): absent means 0How many proxies the request passed through before the one that wrote the line: 0 for a request sent to it directly.
viatext—no (version 5): absent means none: the request came directlyThe proxies the request passed through before this one, first to last, by name (or id), separated by >.
account_sourcetext—no (version 5): absent means noneWhy the provider account that served the line was used: person, team or default for an account assigned in the configuration, request when the request itself led there. Absent when no accounts are assigned.
record_idtext—no (version 5): absent means no idAn id for this line, unique across every proxy and restart, so a line copied into a shared store twice can be told from two requests. Opaque.
request_idtext—no (version 5): absent means no idAn id for the client request, made by the first proxy it reached and passed on with it: every line of one request (each try, on every proxy it went through) has the same one. Opaque. Absent on a request the proxy sent itself (cache warming).
reported_bytext—no (version 5): absent means the proxy in proxy_idOn a line a hub received from a proxy below it (source child): the id of the proxy that sent it. Absent on a line this proxy recorded itself.
sourcetext—no (version 5): absent means locallocal for a line this proxy recorded itself, child for one a proxy below it sent up (kept apart from this proxy's own usage log).
forwardedboolean—no (version 5): absent means falseWhether the request was passed on to another Maple proxy: its tokens, AI units and cost are that proxy's figures, which that proxy's own line counts too. Leave these lines out when adding up spend across chained proxies.
cache_write_1h_tokensintegertokensno (version 6): absent means not reportedThe part of cache_write_tokens the provider keeps in its prompt cache for an hour; the rest were five-minute writes. Absent when the provider did not say.
thinking_tokensintegertokensno (version 6): absent means not reportedThe part of output_tokens the model spent thinking, as the provider reported it. A breakdown only: output_tokens already includes it.
service_tiertext—no (version 6): absent means not reportedThe service tier the provider says served the request: standard, priority or batch.
inference_geotext—no (version 6): absent means not reportedWhere the provider says inference ran, such as us when it ran in the US only.
speedtext—no (version 6): absent means not reportedThe speed the provider says served the request: standard or fast.
web_search_requestsintegercountno (version 6): absent means noneHow many web searches the provider ran on its side for the request.
price_list_versiontext—no (version 6): absent means not pricedThe price list list_cost_usd was priced from, such as anthropic-2026-10-11 (the date it was read).
list_cost_usdnumberUSDno (version 6): absent means not pricedEstimated: the request priced at the provider's published list prices, whether or not the provider is set up with estimate_cost. What monthly dollar budgets count. Not a bill, and separate from ai_units and from cost_estimated: never add them together. Your provider's own console is the authority on what you were charged.
price_basistext—no (version 6): absent means not pricedHow list_cost_usd was priced: list for the model's own list price, family-highest when the model is not in the price list and was counted at the highest list price of its family.
price_sourcetext—no (version 7): absent means not valued, or (before version 7) valued with learned pricesWhere the prices this request's AI-unit savings were valued with came from: copilot_stated (what Copilot stated it charged per token on the model's latest request through the same route), copilot_published (Copilot's published price, less the route's discount), learned (from the model's own earlier requests), copilot_auto_discount (the discount of Copilot Auto or Copilot Fusion applied to the same model's learned prices) or configured (the price set for the model in config.yaml; see Prices for each model).
list_ai_unitsnumberAI unitsno (version 8): absent means nothing publishedThe request's tokens at the model's published list price (the price by name, as Copilot publishes it). Compare with ai_units, what was charged: the difference is the provider's discount, never one of Maple's savings.
discount_ratenumberfractionno (version 8): absent means not knownThe share of the list price taken off, such as 0.3 for 30% off. With a stated cost, what was actually taken off: 1 − ai_units / list_ai_units.
discount_sourcetext—no (version 8): absent means not knownWhere discount_rate came from: stated (what the provider charged, against its list price), promotion:<id> (a promotion the provider announced), observed (the rate the provider last charged in the same tier), model (the model's usual Copilot Auto discount), assumed (Copilot Auto's long-standing 10%, as nothing was published) or list (a request by name, at the list price).
configured_ai_unitsnumberAI unitsno (version 8): absent means no discount configuredlist_ai_units at the discount configured for the sign-in in config.yaml (providers[].discount): shown beside ai_units, never instead of it, and never counted by budgets.
configured_discount_ratenumberfractionno (version 8): absent means no discount configuredThe configured discount configured_ai_units was valued at, such as 0.15 for 15% off.
fusion_idtext—no (version 8): absent means not a Copilot Fusion High or Max requestThe Copilot Fusion turn the request belongs to, the same on every request of the turn.
fusion_tiertext—no (version 8): absent means not a Copilot Fusion High or Max requestThe Copilot Fusion tier: high or max. A Copilot Fusion Standard request is a Copilot Auto request, with auto_basis copilot-auto.
fusion_patterntext—no (version 8): absent means not a Copilot Fusion requestHow the turn was worked: single (one model), cascade (a solver, then a read-only review, and a stronger model when the review rejects the work) or critique (a draft, critics, then one revision); auto when Copilot could not plan the turn and Copilot Auto served it.
fusion_ruletext—no (version 8): absent means not a Copilot Fusion requestThe rule and policy version Copilot's plan named for the turn, as policy/rule.
fusion_phasetext—no (version 8): absent means not a Copilot Fusion requestThe request's part in the turn: solver, judge, escalation, repair, critic or revision, or fallback (Copilot could not plan the turn, and Copilot Auto served it).
fusion_verdictintegerscoreno (version 8): absent means not a review requestOn a review (judge) request: its score, 1 to 5; 3 and above accepts the work.
fusion_outcometext—no (version 8): absent means not the turn's last requestOn the turn's last request: accepted (the review accepted the first answer), escalated (a stronger model's answer was used), repaired (the repair model's was), revised (a critique's revised answer was used), not_accepted (no answer passed the review, and the last one was used) done (a Single turn: one model did the task) or fallback (Copilot could not plan the turn, and Copilot Auto's answer was used).
initiatortext—no (version 8): absent means not recordedWho the provider was told started the request: user (you typed it), agent (the agent loop sent it after a tool's result, or Maple sent it itself) or agent-marked (the tool marked it as its own with X-Maple-Initiator, which is honoured only from this machine or a chained Maple proxy).

"Always in a log line?" matters for anything that reads the log directly: a line leaves out a field that is empty. Releases before this schema also left out ai_units when it was 0; current releases always write it. A version 2 line also leaves out a version 2 number or flag that is 0 or false, and a version 4 line leaves out attempts when it is 1 and a time that was not measured; a version 5 line leaves out hops when it is 0. In an export every column is always present: CSV writes an empty cell for a label with no value and 0/false for ai_units/fallback and for a version 2 number or flag (attempts is 1 on a version 4 line that left it out, hops 0 on a version 5 line); Parquet stores the same labels as nulls, and records the schema version in the file's metadata (maple.usage.schema_version). The version 2 columns come after all the version 1 columns, so a spreadsheet or query that reads version 1 columns by position still finds them where they were; on a version 1 line they are empty cells in CSV and nulls in Parquet. Each later version's columns come after the one before, in the same way.

The same schema, machine-readable:

The events log #

Next to the daily usage files the proxy keeps an events log: things that happen that are not requests, one JSON object per line in events-YYYY-MM-DD.jsonl (one file per UTC day, in the same folder). It is separate so that counting the usage files' lines still counts requests, and so every existing query and export is unchanged. It is on when the usage log is on and off when it is off, and its files are kept for the same number of days (Keep), with the same rules: only files named exactly events-YYYY-MM-DD.jsonl that are empty or start with an event, never a link. A usage log whose file name starts with events has no events log, so the two can never be mistaken for each other.

What it records today is settings changes: each save on the setup page writes one line per setting that changed, naming the setting's key path (such as server.usage_retention_days or providers[copilot].api_key), never its value, except for settings that are a number, an on/off switch or a mode. A key, a token, an address, a path or a model name is never written. Each start of the proxy writes one line with a fingerprint of the configuration, so a change made to config.yaml while the proxy was stopped shows up as changed-outside (which settings changed is not known then, because no values are kept to compare). Health changes and alerts will be written here too.

Each line has the same seven fields, events schema version 1:

FieldAlways there?Meaning
atyesWhen it happened (UTC, RFC 3339 text).
kindyesWhat happened: config.change, health.change, health.demote, health.restore, alert.fired or alert.resolved. Later releases may add kinds.
subjectnoWhat it happened to: a setting's key path, a provider, or an alert's scope.
levelyesinfo, warn or error.
codenoA short code: for a setting, added, changed or removed; for the whole configuration, start, saved, changed-outside or more (more settings changed in one save than are listed one by one).
valuenoA figure or a state, as text: a setting's new value only for numbers, switches and modes, and a fingerprint for the whole configuration.
detailnoA short note, such as where a change came from.

Every field is short and capped in length, and nothing in it is content or a secret. The JSON Schema is published at schema/events-record.v1.json; like the usage schema, a later version may add fields, and never renames, removes or retypes one. The maple.events and maple.alerts named views read these files.

Export to CSV or Parquet #

For handing the data to a tool that cannot read JSON Lines directly:

maple-proxy usage export --format csv --out usage.csv
maple-proxy usage export --format parquet --out usage.parquet --since 2026-09-01 --until 2026-10-01

--since/--until are UTC-day boundaries (YYYY-MM-DD); --until is exclusive. Without --path, it finds the log the same way the running proxy does (usage_ledger from your config.yaml, the default place when that is unset, and CCH_USAGE_LEDGER over both) — the proxy does not need to be running for this, it only reads files. maple-proxy usage status prints where that is and how much disk it takes.

CSV and Parquet get the exact same columns as the raw JSON lines, so a query against either sees the same shape: every column of the schema, in its order, on every export, whether or not the rows hold a value (version 8 has 95, from at to initiator, with person, team, route_reason, auto_weight, account_source, proxy_id, origin_proxy, hops and list_cost_usd among them). New columns only ever go at the end, so a spreadsheet that reads columns by position keeps working. The monthly Parquet files and the maple.usage view of the DuckDB file have the same columns. Parquet is the better choice for a large range you want to archive compactly or hand to a tool that reads it natively (Grafana's DuckDB plugin, a notebook, a data warehouse's own loader) — it compresses well and DuckDB reads it just as directly as JSON:

duckdb -c "SELECT * FROM read_parquet('usage.parquet') LIMIT 20"

Filter your data #

maple-proxy usage query answers questions about the usage log without DuckDB or an export: totals, or a table grouped by what you choose, for any mix of filters.

maple-proxy usage query --last 7d --group-by day
maple-proxy usage query --provider github-copilot --outcome error --group-by model,error_class
maple-proxy usage query --since 2026-09-01 --until 2026-10-01 --group-by agent --format csv
maple-proxy usage query --session ses_1a9e2cded775 --metrics requests,input_tokens,ai_units,latency_p95

The filters:

FilterFlagsMatches
Time--since, --untilA UTC day (YYYY-MM-DD) or a time (RFC 3339); --until is exclusive.
Recent--last7d is today and the six UTC days before it; 24h or 90m is a rolling window. Not with --since.
Provider--provider-type, --account, --provider--provider-type is the kind of provider (anthropic, github-copilot...), every account of it in config.yaml; --account is one account, by its id or nickname; --provider is the account's id, as before.
Model--model, --requestedThe model that answered, and the name the client asked for (auto, an alias).
People--person, --teamWho asked, once people are set up; --person unattributed (or -) is the requests with no person recorded.
Client--token, --agentThe access token's label (local for this machine without one), and the kind of client.
Session--session, --conversationOne session's or one conversation's requests.
Auto--auto-weightheavy, medium or light, for requests routed by auto.
Outcome--outcomeok, error, fallback, cached (answered from the response cache) or warming. Each request has one.
Errors--error-classWhy a request failed, such as rate limited or quota exhausted.
Routing--route-reasonWhy the provider and model were used: alias, auto, fallback:<class>, budget, exhausted-order; - for the model asked for, directly.
Chained proxies--proxy, --proxy-instance, --origin-proxy, --account-source, --source, --reported-byThe proxy that recorded the line (name or id) and its running copy, the first proxy the request reached, why its account was used, and on a hub whether the line is its own (local) or sent up from below (child) and by which proxy.

Several values in one flag (comma-separated, or the flag repeated) mean any of them; different flags must all match. - stands for "not recorded": --person - is the requests with no person, and so is --person unattributed.

--group-by takes day, provider, model, requested, token, person, team, agent, surface, auto_weight, outcome, error_class, cache_class, session, conversation, proxy, proxy_instance, origin_proxy, hops, account_source, source, reported_by, route_reason, initiator, fusion_tier, fusion_pattern, fusion_phase or fusion_outcome. --metrics picks the figures (maple-proxy usage query --help lists them all); figures named _estimated are estimates, never bills, and latency and time-to-first-token percentiles are approximate. --format is table, json or csv, and --timing also prints how long the answer took and what it read.

Every answer ends with notes on what its figures cannot show: lines written before a column existed (time to first token, person and error class are only recorded from schema version 4), and lines that could not be read.

On a hub, usage query also counts what the proxies below it sent up (--children off leaves it out). Then requests counts lines, one for each proxy a request passed through; client_requests counts each request once, and ai_units_spent and cost_estimated_spent count spend once, where it was spent. With nothing sent up, the answer is exactly what it was.

The same filter flags work on usage export (the file holds only the matching requests) and on usage status (which then adds the matching requests' totals). With no filter, an export is exactly what it was before, byte for byte, and it now reads and writes a day at a time instead of holding the whole range in memory.

To answer quickly, usage query keeps a summary of each finished day in your user cache folder (~/.cache/maple-harness/usage-index/ on Linux), private to you. It holds the same counts and labels as the usage log, never anything else, is rebuilt by itself when a day's file changes, and goes when that day's file is removed. You can delete it at any time; nothing is lost. --no-index reads the files directly and writes nothing.

Requests with no person #

Two names stand for a request without a person of its own:

  • unattributed (stored person: empty, NULL): no person was recorded. The request came before people were set up (or before schema version 4), or with an access token tied to no person.
  • local (stored person: local): a request from the proxy's own machine without an access token, once people are set up. Give a person the id local to set rules for those callers.

usage query's table, the setup page and the DuckDB views show unattributed; usage query --format json and --format csv write - for it, and an export leaves the person cell empty (NULL in Parquet). unattributed is reserved: no person can have it as an id.

Keep it tidy: prune #

The proxy already deletes daily files older than server.usage_retention_days (see How long it is kept). To remove more now, by hand:

maple-proxy usage prune --keep-days 90        # lists what would be deleted; nothing removed yet
maple-proxy usage prune --keep-days 90 --yes  # actually deletes it

Only rotated, dated files are ever candidates for deletion. A plain, undated file left over from before rotation existed is never touched by prune — if you want that gone, remove it yourself.

Wire it into Grafana #

Point an existing Grafana plugin at your files rather than a bespoke Maple Harness dashboard, so it stays current with however you actually run Grafana:

Infinity (maintained by Grafana Labs, in the official plugin catalog) reads CSV and JSON directly, by path or URL, and is the simpler route:

grafana-cli plugins install yesoreyeram-infinity-datasource

Add it as a data source, point a CSV query at an exported usage.csv (or a JSON query at a daily file such as maple_harness_proxy_usage_ledger-2026-09-28.jsonl — Infinity reads newline-delimited JSON too), and build panels from the columns above: AI units over time, requests by model, cache hit rate.

DuckDB (maintained by MotherDuck) gives you real SQL against the files instead of Infinity's simpler per-panel queries — worth it if you want to join, filter or aggregate the way the query in Query it directly with DuckDB does, inside a dashboard. As of this writing the plugin is not yet signed, so it needs a manual install rather than grafana-cli plugins install:

unzip motherduck-duckdb-datasource-<version>.zip -d /var/lib/grafana/plugins/motherduck-duckdb-datasource

and, in grafana.ini:

[plugins]
allow_loading_unsigned_plugins = motherduck-duckdb-datasource

(or GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=motherduck-duckdb-datasource for a Docker Grafana). Point it at an exported usage.parquet, or directly at a glob of the rotated .jsonl files — DuckDB reads both. Check each plugin's own release page for the current version and exact steps; the commands above are current as of writing but plugin packaging details do change.

Made with ❤️ by Kinn Coelho Juliao in Ottawa, eh — fuelled by double-doubles, bud. 🍁