Observability

The gateway is the natural place to observe all traffic crossing our boundary. Every call goes through it; every call is traced, logged, and metered.

Tracing

• Every call gets a trace_id (OpenTelemetry)
• One parent span per logical operation (e.g., "create quote")
• Child spans for each resource call, with resource-specific attributes
• Consumer identity is a span attribute, not a separate auth context

Span Attributes

gateway.consumer_id = "atlantes-orchestrator"
gateway.endpoint = "/v1/quotes"
gateway.method = "POST"
gateway.resource = "salesforce"
gateway.resource_endpoint = "/services/data/v59.0/sobjects/Quote__c"
gateway.resource_request_id = "..."
gateway.attempt = 1
gateway.latency_ms = 234
gateway.result = "success" | "error" | "timeout"

Logging

Structured JSON, indexed by trace_id, request_id, consumer_id, resource.

Per-call log line

{
  "timestamp": "...",
  "level": "info",
  "trace_id": "...",
  "consumer_id": "atlantes-orchestrator",
  "resource": "salesforce",
  "endpoint": "/v1/quotes",
  "method": "POST",
  "status": 201,
  "latency_ms": 234,
  "attempt": 1,
  "request_id": "...",
  "resource_request_id": "..."
}

Per-error log line

Same shape with error.code, error.vendor_code, error.message.

Metrics

Metric	Type	Use
gateway.calls.total	Counter	Volume per consumer × resource
gateway.calls.errors	Counter	Error rate
gateway.latency.p95	Histogram	Per-endpoint SLO
gateway.quota.remaining	Gauge	Resource budget health
gateway.circuit.state	Gauge (0/1/2)	Circuit breaker state
gateway.webhook.inbound.received	Counter	Inbound volume
gateway.webhook.outbound.delivered	Counter	Outbound delivery success
gateway.webhook.inbound.rejected	Counter	Signature/dedupe rejections

Alerts

• Per-resource error rate above 5% over 5 minutes
• Per-endpoint p95 latency above SLO
• Circuit breaker open for any resource
• Resource quota remaining below 10%
• Inbound webhook rejection rate spike (possible misconfiguration or attack)
• Consumer error rate spike (possible consumer bug or credential issue)

Health Endpoint

/v1/healthz returns:

• Gateway status
• Live connection state to each of our configured resources
• Authenticated user info as proof of working credentials

Hit by the platform's external health check every 30 seconds.