# Quan sát hệ thống

> **TL;DR** — Với mỗi lệnh gọi tới Wandura, hãy log thời điểm, endpoint, status, `error_code`, độ trễ, **prefix** của key, tập phim và `viewer_ref` của bạn, và cả request id khi tính năng này chạy. Không bao giờ log key, vé, link đã ký hay giá trị thiết bị thô. Theo dõi tỉ lệ xin vé thành công theo mã, `5xx` và độ trễ, sức khoẻ của job đồng bộ catalog, và các header báo ngừng hỗ trợ.

## Cần log gì ở mỗi lệnh gọi
| Trường | Vì sao |
|---|---|
| Timestamp UTC (đến mili giây), endpoint và method | Bộ phận hỗ trợ tìm lệnh gọi của bạn theo thời điểm và endpoint. |
| HTTP status, `error_code` (hoặc `code` của creatives), `reason`, `fields` | Chuyện gì đã xảy ra. |
| Độ trễ | Phát hiện chậm trước khi người xem thấy. |
| `Wandura-Request-Id`, hoặc `request_id` trong body lỗi | Đúng request đó trong log của Wandura. |
| `Wandura-Version`, `Wandura-API-Status`, `Retry-After`, `Deprecation`, `Sunset` | Tín hiệu về phiên bản và vòng đời. |
| **Prefix** của key (`wnd_live_ab12cd`), không bao giờ là key | Key nào, một cách an toàn. |
| Tập phim (`episode_id`, hoặc `film_ref` + `episode_no`), `intent`, kích thước batch và status của từng mục | Sự cố playback xảy ra theo từng tập. |
| `viewer_ref` của bạn | Nối bản ghi của Wandura với người xem của bạn mà không cần dữ liệu cá nhân. |

Mọi response đều mang `Wandura-Request-Id`, và mọi body lỗi JSON đều có `request_id`. Hãy log nó ở mọi lệnh gọi.

## Không bao giờ log
| Giá trị | Thay bằng |
|---|---|
| API key, header `Authorization` | Prefix của key |
| `play_auth_token`, `manifest_url`, link video mở | Không ghi gì, hoặc ghi "có" |
| `union_info`, `drm_kek` thô | Một hash ngắn |
| Email, số điện thoại, tên người xem — kể cả bên trong `viewer_ref` | `viewer_ref` opaque của bạn |
| Toàn bộ body response của `/playback` | Status, mã và `expires_at` |

Quy tắc này áp dụng cả cho công cụ APM, proxy, analytics và công cụ báo crash. Các ví dụ có sẵn một hàm che dữ liệu:

```ts
/** Secrets are dropped; device values are hashed; API keys are cut to the prefix the portal shows. */
const SECRET_FIELDS = new Set(['authorization', 'api_key', 'play_auth_token', 'grant_ticket', 'manifest_url']);
const HASHED_FIELDS = new Set(['union_info', 'drm_kek']);

/** `wnd_live_ab12cd…` → `wnd_live_ab12cd`. Enough for support, useless to an attacker. */
export function keyPrefix(key: string): string {
  return key.slice(0, 15);
}

/** Copy with secrets removed. Run everything you log, trace or send to a crash reporter through it. */
export function redact(value: unknown): unknown {
  if (Array.isArray(value)) return value.map(redact);
  if (typeof value === 'string') return value.replace(/wnd_live_[A-Za-z0-9_-]{6,}/g, (k) => `${keyPrefix(k)}…`);
  if (!value || typeof value !== 'object') return value;
  const out: Record<string, unknown> = {};
  for (const [k, v] of Object.entries(value)) {
    const lk = k.toLowerCase();
    if (SECRET_FIELDS.has(lk)) out[k] = '[redacted]';
    else if (HASHED_FIELDS.has(lk) && typeof v === 'string') out[k] = `sha256:${createHash('sha256').update(v).digest('hex').slice(0, 12)}`;
    else out[k] = redact(v);
  }
  return out;
}
```

## Cần theo dõi gì
| Tín hiệu | Cảnh báo khi | Thường có nghĩa là |
|---|---|---|
| Kết quả xin vé theo `error_code` | `not_entitled` tăng vọt | Một giấy phép đã kết thúc — kiểm tra job đồng bộ catalog |
|  | `invalid_device_info` hoặc `sdk_required` tăng vọt | Một bản phát hành app làm hỏng phần nối Player SDK |
|  | `429` ở vé `play` | Một vòng lặp retry, hoặc đỉnh lưu lượng vượt giới hạn của bạn |
| Tỉ lệ `5xx` và độ trễ xin vé | `5xx` trên 1 % hoặc độ trễ trên 2 giây trong 5 phút | Sự cố phía Wandura: hãy báo ([Xử lý sự cố](https://docs.wandura.ai/vi/v1/developers/production/troubleshooting#escalate)) |
| Lần đồng bộ catalog thành công gần nhất | Cũ hơn hai chu kỳ | Job bị treo sẽ tiếp tục hiện các phim đã rút |
| Số phim và số tập phát được | Giảm đột ngột | Đáng nhắn cho Wandura |
| Header `Deprecation` / `Sunset` | Bất kỳ khi nào xuất hiện | Sắp có thay đổi: [Chuyển phiên bản](https://docs.wandura.ai/vi/v1/developers/guides/migrating-versions) |
| **Last used** của từng key, trên **Developers** | Một key bạn tưởng không dùng lại đang được dùng | Key bị lộ, hoặc một hệ thống bị bỏ quên |

Trên partner.wandura.ai → **Developers** → **API usage** bạn xem được số lệnh gọi theo key và endpoint trong 30 ngày gần nhất.

## Liên quan
- [Xử lý sự cố](https://docs.wandura.ai/vi/v1/developers/production/troubleshooting)
- [Bảo mật](https://docs.wandura.ai/vi/v1/developers/concepts/security#never-in)