agent-analytics

KO | EN

gitlite — search

#ai #typescript #go #android #deep-learning #linux #nodejs #windows #cli #awesome-list #ios #mcp #openai #open-source

agent-analytics

(★ 14)

Open-source self-hosted analytics for AI agents. One Cloudflare Worker, zero config.

agent-analytics 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Agent Analytics

Web analytics your AI agent can read. Add one script tag, store events in your own Cloudflare D1 database or SQLite file, and query the results from CLI or HTTP instead of living in a dashboard.

Works with Claude Code, Codex, Cursor, OpenClaw, or any agent that can run commands and reason over structured output.

Self-host this repo on Cloudflare Workers + D1 or Docker/Kubernetes + SQLite. If you do not want to run infrastructure, use [Agent Analytics Cloud](https://app.agentanalytics.sh).

[Docs](https://docs.agentanalytics.sh) - [API](https://docs.agentanalytics.sh/api/)

## Why Agent Analytics

- Agent-readable by design. Your agent can call CLI commands or HTTP endpoints directly and reason over structured analytics data.
- Self-hostable. Run the same OSS server on Cloudflare Workers + D1, Docker, Kubernetes, or a single Node.js process backed by SQLite.
- Lightweight. Start with one script tag, then add custom events, consent mode, click tracking, errors, performance, and vitals only when you need them.

## Choose Your Self-Hosted Route

<table>
  <tr>
    <td width="50%" valign="top">
      <p>
        <img src="https://img.shields.io/badge/Cloudflare-Workers%20%2B%20D1-F38020?style=for-the-badge&logo=cloudflare&logoColor=white" alt="Cloudflare Workers + D1" />
      </p>
      <h3>Cloudflare Workers + D1</h3>
      <p>The lowest-ops self-hosted route. Deploy the server as a Worker, store analytics in Cloudflare D1, and let Cloudflare handle edge runtime, TLS, and uptime.</p>
      <p><strong>Best for:</strong> people who already use Cloudflare or want the smallest server-management surface.</p>
      <p><strong>You manage:</strong> Wrangler deploys, D1 database setup, Worker secrets, and allowed origins.</p>
    </td>
    <td width="50%" valign="top">
      <p>
        <img src="https://img.shields.io/badge/Docker-Container-2496ED?style=for-the-badge&logo=docker&logoColor=white" alt="Docker" />
        <img src="https://img.shields.io/badge/Kubernetes-StatefulSet-326CE5?style=for-the-badge&logo=kubernetes&logoColor=white" alt="Kubernetes" />
      </p>
      <h3>Docker / Kubernetes + SQLite</h3>
      <p>The portable infrastructure route. Run the Node.js server in a container, persist SQLite on a volume, and optionally deploy it as a single-replica Kubernetes StatefulSet.</p>
      <p><strong>Best for:</strong> local infrastructure, VPS/container hosts, kind/minikube tests, or teams that want to own the runtime.</p>
      <p><strong>You manage:</strong> container uptime, SQLite persistence, backups, TLS/ingress, and the single-writer SQLite rule.</p>
    </td>
  </tr>
</table>

If you do not want to run infrastructure, use [Agent Analytics Cloud](https://app.agentanalytics.sh). That is the managed product, not this OSS server.

## What It Looks Like

```bash
curl "https://your-server.com/stats?project=marketing-site&since=7d" \
  -H "X-API-Key: YOUR_API_KEY"
```

```json
{
  "project": "marketing-site",
  "period": {
    "from": "2026-03-08",
    "to": "2026-03-14",
    "groupBy": "day"
  },
  "totals": {
    "unique_users": 1203,
    "total_events": 4821
  },
  "timeSeries": [
    {
      "bucket": "2026-03-14",
      "unique_users": 187,
      "total_events": 712
    }
  ],
  "events": [
    {
      "event": "page_view",
      "count": 3920,
      "unique_users": 1203
    },
    {
      "event": "signup_click",
      "count": 127,
      "unique_users": 118
    }
  ],
  "sessions": {
    "total_sessions": 1368,
    "bounce_rate": 0.41,
    "avg_duration": 73215,
    "pages_per_session": 3.5,
    "sessions_per_user": 1.1
  }
}
```

Your agent can turn that into: "Traffic is up this week, most volume still comes from page views, and signup clicks are converting at a lower rate than the homepage traffic increase suggests."

## Quick Start: Deploy

### Route 1: Cloudflare Workers + D1

Runs on the free tier with Cloudflare D1.

```bash
git clone https://github.com/Agent-Analytics/agent-analytics.git
cd agent-analytics
npm install

# Create a D1 database
npx wrangler d1 create agent-analytics
```

Update `wrangler.toml` with the database ID Wrangler returns.

- Replace `YOUR_DATABASE_ID` with the value from `wrangler d1 create`
- Keep the D1 binding name as `DB`
- Optionally change the Worker `name` at the top of the file

```bash
# Initialize the schema
npx wrangler d1 execute agent-analytics --remote --file=./schema.sql

# Deploy the Worker
npx wrangler deploy

# Set your read API key and public project token
echo "YOUR_API_KEY" | npx wrangler secret put API_KEYS
echo "YOUR_PROJECT_TOKEN" | npx wrangler secret put PROJECT_TOKENS
```

Your endpoint will look like `https://agent-analytics.YOUR-SUBDOMAIN.workers.dev`.

If Wrangler cannot find your account, set `CLOUDFLARE_ACCOUNT_ID` first:

```bash
export CLOUDFLARE_ACCOUNT_ID=your-account-id
```

### Route 2: Docker / Kubernetes + SQLite

Build and run the self-hosted Node.js server with SQLite persisted in a Docker volume:

```bash
docker build -t agent-analytics:local .

docker run --rm \
  -p 8787:8787 \
  -e API_KEYS=YOUR_API_KEY \
  -e PROJECT_TOKENS=YOUR_PROJECT_TOKEN \
  -e DB_PATH=/data/analytics.db \
  -v agent_analytics_data:/data \
  agent-analytics:local
```

Then verify the server:

```bash
curl http://localhost:8787/health

curl http://localhost:8787/track \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 Smoke Test" \
  -d '{"token":"YOUR_PROJECT_TOKEN","project":"marketing-site","event":"page_view","properties":{"path":"/"}}'

curl "http://localhost:8787/stats?project=marketing-site&since=7d" \
  -H "X-API-Key: YOUR_API_KEY"
```

Or point the CLI at the Docker server:

```bash
AGENT_ANALYTICS_URL=http://localhost:8787 \
AGENT_ANALYTICS_API_KEY=YOUR_API_KEY \
npx --yes @agent-analytics/cli@0.5.25 stats marketing-site --days 7
```

For local Compose:

```bash
API_KEYS=YOUR_API_KEY PROJECT_TOKENS=YOUR_PROJECT_TOKEN docker compose up --build
```

`compose.yaml` mounts a named volume at `/data`, so the SQLite file survives container restarts.

#### Kubernetes

The included Kubernetes manifests run the same Docker image as a single-replica `StatefulSet` with a persistent volume mounted at `/data`.

For a full local `kind` walkthrough, including creating a live project and verifying it with the CLI, see [`deploy/kubernetes/README.md`](deploy/kubernetes/README.md).

No official container image is published yet. Build the image yourself and use that image in your cluster.

For local clusters, build and load `agent-analytics:local` into the cluster runtime:

```bash
docker build -t agent-analytics:local .

# kind
kind load docker-image agent-analytics:local

# minikube
minikube image load agent-analytics:local
```

For remote clusters, push the image to your own registry and replace `agent-analytics:local` in `deploy/kubernetes/statefulset.yaml` with your registry image.

Create secrets and apply the workload:

```bash
kubectl create secret generic agent-analytics-secrets \
  --from-literal=API_KEYS=YOUR_API_KEY \
  --from-literal=PROJECT_TOKENS=YOUR_PROJECT_TOKEN

kubectl apply -f deploy/kubernetes/service.yaml
kubectl apply -f deploy/kubernetes/statefulset.yaml
```

Optional ingress example:

```bash
kubectl apply -f deploy/kubernetes/ingress.example.yaml
```

Treat `ingress.example.yaml` as a template. Update the host, TLS secret, ingress class, and any provider-specific annotations for your cluster.

#### Plain Node.js

If you do not want Docker, run the same server directly with Node.js:

```bash
git clone https://github.com/Agent-Analytics/agent-analytics.git
cd agent-analytics
npm install

API_KEYS=YOUR_API_KEY PROJECT_TOKENS=YOUR_PROJECT_TOKEN npm start
```

Optional environment variables:

- `PORT=3000` to change the server port
- `DB_PATH=./data/analytics.db` to choose the SQLite file location
- `ALLOWED_ORIGINS=https://app.example.com,https://www.example.com` to restrict browser reads

The SQLite database is created automatically if it does not exist.

### SQLite Operational Limits

Docker is supported for one Node process serving many users calling `/track`; Docker is not the bottleneck. The practical limits are SQLite write serialization, disk speed, and long analytical reads competing with ingestion inside the Node process.

For SQLite deployments:

- run exactly one server process or Kubernetes pod against a given SQLite file
- mount a persistent volume at `/data`
- keep `DB_PATH=/data/analytics.db` or another path on that persistent volume
- do not mount the same SQLite file into multiple pods or replicas
- avoid network filesystems unless you have verified SQLite WAL locking behavior on that storage class

Move beyond SQLite when you need sustained high write volume, frequent long-window analytical queries during ingestion, or horizontally scaled API replicas. That next step should be a database adapter backed by Postgres or another client/server database, then a Kubernetes `Deployment` can scale the API separately from storage.

## Add Tracking to Your Site

```html
<script defer src="https://your-server.com/tracker.js"
        data-project="marketing-site"
        data-token="YOUR_PROJECT_TOKEN"></script>
```

In the OSS server, a project is just the string you send with each event. It shows up in `GET /projects` after the first event lands.

Use declarative HTML events when possible:

```html
<button data-aa-event="signup_click" data-aa-event-plan="pro">
  Start free trial
</button>
```

Use the JS API when event properties depend on runtime state:

```javascript
window.aa?.track('checkout_started', { plan: 'pro' });
window.aa?.identify('user_123');
window.aa?.page('Pricing');
```

For browser-side options like consent mode, click tracking, downloads, errors, performance, vitals, and cross-domain identity, see the [Tracker.js guide](https://docs.agentanalytics.sh/reference/tracker-js/).

## What Your Agent Can Do

For self-hosted OSS, point the CLI at your server with environment variables:

```bash
export AGENT_ANALYTICS_URL=https://your-server.com
export AGENT_ANALYTICS_API_KEY=YOUR_API_KEY
```

```bash
npx --yes @agent-analytics/cli@0.5.25 projects
npx --yes @agent-analytics/cli@0.5.25 stats marketing-site --days 7
npx --yes @agent-analytics/cli@0.5.25 events marketing-site --event signup_click --days 7 --limit 20
```

If your agent prefers raw JSON, use the HTTP API directly:

```bash
curl "$AGENT_ANALYTICS_URL/events?project=marketing-site&event=signup_click&since=7d&limit=20" \
  -H "X-API-Key: $AGENT_ANALYTICS_API_KEY"
```

The hosted `login` flow in the CLI is for Agent Analytics Cloud. For this self-hosted OSS server, the simplest path is `AGENT_ANALYTICS_URL` plus `AGENT_ANALYTICS_API_KEY`.

## What Gets Tracked and Stored

- Default `page_view` events include full URL, pathname, hostname, referrer, title, screen resolution, language, browser, browser version, OS, device type, timezone, UTM parameters, session count, and first-touch attribution.
- `tracker.js` uses `localStorage` for anonymous visitor ID, first-touch attribution, visit counters, consent state, and the optional local opt-out flag. It uses `sessionStorage` for session ID, last activity, and current-session UTM context.
- No cookies are required by `tracker.js`.
- Custom events, known user IDs, click/download/form/error/performance/vitals tracking, and consent gating only happen if you call the JS API or enable the related tracker attributes.
- Automated traffic that hits the tracker is filtered out of normal analytics.
- In OSS mode, raw event data stays in your Cloudflare D1 database or SQLite file. You control retention, backups, allowed origins, and API key distribution.
- Want stricter browser behavior? Enable `data-do-not-track="true"` to honor Do Not Track and `data-require-consent="true"` to buffer events until consent is granted.

## Use OSS If / Use Cloud If

| Use OSS if... | Use Cloud if... |
| --- | --- |
| You want to own storage, deployment, retention, and API keys | You want zero-ops onboarding and managed infrastructure |
| You already run Cloudflare Workers or Node.js services | You want account and project management built in |
| You want the minimal self-hosted surface in this repo | You want the broader hosted product surface without wiring it yourself |

## How the Pieces Fit

| Piece | Role |
| --- | --- |
| This repo (`agent-analytics`) | Self-hosted server, auth glue, and `tracker.js` delivery for Workers or Node.js |
| [`@agent-analytics/core`](https://github.com/Agent-Analytics/agent-analytics-core) | Platform-agnostic analytics handler, tracker, and database adapter contracts |
| [`@agent-analytics/cli`](https://www.npmjs.com/package/@agent-analytics/cli) | Agent-friendly CLI that can target your own server via `AGENT_ANALYTICS_URL` |
| [Docs](https://docs.agentanalytics.sh) | Setup guides, tracker guide, API reference, and OpenAPI spec |
| [Agent Analytics Cloud](https://app.agentanalytics.sh) | Hosted product with managed onboarding and no infrastructure |

## OSS API Surface

The self-hosted server in this repo exposes these routes:

- `GET /health`
- `GET /tracker.js`
- `POST /track`
- `POST /track/batch`
- `POST /identify`
- `GET /projects`
- `GET /stats?project=...`
- `GET /events?project=...`

Read endpoints require `X-API-Key`. Write endpoints use the public project token in the JSON body. The public docs and OpenAPI spec cover the broader Agent Analytics platform too, so treat the list above as the source of truth for the OSS server in this repo.

## Contributing

```bash
npm install
npm run dev
npm start
npm test
```

- `npm run dev` starts the Cloudflare Worker locally
- `npm start` runs the Node.js self-hosted server
- Open issues or PRs at https://github.com/Agent-Analytics/agent-analytics/issues

## License

MIT

agent-analytics

agent-analytics 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

agent-analytics

agent-analytics 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README