GKE环境下TypeScript项目中Google Cloud Trace Agent无追踪数据

1. 验证NODE_ENV环境变量是否正确配置 #

你的Trace Agent仅在NODE_ENV=production时启动，先确认GKE容器中该变量已正确设置：

• 在trace.ts中添加调试日志验证：

  import * as TraceAgent from '@google-cloud/trace-agent';
  
  console.log(`当前NODE_ENV: ${process.env.NODE_ENV}`);
  if (process.env.NODE_ENV === 'production') {
      TraceAgent.start({
          ignoreUrls: ['/livez', '/healthz', '/metrics'],
          ignoreMethods: ['OPTIONS'],
          contextHeaderBehavior: 'ignore',
          samplingRate: 10,
          serviceContext: {
              service: 'my-service-name',
              version: process.env.VERSION || 'v0.0.0'
          }
      });
      console.log('Trace Agent 已启动');
  }
  

• 如果日志显示NODE_ENV不是production，需在GKE部署配置中添加该环境变量。

2. 确保Trace Agent是绝对首个初始化的模块 #

虽编译后的代码中require("./app/services/trace")排在首位，但部分第三方模块（如source-map-support）可能隐式加载其他依赖，干扰初始化顺序：

• 暂时注释source-map-support/register的导入，测试是否能生成追踪数据。
• 将Trace Agent启动逻辑直接移到index.ts最顶部，避免中间文件的潜在影响：

  // index.ts 最顶部，无任何前置代码
  import * as TraceAgent from '@google-cloud/trace-agent';
  
  if (process.env.NODE_ENV === 'production') {
      TraceAgent.start({
          ignoreUrls: ['/livez', '/healthz', '/metrics'],
          ignoreMethods: ['OPTIONS'],
          contextHeaderBehavior: 'ignore',
          samplingRate: 10,
          serviceContext: {
              service: 'my-service-name',
              version: process.env.VERSION || 'v0.0.0'
          }
      });
  }
  
  // 之后再导入其他模块
  import 'source-map-support/register';
  import makeApp from './app/app';
  
  makeApp().then(app => app.listen(port));
  

3. 确认Express在Trace Agent启动后加载 #

Trace Agent需要patch Express内部方法来生成追踪数据，必须保证Express的导入在TraceAgent.start()执行完成之后。将启动逻辑移到index.ts顶部，可确保require('./app/app')（内部导入Express）在Agent初始化之后执行。

4. 启用调试日志排查Agent状态 #

在GKE容器环境变量中添加GCLOUD_TRACE_DEBUG=true，或在Agent配置中开启调试日志：

TraceAgent.start({
    // 你的现有配置
    logLevel: 'debug'
});

查看容器日志，确认Agent是否成功启动、有无权限或配置类报错。

5. 确认GKE服务账号权限 #

虽然命令行启动正常，仍需验证GKE节点使用的服务账号拥有roles/cloudtrace.agent权限：

gcloud projects get-iam-policy 你的项目ID --filter="bindings.members:serviceAccount:你的GKE服务账号" --format="value(bindings.role)"

若缺少权限，执行以下命令添加：

gcloud projects add-iam-policy-binding 你的项目ID --member="serviceAccount:你的GKE服务账号" --role="roles/cloudtrace.agent"

内容的提问来源于stack exchange，提问作者Wazbat