可觀測性：雜湊鏈式 SIEM 日誌與算繪報告

一覽

可觀測性模組提供執行期狀態的實作：防竄改的雜湊鏈式 SIEM 事件日誌、算繪與試行報告彙整、HSM 稽核日誌，以及一整套無操作的 metrics 與 trace 實作，讓檢測介面隨時都能呼叫。

每項主題只有一個正式頁面。 可觀測性契約—— ContextAwareExceptionInterface、SpectrumInterface、 JobNotificationInterface，以及 DegradationPolicy 列舉——記載於 Contracts / Observability。本頁則記載具體的執行期狀態實作。兩者互補而非重複：契約頁說明 SPI，本頁則說明 SIEM 日誌、報告與稽核介面。

安裝

composer require nextpdf/core:^3

概念概覽

本模組負責將引擎的執行期狀態轉化為持久且可驗證的輸出。

HashChainSiemEventLog 是安全等級的介面。它實作 SiemEventEmitter 契約，並寫入 JSON-Lines 日誌，其中每筆記錄的雜湊值為 SHA-256(prev_hash_bytes || canonical_event_bytes)。這種線性雜湊鏈讓日誌具備防竄改性：竄改任何位元組、刪除某一行或重新排序各行，都會破壞此鏈。verifyIntegrity() 會走訪整個檔案，並回傳第一筆不一致記錄的索引；若鏈完整無缺則回傳 null。readAll() 會串流讀取各筆記錄。逐行寫入流程中的諮詢式 flock(LOCK_EX) 會把「讀取尾端後再附加」這段臨界區框住，讓同一檔案上的並行 PHP 程序不會交錯寫入記錄。此設計清楚揭示自身界限：它是線性雜湊鏈，而非 RFC 6962 Merkle 樹——足以提供防竄改性，但不足以提供高效的包含性證明。原始碼即如此載明。SiemEvent 透過 toCanonicalJson() 攜帶型別化的事件。SiemEventSeverity 與 SiemEventType 對其進行分類。CorrelationContext 與 CorrelationIdGenerator 會把關聯識別碼串接於相關事件之間。

RenderReportBuilder、RenderReport、PilotReportAggregator 與 PilotSummary 是報告介面（@since 5.1.0）。彙整器會蒐集多個 RenderReport，並產生一份 PilotSummary，可輸出為陣列、JSON 或 Markdown——也就是維運審查所採用的格式。

HsmAuditLogInterface / HsmAuditEvent 會為安全層記錄由 HSM 支援的簽署作業。MetricsCounterInterface、MetricsGaugeInterface、MetricsHistogramInterface 與 TraceSpanInterface 定義 metrics/trace 的型態。NoOp* 實作提供一套完整且惰性的後備，讓引擎在未設定後端的情況下仍可發出 metrics 與 span。

穩定度：實驗性。 SIEM 日誌在內部以週期標記，而非攜帶凍結的 semver @since，而報告介面則為 @since 5.1.0。這些介面已可運作且經過測試，但 API 型態仍可能演進。請將日誌格式（正規 JSON 加雜湊鏈）視為穩定契約，並將 PHP API 視為尚在定形中。

API 介面

類別	主要成員	角色
`HashChainSiemEventLog`	`emit(SiemEvent)`、`verifyIntegrity(): ?int`、`readAll(): Generator`	防竄改的雜湊鏈式 SIEM 日誌
`SiemEvent`	`toCanonicalJson()`	型別化的 SIEM 事件
`SiemEventSeverity` / `SiemEventType`（列舉）	分類	事件嚴重度與類型
`CorrelationContext` / `CorrelationIdGenerator`	關聯串接	串接相關事件
`RenderReportBuilder` / `RenderReport`	報告組裝	單次算繪報告（`@since 5.1.0`）
`PilotReportAggregator`	`addReport()`、`count()`、`getSummary()`、`toJson()`、`toMarkdown()`、`exportReportsJson()`	彙整算繪報告（`@since 5.1.0`）
`PilotSummary`	`toArray()`、`toJson()`、`toMarkdown()`	維運審查摘要（`@since 5.1.0`）
`HsmAuditLogInterface` / `HsmAuditEvent`	HSM 稽核記錄	HSM 作業稽核日誌
`NoOpSiemEventEmitter`、`NoOpMetricsCounter`、`NoOpTraceSpan`、…	惰性後備	完整的無操作實作

執行 composer docs:generate-api-php -- --module=Observability 以取得完整的 PHPDoc 表格。

程式碼範例——快速上手

發出一個事件並驗證日誌的完整性。

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Observability\Siem\HashChainSiemEventLog;
use NextPDF\Observability\Siem\SiemEvent;

$log = new HashChainSiemEventLog('/var/log/nextpdf/siem.jsonl');
$log->emit(new SiemEvent(/* type, severity, payload */));

$firstBroken = $log->verifyIntegrity();
echo $firstBroken === null
    ? "SIEM chain intact.\n"
    : "Tamper detected at record {$firstBroken}.\n";

程式碼範例——生產環境

包裝發送器，讓簽署熱路徑中的日誌寫入失敗由局部決策處理，而不是變成未被攔截的例外。

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Observability\Siem\HashChainSiemEventLog;
use NextPDF\Observability\Siem\Exception\SiemEmitterException;
use NextPDF\Observability\Siem\SiemEvent;
use Psr\Log\LoggerInterface;

final readonly class AuditedSiemSink
{
    public function __construct(
        private HashChainSiemEventLog $log,
        private LoggerInterface $fallback,
    ) {}

    public function record(SiemEvent $event): void
    {
        try {
            $this->log->emit($event);
        } catch (SiemEmitterException $e) {
            // Do not let SIEM I/O abort the signing path; record and continue.
            $this->fallback->critical('SIEM emit failed; event not chained.', [
                'error' => $e->getMessage(),
            ]);
        }
    }
}

邊界情況與陷阱

寫入發生錯誤時，emit() 會擲出 SiemEmitterException。簽署熱路徑中的呼叫端必須加以包裝，並在本地決定要吞掉、重試或中止。發送器不會替你決定。
verifyIntegrity() 會回傳第一筆損壞記錄的索引，或回傳 null。非 null 的結果代表日誌自該點起已遭破壞——請勿信任該點及其之後的記錄。
諮詢式 flock 是逐行程序，且僅作用於同一檔案。跨主機並行需要一個帶外接收端（轉送至 syslog）。請勿假設檔案鎖能在多台機器之間協調。
這是線性雜湊鏈，並非 Merkle 樹。它證明的是防竄改性，而非高效的包含性證明。請勿將其宣傳為後者。
NoOp* 後備是完整且惰性的。請勿為了「省下工作」而根據後端是否可用來分支——無操作本身已不耗任何成本。

效能

emit() 會讀取前一筆記錄的雜湊值，並在檔案鎖下附加一行——每個事件為 O(1)，另外承擔該鎖的成本。verifyIntegrity() 因為要走訪整條鏈，所以相對於記錄數是 O(n)。請排程執行它，而非放在熱路徑中。報告彙整與報告數量呈線性關係。可重現性特性為 structural（結構性）：事件與報告攜帶時間戳記與關聯識別碼，因此兩次執行會在這些欄位上有所不同，而鏈結構則是確定性的。

安全注意事項

SIEM 日誌是一項安全控制。它的防竄改性取決於日誌檔案與驗證步驟是否受到保護：請將檔案存放在適合附加寫入、具存取控制的儲存上，排程執行 verifyIntegrity()，並以帶外方式轉送記錄，使主機遭入侵時無法悄然改寫歷史。事件可能攜帶敏感情境。請在事件建構之前、而非鏈結之後套用專案的日誌清洗義務，因為清洗後的重寫會破壞此鏈。HSM 稽核日誌會記錄簽署作業，本身即與安全相關。請以相同的保護措施對待它。請參閱 /modules/core/security/ 中的引擎威脅模型。

符合性

本模組未提出任何 PDF 規範的規範性主張。它實作的日誌完整性與可觀測性機制，其設計與 NIST SP 800-92 中的日誌管理與完整性驗證實務一致——這是原始碼所記載的控制框架對齊，而非以區塊釘選的 PDF 引用。引擎所產生之文件的符合性，則由 /modules/core/conformance/ 所述的 oracle 與黃金套件驗證。

另請參閱

Contracts / Observability——SPI（結構化例外、Spectrum、降級策略）。
Telemetry module——將資料饋送至外部後端的 OpenTelemetry 橋接。
Audit module——與 SIEM 日誌搭配的合規證據匯出器。
Security module——HSM 稽核日誌所記錄的簽署作業。
Conformance overview