OpenTelemetry Metrics

一个基于 OpenTelemetry 的轻量级指标收集 JavaScript/TypeScript 库，用于在 Web 应用程序中收集和导出指标数据。

特性

• 🚀 基于 OpenTelemetry 标准构建
• 📊 支持 Counter 和 UpDownCounter 指标类型
• 🌐 支持 OTLP HTTP 协议导出
• 📝 完整的 TypeScript 类型支持
• ⚡ 轻量级设计，易于集成
• 🔧 可配置的导出间隔和属性

安装

npm install opentelemetry-metrics

或者使用 yarn：

yarn add opentelemetry-metrics

或者使用 pnpm：

pnpm add opentelemetry-metrics

快速开始

基本用法

import { metrics } from 'opentelemetry-metrics'

// 初始化指标收集器
metrics.start({
  meterName: 'my-app-metrics',
  exportIntervalMillis: 30000, // 30秒导出一次
  url: 'https://your-otel-collector-endpoint/v1/metrics'
})

// 设置全局属性
metrics.setAttributes({
  service: 'my-web-app',
  version: '1.0.0'
})

// 创建计数器
const pageViews = metrics.createCounter('page_views_total', {
  description: '页面访问总数'
})

// 记录指标
pageViews.add(1, { page: '/home' })
pageViews.add(1, { page: '/about' })

// 创建可增减计数器
const activeUsers = metrics.createUpDownCounter('active_users', {
  description: '当前活跃用户数'
})

// 增加活跃用户
activeUsers.add(1, { region: 'us-east' })
// 减少活跃用户
activeUsers.add(-1, { region: 'us-east' })

API 参考

metrics.start(options)

初始化指标收集器。

参数：

• options (MetricsOptions): 配置选项
  • meterName?: string - 指标器名称，默认为 'web-metrics'
  • exportIntervalMillis?: number - 导出间隔（毫秒），默认为 60000（1分钟）
  • url?: string - OTLP 导出端点 URL
  • headers?: Record<string, string> - 自定义请求头
  • 其他 OTLP 导出器配置选项

示例：

metrics.start({
  meterName: 'my-app',
  exportIntervalMillis: 30000,
  url: 'https://otel-collector.example.com/v1/metrics',
  headers: {
    'Authorization': 'Bearer your-token'
  }
})

metrics.setAttributes(attributes)

设置全局属性，这些属性会自动添加到所有指标中。

参数：

• attributes (Record<string, string | number>): 属性键值对

示例：

metrics.setAttributes({
  service: 'frontend',
  environment: 'production',
  version: '2.1.0'
})

metrics.createCounter(name, options?)

创建一个只能递增的计数器。

参数：

• name (string): 指标名称
• options? (object): 可选配置
  • description?: string - 指标描述
  • unit?: string - 指标单位

返回：

• 包含 add(value, attributes?) 方法的对象

示例：

const httpRequests = metrics.createCounter('http_requests_total', {
  description: 'HTTP 请求总数',
  unit: '1'
})

httpRequests.add(1, { method: 'GET', status: '200' })

metrics.createUpDownCounter(name, options?)

创建一个可以增加或减少的计数器。

参数：

• name (string): 指标名称
• options? (object): 可选配置
  • description?: string - 指标描述
  • unit?: string - 指标单位

返回：

• 包含 add(value, attributes?) 方法的对象

示例：

const memoryUsage = metrics.createUpDownCounter('memory_usage_bytes', {
  description: '内存使用量',
  unit: 'bytes'
})

memoryUsage.add(1024000, { type: 'heap' })
memoryUsage.add(-512000, { type: 'heap' }) // 减少内存使用

使用场景

Web 应用监控

import { metrics } from 'opentelemetry-metrics'

// 初始化
metrics.start({
  url: 'https://your-observability-platform.com/otlp/v1/metrics'
})

// 页面性能监控
const pageLoadTime = metrics.createCounter('page_load_duration_ms')
const errorCount = metrics.createCounter('frontend_errors_total')

// 记录页面加载时间
window.addEventListener('load', () => {
  const loadTime = performance.timing.loadEventEnd - performance.timing.navigationStart
  pageLoadTime.add(loadTime, { page: window.location.pathname })
})

// 记录前端错误
window.addEventListener('error', (event) => {
  errorCount.add(1, { 
    error_type: 'javascript_error',
    page: window.location.pathname 
  })
})

用户交互监控

// 用户交互计数器
const buttonClicks = metrics.createCounter('button_clicks_total')
const formSubmissions = metrics.createCounter('form_submissions_total')

// 监控按钮点击
document.addEventListener('click', (event) => {
  if (event.target instanceof HTMLButtonElement) {
    buttonClicks.add(1, { 
      button_id: event.target.id,
      button_text: event.target.textContent?.slice(0, 20) 
    })
  }
})

// 监控表单提交
document.addEventListener('submit', (event) => {
  if (event.target instanceof HTMLFormElement) {
    formSubmissions.add(1, { 
      form_id: event.target.id,
      form_action: event.target.action 
    })
  }
})

开发

构建

pnpm install
pnpm run build

开发模式

pnpm run dev

代码检查

pnpm run lint

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！