> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/framework/diagnostics/otlp.md).

# OTLP 协议接入

接入 OTLP gRPC 客户端和 Listener 服务端，核对处理器装配、数据转换及可靠性限制。

OTLP 是遥测数据传输协议。一个批次可包含多个 Resource，每个资源下有多个 Scope，再包含指标点、日志或追踪。应用若把所有层次压成一个列表，很容易丢失来源、属性或数据点语义。

## 客户端包的职责

`Zongsoft.Diagnostics.Protocols.Client` 提供生成的消息类型及 gRPC 客户端 Stub。它不会自动插桩、采集、批处理、重试或建立 SDK 导出管线。普通应用从[诊断配置](/framework/diagnostics.md)开始；直接协议调用才需要自行构造请求。

Discussions 没有直接构造 OTLP Export 请求的用例，因此不再提供空请求的虚构客户端。发送端应使用现有诊断导出配置；需要直接操作协议时，核对客户端项目生成的服务与 DTO。

业务导出器还要填充资源、作用域和数据点，处理响应及部分成功，控制队列、批次大小和重试范围。生成式 API 版本不等于线协议稳定性，不建议直接将这些类型作为业务长期存储模型。

## 服务端的装配

在插件 Web 宿主部署 gRPC 和协议服务端：

{% code title="TelemetryServer.deploy（片段）" %}

```ini
[plugins zongsoft web grpc]
nuget:Zongsoft.Web.Grpc

[plugins zongsoft diagnostics protocols server]
nuget:Zongsoft.Diagnostics.Protocols.Server
```

{% endcode %}

Listener 的 Logs、Metrics、Traces 服务通过 `gRPC` 标签映射。随包选项声明 `http://*:4317` 的 HTTP/2 端点，实际部署应限定地址、传输安全与发送方访问；普通 HTTP/1 JSON 请求不能验证该 gRPC 入口。

## 注册处理器

接收服务把协议消息转换为框架模型，然后分派给处理器集合。下面是框架 samples 中实际使用的插件注册：

来源：[framework/Zongsoft.Diagnostics/protocols/server/samples/Zongsoft.Diagnostics.Protocols.Server.Samples.plugin](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Diagnostics/protocols/server/samples/Zongsoft.Diagnostics.Protocols.Server.Samples.plugin#L19)（节选；上下文见源文件）。

{% code title="Zongsoft.Diagnostics.Protocols.Server.Samples.plugin" %}

```xml
<extension path="/Workbench/Diagnostics/Telemetry/Listener/Metrics">
	<object name="MetricHandler" type="Zongsoft.Diagnostics.Protocols.Server.Samples.MetricHandler, Zongsoft.Diagnostics.Protocols.Server.Samples" />
</extension>
```

{% endcode %}

来源：[framework/Zongsoft.Diagnostics/protocols/server/samples/MetricHandler.cs](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Diagnostics/protocols/server/samples/MetricHandler.cs#L14)（节选；上下文见源文件）。

{% code title="MetricHandler.cs" %}

```csharp
protected override ValueTask OnHandleAsync(IEnumerable<Telemetry.Metrics.Meter> meters, Parameters parameters, CancellationToken cancellation)
{
	foreach(var meter in meters)
		Terminal.WriteLine(CommandOutletDumper.Dump(meter));

	return ValueTask.CompletedTask;
}
```

{% endcode %}

类型需要由应用提供，并在清单中声明程序集及服务端插件依赖。[服务端样例](https://github.com/Zongsoft/framework/tree/main/Zongsoft.Diagnostics/protocols/server/samples)使用类型化处理器打印指标；打印只用于观察，不提供数据库、持久队列或失败重试。

## 当前转换与可靠性边界

{% hint style="warning" %}
🚨 当前实现不能作为已证明无损的通用 OTLP 接收器：指标处理在资源循环中重新建立集合，最终分派无法保留前面资源的全部指标；Gauge 也投射为框架 Counter 相关模型。接入多资源批次或依赖特定指标语义前，应针对这些行为验证并处理。
{% endhint %}

时间戳从 Unix 纳秒转换为毫秒，存在精度损失。处理器通过并行分派执行，单个处理器异常会记录并隔离，响应不会逐一报告这些失败。没有处理器时也不能从成功响应推断数据被消费。

需要可靠接收时，应明确定义何时入队或落盘、如何处理过载、失败如何被发送方或运维发现。当前协议响应与处理器失败语义必须纳入设计；仅在处理器中捕获异常并打印不足以保证不丢数据。

## 验证顺序

先验证 HTTP/2 端点与服务标签，再挂载记录型处理器，发送包含已知数量资源、作用域和数据点的合成批次，比较接收结果。随后检查空批次、处理器失败、取消和目标存储故障，最后才连接真实遥测源。

源码依据：[分派与时间转换](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Diagnostics/protocols/server/src/Listener.cs)、[指标转换](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Diagnostics/protocols/server/src/Listener.Metrics.cs)、[客户端生成项目](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Diagnostics/protocols/client/src/Zongsoft.Diagnostics.Protocols.Client.csproj)。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zongsoft.com/framework/diagnostics/otlp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.