# @equinor/fusion-framework-module-telemetry 中文文档

规范地址：https://npmcn.com/package/%40equinor/fusion-framework-module-telemetry/

版本：8\.0\.0
npm 元数据更新时间：2026-11-12T09:54:38.381Z
中文译文更新时间：2026-11-13T20:12:53.950Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40equinor/fusion-framework-module-telemetry
原文对照：https://npmcn.com/package/%40equinor/fusion-framework-module-telemetry/?lang=original
源码仓库：https://github.com/equinor/fusion-framework

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：989 kB，235 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：@opentelemetry/api-logs ^0\.223\.0，@opentelemetry/sdk-logs ^0\.223\.0，@opentelemetry/resources ^2\.11\.0，@equinor/fusion-observable 9\.2\.6，@equinor/fusion-framework-module 6\.2\.0，@microsoft/applicationinsights-web ^3\.0\.0，@equinor/fusion-framework-module-event 6\.1\.4，@opentelemetry/exporter-logs-otlp-http ^0\.223\.0
- 首次发布：2022-01-25T07:51:01.894Z
- 最新版本发布：2026-11-12T09:54:38.130Z
- 近 30 天下载量：13772（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：167（近 12 个月 33 个）

## 中文简介

用于使用微软遥测的聚合模块

## 安装

```sh
npm install @equinor/fusion-framework-module-telemetry
```

也可以使用：`pnpm add @equinor/fusion-framework-module-telemetry`、`yarn add @equinor/fusion-framework-module-telemetry`、`bun add @equinor/fusion-framework-module-telemetry`

## README

# @ equinor/ 组合框架- 模块- 遥测

Fusion框架的统一遥测模块. 为跟踪事件,例外,度量衡和自定义遥测数据提供一致的API,同时支持不同后端的可插接适配器.

## 特征

关于框架、应用和部件生命周期诊断、路由保障、安全元数据, 可选的HTTP/平地融合和迁移指导,参见 [操作遥测](https://npmcn.com/package/%40equinor/fusion-framework-module-telemetry/docs/operational-telemetry.md)。 。 。 .

框架模块获取连接到的控件 `telemetry.scope('app')` 执行 `TelemetryConnectable` 供应商合同。 共享手柄支持原始摘要 属性、有限度的计量操作、可观察到的测量和拥有的儿童范围. 关闭飞行范围完全取消了一次飞行作业,避免了报告延误. 没有自定义提供者 `scope`,模块懒散的负载 `createOperationalTelemetry` 从 页:1 `/utils` 入站点;内置提供者不需要运行时间遥测导入.

-   **基于适应器的架构** - 配备Console和应用程序 Insights适配器的飞船,或通过扩展来建造自己的 `BaseTelemetryAdapter`。 。 。 .
-   **等级提供者** ——儿童提供者向父母中继遥测,自动元数据合并.
-   **Zod- 验证计划** ——每个遥测项目在运行时都会被解析和验证.
-   **业绩计量** —— 说 `Measurement` 公用轨道经过时间 `using` 编号 : `Symbol.dispose` 支助.
-   **框架活动整合** - 发射 `onTelemetry` 财务报告和审定财务报表 `onTelemetryError` 通过Fusion事件系统的事件.
-   **可配置过滤** ——每个适应器和每个中继过滤器功能控制哪些项目得到处理.
-   **元数据提取器** ——在每个遥测项目上附加动态元数据(同步,同步,或可观测).

## 安装

```sh
pnpm add @equinor/fusion-framework-module-telemetry
```

## 使用量

### Fusion app中启用遥测

```typescript
import { enableTelemetry } from '@equinor/fusion-framework-module-telemetry';
import { ConsoleAdapter } from '@equinor/fusion-framework-module-telemetry/console-adapter';

const configure = (configurator) => {
  enableTelemetry(configurator, {
    attachConfiguratorEvents: true,
    configure: (builder) => {
      builder.setAdapter(ConsoleAdapter.Identifier, new ConsoleAdapter({ title: 'MyApp' }));
      builder.setMetadata(() => ({ appVersion: '2.0.0' }));
      builder.setDefaultScope(['application']);
    },
  });
};
```

### 追踪事件、例外和衡量标准

```typescript
import { TelemetryType, TelemetryLevel } from '@equinor/fusion-framework-module-telemetry';

const provider = modules.telemetry;

// Track a generic item
provider.track({
  type: TelemetryType.Event,
  name: 'page_view',
  level: TelemetryLevel.Information,
  properties: { page: '/dashboard' },
});

// Shorthand helpers
provider.trackEvent({ name: 'button_click', properties: { id: 'save' } });
provider.trackException({ name: 'api_error', exception: new Error('Not found') });
provider.trackMetric({ name: 'response_time', value: 230 });
provider.trackCustom({ name: 'feature_flag', properties: { flag: 'dark-mode' } });
```

### 衡量业绩

```typescript
// Manual measurement
const measurement = provider.measure({ name: 'data_load' });
await fetchData();
measurement.measure({ properties: { rows: 100 } }, { markAsMeasured: true });

// Automatic measurement with `using` (explicit resource management)
{
  using m = provider.measure({ name: 'render_time' });
  renderComponent();
} // duration tracked automatically on scope exit

// Promise-based measurement
const result = await provider.measure({ name: 'api_call' }).resolve(fetch('/api/data'));
```

### 应用程序透视适配器

```typescript
import { ApplicationInsightsAdapter } from '@equinor/fusion-framework-module-telemetry/application-insights-adapter';

enableTelemetry(configurator, {
  configure: (builder) => {
    builder.setAdapter(
      ApplicationInsightsAdapter.Identifier,
      new ApplicationInsightsAdapter({
        snippet: { config: { connectionString: '...' } },
        prefix: 'myApp',
      }),
    );
  },
});
```

## API 参考

### OTLP/HTTP适配器

`OtlpAdapter` 组合事件、例外、指标(作为日志记录)和自定义遥测 使用标准的 OpenTeleometry HTTP 日志导出器。 它附加了 App-key 和源属性 ,并使用活性的 OpenTeleometry 跟踪上下文进行日志关联。 它不登记 全球日志或跟踪提供者.

OpenTeleometry 软件包 **可选同伴依赖关系**: 普通遥测和控制台 或应用程序 Insights适配器不需要它们。 仅在导入时安装 `@equinor/fusion-framework-module-telemetry/otlp-adapter` 直接 :

```sh
pnpm add @opentelemetry/api-logs@^0.222.0 @opentelemetry/exporter-logs-otlp-http@^0.222.0 @opentelemetry/resources@^2.11.0 @opentelemetry/sdk-logs@^0.222.0
```

Dev-server SPA 捆绑包括 OTLP 执行,所以只环境的 dev-server 用法不需要将这些同位素添加到应用程序寄存器中 .

```typescript
import { OtlpAdapter } from '@equinor/fusion-framework-module-telemetry/otlp-adapter';

enableTelemetry(configurator, {
  configure: (builder) => {
    builder.setAdapter('otlp', new OtlpAdapter({
      url: 'http://localhost:4318/v1/logs',
      serviceName: 'my-app',
    }));
  },
});
```

`url` 是完整的日志信号 URL. `serviceName` 默认为 `fusion.telemetry`· ; `fallback` 默认为 `false`初始化不要求采集器。 报告出口失败 一劳永逸 遥测模块的处理钩等待 `TelemetryProvider.dispose()`,它停止订阅 等待每个适配器 `shutdown()` 冲出并释放出口者。 重复的提供者处理加入相同的 关闭承诺。 通过框架模块处理出错事件报告失败情况 在尝试了所有的适配器之后。 独立的供应商消费者应当 `await provider.dispose()`;独立的适配器消费者应当 `await adapter.shutdown()`。 。 。 .

`OtlpAdapter` 缓冲记录 `BatchLogRecordProcessor`:每次出口多达128个记录, a 2 048个记录队列,以及一秒钟的预定导出延迟。 启动突袭共享请求 而不是用尽出口商的货币限额。 打电话 `await adapter.forceFlush()` 时间 明确生命周期界限或测试,以便立即出出出待处理的记录。 遥测是 最佳努力: 完整队列或突然关闭浏览器会丢失记录 .

仅限环境开发配置,使用 [`FUSION_DEV_SERVER_OTLP_ENDPOINT`](https://npmcn.com/package/dev-server/docs/configuration.md#send-telemetry-to-an-otlp-endpoint) 而不是改变应用代码。 dev服务器将这个相同的公共适配器配置为倒置.

### 退后适配器和应用程序优先级

一个 `ITelemetryAdapter` 可以设置 `readonly fallback = true`。父提供者跳过适配器 用于从已明确配置了非倒置适配器的小孩中转发的记录. 其他母适配器,遥测事件,元数据合并,接力滤波器继续工作. 该决定通过嵌入式提供者传播,包括同步元数据解析.

这为环境带动的发展出口国提供了支持,但没有两次配置一个应用. 只配置元数据、 范围或过滤器的 Apps 仍然使用父返回 。 适配器 无可选 `fallback` 财产保留他们现有的行为.

### 核心出口(`@equinor/fusion-framework-module-telemetry`(中文(简体) )

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `enableTelemetry` | 函数 | 在配置器上注册遥测模块. |
| `TelemetryModule` 编号 : `telemetryModule` | 类型/ 对象 | 框架模块系统模块定义. |
| `ITelemetryProvider` | 接口 | 负责跟踪事件、例外、计量和计量的提供者. |
| `TelemetryConnectable` | 接口 | 可选 `connectTelemetry` 报告实用遥测的模块提供者的能力. |
| `ITelemetryConfigurator` | 接口 | 为适配器,元数据,范围,以及母供应商配置. |
| `Measurement` 编号 : `IMeasurement` | 类/ 接口 | 利用处置支持跟踪已过时间. |
| `TelemetryType` | 数字 | `Event`, (中文(简体) ), `Exception`, (中文(简体) ), `Metric`, (中文(简体) ), `Custom`。 。 。 . |
| `TelemetryLevel` | 数字 | `Debug`, (中文(简体) ), `Information`, (中文(简体) ), `Warning`, (中文(简体) ), `Error`, (中文(简体) ), `Critical`。 。 。 . |
| `TelemetryScope` | 数字 | `Framework`, (中文(简体) ), `Application`。 。 。 . |
| `TelemetryItem` | 类型 | Zod-inferred 碱基遥测项目形状. |
| `TelemetryEvent` 编号 : `TelemetryException` 编号 : `TelemetryMetric` 编号 : `TelemetryCustomEvent` | 类型 | 从Zod schemas推断出的专用物品类型. |
| `TelemetryConfigurator` | 类 | 配置构建器主机在初始化前准备 . |
| `StartupCapture` | 类 | 在任何提供者存在之前抓取一个主机的启动生命周期 . |

操作助手不从根部再出口;从根部导入 `/utils`, (中文(简体) ), `/schemas` 财务报告和审定财务报表 `/integrations` 子路径下面.

### 子路径导出

| 路径 | 按键导出 | 说明 |
| --- | --- | --- |
| `/adapter` | `BaseTelemetryAdapter`, (中文(简体) ), `ITelemetryAdapter` | 用于构建自定义适配器的基础类和界面. |
| `/console-adapter` | `ConsoleAdapter` | 基于控制台的适配器,带有颜色编码输出. |
| `/application-insights-adapter` | `ApplicationInsightsAdapter` | 微软应用透视适配器. |
| `/schemas` | `parseTelemetryItem`计划对象, `DiagnosticContext` | Zod schemas,用于遥测物品的解析器,以及诊断信封类型. |
| `/utils` | `createOperationalTelemetry`, (中文(简体) ), `createOperationalRecords`, (中文(简体) ), `createDiagnosticContext`, (中文(简体) ), `mergeTelemetryItem` | 用于元数据合并和事件映射的业务记录建立者和帮助者. |
| `/integrations` | `createHttpTelemetry`, (中文(简体) ), `observeQueryTelemetry` | 可选的HTTP和查询操作仪器. |
| `/mock` | `enableTelemetryMock`, (中文(简体) ), `MockTelemetryAdapter` | 用于确定性测试的流程中遥测记录器. |

## 测试

从 `@equinor/fusion-framework-module-telemetry/mock` 来记录远程测量过程 保留真实的遥测提供者、验证、元数据、范围、过滤器和事件 一体化.

### 默认

`TelemetryMockConfigurator` 注册一个新空的 `MockTelemetryAdapter` 下划线 `mock` 适配器编号. 除非测试注册了另一个适配器,否则任何设备都不会导出到后端 . 每个配置器都拥有其记录器,因此所记录的项目不跨测试实例共享.

```ts
import { enableTelemetryMock } from '@equinor/fusion-framework-module-telemetry/mock';

let recorder;
enableTelemetryMock(configurator, (builder) => {
  recorder = builder.adapter;
});

const item = await recorder.waitForItem('button-click');
expect(item.properties?.section).toBe('header');
```

`MockTelemetryAdapter.getItems(matcher?)` 返回同步记录的项目. `waitForItem(matcher, options?)` 等待现有或未来的匹配并接受超时 或者说 `AbortSignal`。 。 。 . `TelemetryMockConfigurator` 财务报告和审定财务报表 `telemetryMockModule` 也用于导出 手动构成.

## 配置

遥测模块通过配置 `ITelemetryConfigurator`,它提供了一个流畅的构建器 API:

| 方法 | 说明 |
| --- | --- |
| `setAdapter(id, adapter)` | 注册一个遥测适配器. |
| `configureAdapter(id, fn)` | 通过Aync工厂注册适配器. |
| `setMetadata(extractor)` | 附加元数据提取器(值、函数或可观测值). |
| `setDefaultScope(scope)` | 设置自定义项目的默认范围数组;内置的操作记录保持所捕获的范围. |
| `setSource(source)` | 提供构成根的框架, 应用程序或部件来源 。 标准主机自动设置 . |
| `setParent(provider)` | 设置等级中继的父提供者 . |
| `attachItems(items$)` | 将可观测到的物品流插入提供者. |
| `setFilter(filter)` | 设置适配器和/或中继过滤器功能. |

### 遥测级别

遥测项目可能具有不同的严重程度:

-   **声波** (0): 详细信息,一般用于调试
-   **调试** (1):调试信息
-   **资料** (2)系统运行概况
-   **3⁄4 ̄ ̧漯B** (3) 指出一个非关键问题
-   **错误** (4): 已发生错误, 但系统可以继续运行
-   **关键** (5):可能导致系统停止运行的严重错误

默认情况下,如果没有指定关卡,则 `Information` 使用级别.

## 计量

遥测模块提供 `Measurement` 帮助您跟踪代码中操作的持续时间.

### 基本计量

```typescript
// Create a measurement
const measurement = modules.telemetry.measure({ name: 'MyMeasurement' });

// Perform some operation
// ...

// Record the measurement
measurement.measure(); // Tracks the time since the measurement was created
```

### 解决测量问题

您可以用追踪同步操作的承诺来解决测量问题 :

```typescript
const measurement = modules.telemetry.measure({ name: 'AsyncOperation' });

// Track the time it takes to resolve the promise
const result = await measurement.resolve(
  new Promise<string>((resolve) => {
    setTimeout(() => resolve('result'), 1000);
  }),
  {
    // Additional data to include in the measurement
    data: (result) => ({ properties: { result } })
  }
);
```

### 执行测量

您可以执行一个函数并测量其执行时间:

```typescript
const measurement = modules.telemetry.measure({ name: 'FunctionExecution' });

// Execute and measure the function
const result = await measurement.exec(() => {
  // Simulate some work
  return new Promise<string>((resolve) => setTimeout(() => resolve('result'), 1000));
});
```

### 克隆测量

您可以克隆测量来创建初始状态相同的新实例 :

```typescript
const measurement = modules.telemetry.measure({ name: 'CloneExample' });

for (let i = 0; i < 5; i++) {
  const clonedMeasurement = measurement.clone({ preserveStartTime: true });
  await clonedMeasurement.resolve(
    new Promise((resolve) => setTimeout(() => resolve('result'), 1000))
  );
}

// Measure the total time taken by all cloned measurements
measurement.measure(); 
```

### 使用语句

你可以用这个 `using` 用于在测量超出范围时自动处置的语句:

```typescript
const job = async() => {
  using measurement = modules.telemetry.measure({ name: 'UsingExample' });
  // Perform some operation
  // The measurement will be automatically tracked when the function completes
}
```

> \[叹息\] 这个 `using` 语句是一个 TypeScript 特性,它仍处于建议阶段,可能并非所有环境都可以使用。 要使用此特性, 您需要在其类型脚本配置中启用 :
> 
> ```json
> {
>   "compilerOptions": {
>     "target": "es2022",
>     "module": "NodeNext",
>     "useDefineForClassFields": true
>   }
> }
> ```

## 适配器

适配器负责处理并发送到各自目的地的遥测数据. 所有适配器都支持同步初始化,并在遥测提供者初始化时被自动初始化.

### 使用设置Adapter并配置Adapter

这个 `TelemetryConfigurator` 提供两种增加适配器的方法: `setAdapter` 预设适配器和 `configureAdapter` 用于使用初始化参数创建动态.

#### 简单设定Adapter 示例

```typescript
import { enableTelemetry } from '@equinor/fusion-framework-module-telemetry';
import { ConsoleAdapter } from '@equinor/fusion-framework-module-telemetry/console-adapter';

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, {
    configure: (builder) => {
      const consoleAdapter = new ConsoleAdapter({ title: 'MyApp' });
      builder.setAdapter('console', consoleAdapter);
    }
  });
};
```

#### 具有不同标识符的多个适配器

可以配置多个配有不同标识符的适配器来处理不同类型的遥测数据. 这使遥测项目能够灵活地进行路由和过滤.

```typescript
import { enableTelemetry, TelemetryLevel } from '@equinor/fusion-framework-module-telemetry';
import { ConsoleAdapter } from '@equinor/fusion-framework-module-telemetry/console-adapter';
import { ApplicationInsightsAdapter } from '@equinor/fusion-framework-module-telemetry/application-insights-adapter';

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, {
    configure: (builder) => {
      // Standard console logger for general information
      const standardConsole = new ConsoleAdapter({
        title: 'Standard',
        filter: (item) =>
          item.level >= TelemetryLevel.Information && item.level < TelemetryLevel.Error
      });
      builder.setAdapter('console-standard', standardConsole);

      // Error console logger for errors and critical issues
      const errorConsole = new ConsoleAdapter({
        title: 'Errors',
        filter: (item) => item.level >= TelemetryLevel.Error
      });
      builder.setAdapter('console-error', errorConsole);

      // Application Insights for production telemetry
      const appInsights = new ApplicationInsightsAdapter({
        snippet: {
          config: {
            instrumentationKey: 'production-instrumentation-key'
          }
        },
        filter: (item) => item.level >= TelemetryLevel.Warning
      });
      builder.setAdapter('app-insights-prod', appInsights);
    }
  });
};
```

这个设置允许您:

-   路线一般信息到标准控制台日志
-   将错误发送到专用错误控制台日志
-   向生产监测应用透视系统提交警告及以上

#### 配置 符合要求的适配器

```typescript
import { enableTelemetry, TelemetryLevel } from '@equinor/fusion-framework-module-telemetry';
import { ApplicationInsightsAdapter } from '@equinor/fusion-framework-module-telemetry/application-insights-adapter';

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, {
    configure: async (builder, ref) => {
      builder.configureAdapter('application-insights', async ({ requireInstance }) => {
        const auth = await requireInstance('auth');
        const adapter = new ApplicationInsightsAdapter({
          snippet: {
            config: {
              instrumentationKey: 'app-instrumentation-key'
            }
          },
          filter: (item) => item.level >= TelemetryLevel.Information,
        });
        if (auth.account?.localAccountId) {
          adapter.setAuthenticatedUserContext(auth.account.localAccountId);
        }
        return adapter;
      });
    }
  });
};
```

### 应用程序透视适应器

应用程序 Insights 适配器允许您向 Microsoft 应用程序 Insights 发送遥测数据. 它支持设置应用程序 Insights 客户端和插件的同步初始化.

#### 安装

要使用应用程序透视适配器,需要安装 `@microsoft/applicationinsights-web` 软件包 :

```bash
pnpm add @microsoft/applicationinsights-web
```

#### 配置

应用程序 Insights 适配器支持以下配置选项:

-   `snippet`: 应用程序 Insights 配置对象(需要)
-   `plugins`: 扩展应用程序 Insights 功能的可选插件阵列
-   `identifier`: 客户端实例的可选唯一标识符( 默认为“ 应用程序- 透视” )
-   `filter`: 可选过滤功能,以确定是否应处理遥测项目
-   `prefix`: 可选的前缀, 用于远程测量项目名称

#### 示例

```typescript
import { enableTelemetry } from '@equinor/fusion-framework-module-telemetry';
import { ApplicationInsightsAdapter } from '@equinor/fusion-framework-module-telemetry/application-insights-adapter';

// bootstrap - initialization on server which loads the portal
const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, {
    attachConfiguratorEvents: true, // Track module configurator events
    configure: async (builder, ref) => {
      const adapter = new ApplicationInsightsAdapter({
        snippet: {
          config: {
            instrumentationKey: 'portal-instrumentation-key'
          }
        },
        // filter log level by FUSION_TELEMETRY_LEVEL environment variable
        filter: (item) =>
          item.level >= (process.env.FUSION_TELEMETRY_LEVEL
            ? parseInt(process.env.FUSION_TELEMETRY_LEVEL)
            : TelemetryLevel.Information),
      });

      builder.setAdapter('application-insights', adapter);
      ref.requireInstance('auth').then((auth) => {
        if (auth.account?.localAccountId) {
          adapter.setAuthenticatedUserContext(auth.account.localAccountId);
        }
      });
    }
  });
};

// portal - framework
const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, {
    attachConfiguratorEvents: true,
    configure: async (args) => {
    // reuse the Application Insights adapter from bootstrap
    const aiAdapter = args.ref.modules.telemetry.getAdapter(ApplicationInsightsAdapter.Identifier);
    if (aiAdapter) {
      args.config.setAdapter('application-insights', aiAdapter);
    }
    args.config.setMetadata({
      portal: {
        name: 'Fusion Portal',
        version: '1.0.0',
      }
    });
    args.config.setDefaultScope(['portal']);
    }
  });
};

// app - application
const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, {
    attachConfiguratorEvents: true,
    configure: async (args) => {
    args.config.setMetadata({
      app: {
        name: 'My App',
        version: '1.0.0',
      }
    });
    args.config.setDefaultScope(['app']);
    args.config.setParent(args.ref.modules.telemetry);
    const appAppInsightsAdapter = new ApplicationInsightsAdapter({
      snippet: {
        config: {
          instrumentationKey: 'app-instrumentation-key'
        }
      },
      // only log events with a specific scope
      filter: (item) => item.scope.includes('custom-event'),
    });
    args.config.setAdapter('application-insights-app', appAppInsightsAdapter);
    }
  });
};

// app - custom event
modules.telemetry.trackEvent({
  name: 'CustomEvent',
  type: TelemetryType.Event,
  level: TelemetryLevel.Information,
  properties: {
    customProperty: 'value'
  },
  scope: ['custom-event', 'ag-grid']
});
```

### 控制台适配器

Console适配器提供了将遥测数据记录到控制台的简单方式,可用于开发和调试.

#### 安装

控制台适配器包含有遥测模块,不需要额外安装.

#### 配置

Console 适配器支持以下配置选项:

-   `identifier`: 适配器的可选唯一标识符( 默认为“ console- adapter ”)
-   `filter`: 可选过滤功能,以确定是否应处理遥测项目
-   `title`: 在控制台输出中显示的可选标题( 默认为“ Fusion ”)

#### 示例

```typescript
import { enableTelemetry } from '@equinor/fusion-framework-module-telemetry';
import { ConsoleAdapter } from '@equinor/fusion-framework-module-telemetry/console-adapter';
import { TelemetryLevel } from '@equinor/fusion-framework-module-telemetry';

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, (builder) => {
    // Create a console adapter for development
    const consoleAdapter = new ConsoleAdapter({
      title: 'MyApp',
      // Only log information and above
      filter: (item) => item.level >= TelemetryLevel.Information
    });
    
    builder.setAdapter('console', consoleAdapter);
  });
};
```

### 创建自定义适配器

您可以通过扩展自定义遥测适配器 `BaseTelemetryAdapter` 课。 适配器可以选择执行同步初始化:

```typescript
import type { TelemetryItem } from '@equinor/fusion-framework-module-telemetry';
import { BaseTelemetryAdapter } from '@equinor/fusion-framework-module-telemetry/adapter';

class CustomAdapter extends BaseTelemetryAdapter {
  constructor() {
    super('custom-adapter');
  }

  protected async _initialize(): Promise<void> {
    // Perform async setup here (e.g., establish connections, load configurations)
    await this.setupConnection();
  }

  protected _processItem(item: TelemetryItem): void {
    // Process and send telemetry items
    this.sendToCustomBackend(item);
  }

  private async setupConnection(): Promise<void> {
    // Implementation for setting up the connection
  }

  private sendToCustomBackend(item: TelemetryItem): void {
    // Implementation for sending data to your backend
  }
}
```

要使用您的自定义适配器 :

```typescript
import { enableTelemetry } from '@equinor/fusion-framework-module-telemetry';

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, (builder) => {
    const customAdapter = new CustomAdapter();
    builder.setAdapter('custom', customAdapter);
  });
};
```

## 高级特性

### 元数据提取器

元数据提取器允许您在远程测量项目处理前动态添加元数据. 这有助于在所有遥测项目中增加上下文信息.

```typescript
import { enableTelemetry } from '@equinor/fusion-framework-module-telemetry';

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, (builder) => {
    // Add metadata to all telemetry items
    builder.setMetadata(({ modules, item }) => {
      return {
        ...item,
        properties: {
          ...item.properties,
          // Add user information if available
          user: modules?.auth?.account?.username,
          // Add application version
          version: '1.0.0',
        }
      };
    });
  });
};
```

### 过滤函数

过滤功能允许您控制哪些遥测项目由适配器处理. 这可用于过滤出不想要的遥测或将不同类型的遥测引导到不同的适配器.

```typescript
import { enableTelemetry, TelemetryLevel } from '@equinor/fusion-framework-module-telemetry';
import { ApplicationInsightsAdapter } from '@equinor/fusion-framework-module-telemetry/application-insights-adapter';

const configure = (configurator: IModulesConfigurator<any, any>) => {
  enableTelemetry(configurator, (builder) => {
    // Only process errors and critical events in production
    const isProd = process.env.NODE_ENV === 'production';
    
    const appInsightsAdapter = new ApplicationInsightsAdapter({
      snippet: { /* ... */ },
      // In production, only send errors and critical events
      // In development, send all events
      filter: (item) => isProd 
        ? item.level >= TelemetryLevel.Error 
        : true
    });
    
    builder.setAdapter('application-insights', appInsightsAdapter);
  });
};
```

## 建筑

遥测模块遵循一种等级结构,允许灵活的配置和数据流. 下图显示了不同组件的相互作用:

```mermaid
classDiagram
  class Bootstrap {
      Application Insight Adapter
      filter(item)
  }
  class Portal {
      Dev Tool Adapter
      Application Insight Adapter
      IndexDB Adapter
      filter(item)
  }
  class App {
      Application Insight Adapter
      App Telemetry Events
      filter(item)
  }

  Bootstrap --> Portal
  Portal --> App
  App ..> Portal : App Telemetry Events
```

## 业绩考量

在执行遥测时,考虑下列绩效最佳做法:

1.  **提前过滤**: 尽早应用滤波器来避免处理不必要的遥测数据.
2.  **批量操作**:使用测量来跟踪分批的操作,而不是跟踪单个事件.
3.  **取样**: 在量大的情况下,考虑实施取样以减少遥测数据的数量.
4.  **同步处理**:使用遥测模块的同步方法来避免阻挡主线程.
5.  **选择性遥测**:选择在生产中跟踪什么,以避免压倒你的遥测后端.

## 解决问题

共同问题及其解决办法:

1.  **无遥测数据**数字 :
    
    -   检查适配器是否被正确配置并添加到遥测配置器中
    -   校验过滤功能不排除所有遥测项目
    -   确保网络连接到遥测后端
2.  **缺少上下文信息**数字 :
    
    -   检查元数据提取器配置是否正确
    -   提取元数据时验证是否有所需的模块
3.  **业绩问题**数字 :
    
    -   检查正在生成的过度遥测事件
    -   考虑实施取样或更具选择性的过滤
    -   审查适配器处理时间

## 常见问题

### @equinor/fusion-framework-module-telemetry 是什么？

用于使用微软遥测的聚合模块

### 如何安装 @equinor/fusion-framework-module-telemetry？

在项目目录运行 npm install @equinor/fusion-framework-module-telemetry，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@equinor/fusion-observable（9\.2\.6）、@equinor/fusion-framework-module（6\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @equinor/fusion-framework-module-telemetry 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @equinor/fusion-framework-module-telemetry 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @equinor/fusion-framework-module-telemetry 可以商用吗？

@equinor/fusion-framework-module-telemetry 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @equinor/fusion-framework-module-telemetry 的下载量有多少？

根据 npm 官方下载统计，@equinor/fusion-framework-module-telemetry 在 2026/10/14 – 2026/11/12 这 30 天内被下载 13,772 次，日均约 459 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @equinor/fusion-framework-module-telemetry 还在维护吗？

最新版本 8\.0\.0 发布于 2026/11/12（1 天前）；至今共发布 167 个版本，其中过去 12 个月发布了 33 个；首次发布于 2022/01/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。