88 lines
2.5 KiB
Markdown
88 lines
2.5 KiB
Markdown
# New API Analytics
|
|
|
|
Internal analytics dashboard for New API usage logs. The app reads PostgreSQL log data and visualizes calls, token consumption, model usage, channel usage, per-user aggregation, and raw request logs.
|
|
|
|
## Requirements
|
|
|
|
- Bun for local development and tests.
|
|
- Node.js 20 for the production Docker image.
|
|
- PostgreSQL database with New API tables described in `docs/database.md`.
|
|
- `PG_CONNECTION_STRING` set to a PostgreSQL connection string.
|
|
|
|
## Local Development
|
|
|
|
```bash
|
|
bun install
|
|
bun run dev
|
|
```
|
|
|
|
Open `http://localhost:3000`.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
bun test
|
|
bun run lint
|
|
bun run build
|
|
```
|
|
|
|
`bun test` covers parser helpers, metric conversion, query behavior, cache behavior, theme helpers, and selected API route guardrails.
|
|
|
|
Smoke test: AO/Codex can update this README, pass lint, and open a GitLab MR.
|
|
|
|
## Configuration
|
|
|
|
Create an environment file or export:
|
|
|
|
```bash
|
|
PG_CONNECTION_STRING=postgres://user:password@host:5432/database
|
|
```
|
|
|
|
The app uses this variable in `lib/db.ts` to create a `pg` connection pool.
|
|
|
|
OIDC authentication is optional. If no OIDC variables are set, the dashboard and API remain open.
|
|
To require login through a standard OIDC provider such as Sinodoor, add:
|
|
|
|
```bash
|
|
OIDC_ISSUER=https://casdoor.example.com
|
|
OIDC_CLIENT_ID=analytics
|
|
OIDC_CLIENT_SECRET=replace-me
|
|
AUTH_SECRET=replace-with-random-secret
|
|
# Optional login button label:
|
|
OIDC_PROVIDER_NAME=Sinodoor
|
|
```
|
|
|
|
Generate `AUTH_SECRET` with a stable random value, for example:
|
|
|
|
```bash
|
|
openssl rand -base64 32
|
|
```
|
|
|
|
When OIDC is enabled, configure the provider redirect URI as:
|
|
|
|
```text
|
|
https://your-analytics-domain/api/auth/callback/oidc
|
|
```
|
|
|
|
Partial OIDC configuration is treated as an error instead of falling back to open access.
|
|
|
|
## Deployment
|
|
|
|
The included Dockerfile builds a standalone Next.js output and starts `server.js` on port `8019`.
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
The default `docker-compose.yml` expects `.env.production` and an external Docker network named `sinobridge`.
|
|
|
|
For Coolify deployments, use `docker-compose.coolify.yml`. It expects runtime environment variables from Coolify and an external Docker network named `coolify`.
|
|
|
|
## Operational Notes
|
|
|
|
- API query parameters are validated at the route layer. Invalid integers or reversed date ranges return HTTP 400.
|
|
- Ranking limits are capped at 100 rows per request.
|
|
- Log page size is capped at 200 rows per request.
|
|
- Query results are cached in-process for 120 seconds with a 500-entry cap.
|
|
- Metric definitions and quota conversion are documented in `docs/metrics.md`.
|