Custom Metrics

Send custom application-level metrics to JustAnalytics.

Overview#

Beyond automatic infrastructure metrics, you can send custom metrics from your application code. Use custom metrics to track business KPIs, queue depths, cache hit rates, and any other numeric value.

Recording Metrics#

import JA from '@justanalyticsapp/node';

// Simple metric
JA.recordMetric('custom.queue_size', 42);

// Metric with tags
JA.recordMetric('custom.order_total', 149.99, {
  currency: 'USD',
  region: 'us-east-1',
});

// Metric in a span context
JA.startSpan('process-batch', async (span) => {
  const items = await getBatchItems();
  JA.recordMetric('custom.batch_size', items.length, {
    queue: 'orders',
  });

  const processed = await processBatch(items);
  JA.recordMetric('custom.batch_duration_ms', Date.now() - startTime);
  JA.recordMetric('custom.batch_success_rate', processed / items.length);
});

Naming Conventions#

Use dot-separated names for hierarchical organization:

custom.queue.depth
custom.cache.hit_rate
custom.api.request_count
custom.payment.amount
custom.payment.success_rate

Prefix all custom metrics with custom. to distinguish them from built-in system metrics.

Metric Types#

All metrics are stored as gauge values (point-in-time measurements). The dashboard supports:

Line charts -- value over time
Aggregations -- avg, min, max, sum, count
Group by tags -- break down by tag values

Tags#

Tags add dimensions to your metrics for filtering and grouping:

JA.recordMetric('custom.api_latency_ms', 245, {
  endpoint: '/api/orders',
  method: 'GET',
  status: '200',
  region: 'us-east-1',
});

| Do | Don't | |-----|-------| | Use low-cardinality values (region: 'us-east-1') | Use high-cardinality values (userId: 'user_12345') | | Use consistent tag names across services | Use different names for the same concept | | Keep tag values short | Include full URLs or long strings |

Viewing Custom Metrics#

Custom metrics appear in Monitoring > Infrastructure > Custom Metrics. You can:

Chart any metric over time
Group by tag values
Set alerts on custom metric thresholds
Create custom dashboards

Alerting on Custom Metrics#

Create alert rules using custom metrics:

Rule: Queue Depth Critical
Metric: custom.queue.depth
Condition: > 1000
Window: 5 minutes
Severity: Critical
Tags: queue=orders

Limits#

| Limit | Value | |-------|-------| | Max metric names per site | 500 | | Max tags per metric | 10 | | Max tag key length | 50 characters | | Max tag value length | 200 characters | | Ingestion rate | 1,000 metrics/minute per site |