---
title: Lead Scoring Observability
description: Quy ước telemetry, ngưỡng cảnh báo và kill switch cho Customer Pilot.
status: draft
tags: [lead-scoring, operations, privacy]
---

# Lead Scoring Observability

## Telemetry boundary

AI Platform dùng `Observability` làm telemetry sink trong pilot. Sink giữ counters, latency observations, structured events và alerts trong process; deployment có thể nối log handler hoặc backend vận hành mà không thay đổi domain code.

Các metric chính:

- `scoring_admission_total` và `scoring_admission_latency_seconds`
- `scoring_admission_accepted_total`, `scoring_admission_blocked_total`, `scoring_admission_replay_total`
- `scoring_run_latency_seconds`, `scoring_failed_total`, `scoring_stuck_runs_total`
- `aihub_failures_total`, `aihub_tokens_total`
- `scoring_degraded_total`, `scoring_hitl_total`, `scoring_override_total`
- `scoring_degraded_rate`, `scoring_hitl_rate`, `scoring_override_rate`
- `outbox_deliveries_total`, `outbox_retries_total`, `outbox_dead_letter_total`
- `retention_redactions_total`, `retention_events_cleaned_total`, `retention_failures_total`

`run_id` được gắn vào event và latency record để trace giữa Lead Scoring và AIHub. `run_id`, `X-Request-ID` và `x-request-id` chỉ phục vụ correlation, không phải idempotency key và không tạo exactly-once guarantee.

Outbound AIHub chat completions kèm `x-bf-dim-app` và `x-bf-dim-feature` (map từ `dotb_app`/`dotb_feature`) để ghi nhận app và feature dimension vào logs, Prometheus và OpenTelemetry của AIHub. Các header này chỉ phục vụ attribution, không dùng cho quota hay rate limit.

Token usage chỉ ghi structured counts từ response `usage` của AIHub. Snapshot, prompt, response free text và PII không được ghi vào telemetry.

## Redaction

`redact_payload` thay thế các trường credential, snapshot, payload, message, content, email, phone, note, reason và reviewer identity bằng `[REDACTED]`. `record_exception` chỉ ghi exception type, không ghi exception message hoặc traceback. Credential được truyền vào redaction khi exception xảy ra ở AIHub client.

Sentinel tests phải kiểm tra V-Key, service token, snapshot và PII không xuất hiện trong events, alerts, logs, traces hoặc error payloads.

## Alert thresholds

Ngưỡng được cấu hình qua `Settings` và chỉ là ngưỡng cảnh báo vận hành, không phải SLO hoặc quality gate:

| Metric | Setting | Default |
| --- | --- | ---: |
| `scoring_stuck_runs_total` | `stuck_run_alert_threshold` | 1 |
| `aihub_failures_total` | `aihub_failure_alert_threshold` | 3 |
| `outbox_dead_letter_total` | `outbox_dlq_alert_threshold` | 1 |
| `retention_failures_total` | `retention_failure_alert_threshold` | 1 |

Alert được phát ra khi counter lần đầu chạm ngưỡng. Các ngưỡng này không tự động retry, không tự động tắt hệ thống và không thay thế operational drill.

## Kill switch

`Settings.kill_switch_enabled=true` chặn admission mới tại `POST /v1/scoring-runs` và chặn child run mới từ Re-evaluate sau khi caller và tenant scope đã được xác thực. Approve và Override vẫn được phép. Response của admission bị chặn là `503` với body:

```json
{
  "error_code": "scoring_admission_disabled",
  "detail": "Scoring run initiation is temporarily disabled"
}
```

Kill switch không chặn polling, Approve/Override review, execution task đã được schedule, retention hoặc webhook dispatcher. Các run đã accepted và outbox events tiếp tục drain hoặc được terminalize theo recovery/DLQ policy. Tắt switch bằng cách cập nhật settings vận hành, không replay request cũ tự động.