Go Agent 常见问题说明

instgo支持的版本？

Go版本1.18及以上。

编译时候是否一定要设置LicenseKey

不强制设置，设置LicenseKey是为了Instgo 接入时候能按版本规则下载对应Agent，否则就默认使用线上最新稳定版本。

是否支持vendor模式编译

注意在go build后添加 -mod=vendor。

是否支持go install 方式编译

支持，与go build相同，将instgo 添加到go install前编译，无需做其他修改。

instgo 是否支持打印的日志级别设置

instgo编译前加上环境变量ARMS_LOG_LEVEL即可，默认值是warn，可以设置为debug/info/warn/error。

手动声明环境变量后启动进程可观测不生效，控制台页面看不到应用

• 确认业务启动日志是否打印了arms not enable，若存在说明环境变量声明失败。

• 确认LicenseKey、RegionId、Arms Enable、应用名称是否都声明。

• 使用supervisor来启动的应用，环境变量声明不会生效，有以下两种解决办法：

  • 编译时候通过增加ldflags声明环境变量内容，这样可以编译后启动不需要手动export。

    instgo go build -ldflags  " -X 'github.com/alibaba/loongsuite-go-agent/pkg/exporters.ArmsApmName=${appName}' -X 'github.com/alibaba/loongsuite-go-agent/pkg/exporters.ArmsEnable=true'  -X 'github.com/alibaba/loongsuite-go-agent/pkg/exporters.LicenseKey=${licenseKey}' -X 'github.com/alibaba/loongsuite-go-agent/pkg/exporters.RegionId=${regionId}'"

  • 在运行二进制前直接声明。

    ARMS_ENABLE=true ARMS_APP_NAME={AppName} ARMS_REGION_ID={regionId} ARMS_LICENSE_KEY={licenseKey} ./xxxx

编译时间长，如何降低编译时间

参考文档：使用Cache加快Instgo编译速度

支持哪些环境下编译

Linux/Mac/Windows (X86/ARM64）均支持。

编译报错

• 编译环境的go 版本是否大于等于go mod 中写的版本。

• 确认go build 是否会报错 。

• go 1.18.4 编译会报错，go版本问题，使用1.18.5编译即可。

===== Fatal Error ======
Error     : Failed to run command
Reason    : WORK=/var/folders/th/zchyp81n1js5dkwzd3dlpmk00000gp/T/go-build1761443998
# client/otel_pkgdep/rules/http17791
/Users/zhb192729/gitlab/example/client/otel_pkgdep/inst-api-semconv/instrumenter/http/http_attrs_extractor.go:129:48: internal compiler error: assertion failed
Please file a bug report including a short program that triggers the error.
https://go.dev/issue/new
# client/otel_pkgdep/rules/http18719
/Users/zhb192729/gitlab/example/client/otel_pkgdep/inst-api-semconv/instrumenter/http/http_attrs_extractor.go:129:48: internal compiler error: assertion failed
Please file a bug report including a short program that triggers the error.

• Mac/Windows下编译出现filename or extension is too long，这个报错是因为Mac/Windows下命令行的字符数量固定，换成Linux 编译即可。

• vendor 编译报错，确认go mod 是否包含google.golang.org/protobuf，没有的话在项目main.go文件的import中增加以下依赖：

  _ "google.golang.org/protobuf/proto"
  _ "google.golang.org/protobuf/runtime/protoimpl"

看不到应用或者应用显示不是Go

• ECS接入查看是否正确配置以下环境变量：

  export ARMS_ENABLE=true
  export ARMS_APP_NAME=XXX
  export ARMS_REGION_ID=XXX
  export ARMS_LICENSE_KEY=XXX

  参数名	说明
  ARMS_APP_NAME	应用名称
  ARMS_REGION_ID	对应的阿里云账号RegionID，可参考服务接入点。
  ARMS_LICENSE_KEY	License Key，可通过列出LicenseKey获取。

• 容器通过ack-onepilot接入，确认pod label是否配置正确：

  labels:
    aliyun.com/app-language: golang # Go应用必填，标明此应用是Go应用
    armsPilotAutoEnable: 'on'
    armsPilotCreateAppName: 'appName' # 请将<your-deployment-name>替换为您的应用名称

• 非阿里云环境请确保已完成专线打通或者公网能对外访问。

接口过滤问题

• 若需要过滤/mongo或者/mon 开头的接口，可以配置/mon.*。接口调用配置包含以下三项：慢调用阈值（必填，单位 ms，默认 500，接口响应时间超过该值将被标记为慢调用，例如设置为 501）；HTTP状态码白名单（默认 HTTP 返回码大于 400 视为错误，加入白名单的状态码将在错误统计中被忽略）；无效接口调用过滤（不需要 ARMS 监控统计的接口，多个规则以英文逗号分隔，例如 POST /mongo,/mon.*）。

• 指标过滤需升级到2.2.3版本支持。

应用概览看不到数据

• 应用接入启动后看下是否有下列日志在标准输出，没有的话表示接入不成功（ECS下环境变量没有加、容器K8s下通过ack-onepilot 接入 label没有写或者位置不对，请按照接入文档处理）。

  Load Aliyun Golang Agent version:  xxx  report to region:  xxx

• 第一次接入需要等待1-2分钟等待资源初始化成功。

• 如果暂停监控开关被开启，则无法上报数据，请在应用设置页面查看暂停监控开关是否已开启，若已开启请将其关闭。

• 确认探针管理是否有这个应用的实例数据，状态是否正常。

调用链分析没有数据

先查看应用的trace 采样率是多少，默认10%，如果看不到，可能是因为请求太少没有采集到，可以先调整采样率看下是否有数据。

在应用配置页签的采样设置区域，将采样策略设置为固定采样率，修改采样率百分比的值（例如设置为1），然后单击保存。

确认go mod中使用的SDK是否支持

ARMS应用监控支持的Go组件和框架。

查看网络是否联通

Golang应用监控网络配置。

查看Agent监控日志是否有报错

在二进制运行目录存在arms_go_agent.log日志，查看是否有上报数据错误日志。

调用链分析页面日志无法跳转

确认是否在应用设置-应用日志关联设置，开关是否打开，是否正确配置sls信息。

SLS 日志服务绑定需正确配置区域、Project名称、关联类型（日志库或数据集）、Logstore名称及关联索引（支持全文索引或指定字段索引）。

日志中没有traceId、SpanId

1. 查看使用的框架是否在以下列表中：

   组件	仓库地址	低版本	高版本
   Gokit Log	https://github.com/go-kit/log	v0.1.0	v0.2.1
   Zerolog	https://github.com/rs/zerolog	v1.10.0	v1.34.0
   Zap	https://github.com/uber-go/zap	v1.13.0	v1.27.0
   Logrus	https://github.com/sirupsen/logrus	v1.5.0	无限制
   Log	https://pkg.go.dev/log	v1.21	无限制
   Slog	https://pkg.go.dev/log/slog	v1.21	无限制
   go-zero logx	https://github.com/zeromicro/go-zero/tree/master/core/logx	v1.6.5	无限制
   Kratos log	https://github.com/go-kratos/kratos/blob/main/middleware/logging	v2.1.2	v2.4.0

2. 使用自定义的format输出日志可能导致key冲突，确认业务代码中是否也加了trace_id、span_id，如果有，可以将arms 注入的trace_id、span_id key 修改为一个唯一key，如下修改为arms_trace_id、arms_span_id。

   在 ARMS 应用的日志关联配置页面，修改日志填充TraceId名称和日志填充SpanId名称两个字段的值即可。