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

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

特征

关于框架、应用和部件生命周期诊断、路由保障、安全元数据, 可选的HTTP/平地融合和迁移指导,参见 操作遥测。 。 。 .

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

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

安装

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

使用量

Fusion app中启用遥测

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']);
    },
  });
};

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

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' } });

衡量业绩

// 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'));

应用程序透视适配器

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 直接 :

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 用法不需要将这些同位素添加到应用程序寄存器中 .

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 而不是改变应用代码。 dev服务器将这个相同的公共适配器配置为倒置.

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

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

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

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

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

子路径导出

测试

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

默认

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

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:

遥测级别

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

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

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

计量

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

基本计量

// 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

解决测量问题

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

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 } })
  }
);

执行测量

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

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));
});

克隆测量

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

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 用于在测量超出范围时自动处置的语句:

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 特性,它仍处于建议阶段,可能并非所有环境都可以使用。 要使用此特性, 您需要在其类型脚本配置中启用 :

{
  "compilerOptions": {
    "target": "es2022",
    "module": "NodeNext",
    "useDefineForClassFields": true
  }
}

适配器

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

使用设置Adapter并配置Adapter

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

简单设定Adapter 示例

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);
    }
  });
};

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

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

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);
    }
  });
};

这个设置允许您:

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

配置 符合要求的适配器

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 软件包 :

pnpm add @microsoft/applicationinsights-web

配置

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

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

示例

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 ”)

示例

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 课。 适配器可以选择执行同步初始化:

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
  }
}

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

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);
  });
};

高级特性

元数据提取器

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

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',
        }
      };
    });
  });
};

过滤函数

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

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);
  });
};

建筑

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

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. 业绩问题数字 :

   • 检查正在生成的过度遥测事件
   • 考虑实施取样或更具选择性的过滤
   • 审查适配器处理时间