feat: Add post label tracking with Redis and metrics

This commit introduces a new feature to track labeled posts using Redis
and trigger account-level actions when thresholds are met. It includes
the following changes:

- Added Redis configuration to `.env.example` and the `compose.yaml`
file to run Redis. - Implemented post tracking logic using Redis. -
Added functionality to apply account labels, report accounts, and
comment on accounts based on label thresholds. - Added example
configuration files (`tracked-labels.json` and
`tracked-labels.example.json`). - Implemented Prometheus metrics for
monitoring label tracking and account actions. - Added a health check
endpoint. - Updated `README.md` with instructions on how to use the new
feature.

.env.example

···
 CURSOR_UPDATE_INTERVAL=10000
 LABEL_LIMIT=2900 * 1000
 LABEL_LIMIT_WAIT=300 * 1000
+
+# Redis configuration for post label tracking
+# Used to track labeled posts and trigger account-level actions when thresholds are met
+REDIS_URL=redis://localhost:6379

README.md

···
 bun run start
 ```
 
-To run in docker:
+To run with Docker Compose (recommended):
+
+```bash
+# Create required files
+touch cursor.txt
+cp .env.example .env
+# Edit .env with your values
+
+# Start services (automod + Redis)
+docker compose up -d
+
+# View logs
+docker compose logs -f
+
+# Stop services
+docker compose down
+```
+
+To run standalone Docker container (you'll need to provide your own Redis):
 
 ```bash
-docker build -pull -t skywatch-tools .
-docker run -d -p 4101:4101 skywatch-autolabeler
+docker build -t skywatch-tools .
+docker run -d \
+  -p 4101:4101 \
+  -e REDIS_URL=redis://your-redis-host:6379 \
+  --env-file .env \
+  -v $(pwd)/cursor.txt:/app/cursor.txt \
+  skywatch-tools
 ```
 
 ## Brief overview
···
 In certain cases, where regexp will create too many false positives, it will flag content as a report against related to the account, so that it can be reviewed later.
 
 For information on how to set-up your own checks, please see the [developing_checks.md](./src/developing_checks.md) file.
+
+## Post Label Tracking
+
+The system includes automated tracking of labeled posts to detect repeat offenders. When configured labels accumulate on posts from the same account, the system automatically applies account-level actions.
+
+### Configuration
+
+**Redis Setup**
+
+Redis is required for tracking labeled posts. Set the `REDIS_URL` environment variable:
+
+```bash
+REDIS_URL=redis://localhost:6379
+```
+
+**Tracked Labels Configuration**
+
+Create `tracked-labels.json` in the project root to configure which labels to track:
+
+```json
+[
+  {
+    "label": "spam",
+    "threshold": 5,
+    "accountLabel": "repeat-spammer",
+    "accountComment": "Account has posted spam content multiple times",
+    "windowDays": 30,
+    "reportAcct": true,
+    "commentAcct": false
+  }
+]
+```
+
+**Configuration Fields:**
+
+- `label` (required): The post label to track
+- `threshold` (required): Number of labeled posts before triggering account action
+- `accountLabel` (required): Label to apply to the account when threshold is met
+- `accountComment` (required): Comment text for account reports/comments
+- `windowDays` (optional): Only count posts within this many days (omit for all-time tracking)
+- `reportAcct` (optional): Whether to report the account when threshold is met (default: false)
+- `commentAcct` (optional): Whether to add a comment to the account when threshold is met (default: false)
+
+See `tracked-labels.example.json` for complete examples.
+
+### How It Works
+
+1. When a post is labeled with a tracked label, the system records it in Redis
+2. The system maintains a count of labeled posts per account per label
+3. When the threshold is reached, the system automatically:
+   - Labels the account with the configured `accountLabel`
+   - Optionally reports the account (if `reportAcct: true`)
+   - Optionally adds a comment (if `commentAcct: true`)
+4. If `windowDays` is set, only posts within that time window are counted
+
+### Data Storage
+
+- Redis keys follow the pattern: `post-labels:{did}:{label}`
+- Post URIs are stored in sorted sets with timestamps as scores
+- Keys automatically expire after 30 days (sliding window)
+- Old posts are pruned based on `windowDays` configuration
+
+## Monitoring and Observability
+
+The system exposes Prometheus metrics and health check endpoints for monitoring.
+
+### Metrics Endpoint
+
+Available at `http://localhost:4001/metrics` (configurable via `METRICS_PORT` environment variable)
+
+**Custom Metrics:**
+
+- `posts_tracked_total` - Counter for posts tracked by label type
+  - Labels: `label_type`
+
+- `thresholds_met_total` - Counter for label thresholds met
+  - Labels: `label_type`, `account_label`
+
+- `account_actions_triggered_total` - Counter for account-level actions triggered
+  - Labels: `action_type` (label|report|comment), `label_type`, `success` (true|false)
+
+- `redis_connected` - Gauge for Redis connection status (1=connected, 0=disconnected)
+
+**Example Prometheus queries:**
+
+```promql
+# Rate of posts being tracked per label
+rate(posts_tracked_total[5m])
+
+# How many times each threshold has been met
+thresholds_met_total
+
+# Success rate of account labeling
+sum(rate(account_actions_triggered_total{action_type="label",success="true"}[5m])) / sum(rate(account_actions_triggered_total{action_type="label"}[5m]))
+```
+
+### Health Check Endpoint
+
+Available at `http://localhost:4001/health`
+
+Returns HTTP 200 when healthy, HTTP 503 when unhealthy.
+
+**Response format:**
+
+```json
+{
+  "status": "healthy",
+  "redis": "connected",
+  "timestamp": "2025-01-18T12:34:56.789Z"
+}
+```
+
+Use this endpoint for:
+- Kubernetes liveness/readiness probes
+- Load balancer health checks
+- Uptime monitoring systems

compose.yaml

···
 version: "3.8"
 
 services:
+  redis:
+    image: redis:7-alpine
+    container_name: skywatch-redis
+    restart: unless-stopped
+
+    # Expose Redis port for debugging (optional, remove in production)
+    ports:
+      - "6379:6379"
+
+    # Persist Redis data
+    volumes:
+      - redis-data:/data
+
+    # Redis configuration
+    command: redis-server --appendonly yes --appendfsync everysec
+
+    # Health check
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 3
+      start_period: 10s
+
   automod:
     # Build the Docker image from the Dockerfile in the current directory.
     build: .
···
     # Restart the container automatically if it stops unexpectedly.
     restart: unless-stopped
 
+    # Wait for Redis to be healthy before starting
+    depends_on:
+      redis:
+        condition: service_healthy
+
     # Expose the metrics server port to the host machine.
     ports:
       - "4100:4101"
···
     env_file:
       - .env
 
+    # Override REDIS_URL to use the Redis service
+    environment:
+      - REDIS_URL=redis://redis:6379
+
     # Mount a volume to persist the firehose cursor.
     # This links the `cursor.txt` file from your host into the container at `/app/cursor.txt`.
     # Persisting this file allows the automod to resume from where it left off
     # after a restart, preventing it from reprocessing old events or skipping new ones.
     volumes:
       - ./cursor.txt:/app/cursor.txt
+
+volumes:
+  redis-data:

src/main.ts

···
 } from "./rules/profiles/checkProfiles.js";
 import { checkFacetSpam } from "./rules/facets/facets.js";
 import { checkAccountAge } from "./rules/account/age.js";
+import { connectRedis, redis } from "./redis.js";
+
+// Initialize Redis connection for post label tracking
+connectRedis();
 
 let cursor = 0;
 let cursorUpdateInterval: NodeJS.Timeout;
···
 
 jetstream.start();
 
-function shutdown() {
+async function shutdown() {
   try {
     logger.info({ process: "MAIN" }, "Shutting down gracefully");
     fs.writeFileSync("cursor.txt", jetstream.cursor!.toString(), "utf8");
     jetstream.close();
     metricsServer.close();
+
+    // Close Redis connection
+    logger.info({ process: "MAIN" }, "Closing Redis connection");
+    await redis.quit();
+    logger.info({ process: "MAIN" }, "Redis connection closed");
   } catch (error) {
     logger.error({ process: "MAIN", error }, "Error shutting down gracefully");
     process.exit(1);

src/metrics.ts

···
 import express from "express";
-import { Registry, collectDefaultMetrics } from "prom-client";
+import { Registry, collectDefaultMetrics, Counter, Gauge } from "prom-client";
 
 import { logger } from "./logger.js";
+import { isRedisConnected } from "./redis.js";
 
 const register = new Registry();
 collectDefaultMetrics({ register });
 
+export const postsTrackedCounter = new Counter({
+  name: "posts_tracked_total",
+  help: "Total number of posts tracked for label threshold monitoring",
+  labelNames: ["label_type"],
+  registers: [register],
+});
+
+export const thresholdsMetCounter = new Counter({
+  name: "thresholds_met_total",
+  help: "Total number of times label thresholds have been met",
+  labelNames: ["label_type", "account_label"],
+  registers: [register],
+});
+
+export const accountActionsCounter = new Counter({
+  name: "account_actions_triggered_total",
+  help: "Total number of account-level actions triggered",
+  labelNames: ["action_type", "label_type", "success"],
+  registers: [register],
+});
+
+export const redisConnectedGauge = new Gauge({
+  name: "redis_connected",
+  help: "Redis connection status (1 = connected, 0 = disconnected)",
+  registers: [register],
+  async collect() {
+    this.set(isRedisConnected() ? 1 : 0);
+  },
+});
+
 const app = express();
 
 app.get("/metrics", (req, res) => {
···
       logger.error({ process: "METRICS", error: (ex as Error).message }, "Error serving metrics");
       res.status(500).end((ex as Error).message);
     });
+});
+
+app.get("/health", (req, res) => {
+  const redisConnected = isRedisConnected();
+  const status = redisConnected ? "healthy" : "unhealthy";
+  const statusCode = redisConnected ? 200 : 503;
+
+  res.status(statusCode).json({
+    status,
+    redis: redisConnected ? "connected" : "disconnected",
+    timestamp: new Date().toISOString(),
+  });
 });
 
 export const startMetricsServer = (port: number, host = "127.0.0.1") => {

src/tests/trackPostLabel.test.ts

···
   addPostAndCheckThreshold: vi.fn(),
 }));
 
+vi.mock("../metrics.js", () => ({
+  postsTrackedCounter: {
+    inc: vi.fn(),
+  },
+  thresholdsMetCounter: {
+    inc: vi.fn(),
+  },
+}));
+
 // Now import after mocks are set up
 import { trackPostLabel } from "../trackPostLabel.js";
 import { logger } from "../logger.js";
 import { addPostAndCheckThreshold } from "../redis.js";
+import { postsTrackedCounter, thresholdsMetCounter } from "../metrics.js";
 
 describe("trackPostLabel", () => {
   const testDid = "did:plc:test123";
···
         testAtURI,
         expect.any(Object),
       );
+    });
+  });
+
+  describe("metrics tracking", () => {
+    it("should increment postsTrackedCounter when post is tracked", async () => {
+      vi.mocked(addPostAndCheckThreshold).mockResolvedValue(2);
+
+      await trackPostLabel(testDid, testAtURI, "spam");
+
+      expect(postsTrackedCounter.inc).toHaveBeenCalledWith({
+        label_type: "spam",
+      });
+    });
+
+    it("should increment postsTrackedCounter for different labels", async () => {
+      vi.mocked(addPostAndCheckThreshold).mockResolvedValue(1);
+
+      await trackPostLabel(testDid, testAtURI, "scam");
+
+      expect(postsTrackedCounter.inc).toHaveBeenCalledWith({
+        label_type: "scam",
+      });
+    });
+
+    it("should increment thresholdsMetCounter when threshold is met", async () => {
+      vi.mocked(addPostAndCheckThreshold).mockResolvedValue(5);
+
+      await trackPostLabel(testDid, testAtURI, "spam");
+
+      expect(thresholdsMetCounter.inc).toHaveBeenCalledWith({
+        label_type: "spam",
+        account_label: "repeat-spammer",
+      });
+    });
+
+    it("should not increment thresholdsMetCounter when below threshold", async () => {
+      vi.mocked(addPostAndCheckThreshold).mockResolvedValue(3);
+
+      await trackPostLabel(testDid, testAtURI, "spam");
+
+      expect(postsTrackedCounter.inc).toHaveBeenCalled();
+      expect(thresholdsMetCounter.inc).not.toHaveBeenCalled();
+    });
+
+    it("should not increment metrics for untracked labels", async () => {
+      await trackPostLabel(testDid, testAtURI, "untracked");
+
+      expect(postsTrackedCounter.inc).not.toHaveBeenCalled();
+      expect(thresholdsMetCounter.inc).not.toHaveBeenCalled();
+    });
+
+    it("should not increment metrics on error", async () => {
+      vi.mocked(addPostAndCheckThreshold).mockRejectedValue(
+        new Error("Redis error"),
+      );
+
+      await trackPostLabel(testDid, testAtURI, "spam");
+
+      expect(postsTrackedCounter.inc).not.toHaveBeenCalled();
+      expect(thresholdsMetCounter.inc).not.toHaveBeenCalled();
     });
   });
 });

src/tests/triggerAccountLabel.test.ts

···
   createAccountComment: vi.fn(),
 }));
 
+vi.mock("../metrics.js", () => ({
+  accountActionsCounter: {
+    inc: vi.fn(),
+  },
+}));
+
 // Import after mocks
 import { triggerAccountLabel } from "../triggerAccountLabel.js";
 import { logger } from "../logger.js";
···
   createAccountReport,
   createAccountComment,
 } from "../moderation.js";
+import { accountActionsCounter } from "../metrics.js";
 
 describe("triggerAccountLabel", () => {
   const testDid = "did:plc:test123";
···
         }),
         expect.any(String),
       );
+    });
+  });
+
+  describe("metrics tracking", () => {
+    it("should increment accountActionsCounter for successful label", async () => {
+      const action: AccountLabelAction = {
+        type: "label-account",
+        did: testDid,
+        config: {
+          label: "spam",
+          threshold: 5,
+          accountLabel: "repeat-spammer",
+          accountComment: "Test",
+        },
+        currentCount: 5,
+      };
+
+      vi.mocked(createAccountLabel).mockResolvedValue(undefined);
+
+      await triggerAccountLabel(action);
+
+      expect(accountActionsCounter.inc).toHaveBeenCalledWith({
+        action_type: "label",
+        label_type: "spam",
+        success: "true",
+      });
+    });
+
+    it("should increment accountActionsCounter for successful report", async () => {
+      const action: AccountLabelAction = {
+        type: "label-account",
+        did: testDid,
+        config: {
+          label: "scam",
+          threshold: 3,
+          accountLabel: "repeat-scammer",
+          accountComment: "Test",
+          reportAcct: true,
+        },
+        currentCount: 3,
+      };
+
+      vi.mocked(createAccountLabel).mockResolvedValue(undefined);
+      vi.mocked(createAccountReport).mockResolvedValue(undefined);
+
+      await triggerAccountLabel(action);
+
+      expect(accountActionsCounter.inc).toHaveBeenCalledWith({
+        action_type: "label",
+        label_type: "scam",
+        success: "true",
+      });
+      expect(accountActionsCounter.inc).toHaveBeenCalledWith({
+        action_type: "report",
+        label_type: "scam",
+        success: "true",
+      });
+    });
+
+    it("should increment accountActionsCounter for successful comment", async () => {
+      const action: AccountLabelAction = {
+        type: "label-account",
+        did: testDid,
+        config: {
+          label: "misinformation",
+          threshold: 10,
+          accountLabel: "frequent-misinfo",
+          accountComment: "Test",
+          commentAcct: true,
+        },
+        currentCount: 10,
+      };
+
+      vi.mocked(createAccountLabel).mockResolvedValue(undefined);
+      vi.mocked(createAccountComment).mockResolvedValue(undefined);
+
+      await triggerAccountLabel(action);
+
+      expect(accountActionsCounter.inc).toHaveBeenCalledWith({
+        action_type: "label",
+        label_type: "misinformation",
+        success: "true",
+      });
+      expect(accountActionsCounter.inc).toHaveBeenCalledWith({
+        action_type: "comment",
+        label_type: "misinformation",
+        success: "true",
+      });
+    });
+
+    it("should increment all three metrics for full config", async () => {
+      const action: AccountLabelAction = {
+        type: "label-account",
+        did: testDid,
+        config: {
+          label: "harassment",
+          threshold: 2,
+          accountLabel: "repeat-harasser",
+          accountComment: "Test",
+          reportAcct: true,
+          commentAcct: true,
+        },
+        currentCount: 2,
+      };
+
+      vi.mocked(createAccountLabel).mockResolvedValue(undefined);
+      vi.mocked(createAccountReport).mockResolvedValue(undefined);
+      vi.mocked(createAccountComment).mockResolvedValue(undefined);
+
+      await triggerAccountLabel(action);
+
+      expect(accountActionsCounter.inc).toHaveBeenCalledWith({
+        action_type: "label",
+        label_type: "harassment",
+        success: "true",
+      });
+      expect(accountActionsCounter.inc).toHaveBeenCalledWith({
+        action_type: "report",
+        label_type: "harassment",
+        success: "true",
+      });
+      expect(accountActionsCounter.inc).toHaveBeenCalledWith({
+        action_type: "comment",
+        label_type: "harassment",
+        success: "true",
+      });
+    });
+
+    it("should increment failure metric when label fails", async () => {
+      const action: AccountLabelAction = {
+        type: "label-account",
+        did: testDid,
+        config: {
+          label: "spam",
+          threshold: 5,
+          accountLabel: "repeat-spammer",
+          accountComment: "Test",
+        },
+        currentCount: 5,
+      };
+
+      vi.mocked(createAccountLabel).mockRejectedValue(new Error("Label failed"));
+
+      await triggerAccountLabel(action);
+
+      expect(accountActionsCounter.inc).toHaveBeenCalledWith({
+        action_type: "label",
+        label_type: "spam",
+        success: "false",
+      });
+    });
+
+    it("should increment failure metric when report fails after successful label", async () => {
+      const action: AccountLabelAction = {
+        type: "label-account",
+        did: testDid,
+        config: {
+          label: "scam",
+          threshold: 3,
+          accountLabel: "repeat-scammer",
+          accountComment: "Test",
+          reportAcct: true,
+        },
+        currentCount: 3,
+      };
+
+      vi.mocked(createAccountLabel).mockResolvedValue(undefined);
+      vi.mocked(createAccountReport).mockRejectedValue(new Error("Report failed"));
+
+      await triggerAccountLabel(action);
+
+      expect(accountActionsCounter.inc).toHaveBeenCalledWith({
+        action_type: "label",
+        label_type: "scam",
+        success: "true",
+      });
+      expect(accountActionsCounter.inc).toHaveBeenCalledWith({
+        action_type: "report_or_comment",
+        label_type: "scam",
+        success: "false",
+      });
+    });
+
+    it("should not increment metrics when reportAcct is false", async () => {
+      const action: AccountLabelAction = {
+        type: "label-account",
+        did: testDid,
+        config: {
+          label: "spam",
+          threshold: 5,
+          accountLabel: "repeat-spammer",
+          accountComment: "Test",
+          reportAcct: false,
+        },
+        currentCount: 5,
+      };
+
+      vi.mocked(createAccountLabel).mockResolvedValue(undefined);
+
+      await triggerAccountLabel(action);
+
+      // Should only have one call for the label action
+      expect(accountActionsCounter.inc).toHaveBeenCalledTimes(1);
+      expect(accountActionsCounter.inc).toHaveBeenCalledWith({
+        action_type: "label",
+        label_type: "spam",
+        success: "true",
+      });
     });
   });
 });

src/trackPostLabel.ts

···
 import { logger } from "./logger.js";
 import { TRACKED_LABELS } from "./config.js";
 import { addPostAndCheckThreshold } from "./redis.js";
+import { postsTrackedCounter, thresholdsMetCounter } from "./metrics.js";
 import type { TrackedLabelConfig } from "./types.js";
 
 /**
···
     // Record the post and get current count
     const currentCount = await addPostAndCheckThreshold(did, atURI, config);
 
+    // Increment tracking metric
+    postsTrackedCounter.inc({ label_type: label });
+
     logger.info(
       {
         process: "TRACK_LABEL",
···
 
     // Check if threshold is met
     if (currentCount >= config.threshold) {
+      // Increment threshold met metric
+      thresholdsMetCounter.inc({
+        label_type: label,
+        account_label: config.accountLabel,
+      });
+
       logger.warn(
         {
           process: "TRACK_LABEL",
···
           label,
           currentCount,
           threshold: config.threshold,
+          accountLabel: config.accountLabel,
         },
         `Threshold met for ${label} - triggering account action`,
       );

src/triggerAccountLabel.ts

···
   createAccountReport,
   createAccountComment,
 } from "./moderation.js";
+import { accountActionsCounter } from "./metrics.js";
 import type { AccountLabelAction } from "./trackPostLabel.js";
 
 /**
···
     // Step 1: Always label the account
     await createAccountLabel(did, config.accountLabel, config.accountComment);
     result.labeled = true;
+    accountActionsCounter.inc({
+      action_type: "label",
+      label_type: config.label,
+      success: "true",
+    });
 
     logger.info(
       {
···
     if (config.reportAcct) {
       await createAccountReport(did, config.accountComment);
       result.reported = true;
+      accountActionsCounter.inc({
+        action_type: "report",
+        label_type: config.label,
+        success: "true",
+      });
 
       logger.info(
         {
···
     if (config.commentAcct) {
       await createAccountComment(did, config.accountComment);
       result.commented = true;
+      accountActionsCounter.inc({
+        action_type: "comment",
+        label_type: config.label,
+        success: "true",
+      });
 
       logger.info(
         {
···
 
     result.error =
       error instanceof Error ? error.message : String(error);
+
+    // Track failure metric
+    accountActionsCounter.inc({
+      action_type: result.labeled ? "report_or_comment" : "label",
+      label_type: config.label,
+      success: "false",
+    });
 
     logger.error(
       {