腾讯云可观测平台 K8s 环境自动接入 Node.js 应用 （推荐）

一、前提条件

请参考 OpenTelemetry-JavaScript 方案支持的组件和框架，确保 Node.js 版本、依赖库与框架在探针支持的范围内。对于自动埋点支持的依赖库和框架，在接入成功后即可完成数据上报，不需要修改代码。如果自动埋点不满足你的场景，或者需要增加业务层埋点，请使用 OpenTelemetry API 进行自定义埋点。

二、步骤1：安装 Operator

在 K8s 集群安装 Operator，推荐从 APM 控制台一键安装 Operator，详情请参考 安装 tencent-opentelemetry-operator。

三、步骤2：确定探针版本

请参考 探针版本选择，找到和 Node.js 版本所匹配的探针版本。

四、步骤3：在工作负载添加 annotation

以容器服务 TKE 为例，通过如下步骤可以在工作负载中添加 annotation，对于通用 K8s 集群，请通过 kubectl 等工具添加 annotation。

1. 登录 容器服务 控制台。

2. 单击集群，进入对应的 TKE 集群。

3. 在工作负载中找到需要接入 APM 的应用，单击更多，单击编辑 yaml。

4. 在 Pod annotation 中添加如下内容，单击完成，即可完成接入。

cloud.tencent.com/inject-nodejs: "true"cloud.tencent.com/otel-service-name: <serviceName>

注意：说明：

注意：<serviceName>：应用名，必填。多个使用相同应用名接入的进程，在 APM 中会表现为相同应用下的多个实例。最长63个字符，只能包含小写字母、数字及分隔符 “-”，且必须以小写字母开头，数字或小写字母结尾。

如果使用非最新版本探针，需要额外添加如下 Pod annotation（以版本 0.56.0 为例）：

cloud.tencent.com/nodejs-instr-version: "0.56.0"

请注意，以上内容需要添加到 spec.template.metadata.annotations 中，作用于 Pod 的 annotation，而不是工作负载的 annotation，可以参考如下代码片段。

apiVersion: apps/v1kind: Deploymentmetadata: labels: k8s-app: my-app name: my-app namespace: defaultspec: selector: matchLabels: k8s-app: my-app template: metadata: labels: k8s-app: my-app annotations: cloud.tencent.com/inject-nodejs: "true" # 添加到此处 cloud.tencent.com/otel-service-name: my-app spec: containers: – image: my-app:0.1 name: my-app

五、Next.js 框架注意事项

Operator 默认使用 gRPC 协议上报数据，但如果你的应用使用 Next.js 框架，需要将接入点地址的协议更改为 http，并通过环境变量 OTEL_EXPORTER_OTLP_ENDPOINT 进行指定。假定你在控制台获取的接入点地址为 grpc://ap-shanghai.apm.tencentcs.com:4317，你需要将接入点地址修改为 http://ap-shanghai.apm.tencentcs.com:4317。

可以在项目的启动脚本中加入此设置项。

export OTEL_EXPORTER_OTLP_ENDPOINT=<HTTP协议接入点>

或者通过 YAML 文件添加环境变量。

env: – name: OTEL_EXPORTER_OTLP_ENDPOINT value: <HTTP协议接入点>

六、接入验证

对工作负载添加 annotation 后，基于不同的发布策略，触发应用 Pod 的重启。新启动的 Pod 会自动注入探针，并连接到 APM 服务端上报监控数据，上报的业务系统为 Operator 的默认业务系统。在有正常流量的情况下，应用性能监控 > 应用列表 中将展示接入的应用，单击应用名称/ID 进入应用详情页。

再选择实例分析，即可看到接入的应用实例。由于可观测数据的处理存在一定延时，如果接入后在控制台没有查询到应用或实例，请等待30秒左右。

七、更多接入配置项（可选）

在工作负载级别，可以添加更多的 annotation 对接入行为进行调整。