mercadodevida/work/artifacts/F-029/architect.md

Architect — F-029 Observability: traces and business metrics

Summary

F-029 adds request tracing and business metrics to the backend. Tracing spans critical business operations; metrics expose request counts/histograms and business KPIs.

Design

Module

Create project/src/modules/observability/ with:

• infrastructure/otel-tracer.ts — no-op tracer stub, swap later with real OTel.
• infrastructure/metrics.ts — in-process meter for http_requests_total, http_request_duration_seconds, checkout_completed_total, order_value_sum.
• Fastify request hook for tracing and metrics.

Approach

• instrumentFastify(app, tracer, meter) adds onRequest and onResponse hooks.
• tracer.trace('checkout.start', async () => ...) in checkout service.
• meter.counter('checkout.completed').add(order.total) at checkout completion.
• No new production dependency — use lightweight stubs compatible with future OTel swap.

Files

• project/src/modules/observability/**
• project/src/app/build-app.ts — wire instrumentation at startup.

Acceptance trace

• AC1: request tracing spans created for checkout path.
• AC2: metrics http_requests_total and http_request_duration_seconds observed via /metrics route.
• AC3: business metric checkout_completed_total increments per successful checkout.

Evidence

• work/artifacts/F-029/implementer.md