finclip-app-manager/vendor/gitlab.finogeeks.club/finclip-backend/apm/README.md

246 lines
6.2 KiB
Markdown
Raw Permalink Normal View History

2023-11-02 18:36:36 +08:00
# 使用步骤
0. 注意事项当发布改apm新版本时请务必修改好build.go文件下的version变量比如:
```
var (
lock = &sync.Mutex{}
client *Client
version = "v0.2.1"
)
```
1. 将需要使用该apm工具的项目移动到$GOPATH/src目录下。
2. 在需要使用apm工具的项目目录下执行以下命令下载依赖
```
go get git.finogeeks.club/base/apm
go get git.finogeeks.club/base/apm@v0.2.1
go get github.com/SkyAPM/go2sky-plugins/gin/v3
go get github.com/Shopify/sarama@v1.24.1
```
3. 使用以下命令会将$GOPATH下的mod同步到vendor目录下。
```
go mod vendor
注意:在执行"go mod vendor"后,记得用"git add vendor/"将依赖的文件添加到git里否则drone构建时会缺失部分文件。
```
4. 如果需要更新apm依赖就执行以下命令
```
go get git.finogeeks.club/base/apm@{{git-tag}}
go mod vendor
或者:
go get git.finogeeks.club/base/apm@{{git-sha}}
go mod vendor
比如:
go get git.finogeeks.club/base/apm@v0.2.1
go mod vendor
或者:
go get git.finogeeks.club/base/apm@955a98a3c1
go mod vendor
```
# 使用样例
## 特别注意项
使用apm相关API时不要在任何地方使用`fmt.Sprint`等字符串操作的函数,这样会非常非常影响性能!!!
## 初始化
```
apm.BuildApmClient(apm.CreateBuild(cfg.SkyWalkingUrl, cfg.ServerName, cfg.SkyWalkingPartitions, cfg.SkyWalkingEnable))
```
## no trace,使用这个方法创建出来的ctx不会被埋点
```
ctx = ApmClient().NoTraceContext(ctx)
```
## 通用exitSpan
```
eSpan := apm.ApmClient().CreateExitSpan(ctx, operationName, peer, injector)
defer eSpan.End()
```
## 通用entrySpan
```
span, ctx := apm.ApmClient().CreateEntrySpan(ctx, operationName, extractor)
defer span.End()
```
## 通用localSpan
```
span, ctx := apm.ApmClient().CreateLocalSpan(ctx, opts...)
span.SetOperationName(operationName)
defer span.End()
比如:
span, ctx := apm.ApmClient().CreateLocalSpan(context.Background())
span.SetOperationName("updateLicenseValid")
defer span.End()
```
## HTTP示例
### 注入gin middleware
```
apm.ApmClient().InjectHttpMiddleware(g)
```
### exitSpan
```
span := apm.ApmClient().CreateHttpExitSpanWithUrl(ctx, req, url)
defer span.End()
或者
span := apm.ApmClient().CreateHttpExitSpanWithUrlAndInjector(ctx, http.MethodGet, url, func(header string) error {
headers[propagation.Header] = header
return nil
})
defer span.End()
```
## gRPC示例
### entrySpan
```
span, ctx := apm.ApmClient().CreateGRpcEntrySpan(ctx, method)
defer span.End()
```
### exitSpan
```
span := apm.ApmClient().CreateGRpcExitSpan(ctx, operationName, method, thirdService)
defer span.End()
```
## Kafka示例
### 配置kafka consumer
为使使用的kafka客户端库sarama支持header需要在consumer端配置kafka集群版本具体如下
```
version, e := sarama.ParseKafkaVersion("2.3.0")
if e != nil {
panic(err)
}
// 消费者共同配置
consumerConfig = cluster.NewConfig()
consumerConfig.Version = version
```
### entrySpan
```
span, ctx := apm.ApmClient().CreateKafkaEntrySpan(ctx, topic, method, msg)
defer span.End()
```
### exitSpan
```
span := apm.ApmClient().CreateKafkaExitSpan(ctx, topic, method, address, msg)
defer span.End()
span.Error(time.Now(), "topic", topic, "error", err.Error())
```
## MongoDB示例
### exitSpan
```
span := apm.ApmClient().CreateMongoExitSpan(ctx, action, address, dbName)
defer span.End()
span.Log(time.Now(), "collection", USER_REGION_C_NAME, "method", "Add")
span.Error(time.Now(), "collection", t.CollName, "method", "Find.One", "error", err.Error())
具体示例:
span := apm.ApmClient().CreateMongoExitSpan(ctx, "Table.Count", config.Cfg.MongoURL, t.dbName)
defer span.End()
span.Log(time.Now(), "collection", USER_REGION_C_NAME, "method", "Add")
```
## MySql示例
### exitSpan
```
span := apm.ApmClient().CreateMySqlExitSpan(ctx, action, address, dbName)
defer span.End()
span.Log(time.Now(), "collection", USER_REGION_C_NAME, "method", "Add")
span.Error(time.Now(), "collection", t.CollName, "method", "Find.One", "error", err.Error())
具体示例:
span := apm.ApmClient().CreateMySqlExitSpan(ctx, "Table.Count", config.Cfg.MySqlURL, t.dbName)
defer span.End()
span.Log(time.Now(), "collection", USER_REGION_C_NAME, "method", "Add")
```
## ElasticSearch示例
### exitSpan
```
span := apm.ApmClient().CreateESExitSpan(ctx, action, address)
defer span.End()
span.Log(time.Now(), "ReportMsg.InsertMany start")
span.Log(time.Now(), "index", config.Cfg.PrivateDataReportIndex, "method", "INSERT_EVENT")
span.Error(time.Now(), "index", config.Cfg.PrivateDataReportIndex, "method", "INSERT_EVENT", "error", err.Error())
```
## Redis示例
### exitSpan
```
_, _, dbName := apm.ParseURL(config.Cfg.RedisUrl)
span := apm.ApmClient().CreateRedisExitSpan(c.Request.Context(), "TestYace", config.Cfg.RedisUrl, dbName)
defer span.End()
span.Log(time.Now(), "collection", USER_REGION_C_NAME, "method", "Add")
```
### redis辅助工具
目前mop项目中使用了多种redis部署方案可以使用类似于以下的方式处理
```
span := createRedisSpan(ctx, "RedisSet")
span.Log(time.Now(), "key", key)
defer span.End()
func createRedisSpan(ctx context.Context, action string) go2sky.Span {
switch config.Cfg.RedisMode {
case MODE_SENTINEL_V2:
span := apm.ApmClient().CreateRedisExitSpan(ctx, action,
config.Cfg.RedisSentinelAddr, "")
span.Log(time.Now(), "Mode", config.Cfg.RedisMode)
span.Log(time.Now(), "MasterName", config.Cfg.RedisMasterName)
return span
case MODE_CLUSTER:
span := apm.ApmClient().CreateRedisExitSpan(ctx, action,
config.Cfg.RedisAddr, "")
span.Log(time.Now(), "Mode", config.Cfg.RedisMode)
return span
case MODE_CLUSTER_V2:
span := apm.ApmClient().CreateRedisExitSpan(ctx, action,
config.Cfg.RedisAddr, "")
span.Log(time.Now(), "Mode", config.Cfg.RedisMode)
return span
default:
if config.Cfg.RedisMode == MODE_SENTINEL {
span := apm.ApmClient().CreateRedisExitSpan(ctx, action,
config.Cfg.RedisSentinelAddr, "")
span.Log(time.Now(), "Mode", config.Cfg.RedisMode)
span.Log(time.Now(), "MasterName", config.Cfg.RedisMasterName)
return span
} else {
span := apm.ApmClient().CreateRedisExitSpan(ctx, action,
config.Cfg.RedisAddr, "")
span.Log(time.Now(), "Mode", config.Cfg.RedisMode)
return span
}
}
}
```