Dartvel monitoring: metrics, traces, crashes and alerts

Every generated backend serves metrics and a health check, and every app records its own crashes, with nothing to install.

curl https://your-host/metrics
curl https://your-host/health
dartvel metrics

// Registered on first use, and served at GET /metrics as Prometheus text.
DV.ObservabilityAndLogging.metrics
    .counter('refunds_total', <String, String>{'currency': 'usd'})
    .increment();

DV.ObservabilityAndLogging.metrics.gauge('queue_depth').set(12);

DV.ObservabilityAndLogging.metrics
    .histogram('checkout_seconds')
    .observe(0.42);

// Each check answers for itself when GET /health is asked, under a
// deadline. Degraded is not down: a cold cache is slow, and reporting it
// as an outage pages somebody for nothing.
DV.ObservabilityAndLogging.health.register('payments', () async {
  final bool reachable = await gatewayReachable();
  return reachable
      ? DVHealthResult.up()
      : DVHealthResult.down('the gateway did not answer');
});

DV.log writes one line with whatever belongs beside it, and DV.ObservabilityAndLogging is the rest of the surface. There is no second logger to configure per package.

The two halves take different arguments. In the app, level is a string and defaults to info. On the server it is a DVLogLevel, and a line can carry a code.

// One line, with whatever belongs beside it. DV.log and
// DV.ObservabilityAndLogging are the surface; there is no second logger to
// configure per package.
void recordRefund(String orderId, int cents) {
  DV.log(
    'refunded an order',
    context: <String, Object>{'order': orderId, 'cents': cents},
  );
}

// The same two names on the server: DV.log for a line, and
// DV.ObservabilityAndLogging for everything the server serves about itself.
DV.log('Refund accepted', context: <String, Object?>{'orderId': 'o-42'});

DV.log(
  'Gateway slow',
  level: DVLogLevel.warn,
  // A code is what an alert rule matches on. Wording changes; this does not.
  code: 'PAY-SLOW',
  context: <String, Object?>{'gateway': 'stripe', 'ms': 2400},
);

Sampling is decided from the trace id, so every service in a trace makes the same choice without talking to the others.

// Timed as one named step, so a slow checkout points at the work inside
// it instead of at the request as a whole.
Future<T> priced<T>(Future<T> Function() work) =>
    DV.ObservabilityAndLogging.trace<T>('pricing', work);

// The request already has a span, joined to the traceparent it arrived
// with. This is for the work inside it worth seeing on its own.
final DVSpan span =
    DV.ObservabilityAndLogging.tracer.startSpan('reprice-basket');
span.setAttribute('basket.id', 'b-9');
try {
  await Future<void>.delayed(const Duration(milliseconds: 5));
} finally {
  // In a finally: a thrown error would otherwise leave the span open, and
  // the trace then shows a request that never ended.
  span.end();
}

The generated client installs crash reporting at startup. A crash is written as it happens and sent on the next launch, once.

With sink: dartvel under dartvel.crashes, your own backend receives reports. Server processes record a 500, a failing schedule and a dead-lettered job.

DVAlerting fires a rule after it has held for a set time and delivers through DV.Notifications or PagerDuty, once per episode.

An alert opens an incident with a timeline, and a status snapshot shows each component's health without internal detail.

// A promise with a budget attached, and a rule that fires on the budget
// instead of on a single bad minute.
const DVServiceLevel checkout = DVServiceLevel(
  name: 'checkout',
  objective: DVObjective.successRate(0.995, over: Duration(days: 30)),
  applies: DVAppliesTo.backendFunction('placeOrder'),
);

final DVAlertRule backlog = DVAlertRule(
  name: 'mail-backlog',
  signal: const DVSignalRef.queueDepth('mail'),
  condition: const DVAlertWhen.above(100),
  // A rule that fires on the first sample pages somebody for a spike that
  // cleared itself.
  forDuration: const Duration(minutes: 5),
  notify: const <DVAlertTarget>[DVAlertTarget.team('ops')],
);

Declare consent categories under dartvel.analytics. Events in a denied category are dropped at the call, never sent later.

GETTING STARTED

APP

DATA

BACKEND

OPERATIONS

SHIPPING

REFERENCE

Monitoring

Read metrics and health from any backend

Log a line, on the client and on the server

Follow one request across services

Crash reports are on from the first build

Alert on error budgets and open incidents

Product analytics that respect consent

Status