@ancplua/qyl-api-schema (英语)
TypeSpec为Qyl客户端可见产品API提供的真实来源. 此寄存器 它不执行服务器, 存储引擎,或OTLP接收器.
合同涵盖每个客户可见的qyl采集器和跑道表面:
- 追踪 —— 说
GET /api/v1/traces,一个跟踪, 及其跨度(api/routes.tsp, (中文(简体) ),otel/span.tsp) (中文(简体) ). - 日志 —— 说
GET /api/v1/logs和现场SSE流GET /api/v1/stream/logs及其心跳(api/streaming.tsp, (中文(简体) ),otel/logs.tsp) (中文(简体) ). - 计量,只读
GET /api/v1/metrics列出参数描述符 为一个项目录制,GET /api/v1/metrics/{metric_name}/series列出 在一个标准名称下有不同的属性流,以及GET /api/v1/metrics/{metric_name}/query跨时间范围合计 1 公分 装入桶中models/metrics.tsp) (中文(简体) ). 系列保留其资源和仪器 范围。 使用series_id当仪器描述符冲突时选择一个精确的流; 模糊范围查询返回 409 。 测量点在OTLP上写着 本合同没有说明。 不支持配置文件 . - 会议 —— 说
GET /api/v1/sessions,一个会,它的痕迹和/stats(单位:千美元)models/session.tsp) (中文(简体) ). - 卫生 —— 说
GET /health财务报告和审定财务报表GET /alive,其HealthReport携带contract_revision握个手models/health.tsp) (中文(简体) ). - MCP工具 qyl MCP工具的输入和结构化输出模型
(单位:千美元)
models/mcp-tools.tsp) (中文(简体) ). - 工作区 本地 MCP 工作台:会话、工作空间、服务器、协议
流、处决、测试案例、套房、评估运行和出口
(单位:千美元)
api/workbench.tsp, (中文(简体) ),models/workbench.tsp) (中文(简体) ). - 运行者 ——本地跑者只回放回放
/runner/resources缩写, SSE 流程、日志和重新启动/停止动作collector, (中文(简体) ),project财务报告和审定财务报表command流程(api/runner.tsp, (中文(简体) ),models/runner.tsp. MCP 服务器身份和工具 发现被Workbench连接和发现快照曝光. - 共享 ——RFC 9457问题细节(
common/errors.tsp),光标页 (单位:千美元)common/pagination.tsp)和常见的平板common/),加奥特尔 资源、跨度和日志预测otel/) (中文(简体) ).
遥测本身从未通过本合同更改或删除;保留
将取去. 唯一的可写资源是说明(/api/v1/annotations, (中文(简体) ),
保存的查询
(单位:千美元)/api/v1/saved-queries,用于跟踪、日志或度量的命名结构过滤器,
运行与 POST …/{saved_query_id}:run)和失败状态
(单位:千美元)PATCH /api/v1/failures/{failure_id},记录的失败状态、受让人或
被忽略直到时间。 说明和保存的查询扩展共享的写基础
common/resource.tsp: 服务器指定 id, (中文(简体) ), created_at, (中文(简体) ), updated_at 财务报告和审定财务报表 etag· ;
Idempotency-Key 创建, 答案 201 与 Location· ; If-Match 打开
PATCH 财务报告和审定财务报表 DELETE,拒绝 428 失踪时 412 讽t 这个
失败状态 PATCH 一样 If-Match。收集器键带有角色
ingest, (中文(简体) ), read, (中文(简体) ), write 财务报告和审定财务报表 delete (单位:千美元)CollectorKeyRole); 写入需要 write, (中文(简体) ),
删除 delete。 。 。 .
错误和页面
每个错误机构都是RFC 9457问题 application/problem+json数字 : type, (中文(简体) ),
title, (中文(简体) ), status, (中文(简体) ), detail 财务报告和审定财务报表 instance,加上扩展成员 code每一个
问题类型修正其 type URI (美国)https://qyl.at/problems/<name>) 及其定义 code
(单位:千美元)not_found, (中文(简体) ), validation_failed,所以客户端的分支 要么,从不
title 或者说 detail问题机构没有标题。 发布响应头
服务器发送的操作 : X-Trace-Id 在收藏家的500个回应,
WWW-Authenticate 工作台的401个回复.
每个列表操作页都带有不透明的光标。 这需要 limit
(单位:千美元)PageLimit:1至1000,略去时为100)和 cursor,其页面带有
has_more 在每页中,除末页外, next_cursor,下一个请求
发回作为 cursor。 。 。 .
合同管道
authored Qyl TypeSpec
|
+----> OpenAPI ----> bundled JSON Schema
+----> Qyl.Api.Contracts
+----> generated TypeScript contracts
Qyl域模型,路由,响应,流出事件,以及出错在此被编写.
与OTel兼容的模型载有生产者发送的值; Qyl.Telemetry.SemanticConventions 拥有
注册词汇和语义验证. 属性密钥横过线作为打开的字符串地图,所以本合同没有
列出 OpenTeleometry 属性注册 .
边界
- 每个客户端可见的Qyl 请求,响应,流事件,以及错误被定义于 此仓库 .
- OTLP 摄取在运行时间使用 OpenTeleometry protobuf 的官方消息,并且是 这里没有重新定义 .
- 模式
otel/qyl线路使用的是客户端的JSON预测,而不是 OTLP电讯信息. - 收集器存储行、摄入批次、查询模型和内部预测 不跨越 HTTP、 gRPC、 MCP、 流线或生成客户端边界 .
如果运行时形状需要变成客户端可见,请先将其添加到TypeSpec中, 重新生成文物,并将运行时间模型映射到生成的合同.
已出版文物
两个登记册都从一个发行标签上印出同样的版本。 合同预付款
它自己的主要节奏,没有跟踪qyl产品版本——它已经是
5.0.0 当qyl发射时 1.0.0从 npm 或 nuget.org 读取当前版本
而不是从这里的作词;此行移动快于修正的README.
| 生态系统 | 艺术 | 目的 |
|---|---|---|
| npm/ 类型Spec | @ancplua/qyl-api-schema | 为 Spec 用户编写的计划 |
| 新建 | Qyl.Api.Contracts | 只有BCL产生的.NET合同 |
| 已生成 | OpenAPI, JSON Schema, 类型脚本 | 客户和验证投入 |
main.tsp 是本地编译的切入点,并包含发射道. index.tsp
是已公布的 TypeSpec 切入点,只包含客户端的创建合同.
软件包出口
| 子路径 | 内容 |
|---|---|
@ancplua/qyl-api-schema | index.tsp,整个类型Spec合同 |
@ancplua/qyl-api-schema/otel | otel/otel-conventions.tsp: 仅针对不想要qyl API 的 TypeSpec 消费者的OTel 形状资源, 跨度和日志模型 |
@ancplua/qyl-api-schema/types | 生成类型脚本合同类型和 CONTRACT_REVISION 常数 |
@ancplua/qyl-api-schema/openapi | qyl.openapi.json |
@ancplua/qyl-api-schema/json-schema | 捆绑的JSON斯克马 |
@ancplua/qyl-api-schema/zod | 运行时间验证器, 下方 |
@ancplua/qyl-api-schema/runtime | 生成的演示文稿助手 AttributeValue 匹配器( e)decodeAttributeValue, (中文(简体) ), formatAttributeValue, (中文(简体) ), attributeString, (中文(简体) ), attributeNumber, (中文(简体) ), attributeIdentity, (中文(简体) ), matchAttributeValue)和 UnixNanos 字符串助手( e)parseUnixNanos, (中文(简体) ), compareUnixNanos, (中文(简体) ), unixNanosDelta, (中文(简体) ), unixNanosToEpochMs, (中文(简体) ), unixNanosToIso, (中文(简体) ), epochMsToUnixNanos) (中文(简体) ). 撰写于 src/runtime/编译为 generated/runtime/ |
运行时间验证
@ancplua/qyl-api-schema/zod 从捆绑的 JSON Schema 创建 Zod 验证器
运行时间。 上面是翻译层 z.fromJSONSchema ——写入 src/zod/
并编入 generated/zod-runtime/ - 不是第二个手写的计划,所以
合同更改不能留下描述上一个形状的验证符 .
import { publishedContractSchema } from "@ancplua/qyl-api-schema/zod";
import type { Span } from "@ancplua/qyl-api-schema/types";
const SpanSchema = publishedContractSchema<Span>("OTel.Traces.Span");
const span = SpanSchema.parse(await response.json());
zod 是一个可选的对等依赖( e)>=4.5.0 <5:消费者不
安装它从不导入此子路径, 其他子路径也不依赖
就在这 定义名称为已公布 $defs 键 — OpenAPI 的同名名称
组件和生成的 C# 和 TypeScript 的 DTO 携带——和
contractDefinitionNames() 列出全部。 未检查类型参数
与计划相对应,因此与匹配类型从 ./types。 。 。 .
合同修订
scripts/emit-contract-revision.mjs 确定性的修改 sha256: 加号
合同中的头16个六十六个字符 语义文摘——两入
期间生成的面孔 bun run compile一个收藏家报告它建造的修改
因此客户端可以检测到从不同角度构建的同伴
合同,而不是一次发现一个不匹配的字段。 读取
运行中的收藏器或生成的文物的当前值;它是衍生出来的,永远不会
手持着.
打开API info.version 是发行版本 : prepack 把它印入包装
文档从释放标记中,跟踪文档保留 TypeSpec 的 0.0.0编辑
摘要排除 info.version,所以一个只改变其版本的版本
该修订版.
调查合同
生成的 Mcp.Tools 表面覆盖32个工具的qyl MCP集. 26个读取工具中每个都有不同的,有打字的 POST /api/v1/analysis/<tool_name> 操作。 结构化上游支持共享匹配者操作器;读取结果带有绝对值 window 财务报告和审定财务报表 coverage 与无效的未知数。 现有的跟踪、日志、计量和会话REST路径仍然可用.
失败状态通过 PATCH /api/v1/failures/{failure_id} 与 If-Match。失败的手柄、验证符和光标由采集器进行范围界定和验证。 注释合同支持失败目标,标签,分类和重试键. 这些合同只载有产品数据;遥测运行时间的依赖性仍然存在于其生产者储存库中.
收集器的行为和种子活工具的答案由收集器和MCP套件对照同样的生成的合同进行测试.
捐款
如何建造、提供、再生和出版 捐款额。 。 。 .
许可证
阿帕奇 - 2.0