Watch a flow - focale

Mark a confirmed backend handler as a flow focale should care about. Use the flow key from onboarding (for example auth.signup or checkout). Preserve existing behavior; only observe. focale can land this for you in the watching pull request. You only need this page if you are wrapping a handler yourself.

What to emit

Signal	When
Trace	Every attempt: enter, success, failure. Set span status OK/ERROR; record exceptions on failure.
Metrics	Counters `focale.flow.started` / `succeeded` / `failed` and histogram `focale.flow.duration` (ms).
Log	ERROR/WARN on failure (or a rare important branch). Do not log every success.

Shared attributes: focale.flow_key, and focale.signal as {flowKey}.started | .succeeded | .failed when relevant.

Node sketch

import { trace, metrics, SpanStatusCode } from '@opentelemetry/api';
import { logs, SeverityNumber } from '@opentelemetry/api-logs';

const tracer = trace.getTracer('focale');
const meter = metrics.getMeter('focale');
const started = meter.createCounter('focale.flow.started');
const succeeded = meter.createCounter('focale.flow.succeeded');
const failed = meter.createCounter('focale.flow.failed');
const duration = meter.createHistogram('focale.flow.duration', { unit: 'ms' });
const logger = logs.getLogger('focale');

export async function signup(req) {
  const flowKey = 'auth.signup';
  const attrs = { 'focale.flow_key': flowKey, 'focale.signal': `${flowKey}.started` };
  started.add(1, attrs);
  const t0 = Date.now();
  return tracer.startActiveSpan(flowKey, { attributes: attrs }, async (span) => {
    try {
      // existing signup work
      const result = await doSignup(req);
      span.setAttribute('focale.signal', `${flowKey}.succeeded`);
      span.setStatus({ code: SpanStatusCode.OK });
      succeeded.add(1, { 'focale.flow_key': flowKey });
      return result;
    } catch (err) {
      span.setAttribute('focale.signal', `${flowKey}.failed`);
      span.recordException(err);
      span.setStatus({ code: SpanStatusCode.ERROR });
      failed.add(1, { 'focale.flow_key': flowKey });
      logger.emit({
        severityNumber: SeverityNumber.ERROR,
        body: err instanceof Error ? err.message : String(err),
        attributes: { 'focale.flow_key': flowKey },
      });
      throw err;
    } finally {
      duration.record(Date.now() - t0, { 'focale.flow_key': flowKey });
      span.end();
    }
  });
}

Boot once at process start so exporters are live and a span carries focale.boot=true. See install for FOCALE_DSN and OTLP for the wire contract.

Use the flow names you confirmed during onboarding when you can. That is how home knows which money or trust path broke.