Dónde vive el ledger

Un archivo de solo añadidos para toda la máquina. Qué se escribe en él, cuándo, y qué pasa si se pierde o se daña.

Un archivo para la máquina #

El ledger es quota.jsonl, en ~/.autodev/. Hay uno para la máquina y no uno para cada proyecto, porque una suscripción atraviesa todos sus proyectos. Es JSON Lines, y AutoDev solo le añade líneas.

No es uno de los índices que AutoDev puede reconstruir, y nunca rota. Es la única copia de los datos de medición. El log de eventos rota cuando crece, y aplicarlo al ledger borraría el historial con el que se dibuja el panel.

Cómo es una línea #

Una línea es un registro. Los tres tipos están en Qué se mide, y esta es su forma:

{"type":"call","ts":"<time>","provider":"<provider>","root":"<project path>","ms":<n>,"ok":true,"model":"<model>","usd":null,"usdDelta":null,"tokens":null,"usage":null,"quota":[],"compactions":[],"inferences":null,"contextWindow":null,"context":null}
{"type":"limit","ts":"<time>","provider":"<provider>","root":"<project path>","retryAt":"<time>","source":"text","kind":null}
{"type":"work","ts":"<time>","provider":"<provider>","root":"<project path>","commit":"<sha>","mode":"thread","taskId":null}

Todo registro lleva root, la ruta absoluta del proyecto. Un call también lleva el modelo. Si compartes el archivo, compártelo sabiéndolo.

Cómo se escribe #

Todo proveedor se construye mediante una sola función, así que toda llamada queda registrada: cada turno de cada participante, y las llamadas que comprueban la ejecución, como la auditoría de finalización. El registro call se escribe cuando la llamada termina, y un registro limit lo sigue cuando la llamada informó un límite. Un registro work se escribe cuando AutoDev acredita un commit.

La escritura se hace con el mejor esfuerzo. Si no se puede escribir el ledger, la llamada sigue teniendo éxito y una advertencia quota.record_failed va al log, porque la instrumentación no debe poder romper lo que mide. Los proyectos concurrentes añaden al mismo archivo, y por eso es JSON Lines y no un único array JSON.

Leerlo tú mismo #

Toda cifra del panel se calcula a partir de este archivo, con código que lo lee y nada más. Puedes leer los mismos registros:

autodev quota --json

autodev report --json imprime el modelo del informe del mismo modo. Cada línea de quota.jsonl es JSON llano, así que cualquier herramienta que lea JSON Lines lo lee.

Si se daña o se pierde #

Una línea que no se puede leer se cuenta y se muestra en la sección Integrity de autodev quota, y se omite. Una última línea escrita a medias se repara en el siguiente añadido. Un archivo borrado se ha perdido: nada lo reconstruye, y el panel empieza de nuevo con un historial vacío.

AutoDev no envía el ledger a ninguna parte. El servidor que inicia el acceso remoto puede servir la vista de cuota derivada a quien tenga el token o a un navegador emparejado, bajo las reglas de su nivel de telemetría. Qué puedes hacer desde el teléfono las enumera.

Dónde vive el estado enumera los demás archivos de ~/.autodev/, y Leer el panel de cuota trata de lo que el panel hace con este.