J2EE Web 服務客戶端服務品質 (QoS) 監測架構設計與實現 (一)

背景與動機

Web 服務 (SOAP/HTTP) 成為企業整合標準，但傳統 HTTP 存取日誌無法反映「使用者感知的端到端回應時間」：單一業務交易包含多次 SOAP 呼叫，且網路傳輸、客戶端處理耗時皆在伺服器端不可見。本文提出客戶端主動測量 + SOAP 附件攜帶回報的輕量級架構，實現真實 QoS 可視化。

架構總覽

核心組件

關鍵設計決策

1. 零新增網路往返：度量資料隨「下一筆業務請求」捎帶上傳，不發額外 HTTP 請求。
2. 非侵入式：業務 Bean 僅增加一行 `Payload.begin()/commit()`，不修改 WSDL/介面。
3. 容錯隔離：度量收集失敗 (佇列滿、DB 掛掉) 絕不拋出例外回業務流程，採用「記錄失敗本地日誌 + 定時重試」。
4. 跨平台：基於標準 JAX-RPC / JAX-WS HandlerChain，可移植至 WebLogic、WebSphere、JBoss、GlassFish。

客戶端 Payload API 設計

public final class Payload {
    private static final ThreadLocal tx = new ThreadLocal<>();

    public static void beginTransaction(String businessTxId) {
        Transaction t = new Transaction();
        t.businessTxId = businessTxId;
        t.clientStart = System.nanoTime();
        tx.set(t);
    }

    public static void commitTransaction() {
        Transaction t = tx.get();
        if (t == null) return;
        t.clientEnd = System.nanoTime();
        t.clientElapsedMs = (t.clientEnd - t.clientStart) / 1_000_000;
        // 序列化為 SOAP Attachment (由 Handler 自動攜帶)
        tx.remove();
    }

    // 供 Client Handler 讀取
    static Transaction getCurrent() { return tx.get(); }

    static class Transaction implements Serializable {
        String businessTxId;
        long clientStart, clientEnd;
        long clientElapsedMs;
    }
}

客戶端 SOAP Handler (JAX-RPC 範例)

public class MetricsClientHandler extends GenericHandler {
    public QName[] getHeaders() { return new QName[0]; }

    public boolean handleRequest(MessageContext ctx) {
        SOAPMessageContext smc = (SOAPMessageContext) ctx;
        try {
            SOAPMessage msg = smc.getMessage();
            Transaction tx = Payload.getCurrent();
            if (tx != null) {
                // 建立 AttachmentPart
                AttachmentPart part = msg.createAttachmentPart();
                part.setContent(tx, "application/x-java-serialized-object");
                part.setContentId("");
                msg.addAttachmentPart(part);
                msg.saveChanges();
            }
        } catch (Exception e) {
            // 靜默失敗，記錄本地日誌
            log.warn("Metrics attachment failed", e);
        }
        return true;
    }
}

伺服器端處理流程

1. SOAPHandler.handleRequest() → 遍歷 `msg.getAttachments()` 找 `Content-Type: application/x-java-serialized-object`。
2. 反序列化 `Transaction` 物件。
3. 送入 JMS Queue (`metricsQueue`)，立即返回，不阻塞業務執行緒。

MDB 持久化與分析

@MessageDriven(activationConfig = {
    @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
    @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/metricsQueue")
})
public class MetricsMDB implements MessageListener {
    @Resource DataSource ds;

    public void onMessage(Message msg) {
        try (Connection c = ds.getConnection()) {
            ObjectMessage om = (ObjectMessage) msg;
            Transaction tx = (Transaction) om.getObject();
            // 寫入度量表
            try (PreparedStatement ps = c.prepareStatement(
                    "INSERT INTO qos_metrics (biz_tx_id, client_elapsed_ms, server_received_ts) VALUES (?, ?, ?)")) {
                ps.setString(1, tx.businessTxId);
                ps.setLong(2, tx.clientElapsedMs);
                ps.setTimestamp(3, new Timestamp(System.currentTimeMillis()));
                ps.executeUpdate();
            }
        } catch (Exception e) {
            // 重試邏輯：重發至 DLQ 或寫本地檔案
            log.error("Persist metrics failed", e);
        }
    }
}

價值與擴展

• 真實用戶體驗：包含網路延遲、客戶端渲染、JS 執行等伺服器不可見耗時。
• 瓶頸定位：關聯伺服器端 JMX 指標 (CPU、GC、連線池)，繪製「客戶端耗時 vs 伺服器資源」散佈圖，快速鎖定瓶頸層級。
• SLA 監控：依業務交易類型設定 P95/P99 閾值，超標自動告警。
• 擴展：加入 `serverStart/serverEnd` (伺服器端 Handler 記錄) → 區分「網路傳輸」與「伺服器處理」耗時。

第二部分預告

下篇將詳細實作：JAX-WS 2.x HandlerChain 整合、Spring Boot Actuator 指標暴露、Grafana 儀表板模板、異常鏈路追蹤關聯 (OpenTelemetry/W3C TraceContext)。