XiHan.Framework.Observability.Abstractions

可观测性的抽象包：两项能力的 ID（导出与运行信息），以及进程与主机运行信息的契约 IHostMonitor 与七份记录。实现见 Observability.Host 与 Observability.OpenTelemetry。

项	内容
包 ID	XiHan.Framework.Observability.Abstractions
环层	Ring 2（抽象）
能力	定义 observability.export@1 与 observability.host@1（ObservabilityCapabilities），本包不提供
特性入口	—
配置节	—
依赖	XiHan.Framework.Primitives；无第三方包
AOT	兼容
稳定性	Preview

概述

内核的追踪与指标直接基于 System.Diagnostics，不需要抽象；本包只承载两件事：能力 ID 常量，供两个实现包与应用清单共用；运行信息的契约，供管理界面的服务监控读取（RFC-0023，ADR-0056）。

IHostMonitor 的七个方法各返回一份不可变记录。契约约定读取不阻塞、不抛出、不启动外部命令；读不到的项为 null，不以 0 或空串顶替；使用率与速率取后台采样器最近一次的值，启动后第一个采样间隔内为空；CPU 型号与核心、GPU、主板首次读取后缓存。

何时使用

应用代码依赖 IHostMonitor 时只引用本包，装配时再选实现（Observability.Host）。在清单里按能力 ID 声明依赖时引用 ObservabilityCapabilities。

安装与启用

dotnet add package XiHan.Framework.Observability.Abstractions --prerelease

当前是预览版，安装要带 --prerelease；从源码或本地包源引用见快速上手。两个实现包都依赖本包，Profiles.Full 已包含。

主要类型

类型	说明
ObservabilityCapabilities	Export（observability.export）、Host（observability.host）、Version（1）
IHostMonitor	ReadRuntime、ReadProcessor、ReadMemory、ReadDisks、ReadNetworkInterfaces、ReadGpus、ReadBoard
RuntimeInfo	OsDescription、OsPlatform（windows / linux / macos / freebsd / other）、OsVersion、OsArchitecture、Framework、RuntimeIdentifier、ProcessArchitecture、MachineName、UserName、Interactive、ProcessId、ProcessName、ProcessStartedAt、ProcessUptime、SystemStartedAt、SystemUptime、WorkingSetBytes、PrivateBytes、ManagedHeapBytes、ThreadCount、HandleCount、Gen0Collections / Gen1Collections / Gen2Collections、ProcessCpuUsagePercent
ProcessorInfo	Name、Vendor、Architecture、PhysicalCores、LogicalCores、FrequencyMhz、CacheBytes、UsagePercent
MemoryInfo	TotalBytes、AvailableBytes、FreeBytes、CachedBytes、UsedBytes、UsagePercent
DiskInfo	Name、Device、Label、Format、Type、TotalBytes、FreeBytes、AvailableBytes、UsedBytes、UsagePercent
NetworkInterfaceInfo	Id、Name、Description、Type、Status、SpeedBitsPerSecond、PhysicalAddress、IPv4Addresses、IPv6Addresses、Gateways、DnsServers、BytesReceived / BytesSent、PacketsReceived / PacketsSent、ReceiveBytesPerSecond / SendBytesPerSecond
GpuInfo	Name、Vendor、VendorId、DeviceId、Driver、DriverVersion、MemoryBytes、TemperatureCelsius
BoardInfo	Manufacturer、Product、Version、SerialNumber、SystemManufacturer、SystemProduct、BiosVendor、BiosVersion、BiosDate

使用示例

在后台作业或服务里读取并判断阈值，空值表示读不到，不当作 0：

using XiHan.Framework.Observability.Abstractions;

namespace MyApp.Diagnostics;

public sealed class CapacityCheck(IHostMonitor monitor)
{
    public IReadOnlyList<string> FindAlerts()
    {
        var alerts = new List<string>();
        if (monitor.ReadMemory().UsagePercent is > 90)
        {
            alerts.Add("memory");
        }

        // 启动后第一个采样间隔内 UsagePercent 为 null，这里自然跳过
        if (monitor.ReadProcessor().UsagePercent is > 95)
        {
            alerts.Add("cpu");
        }

        foreach (var disk in monitor.ReadDisks())
        {
            if (disk.UsagePercent is > 85)
            {
                alerts.Add($"disk:{disk.Name}");
            }
        }

        return alerts;
    }
}

行为与限制

• 契约只规定读取的语义；平台读取路径、采样与缓存由实现决定，内置实现的规则见 Observability.Host。
• 百分比在 0 到 100 之间、不取整；收发速率 ReceiveBytesPerSecond / SendBytesPerSecond 的单位是字节每秒，网卡链路速率 SpeedBitsPerSecond 的单位是 bit/s。
• 记录不包含命令行参数、环境变量与当前目录。
• RuntimeInfo.UserName 是运行进程的系统账户，不是登录凭据，ToString() 照常打印（ADR-0093）。

相关

• 可观测性
• Observability.Host
• Observability.OpenTelemetry
• 规范：RFC-0023《可观测性：导出与运行信息》