# Observability — magento-orderwebhook

> **Last verified:** 2026-02-26 (Europe/London)
> **Owner:** Engineering
> **Related:** [BOUNDARIES.md](BOUNDARIES.md) | [INTEGRATIONS.md](INTEGRATIONS.md)

---

## Summary

| Capability | Status | Notes |
|------------|--------|-------|
| Logging | PRESENT (conditional) | PSR-3 logger injected; controlled by `order_webhook/general/log_enabled` config |
| Metrics | ABSENT | No metrics instrumentation found |
| Tracing | ABSENT | No distributed tracing found |
| Correlation IDs | ABSENT | No correlation ID propagated to NGauge |

---

## Logging

### Log Control

Logging is gated by the `order_webhook/general/log_enabled` admin config setting (default: `1`). When disabled, no log entries are written.

### Log Prefix

All log messages from `WebhookSender` are prefixed `[OrderWebhook]`.

### Log Events

| Event | Level | Location | Contains PII? | Notes |
|-------|-------|----------|--------------|-------|
| Webhook disabled — skipping | INFO | `WebhookSender` | No | Logged when `enabled = 0` |
| Re-entrancy guard active — skipping | INFO | `WebhookSender` | No | Prevents recursive logging loop |
| Sending webhook | INFO | `WebhookSender` | Order ID (non-PII) | Logs order increment ID and event type |
| Webhook sent successfully | INFO | `WebhookSender` | No | Logged on 2xx response |
| Webhook failed (attempt N) | WARNING/ERROR | `WebhookSender` | No | Logs HTTP status and attempt number |
| Max retries exceeded | ERROR | `WebhookSender` | No | Logged after all retries exhausted |
| Exception in observer | ERROR | `OrderPlaceAfter`, `OrderSaveAfter` | No | `try/catch` wraps `execute()` in both observers |

`UNKNOWN — Requires Clarification`: Whether the log channel writes to a dedicated file (e.g., `order_webhook.log`) or the default Magento `system.log`. Log channel configuration not found in source.

---

## Failure Handling

| Failure Type | Owned By | Detection | Handling |
|--------------|----------|-----------|----------|
| NGauge HTTP error (4xx/5xx) | This module | HTTP response code check | Log error; retry with exponential backoff up to `retry_attempts` |
| NGauge timeout | This module | HTTP client timeout | Log error; retry with exponential backoff |
| Max retries exceeded | This module | Retry counter | Log error; exit gracefully — order not blocked |
| Observer exception | This module | `try/catch` in `execute()` | Exception caught and logged; observer does not propagate |
| Re-entrancy (recursive save loop) | This module | Static `$sending` flag | Silent skip — log entry written when skipping |
| Decryption failure | `UNKNOWN — Requires Clarification` | None visible | `UNKNOWN — Requires Clarification` |

---

## Correlation IDs

No correlation ID is passed from Magento to NGauge or returned. There is no mechanism to trace a specific Magento order in NGauge logs from the Magento side (other than order increment ID and NGauge-assigned `ngauge_order_id`).

`UNKNOWN — Requires Clarification`: Does NGauge generate or return a request/trace ID in the response?

---

## Metrics

No custom metrics are emitted. There is no StatsD, Prometheus, or similar instrumentation.

---

## Admin Visibility

- NGauge sync status is visible in the admin order view via the `NgaugeFields` block.
- `ngauge_order_no`, `ngauge_order_id`, and `ngauge_order_link` are shown when present.
- The "Send to NGauge" button is hidden once `ngauge_order_id` is set — this provides implicit sync-status feedback to admins.

---

## Confirmed Facts

- Logging is PSR-3 compliant, injected via constructor in `WebhookSender`.
- Both observers wrap their `execute()` in try/catch — observer failures are contained.
- Static re-entrancy guard prevents recursive save-loop and provides a log entry when triggered.
- Single `orderRepository->save()` reduces ambiguity about when NGauge data was persisted.
- No distributed tracing or metrics instrumentation exists.

---

## Unknowns

1. `UNKNOWN — Requires Clarification`: Which log file does the logger write to? (`system.log`, `exception.log`, or a dedicated channel?)
2. `UNKNOWN — Requires Clarification`: Are log entries searchable or aggregated in any log management tool (Kibana, Datadog, etc.)?
3. `UNKNOWN — Requires Clarification`: What happens if `EncryptorInterface` fails to decrypt the API key? Is this exception caught?
4. `UNKNOWN — Requires Clarification`: Does NGauge return a request/trace ID that could be logged for correlation?

---

## Evidence

- `/modules/magento-orderwebhook/src/Model/WebhookSender.php`
- `/modules/magento-orderwebhook/src/Observer/OrderPlaceAfter.php`
- `/modules/magento-orderwebhook/src/Observer/OrderSaveAfter.php`
- `/modules/magento-orderwebhook/src/etc/config.xml`
- `/modules/magento-orderwebhook/src/etc/adminhtml/system.xml`
- `/modules/magento-orderwebhook/src/Block/Adminhtml/Order/NgaugeFields.php`
- `/modules/magento-orderwebhook/src/view/adminhtml/templates/order/view/ngauge_fields.phtml`
