StatsD

​

The MetricsType interface

type MetricsType = {
  increment: (stat: string, value?: number, tags?: Record<string, string>) => void;
  decrement: (stat: string, value?: number, tags?: Record<string, string>) => void;
  gauge:     (stat: string, value: number,  tags?: Record<string, string>) => void;
  timing:    (stat: string, value: number,  tags?: Record<string, string>) => void;
  histogram: (stat: string, value: number,  tags?: Record<string, string>) => void;
};

// ✅ Good — low-cardinality tag
tools.metrics.increment('subscription.created', 1, { plan: subscription.plan });

// ❌ Bad — high-cardinality tag
tools.metrics.increment('subscription.created', 1, { userId: user.id });

​

Why

​

Setup

1. In apps/backend/package.json, ensure "tooling-metrics-statsd": "workspace:*" is listed under dependencies.
2. Run make deps-install.
3. In development.ts and test.ts, use mock mode:
   metrics: {
     client: MetricsClientType.STATSD,
     options: { mock: true },
   }
   
4. In production.ts, point at your StatsD agent:
   metrics: {
     client: MetricsClientType.STATSD,
     options: {
       host: process.env.STATSD_HOST,
       port: Number(process.env.STATSD_PORT ?? 8125),
       globalTags: { env: 'production', service: 'backend' },
     },
   }
   
5. In your production environment, set:
   STATSD_HOST=your-statsd-agent-host
   STATSD_PORT=8125
   
6. Run make test module=tooling-metrics-statsd and make test module=backend.

​

Emitting metrics

// Counter — how many times something happened
tools.metrics.increment('webhook.received', 1, { provider: 'stripe' });

// Gauge — current state
tools.metrics.gauge('queue.depth', queueDepth, { queue: 'email' });

// Timing — how long something took (ms)
tools.metrics.timing('subscription.upgrade.duration', durationMs, { plan: newPlan });

// Histogram — distribution of a value
tools.metrics.histogram('invoice.amount', amountCents, { currency: 'usd' });

​

Gotchas

• StatsD uses UDP — metric sends are fire-and-forget and will not throw on failure. Errors are routed to tools.logger.error via the errorHandler in buildStatsdClient.
• globalTags are merged into every metric. Keep them low-cardinality (env, service) — never put per-request data in global tags.
• mock: true must be removed in production. If you accidentally leave it on, all metrics are silently swallowed — your dashboards will appear empty.
• Never omit host and port in production. hot-shots defaults to localhost:8125, which silently drops metrics if no agent is listening there.

​

What’s next?

• Configuration — switching pluggable tool implementations.
• Tooling system — how loaders and workspace packages fit together.