|
# Stardust Go SDK
星尘监控（Stardust）Go SDK，提供 APM 监控和配置中心的接入能力。
## 特性
- ✅ APM 链路追踪
- ✅ 配置中心
- ✅ 心跳性能指标上报
- ✅ 令牌自动续期与 401 重登录
- ✅ 服务端动态采样周期
- ✅ HTTP 入站/出站自动埋点（W3C traceparent 跨语言互通）
- ✅ database/sql 驱动自动埋点
- ✅ Redis 通用包装与可选 go-redis v9 Hook
- ✅ 无第三方依赖，仅使用 Go 标准库
- ✅ 支持 Go 1.18+
## 安装
```bash
go get github.com/NewLifeX/Stardust/SDK/Go/stardust
```
## APM 监控快速开始
```go
package main
import (
"github.com/NewLifeX/Stardust/SDK/Go/stardust"
)
func main() {
// 一行接入：创建、登录并启动自动埋点
tracer := stardust.Init("http://star.example.com:6600", "MyGoApp", "MySecret")
defer tracer.Stop()
// 需要自定义时改用 builder：
// tracer := stardust.NewTracer(server, appID, secret).SetVersion("1.0.0")
// tracer.Start()
// 手动埋点
span := tracer.NewSpan("业务操作", "")
span.Tag = "参数信息"
doSomething()
span.Finish()
}
```
## 自动埋点
`NewTracer` 创建后会自动完成两件事：设为默认追踪器，并把出站埋点安装到 `http.DefaultTransport`。
`Start()` 只负责登录、心跳与上报，不参与埋点安装。后创建的追踪器会成为新的默认追踪器；
多实例场景请显式使用实例方法，或最后创建主实例。
```go
tracer := stardust.NewTracer("http://star.example.com:6600", "MyGoApp", "MySecret")
tracer.SetAutoInstrument(false) // 如不需要默认传输自动埋点，可关闭
tracer.Start()
defer tracer.Stop()
```
### 链路上下文（W3C traceparent）
自动埋点遵循 W3C Trace Context：
```text
traceparent: 00-<trace-id>-<span-id>-<flags>
```
- SDK 生成 32 位小写十六进制 TraceId 与 16 位 SpanId。
- 入站解析 `traceparent`，复用 TraceId 并把上游 SpanId 作为入口片段的 ParentId；缺失或非法时新建链路。
- 为兼容 .NET 历史实现，入站允许短于 32 位的 trace-id。
- 出站以当前片段注入 `traceparent`；调用方已显式设置时不覆盖。
- SDK 自身的登录、心跳、上报与配置中心请求不创建片段，也不注入 `traceparent`。
手动读取/传播上下文：
```go
ctx, span := tracer.NewSpanFromContext(ctx, "业务操作")
defer span.Finish()
if current := stardust.SpanFromContext(ctx); current != nil {
fmt.Println(current.TraceID, current.ID)
}
```
### HTTP 出站
默认传输已自动埋点，普通 `http.Client` 即可；也可显式包装：
```go
client := tracer.WrapClient(&http.Client{Timeout: 5 * time.Second})
resp, err := client.Do(req.WithContext(ctx))
```
- 片段名称：`{METHOD} {host}{path}`，Tag 为完整 URL。
- 客户端 4xx/5xx 或网络异常记为错误片段。
### HTTP 入站（一行接入）
```go
handler := stardust.WrapHandler(mux)
http.ListenAndServe(":8080", handler)
// 或处理函数
http.HandleFunc("/api", stardust.WrapHandlerFunc(api))
```
- 片段名称：`{METHOD} {path}`，Tag 为原始 RequestURI。
- 服务端 5xx 或 panic 记为错误片段，panic 会记录后原样抛出。
- 嵌套包装会通过请求标记去重，同一请求只产生一个入口片段。
- Gin/Echo 等框架请使用其自身中间件 + `NewSpanFromContext`，或把框架的 `http.Handler` 交给 `WrapHandler`。
### 数据库（一行接入）
```go
// 方式一：直接打开（driver.Driver 为真实驱动实例）
db, err := stardust.OpenDB(&sqlite3.SQLiteDriver{}, "file:app.db", tracer)
// 方式二：注册包装后的驱动
sql.Register("mydb", stardust.WrapDriver(&mysql.MySQLDriver{}, tracer))
// 方式三：包装连接器
db := sql.OpenDB(stardust.WrapConnector(connector, tracer))
```
- 片段名称：`db:{system}:{action}:{tables}`，如 `db:sqlite:select:users`；Tag 为 SQL 文本（上报时按 `MaxTagLength` 截断）。
- 表名识别 `from`、`insert into`、`update`、`join`、`drop table`、`truncate table`，并去掉 `_20240101` 等日期分表后缀。
- 覆盖 `driver.Driver/Conn/Stmt/Tx`，以及 `ExecerContext`、`QueryerContext`、`ConnBeginTx`、`ConnPrepareContext`、`Pinger`、`SessionResetter`、`Validator` 等可选接口。
- 底层返回 `driver.ErrSkip` 时按 `database/sql` 约定回退，不产生多余片段。
- 上下文已有片段时作为其子片段，否则新建链路。
### Redis
核心模块提供通用包装，适合任意 Redis 客户端：
```go
err := tracer.TraceRedis(ctx, "GET", func(ctx context.Context) error {
return rdb.Get(ctx, "user:1").Err()
})
// 带参数摘要
err = tracer.TraceRedisWithTag(ctx, "SET", "user:1", func(ctx context.Context) error {
return rdb.Set(ctx, "user:1", "alice", 0).Err()
})
```
go-redis v9 可使用独立模块 `SDK/Go/stardust-redis`（核心包仍保持零第三方依赖）：
```go
import stardustredis "github.com/NewLifeX/Stardust/SDK/Go/stardust-redis"
rdb := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})
rdb.AddHook(stardustredis.NewHook(tracer))
```
> `stardust-redis` 通过核心模块伪版本依赖核心包；仓库内 `SDK/Go/go.work` 已同时加入两个模块，开发和测试无需手工 `replace`。若核心提交尚未发布，可在业务 `go.mod` 中临时 `replace` 到本地源码。核心包仍保持零第三方依赖。
- 片段名称：`redis:{COMMAND}`，如 `redis:GET`；Tag 为 key/参数摘要。
- 管道记为 `redis:PIPELINE`，Tag 为前几个命令名称。
### 自动埋点限制
- 只覆盖 Go 标准库 `net/http` 与 `database/sql`；gRPC、消息队列等需手动埋点。
- 标准库没有路由模板信息，入站片段名称使用实际路径；需要模板名称时请结合框架中间件自行创建片段。
- 数据库表名基于简单 SQL 关键字解析，复杂 SQL、动态表名或存储过程可能无法识别。
- 数据库类型从驱动类型名推断（如 sqlite/mysql/postgres/sqlserver/oracle），自定义驱动可能显示为类型名前缀。
- 核心模块不内置 Redis 客户端依赖；go-redis 需额外引入 `stardust-redis` 模块。
- 自动埋点自身不改变业务返回值；上游 `traceparent` 非法时自动降级为新链路。
## APM 配置项
所有设置方法均返回 `*Tracer`，支持链式调用：
| 方法 | 说明 | 默认值 |
|------|------|--------|
| `SetAppName(name)` | 应用名称 | 与 AppId 相同 |
| `SetVersion(version)` | 应用版本号。建议显式设置（SDK 默认 `1.0`）；服务端只有收到 Version 才下发 `Excludes`/`EnableMeter` | `1.0` |
| `SetIP(ip)` | 本机 IP。为空时自动枚举网卡（跳过回环地址，必要时 UDP 探测） | 自动获取 |
| `SetEnableMeter(enable)` | 是否在监控上报中携带进程性能信息（心跳始终携带） | `true` |
| `SetPeriod(seconds)` | 初始采样周期（秒），服务端响应会覆盖 | `60` |
| `SetHTTPClient(client)` | 自定义 HTTP 客户端 | 10 秒超时 |
| `SetAutoInstrument(enable)` | 开/关默认 HTTP 传输自动埋点 | `true`（`NewTracer` 自动安装） |
> 登录请求会携带 `Version` 与 `IP`；上报响应中的 `Period`、`MaxSamples`、`MaxErrors`、`Timeout`、`MaxTagLength`、`Excludes`、`EnableMeter` 会即时应用到后续采样。
## 心跳性能指标
启用后，心跳请求（`POST /App/Ping`）的请求体为 `AppInfo`，包含：
| 字段 | 类型 | 说明 |
|------|------|------|
| `Id` | int | 进程 ID |
| `Name` / `Version` / `IP` | string | 应用名、版本、本机 IP |
| `CommandLine` | string | 启动命令行 |
| `UserName` / `MachineName` | string | 当前用户与机器名 |
| `StartTime` | string | 进程启动时间（RFC3339） |
| `ProcessorTime` / `CpuUsage` | int64 / float64 | 处理器时间与 CPU 占比（Go SDK 暂为 0） |
| `WorkingSet` / `HeapSize` | int64 | 进程内存（`MemStats.Sys`）与堆分配（`HeapAlloc`） |
| `Threads` | int | Goroutine 数量 |
| `GCCount` | int | 距上次采集的 GC 次数增量 |
| `Time` | int64 | 当前 Unix 毫秒时间戳 |
其余线程池、句柄、连接数字段保留协议兼容，Go SDK 暂填 0。
## 令牌与采样周期
- 登录响应返回 `Token` 与 `Expire`（秒）；令牌缺失或距离过期不足 5 分钟时自动重新登录。
- 心跳响应返回新 `Token` 时自动更新本地令牌。
- 服务端返回 HTTP 401 或 `code=401` 时，自动重新登录并重试一次。
- 上报间隔由服务端下发的 `Period` 动态决定，修改后下一次等待即生效；`Stop()` 可立即退出等待。
## 配置中心快速开始
```go
package main
import (
"fmt"
"github.com/NewLifeX/Stardust/SDK/Go/stardust"
)
func main() {
config := stardust.NewConfigClient("http://star.example.com:6600", "MyGoApp", "MySecret")
config.Start()
defer config.Stop()
// 获取配置
value := config.Get("database.host")
fmt.Println("Database Host:", value)
// 监听配置变更
config.OnChange(func(configs map[string]string) {
fmt.Println("配置已更新:", configs)
})
select {}
}
```
## 完整文档
详细文档请参考：[/Doc/SDK/stardust-sdk-go.md](/NewLife/Stardust/Blob/master/SDK/Go/stardust/../../../Doc/SDK/stardust-sdk-go.md)
## 框架集成
### Gin 框架
```go
import (
"github.com/gin-gonic/gin"
"github.com/NewLifeX/Stardust/SDK/Go/stardust"
)
var tracer = stardust.NewTracer("http://star.example.com:6600", "MyGinApp", "secret")
func StardustMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
name := c.Request.Method + " " + c.Request.URL.Path
span := tracer.NewSpan(name, "")
span.Tag = c.Request.Method + " " + c.Request.RequestURI
defer span.Finish()
c.Next()
}
}
```
## License
MIT License
|