# Veristar

> Privacy-friendly web and API analytics for projects building on Stellar.

- [Veristar](https://docs.veristar.app/introduction.md): Privacy-friendly web and API analytics for projects building on Stellar, run as a shared and free service.
- [How it works](https://docs.veristar.app/how-it-works.md): The path a pageview or an API request takes from your site or app to your dashboard, in plain terms.
- [Architecture](https://docs.veristar.app/architecture.md): The services, hosts, data flows, queues and stores that make up Veristar, with diagrams of each path.
- [0001: Umami as the base platform](https://docs.veristar.app/adr/0001-base-platform.md): Why Veristar builds its web analytics on Umami.
- [0002: Separate services beside Umami, not a fork](https://docs.veristar.app/adr/0002-overlay-not-fork.md): Why the extra features run as separate services beside an unmodified Umami.
- [0003: Licensing](https://docs.veristar.app/adr/0003-licensing.md): The open-source licence of the repository and of the infrastructure tooling it depends on.
- [Tenant onboarding](https://docs.veristar.app/onboarding/overview.md): Guides for adding web analytics to a site and API analytics to a backend, with code taken from tested examples.
- [Web analytics quickstart](https://docs.veristar.app/onboarding/web/quickstart.md): Register a site, paste one script tag and see pageviews, visitors and referrers in your dashboard.
- [API analytics quickstart](https://docs.veristar.app/onboarding/api/quickstart.md): Count your backend's HTTP requests, status codes and latency by adding a second OpenTelemetry exporter.
- [Static HTML](https://docs.veristar.app/onboarding/web/static-html.md): Add the tracker to hand-written pages and sites built by a static site generator.
- [Vite and React](https://docs.veristar.app/onboarding/web/vite-react.md): Add the tracker to a client-routed React app built with Vite.
- [Vue](https://docs.veristar.app/onboarding/web/vue.md): Add the tracker to a Vue app built with Vite and Vue Router.
- [Astro](https://docs.veristar.app/onboarding/web/astro.md): Add the tracker to an Astro site, static or server rendered.
- [SvelteKit](https://docs.veristar.app/onboarding/web/sveltekit.md): Add the tracker to a SvelteKit app.
- [React Router with server rendering](https://docs.veristar.app/onboarding/web/react-router.md): Add the tracker to a React Router app in framework mode with server rendering.
- [Next.js](https://docs.veristar.app/onboarding/web/nextjs.md): Add the tracker to a Next.js app that uses the App Router.
- [The npm package](https://docs.veristar.app/onboarding/web/npm.md): Bundle the tracker into your app as an npm package instead of a script tag.
- [Self-hosting sdk.js](https://docs.veristar.app/onboarding/web/self-hosting.md): Serve the tracker file from your own domain while events still go to the gateway.
- [Content security policy](https://docs.veristar.app/onboarding/web/content-security-policy.md): The Content-Security-Policy directives that let the tracker load and send events.
- [Upgrading the tracker](https://docs.veristar.app/onboarding/web/upgrading.md): Move your pages to a newer pinned tracker version, at the time you choose.
- [Consent: starting the tracker later](https://docs.veristar.app/onboarding/web/consent.md): Load the tracker without measuring, and start it once the visitor agrees.
- [Custom events](https://docs.veristar.app/onboarding/web/custom-events.md): Send named events of your own, such as a click on a sign-up button, next to the pageviews.
- [Wallet events from the Stellar Wallets Kit](https://docs.veristar.app/onboarding/web/wallets-kit.md): Count wallet connections and other wallet activity from the Stellar Wallets Kit.
- [Node.js](https://docs.veristar.app/onboarding/api/node.md): Dual export from a Node.js service on Express with the OpenTelemetry Node SDK.
- [Python](https://docs.veristar.app/onboarding/api/python.md): Dual export from a Python service on FastAPI with the OpenTelemetry Python SDK.
- [Go](https://docs.veristar.app/onboarding/api/go.md): Dual export from a Go service on net/http with otelhttp and the OpenTelemetry Go SDK.
- [Rust](https://docs.veristar.app/onboarding/api/rust.md): Dual export from a Rust service on actix-web with the OpenTelemetry Rust SDK.
- [Fan-out from your own Collector](https://docs.veristar.app/onboarding/api/collector-fanout.md): Forward metrics from an OpenTelemetry Collector you already run, without changing your apps.
- [Setting http.route](https://docs.veristar.app/onboarding/api/http-route.md): Make sure every request carries the route template, so the API dashboard groups requests by route.
- [What gets dropped](https://docs.veristar.app/onboarding/api/what-gets-dropped.md): What the platform's collector keeps for the API dashboards and what it discards on arrival.
- [Troubleshooting API analytics](https://docs.veristar.app/onboarding/api/troubleshooting.md): Checks for the OTLP endpoint, the token and the data when API metrics do not appear.
- [Support](https://docs.veristar.app/support.md): How tenants and everyone else get help, and the response and resolution targets the operator commits to.
- [Operator guide](https://docs.veristar.app/operators/overview.md): For the SCF operators who govern the shared service: enrollment, removal and cross-project views.
- [Review and enrollment modes](https://docs.veristar.app/operators/review-and-enrollment.md): Self-service enrollment, approval-required enrollment and project review.
- [Removing a project](https://docs.veristar.app/operators/removal.md): Remove a project that is not part of the Stellar ecosystem.
- [Reading the global views](https://docs.veristar.app/operators/global-views.md): Compare every enrolled project on the core web and API metrics.
- [What the numbers mean](https://docs.veristar.app/operators/reading-the-numbers.md): Bands, daily-unique visitors and span-derived API data, and how they shape cross-project comparisons.
- [Operator API keys](https://docs.veristar.app/operators/api-keys.md): Give a downstream machine read access to aggregate metrics through the machine API.
- [Live proof of adoption](https://docs.veristar.app/adoption/overview.md): How the platform demonstrates live adoption by real SCF-awarded projects, and the evidence it collects.
- [Pilot pack](https://docs.veristar.app/adoption/pilot-pack.md): What to send a project that takes part in the live proof of adoption.
- [Deploying Veristar](https://docs.veristar.app/deploy/overview.md): Stand up, verify, upgrade and remove a Veristar environment from this repository, step by step.
- [Prerequisites and accounts](https://docs.veristar.app/deploy/prerequisites.md): The accounts, inputs and controller tools an environment needs before the first command.
- [Secrets: SOPS with age](https://docs.veristar.app/deploy/secrets.md): How secrets are encrypted with SOPS and age, and which files hold them.
- [OpenTofu: infrastructure, state and the Ansible inventory contract](https://docs.veristar.app/deploy/opentofu.md): The OpenTofu infrastructure, its state, and the inventory it hands to Ansible.
- [Ansible: roles, playbooks and images](https://docs.veristar.app/deploy/ansible.md): The Ansible roles, playbooks and images that configure every node.
- [Bootstrap a new environment](https://docs.veristar.app/deploy/bootstrap.md): The first converge of an empty environment, end to end, with a check after each step.
- [Verifying an environment](https://docs.veristar.app/deploy/verification.md): Checks that prove a converged environment works, from the outside in.
- [Backups: storage account, stanza and WAL archiving](https://docs.veristar.app/deploy/backups.md): How the pgBackRest repository is created and protected, from storage to WAL archiving.
- [The probe outside Azure, with Uptime Kuma and ntfy](https://docs.veristar.app/deploy/probe.md): The probe that checks the platform from outside its hosting, with a status page and alerts.
- [Upgrading an environment](https://docs.veristar.app/deploy/upgrade.md): Release a new version and roll it out one node at a time, with signatures checked first.
- [Tearing down an environment](https://docs.veristar.app/deploy/teardown.md): Remove an environment's servers, network, addresses and DNS, with protection for production.
- [Production readiness checklist](https://docs.veristar.app/deploy/production-readiness.md): The checks production passes and signs off before it takes its first real project.
- [Local converge: the Ansible roles against real Debian 13 systems](https://docs.veristar.app/deploy/local-converge.md): Run the same Ansible roles against Debian 13 containers on one machine.
- [Operator runbooks](https://docs.veristar.app/runbooks/overview.md): One runbook per operational task, and the conventions every runbook shares.
- [Alerts runbook](https://docs.veristar.app/runbooks/alerts.md): Every alert, its threshold, what it means and what to do.
- [Edge node failure](https://docs.veristar.app/runbooks/edge-node-failure.md): Diagnose and recover an edge node that answers badly or not at all.
- [Database failover and replica rebuild](https://docs.veristar.app/runbooks/database-failover.md): Patroni failover between the core nodes and rebuilding a replica.
- [Disaster recovery: both database nodes or the database lost](https://docs.veristar.app/runbooks/disaster-recovery.md): Bring the platform back when both core nodes or the database cluster are lost.
- [Point-in-time restore](https://docs.veristar.app/runbooks/point-in-time-restore.md): Restore the PostgreSQL cluster to a past moment on a fresh node, without touching the running cluster.
- [Queue backlog and dead-letter queues](https://docs.veristar.app/runbooks/queue-backlog-and-dlq.md): Handle a growing queue and inspect or replay dead-lettered messages.
- [Certificate problems](https://docs.veristar.app/runbooks/certificates.md): Diagnose and fix certificate issuance and renewal on edge and core nodes.
- [Security incident](https://docs.veristar.app/runbooks/security-incident.md): Respond to a suspected attack or breach, with clear roles and steps.
- [Investigating suspected metric inflation](https://docs.veristar.app/runbooks/metric-inflation.md): Investigate a project whose numbers look higher than its real use.
- [Capacity changes](https://docs.veristar.app/runbooks/capacity.md): Add resources before a limit is reached, or remove them when they are not used.
- [Security patch](https://docs.veristar.app/runbooks/security-patch.md): Take a vulnerability from signal to patched production within the 24-hour commitment.
- [Secret rotation](https://docs.veristar.app/runbooks/secret-rotation.md): Replace each secret of an environment, and what users notice while you do.
- [Collector upgrade](https://docs.veristar.app/runbooks/collector-upgrade.md): Build, test and roll out a new version of the OTLP collector.
- [Umami upgrade and rollback](https://docs.veristar.app/runbooks/umami-upgrade.md): Upgrade the pinned Umami image through the compatibility gate, and roll back.
- [Tracker release and revocation](https://docs.veristar.app/runbooks/tracker-release.md): Release a new immutable tracker version, and revoke one if needed.
- [DB-IP monthly update](https://docs.veristar.app/runbooks/dbip-update.md): Update the monthly DB-IP country file baked into the gateway image.
- [Monthly SLO report](https://docs.veristar.app/runbooks/slo-report.md): Produce the monthly SLO report from the probe's measurements.
- [Adding and removing operators](https://docs.veristar.app/runbooks/operators.md): Add and remove operators through the list of GitHub account ids.
- [Operator API key revocation](https://docs.veristar.app/runbooks/operator-key-revocation.md): Revoke an operator API key and confirm that it no longer works.
- [Tenant suspension and removal](https://docs.veristar.app/runbooks/tenant-removal.md): Suspend, resume and remove a project, and follow a removal to completion.
- [Erasure requests](https://docs.veristar.app/runbooks/erasure-requests.md): What an operator does when a data subject or a tenant asks for data to be erased.
- [Service targets](https://docs.veristar.app/sla.md): The operational targets for ingestion, dashboards and security patching, and how each one is measured.
- [Availability statement](https://docs.veristar.app/reference/availability.md): The availability targets, the failover behaviour they rest on, and what has been measured.
- [Observability reference (phase 17)](https://docs.veristar.app/reference/observability.md): The metrics, probes and alert rules behind monitoring, and the sources they were checked against.
- [Wire format v1](https://docs.veristar.app/reference/wire-v1.md): How sdk.js talks to the gateway: endpoints, payloads and limits.
- [Browser proof](https://docs.veristar.app/reference/browser-proof.md): The proof of work every page load solves, and what it does and does not prove.
- [Control plane HTTP API](https://docs.veristar.app/reference/control-plane-api.md): The HTTP contract between the console and the control plane: routes, fields and error codes.
- [Tenants in the key's scope](https://docs.veristar.app/api-reference/tenants-in-the-keys-scope.md): A key for all tenants lists every tenant except internal ones, in id order. A key scoped to one tenant lists that tenant only.
- [Web totals per tenant, UTC day and band](https://docs.veristar.app/api-reference/web-totals-per-tenant-utc-day-and-band.md): Sums of `agg.web_daily` over the tenant's sites for every day the aggregation task has read (a day it read without traffic has zeros, a day it never read is absent). Ordered by tenant, day and band. Visitors of a day are unique within that day and site; over a range they add up (control-plane-api 8)…
- [Web breakdowns per tenant, UTC day, band, dimension and key](https://docs.veristar.app/api-reference/web-breakdowns-per-tenant-utc-day-band-dimension-and-key.md): Sums of `agg.web_daily_dim` over the tenant's sites. `value` is Umami's `y`: distinct visitors of that day whose page views carry the key. Ordered by tenant, day, band, dimension and key.
- [Web totals per UTC hour, read live from Umami](https://docs.veristar.app/api-reference/web-totals-per-utc-hour-read-live-from-umami.md): Reads Umami's own `/stats` for every active site of one tenant, both bands and every hour of the range, through the control plane's Umami service account, and returns the sums per hour and band. Only aggregates leave the control plane. The current hour is read up to the moment of the request and has…
- [API request numbers per tenant and UTC day](https://docs.veristar.app/api-reference/api-request-numbers-per-tenant-and-utc-day.md): From `api.metrics_daily`. For each tenant and service the source is chosen over the whole range: metric rows when the service has any, otherwise span rows (control-plane-api 7.3); the two are never added. One item per tenant and day with requests, over every service or the one named by `service`. Eq…
- [API request numbers per tenant, UTC day, service, method and route](https://docs.veristar.app/api-reference/api-request-numbers-per-tenant-utc-day-service-method-and-route.md): From `api.metrics_daily` with the source choice of `/api/daily`. Ordered by tenant, day, service, method and route.
- [API request numbers per tenant and UTC hour](https://docs.veristar.app/api-reference/api-request-numbers-per-tenant-and-utc-hour.md): From `api.metrics_hourly`, which the rollup job refreshes every 5 minutes, so the newest minutes of the current hour can be missing until the next rollup. Source choice as `/api/daily`, over the hour range. One item per tenant and hour with requests.
- [This document](https://docs.veristar.app/api-reference/this-document.md)
- [Gateway limits](https://docs.veristar.app/reference/gateway-limits.md): Every limit of the collect gateway, with its starting value and the reason for it.
- [API metrics capacity](https://docs.veristar.app/reference/capacity.md): Measured storage cost of API metric rows, extrapolated to the retention horizons.
- [Web metrics](https://docs.veristar.app/reference/web-metrics.md): How each of the seven web metrics is produced, and how visitors and visits are counted.
- [OTLP collector (scf-otelcol)](https://docs.veristar.app/reference/collector.md): What the OTLP collector accepts and publishes, and the upstream behaviour its configuration rests on.
- [API metrics storage](https://docs.veristar.app/reference/api-storage.md): The tables, functions, rights and queries that hold API latency metrics.
- [Country lookup (DB-IP)](https://docs.veristar.app/reference/geo.md): How the gateway derives a country code with a local DB-IP database, and nothing more precise.
- [Umami contract](https://docs.veristar.app/reference/umami-contract.md): What the platform relies on in Umami, checked automatically against the pinned image.
- [Security policy](https://docs.veristar.app/security/SECURITY.md): How to report a vulnerability privately, the response targets and the scope of the policy.
- [Threat model](https://docs.veristar.app/security/threat-model.md): What the platform protects, its trust boundaries, and the mitigation and test for each threat.
- [Bot and inflation strategy](https://docs.veristar.app/security/bot-and-inflation.md): How the platform detects and limits bot traffic and artificial metric inflation.
- [Supply chain](https://docs.veristar.app/security/supply-chain.md): How images and the tracker are built, gated, signed, verified and kept up to date.
- [Verify the tracker](https://docs.veristar.app/security/verify-tracker.md): Check that the sdk.js your pages load is exactly the released file.
- [Branch protection for main](https://docs.veristar.app/security/branch-protection.md): The repository settings that make every change go through a reviewed pull request with passing checks.
- [Privacy strategy](https://docs.veristar.app/compliance/privacy-strategy.md): How the platform minimises personal data: what is held in memory, queued and stored, and for how long.
- [Jurisdictions: use without and with end-user opt-in](https://docs.veristar.app/compliance/jurisdictions.md): Where the tracker can run without end-user opt-in, and where consent mode applies.
- [Data residency](https://docs.veristar.app/compliance/data-residency.md): Where each kind of data is processed and stored in the production deployment.
- [Erasure workflow](https://docs.veristar.app/compliance/erasure.md): How a project owner asks for erasure, what is erased, and how the request is tracked.
- [Data protection impact assessment](https://docs.veristar.app/compliance/dpia.md): The data protection impact assessment for cookieless web analytics and API request metrics.
- [Records of processing](https://docs.veristar.app/compliance/records-of-processing.md): The records of processing activities for the service.
- [Sub-processors](https://docs.veristar.app/compliance/subprocessors.md): The sub-processors that support the service, and what each one handles.
- [Terms of use](https://docs.veristar.app/compliance/terms.md): The terms of use that every project accepts when it enrolls.
- [Data processing terms (template)](https://docs.veristar.app/compliance/dpa-template.md): A template for the data processing terms between the operator and a tenant.
- [Legal sources register](https://docs.veristar.app/compliance/sources.md): The register of legal sources the compliance documents rely on.
- [Handover plan](https://docs.veristar.app/handover/plan.md): How stewardship of the service moves from the original operator to a community-appointed operator.
- [Handover readiness checklist](https://docs.veristar.app/handover/checklist.md): Every item that changes hands so the new operator can run the service on its own, with the evidence for each.
- [Rebuild and data migration](https://docs.veristar.app/handover/rebuild.md): How a new operator builds its own environment, moves every tenant's data, takes over the domain and rotates credentials.

## OpenAPI Specs

- [metrics-v1](/reference/openapi/metrics-v1.yaml)


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