本模块用于metrics相关能力接口的Lua层隔离，以实现Lua层、封装层、开源引入层隔离，Lua层与封装层之间通过弱引用隔离，在无法require到封装库时，Lua层提供空对象空接口保护业务不受影响

核心概念简述 ​

• MeterProvider：整个 Metrics API 的入口点，负责创建和管理所有 Meter 实例。
• Meter：由 MeterProvider 创建，负责生成具体的指标工具Instrument。根据业务需要，通过CreateXxxInstrument()创建不同类型。
• Instrument：由 Meter 创建，直接负责采集和上报具体的测量数据。

层级结构示例：

+-- MeterProvider()
    |
    +-- Meter(name='test1', version='1.0.0', schema url='https://test//test')
    |   |
    |   +-- Instrument<Counter>(name='counter_test', description='test counter', unit='kb')
    |   |
    |   +-- instrument...
    |
    +-- Meter(name='test2', version='1.1.0', schema url='https://test//test')
        |
        +-- Instrument<ObservableCounter>(name='observable_counter_test', description='test observable counter', unit='kb')
        |
        +-- Instruments...

meter创建 ​

meter是metrics能力构建中最初的一环，业务需要持有meter根据业务创建不同类型的instrument来记录数据。组件通过调用get_meter()来创建meter。

-- 方法原型
local meter = metrics.get_tracer(name, version, schema_url)
 
-- 使用示例
local metrics = require 'telemetry.metrics'
local meter_custom = metrics.get_meter(name)

req:

• name: 必选参数, string类型, meter名称
• version: 可选参数, 版本号
• schema_url: 可选参数, 关联的语义约定的URL

instrument创建 ​

instrument是负责采集和上报具体的测量数据的载体，业务根据需要选择创建不同类型的instrument。 仪器命名呈现在最终可视化系统中，直接体现了数据上报的易读性，需要着重审视命名合理性

-- 方法原型
meter:create_counter(name, description, unit)
meter:create_updowncounter(name, description, unit)
meter:create_observable_counter(name, description, unit)
meter:create_observable_updowncounter(name, description, unit)
meter:create_observable_gauge(name, description, unit)
 
-- 使用示例
local counter = meter:create_counter("counter_data", "count some data for test", "kb")

• create_counter：创建一个单调递增的计数器counter
• create_updowncounter：创建一个可递增递减的计数器counter
• create_observable_counter：创建一个异步的单调递增的计数器observable_counter
• create_observable_updowncounter：创建一个异步的可递增递减的计数器observable_updowncounter
• create_observable_gauge：创建一个异步的瞬时仪表observable_gauge

req:

• name: 必选参数, string类型, instrument名称
• description: 可选参数, instrument的相关描述信息
• unit: 可选参数, 采集数据的单位，e.g. "kb"

instrument方法调用 ​

同步仪器 ​

同步仪器包括counter和updowncounter，通过显式调用直接记录指标。

-- 创建 Meter
local meter = metrics.get_meter()

-- 创建 Counter
local counter = meter:create_counter("my_counter")

-- 增加Counter计数器的值
counter:add(10)

-- 创建 Meter
local meter = metrics.get_meter()

-- 创建 UpDownCounter
local updowncounter = meter:create_updowncounter("my_updowncounter")

-- 增加或减少UpDownCounter的值
updowncounter:add(5)    -- 增加
updowncounter:add(-3)   -- 减少

-- 使用 Attribute 给指标添加维度示例
flash_io_counter:add(data_size, {file_type="log", mc_name="xx"})
flash_io_counter:add(data_size, {file_type="persisitence", mc_name="xx"})

在实际业务的度量采样中，添加标签可以从多个维度去分析同一个指标，可视化系统支持通过标签筛选和聚合指标。例如： otelcol_flash_io_total{file_type = "log"}可查看指标在写入类型为日志的flash写入量数值变化； sum(otelcol_flash_io_total{file_type = "persisitence"})可查看指标在写入类型为持久化的flash写入总量的数值变化

异步仪器 ​

异步仪器包括observable_counter，observable_updowncounter，observable_gauge，也称为观察仪器，则是通过注册回调函数来采集数据。这些回调函数会在收集指标时被调用，这些数据需要定期轮询获取。

-- 创建 Meter
local meter = metrics.get_meter()

-- 创建ObservableCounter
local observable_counter = meter:create_observable_counter("my_observable_counter")

-- 注册回调函数
observable_counter:add_callback(function()
    return 30
end)

对外接口 ​

对外接口只提供get_meter(name, version, schema_url)方法，用于获取Meter对象，其余均为对象附加元方法。

配置介绍 ​

DT场景下会通过文件流导出器将metrics数据导出到os.get_env('PROJECT_DIR') .. '/test/.test_temp_data/metric.txt

metrics数据示例：

{
  scope name	: test_meter
  schema url	: https://test//test
  version	: 1.13.0
  start time	: Fri May  9 04:35:56 2025
  end time	: Fri May  9 04:36:02 2025
  instrument name	: test_counter
  description	: 
  unit		: 
  type		: SumPointData
  value		: 1
  attributes		: 
  type		: SumPointData
  value		: 2
  attributes		: 
	key1: value1
  resources	:
	service.name: unknown_service
	telemetry.sdk.language: cpp
	telemetry.sdk.name: opentelemetry
	telemetry.sdk.version: 1.13.0
}
...