> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cantor8.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Observability

> Monitor health, supply, and ledger activity with actionable signals, and ship logs to Cantor8.

You monitor Token App. It is the process you run. Cantor8 monitors the Registry. You see Token App's calls to it fail or slow down.

Logs are JSON lines on stdout. You can also ship them to Cantor8. [Log shipping](#log-shipping) covers that. Health, status, and metrics are HTTP on port 8002.

| Endpoint | Auth | Use |
| - | - | - |
| `GET /healthz` | None | Liveness. The chart probes this |
| `GET /metrics` | None | Prometheus scrape. Keep it on the cluster network |
| `GET /status` | Bearer token | Last monitor cycle, supply, and queue depths, without a live ledger query |

Set `monitoring.serviceMonitor.enabled` to have the chart create a Prometheus Operator `ServiceMonitor` for `/metrics`. The scrape interval in the chart default is 15 seconds.

The monitor reads holdings on a poll, default 300 seconds (`monitoring.tokenMetricsPollIntervalSeconds`). `/status` and the supply gauges update when a cycle succeeds. A stale success timestamp means those numbers have stopped moving, and so has every background job the monitor drives.

## Resources

| | CPU | Memory |
| - | - | - |
| Token App request | 2 | 10 GiB |
| Token App limit | 4 | 16 GiB |
| Database Cantor8 runs | 2 vCPU | 1 GiB, 20 GiB storage, PostgreSQL 14 |

> [!WARNING]
>
> Keep the Token App memory request. The holdings scan consumes it. Run one replica.

The pod listens on 8002. Startup allows a long first boot (the chart waits up to about five minutes) because the process migrates its database and opens the ledger stream before it is ready.

## Token App signals

Alert on these. Names are the Prometheus metric names.

| Signal | Alert when |
| - | - |
| `up` from the `/healthz` probe, or the probe itself | The pod is unready, restarting, or failing liveness |
| `token_app_monitor_last_success_timestamp_seconds` | `time() -` this value is more than a small multiple of the poll interval. At the default 300 second poll, a cycle older than about 15 minutes means the loop has stopped |
| `token_app_monitor_cycle_errors_total` | The rate is above zero |
| `token_app_monitor_dropped_batches_total` | The rate is above zero. A consumer queue is full and holdings snapshots are being discarded |
| `token_op_errors_total` | Mint or burn failures, labeled `instrument` and `operation` (`mint` or `burn`) |
| `token_app_token_factory_request_total` | Responses to the Registry that are not successes, labeled `operation` and `status` |
| `token_app_ledger_request_total` | Ledger calls that are not successes |
| Container memory | Usage approaches the 16 GiB limit during catch-up or steady state |
| Restarts | Any restart. The process is a single writer; a crash pauses the monitor until the pod is ready again |

Supply and flow, for dashboards rather than pages:

| Metric | Meaning |
| - | - |
| `token_app_token_circulating_supply{instrument}` | Spendable plus locked, from the last scan |
| `token_app_token_holdings{instrument}` | Number of holding contracts |
| `token_app_token_holders{instrument}` | Distinct owners |
| `token_flow_supply_total{instrument,operation}` | Amount minted or burned by successful calls |
| `token_flow_holdings_total{instrument,operation}` | Holdings created or burned by those calls |
| `token_app_request_total` and `token_app_request_latency_seconds` | Inbound API rate and latency, by path and status |
| `token_app_monitor_scan_duration_seconds` | How long the last scan took |

`/status` reports the same supply figures plus `top_holder_share`, `supply_concentration_hhi`, and `operational.monitor` (`last_success_at`, `age_seconds`, `last_scan_duration_seconds`, `poll_interval_seconds`, `cycles_total`, `cycle_errors_total`). Prefer the timestamp metric for the page. Use `/status` when a person wants the snapshot.

## The Registry, from Token App

Your view of the Registry is `token_app_token_factory_request_total` and the latency histogram `token_app_token_factory_request_latency_seconds`. A rise in failures there, with your participant healthy, is a Registry or credential problem. A rise in `token_app_ledger_request_total` failures, with the Registry healthy, is your participant.

## A healthy launch check

After [Launch](https://docs.cantor8.tech/token-factory/launch.md) step 4:

* `/healthz` is ok and the pod has been ready longer than one monitor interval
* `token_app_monitor_last_success_timestamp_seconds` is within one interval of now
* the treasury mint increased `token_flow_supply_total` and `token_app_token_circulating_supply` for that instrument
* `token_op_errors_total` is flat

## Log shipping

The Helm chart can send Token App logs to Cantor8. It is off by default, and Token App does not depend on it. Metrics stay on `GET /metrics`. [Deployment](https://docs.cantor8.tech/token-factory/deployment.md#log-shipping) has the values and the secret.

| What is shipped | Format |
| - | - |
| Token App log lines | JSON lines |
| uvicorn lines | Plain text |
| `/healthz` request lines | Not shipped |

Shipping is best effort. If a push fails, Alloy drops that batch, and the Token App pod stays healthy. A gap in shipped logs is not a Token App fault.

Log shipping does not move monitoring to Cantor8. You still monitor Token App with the signals on this page. Cantor8 still monitors the Registry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.