# exporter-common

**Repository Path**: go-tips/exporter-common

## Basic Information

- **Project Name**: exporter-common
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# exporter-common

`exporter-common` 是一个 Go 语言库，用于简化 Prometheus Exporter 的开发。它封装了指标的注册、线程安全更新等重复性工作，让你专注于采集逻辑。

## 特性

- 提供线程安全的 `MetricsServer`，管理多个 `GaugeVec` 指标。
- 支持动态注册指标（名称、帮助文本、标签列表）。
- 简洁的 `SetGauge` 方法更新指标值。
- 与标准 `promhttp.Handler` 无缝集成。

## 安装

```bash
go get gitee.com/go-tips/exporter-common.git
```

## 快速开始

以下是一个完整的示例，展示如何使用该库创建一个简单的 Exporter，监控某个服务的连通性。

```go
package main

import (
    "net/http"
    "time"

    "gitee.com/go-tips/exporter-common.git/metrics"
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promhttp"
)

func main() {
    // 1. 创建 MetricsServer
    ms := metrics.NewMetricsServer()

    // 2. 注册指标（可以注册多个）
    ms.MustRegisterGauge(metrics.GaugeVecConfig{
        Name:   "service_up",
        Help:   "Service health status (1=up, 0=down)",
        Labels: []string{"service", "instance"},
    })

    // 3. 启动采集 goroutine
    go collect(ms)

    // 4. 暴露指标端点
    http.Handle("/metrics", promhttp.Handler())
    http.ListenAndServe(":8080", nil)
}

func collect(ms *metrics.MetricsServer) {
    ticker := time.NewTicker(15 * time.Second)
    for range ticker.C {
        // 模拟采集：检查两个服务的状态
        ms.SetGauge("service_up", prometheus.Labels{
            "service":  "api",
            "instance": "localhost:8081",
        }, 1.0)

        ms.SetGauge("service_up", prometheus.Labels{
            "service":  "db",
            "instance": "localhost:5432",
        }, 0.0)
    }
}
```

## API 参考

### `GaugeVecConfig`

定义要注册的指标。

```go
type GaugeVecConfig struct {
    Name   string   // 指标名称（符合 Prometheus 命名规范）
    Help   string   // 帮助文本
    Labels []string // 标签列表
}
```

### `NewMetricsServer() *MetricsServer`

创建新的 MetricsServer 实例。

### `func (m *MetricsServer) RegisterGauge(cfg GaugeVecConfig) error`

注册一个 GaugeVec 指标。如果指标名称已存在，返回错误。

### `func (m *MetricsServer) MustRegisterGauge(cfg GaugeVecConfig)`

注册指标，如果出错则 panic。适用于初始化阶段。

### `func (m *MetricsServer) SetGauge(name string, labels prometheus.Labels, value float64)`

设置指定指标的值。`labels` 必须包含该指标注册时定义的所有标签，且值类型正确。如果指标未注册，该方法静默失败（可选择记录日志）。

## 注意事项

1. **标签必须匹配**：调用 `SetGauge` 时传入的 `prometheus.Labels` 必须包含该指标注册时声明的所有标签，否则会导致 panic。
2. **线程安全**：`SetGauge` 内部使用读写锁保护，可安全并发调用。
3. **指标命名**：请遵循 Prometheus [命名最佳实践](https://prometheus.io/docs/practices/naming/)。
4. **HTTP 服务**：该库只负责指标管理，不启动 HTTP 服务，你需要自行使用 `promhttp.Handler()` 暴露 `/metrics`。

## 示例项目

你可以参考以下两个实际项目来了解如何使用：

- [netif-stats](https://gitee.com/...) - 监控网络接口连通性
- [traffic-stats](https://gitee.com/...) - 监控 IP 流量（基于 iptables）

## 贡献

欢迎提交 Issue 和 PR。

## 许可证

MIT