@earendil-works/pi-遥测

供应商中性遥测合同和Pi包的打字系统.

本套件提供:

• 一个明确的、基于召回的 TelemetryContext 编号 : TelemetrySpan 合同;
• a 共用资源 NOOP_TELEMETRY_CONTEXT· ;
• 参考文献 InMemoryTelemetryContext 执行;
• 带有推断出类型Script的序列式计划定义;
• 没有导出者、全局电流平流状态或依赖遥测后端.

应用程序可以使用内存参考,或者为OpenTeleometter,哨兵,日志或另一个后端提供适配器. Pi包明确通过遥测上下文,并分别定义了它们的域计划.

目录

• 安装
• 遥测概念
• 核心内容 API
• 适配器合同
• 无上下文
• 记忆参考适应器
• 适配器
• 已键入Schemas
  • 开始和完成属性
• Schema 元数据
• Pi 软件包集成
• 安全和可移动性
• API 参考
• 发展
• 许可证

安装

npm install @earendil-works/pi-telemetry

# Bun alternative
bun add @earendil-works/pi-telemetry

遥测概念

遥测描述一个程序在运行时所做的. 使用跨度、属性、事件、状态和明确上下文的软件包模型:

例如,加载一个账户可以产生这种遥测:

example.account.load                         span
├─ attributes: account.id=123, found=true   facts about the span
├─ event: example.cache.lookup              occurrence during the span
│  └─ attribute: cache.hit=false            fact about the event
└─ status: ok                               final outcome

一个跨度是诊断数据,而不是商业状态. 记录它不得改变账户载荷的运行、成功、失败或持续。 一个适配器将这些通用概念翻译为OpenTeleometry,哨兵,logs或另一个后端使用的相应概念.

核心内容 API

A 类 TelemetryContext 开始一个跨度 围绕召回。 回调收到一个 TelemetrySpan,这也是孩子跨度的明确的父母背景.

import {
  NOOP_TELEMETRY_CONTEXT,
  type TelemetryContext,
} from '@earendil-works/pi-telemetry';

async function loadAccount(
  accountId: string,
  telemetryContext: TelemetryContext = NOOP_TELEMETRY_CONTEXT,
) {
  return telemetryContext.startSpan(
    {
      name: 'example.account.load',
      attributes: { 'example.account.id': accountId },
    },
    async (span) => {
      const account = await readAccount(accountId);
      span.setAttributes({ 'example.account.found': account !== undefined });
      return account;
    },
  );
}

将回调跨度传递给较低级别的工作,以创建清晰的筑巢:

return telemetryContext.startSpan({ name: 'example.parent' }, async (parentSpan) => {
  return parentSpan.startSpan({ name: 'example.child' }, async (childSpan) => {
    childSpan.addEvent('example.cache.lookup', { 'example.cache.hit': true });
    return performWork();
  });
});

没有公众 end() 方法. startSpan() 拥有和解并保持跨度,直到召回值或承诺达成为止。 对于以正常返回值为代表的预期失败,明确规定状态:

return telemetryContext.startSpan({ name: 'example.save' }, async (span) => {
  const result = await save();
  if (!result.ok) {
    span.setStatus({
      status: 'error',
      error: { name: 'SaveError', message: result.reason },
    });
  }
  return result;
});

适配器合同

适配器执行器 TelemetryContext 将通用API连接到它的后端。 它必须:

• 创建一个孩子的跨度,并同步引用回调,准确一次;
• 保存回调的返回值和拒绝值,在同步抛出后返回一个以同样值拒绝的承诺;
• 保持土生土长,直到返回的诺言达成为止;
• 将正常补全作为 ok 并投掷/拒绝为错误,除非设定了明确的状态;
• 重复一个 setStatus() 要求最后写成;
• 合并 setAttributes() ,后定义的值取代先前的值 undefined 忽略;
• 使录制方法同步、被动和非抛出;
• 无视定居后发出的呼吁;
• 忽略一个失败的录制调用 解析 , 压制后端失败, 并且仍然执行商业回调一次 .

适配器可以在内部激活后端-内在环境上下文,用于自动仪表,但pi代码总是通过 TelemetryContext 参数。 导出器缓冲,冲出,采样,后端ID,后端特定上下文对象属于适配器. 使用 适配器套装 检查这些可见的语义.

无上下文

使用 NOOP_TELEMETRY_CONTEXT 当遥测为可选时:

import { NOOP_TELEMETRY_CONTEXT } from '@earendil-works/pi-telemetry';

const result = await NOOP_TELEMETRY_CONTEXT.startSpan(
  { name: 'example.operation' },
  () => runOperation(),
);

无上下文 :

• 同步引用回调;
• 保存返回的值和同步拒绝,并将同步丢入以相同值拒绝的承诺;
• 使用一个共享的冷冻惰性跨度,包括嵌入式跨度;
• 不检查或保留姓名、属性、事件或状态.

记忆参考适应器

InMemoryTelemetryContext 是后端中性引用执行。 用于测试、本地诊断和应用,如果有意想要在没有出口者的情况下进行本地过程捕获:

import { InMemoryTelemetryContext } from '@earendil-works/pi-telemetry';

const telemetry = new InMemoryTelemetryContext();

await telemetry.startSpan(
  { name: 'example.operation', attributes: { input: 'demo' } },
  async (span) => {
    span.addEvent('example.started');
    span.setAttributes({ output_count: 3 });
  },
);

console.log(telemetry.getSpans());

getSpans() 返回跨度启动顺序的已解开快照。 每个 RecordedTelemetrySpan 包含一个决定性的数字 ID, 父ID, 合并属性, 命令事件, 最终状态, 和解状态, 以及决定性的结束序列 。 它没有记录时间戳.

适配器可以正常使用 TelemetryContext,但存储是无约束的,并进行本地处理。 创建一个新实例来隔离测试或记录范围,除非呼叫者的数据政策允许,否则不捕捉敏感属性.

适配器

@earendil-works/pi-telemetry/testing 输出一个按组装型号排列的、独立运行的套装。 固定提供了新的上下文,并将其后端的完成跨度转换为正常 RecordedTelemetrySpan 快照 :

import {
  createTelemetryAdapterConformance,
  type TelemetryAdapterFixture,
} from '@earendil-works/pi-telemetry/testing';
import { describe, it } from 'vitest';

const conformance = createTelemetryAdapterConformance(async () => {
  const adapter = createMyTelemetryAdapter();
  return {
    context: adapter.context,
    getSpans: async () => adapter.normalizedSpans(),
    async [Symbol.asyncDispose]() {
      await adapter.close();
    },
  } satisfies TelemetryAdapterFixture;
});

for (const group of new Set(conformance.map((testCase) => testCase.group))) {
  describe(group, () => {
    for (const testCase of conformance.filter((candidate) => candidate.group === group)) {
      it(testCase.name, () => testCase.run());
    }
  });
}

套房检查同步的单一收录,结果和拒绝身份,自动和明确状态,属性合并,事件顺序,定居后惰性呼叫,筑巢并同时进行亲和,并抑制无法读取的遥测有效载荷故障. getSpans() 可能会在返回前冲出同步导出者。 测试子路径使用Node的断言 API;根遥测包保持运行时中立.

已键入Schemas

低等跨度 API 有意接受开放名称和属性包,因此适配器仍然通用. 域包可以定义封闭的,可序列化的策略并推断出它们中的确切类型TypeScript.

import {
  createTypedSpanStarter,
  defineTelemetrySchema,
} from '@earendil-works/pi-telemetry';

export const EXAMPLE_TELEMETRY_SCHEMA = defineTelemetrySchema({
  version: 1,
  spans: {
    'example.read': {
      description: 'Read one resource',
      parents: { kind: 'any' },
      startAttributes: {
        'example.resource': {
          type: 'string',
          required: true,
          values: ['account', 'project'],
          description: 'Resource kind',
        },
      },
      endAttributes: {
        'example.item_count': {
          type: 'number',
          description: 'Number of returned items',
        },
      },
      events: {
        'example.cache': {
          description: 'Cache lookup result',
          attributes: {
            'example.cache.hit': {
              type: 'boolean',
              required: true,
              description: 'Whether the cache contained the resource',
            },
          },
        },
      },
      status: {
        default: 'ok',
        errorWhen: 'The read throws or returns an error result',
      },
    },
  },
} as const);

const startSpan = createTypedSpanStarter(
  telemetryContext,
  [EXAMPLE_TELEMETRY_SCHEMA],
);

起步器每个跨度暴露出一个超载,并在编译时检查名称和属性. 在呼叫前必须缩小联盟值名称,保留每个运行时名称与其属性计划之间的关系. 它的回调接收到一个孩子的启动器 通过相同的计划, 已经捆绑在回调范围:

await startSpan(
  'example.read',
  { 'example.resource': 'account' },
  async (span, startChildSpan) => {
    span.addEvent('example.cache', { 'example.cache.hit': true });
    const accounts = await readAccounts();
    span.setAttributes({ 'example.item_count': accounts.length });

    await startChildSpan(
      'example.read',
      { 'example.resource': 'project' },
      async (childSpan) => {
        const projects = await readProjects();
        childSpan.setAttributes({ 'example.item_count': projects.length });
      },
    );

    return accounts;
  },
);

开始和完成属性

startAttributes 财务报告和审定财务报表 endAttributes 描述一个属性通常已知时,而不是单独的运行时存储 :

两套都在同一后端间距上成为了普通属性. 没有单独的终端属性有效载荷或终端回调。 在上述例子中, example.resource 何时知道 example.read 启动时 example.item_count 只在 readAccounts() 返回 :

await startSpan(
  'example.read',
  { 'example.resource': 'account' }, // required start attribute
  async (span) => {
    const accounts = await readAccounts();
    span.setAttributes({
      'example.item_count': accounts.length, // optional completion attribute
    });
    return accounts;
  },
); // resolving the callback settles the span

“结束”是指完成浓缩:在召回有效时,可以在任何时间设定最终属性,在无法使用时可以省略。 通话 setAttributes() 0倍有效。 这关系到早期的失败,取消,以及可能不存在于每个路径的特定提供者的数据.

重复 setAttributes() 调用合并到同一属性包。 后来定义的值取代了同一密钥的较早值,同时 undefined 被忽略。 计程镜法只接受当前跨度所声明的结束属性.

属性不会结束长度 。 返回、解决、投掷或拒绝回调控制结算; startSpan() 进行实际的终端操作。 在和解后拨打的适配电话是无效的.

启动器可以编写多个独立版本的策略:

import { AGENT_TELEMETRY_SCHEMAS } from '@earendil-works/pi-agent-core';

const startAgentSpan = createTypedSpanStarter(
  telemetryContext,
  AGENT_TELEMETRY_SCHEMAS,
);

Inline schema 阵列自动保留其tuple类型. 单独宣布的数组应使用 as const。整个阵列的字面上重复名称在编译时被拒绝;计划不合并、检查,也不在运行时保留.

Schema-衍生类型拒绝缺少所需的属性,未知的密钥,无效的闭合集值,未宣布的事件,以及空子计划中的属性. 尾端属性总是可选的浓缩;类型系统不需要 setAttributes() 被调用.

defineTelemetrySchema() 是输入的身份函数。 它返回了普通的JSON-序列相上的数据,并且不执行运行时验证或执行父规则.

Schema 元数据

支持的属性类型有:

• string, (中文(简体) ), number,以及 boolean· ;
• string[], (中文(简体) ), number[],以及 boolean[]。 。 。 .

属性定义支持 :

• values: 已关闭的平面值集;
• elementValues: 阵列元素的封闭集;
• examples: 文献实例;
• sensitive需要特殊处理的数据标记;
• cardinality: 需要记录 low 或者说 high 至高无上.

开始和事件属性声明 required。结尾属性不;见 开始和完成属性。 。 。 .

父元数据是描述性计划数据 :

• { kind: 'any' }: 根或任何调用器;
• { kind: 'root_or_external' }: 根或计程器以外的调用器;
• { kind: 'spans', spans: [...] }:只有所列计划跨度.

适配器不需要理解计划对象. 仪器辅助和测试人员利用它们保持所排放的名称和属性的一致性.

Pi 软件包集成

包的所有权被故意分割:

• @earendil-works/pi-telemetry 拥有供应商中立合同、不公开和模拟参考背景、计划公用事业和适配器兼容套件;
• @earendil-works/pi-ai 接受和宣传 telemetryContext 在提供者请求选项中,但没有遥测计划;
• @earendil-works/pi-agent-core 拥有并输出 Pi AI 请求和驾驭 schemas, 它们的组合只读 schema tuple, 和打出跨度帮助器.

import {
  AGENT_TELEMETRY_SCHEMAS,
  AI_TELEMETRY_SCHEMA,
  HARNESS_TELEMETRY_SCHEMA,
  startAiSpan,
  startHarnessSpan,
} from '@earendil-works/pi-agent-core';

皮子计划是用皮子的 pi.ai.*, (中文(简体) ), pi.harness.*,以及 pi.session.* 名称。 适配器可以将其翻译为后端常规而无需更改所排放的pi词汇.

安全和可移动性

遥测是过程局部诊断,不是持久应用状态. 不坚持 TelemetryContext, (中文(简体) ), TelemetrySpan,或记录、信件、快照或被推迟的手柄中的后端-内存跟踪对象.

属性值被故意限制在原始的分级和数组. 域仪器应避免提示、补全、工具参数或输出、文件内容、供应商有效载荷、信头、证书和自由形式的出错细节,除非其计划和数据政策明确允许.

软件包不使用 AsyncLocalStorage 或其它运行时间特定环境上下文 API。 它适合Node.js, Bun,浏览器,以及工人;后端适配器仍然负责自己的运行时间相容性.

API 参考

核心类型和价值

方案定义和推论

测试子路径

发展

从此包目录 :

bun run test
bun run build

仓库全库类型检查、格式化、林地化和烟雾检查:

bun run check

许可证

麻省理工学院