feat(observability): OpenTelemetry instrumentation for the generator and REST API

[sebastienrousseau]

Labels: enhancement, priority/p2, observability

User story

As a platform engineer running pain001 in a microservices mesh
I want OpenTelemetry spans around generate_xml_string,
process_files, and every REST handler
so that I can trace payment-file latency in Datadog / Honeycomb /
Tempo alongside the rest of my services without writing custom adapters.

Why now

Enterprise procurement teams expect OTel as table stakes in 2026. Pairs
naturally with the existing Prometheus surface (metrics + traces +
logs is the three-legged stool). Trivially small change.

Scope

In

• OTEL_ENABLED=true env var as the master switch (off by default).
• @traced decorator on generate_xml_string, process_files,
  validate_scheme, and each FastAPI handler.
• Span attributes: pain001.message_type, pain001.row_count,
  pain001.scheme, pain001.profile, http.route (REST).
• New optional extra: pain001[otel] pulling in
  opentelemetry-api, opentelemetry-sdk,
  opentelemetry-exporter-otlp, and FastAPI auto-instrumentation.

Out

• Hosted collector / exporter config (document, don't ship).
• Custom samplers (use the OTel SDK defaults).

Acceptance criteria

Given `pip install "pain001[otel]"` and `OTEL_ENABLED=true`
And `OTEL_EXPORTER_OTLP_ENDPOINT` points at a collector
When `pain001 generate ...` runs
Then a trace appears at the collector with at least three spans:
`pain001.generate`, `pain001.validate`, `pain001.write`

Given `OTEL_ENABLED` is unset
When pain001 runs
Then no OTel SDK is initialised, no spans are emitted, and there is
zero startup overhead from the otel extra

Effort

S (3-5 days).

---