文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>注册配置治理>Polaris（北极星）>Java 应用开发>使用 Java Agent>使用 Java Agent 接入

使用 Java Agent 接入

最近更新时间：2025-08-11 10:30:51

我的收藏

本页目录：

功能概述

Spring Cloud Tencent 的 Java Agent 支持针对容器部署的应用以及虚拟机部署的应用进行注入。对于 Spring Cloud 应用（原生 Spring Cloud 应用或者其他 Spring Cloud 扩展的应用），可以不用对应用代码及依赖进行任何变更的情况下，即可使用 Spring Cloud Tencent 的功能。下文将分别对容器场景和虚机场景的使用方法进行说明。

前提条件

已创建 Polaris（北极星）引擎实例。
登录 TSF 控制台。
在服务治理中心下的实例列表页面，单击目标引擎的 ID，进入基本信息页面。

使用步骤

1. 登录 TSF 控制台。
2. 在左侧导航栏选择Polaris（北极星）后，进入北极星引擎实例列表页。
3. 单击目标引擎的 ID，进入基本信息页面。
容器场景
虚拟机场景

步骤1：安装 polaris-controller

说明：
1. 添加容器集群会安装 Polaris-Controller 组件，请确保您的集群至少有 1C2G 的空闲资源，否则会添加失败。
2. 容器集群中安装 Polaris-Controller 组件后默认支持 K8s Service 服务同步（按需同步）和 Java Agent 自动注入能力。您也可以在控制台选择全量同步使用 k8s 全量同步方式。
1. 在目标引擎基本信息页顶部页签单击 K8s 集群，单击关联集群，单击查看关于 K8s 集群关联到 Polaris 的相关介绍。
2. 根据自身业务需求选择目标关联的 K8s 集群，支持 TKE (容器集群) / EKS (弹性容器集群)。即在目标集群中完成 polaris-controller 的安装。
3. K8s Service 同步接入：
全量同步：集群内全部 service 自动同步至北极星。

按需同步：仅指定的 namespace 或者 service 自动同步至北极星。


步骤2：在命名空间开启自动注入功能

在目标应用所在的 K8s 命名空间，通过以下命令开启自动注入：
kubectl label namespace <命名空间名> polaris-injection=enabled
通过以下命令查询命名空间是否开启了自动注入：
kubectl get namespace -L polaris-injection

输出结果：
NAME             STATUS   AGE    POLARIS-INJECTION
default          Active   3d2h   enabled
注入范围控制列表
label 键
范围
label 值
含义
polaris-controller 版本
polarismesh.cn/inject
Pod
disabled
声明当命名空间开启默认注入时，作为黑名单功能使用，指定 pod 不注入 javaagent
v1.7.3及以上版本
polarismesh.cn/inject
Pod
enabled
声明当命名空间未开启默认注入时，作为白名单功能使用，单独指定 pod 注入 javaagent
v1.7.3及以上版本
polarismesh.cn/inject
Namespace
enabled
声明该命名空间下的 pod，默认注入 javaagent
v1.7.3及以上版本
polaris-injection
Namespace
enabled
声明该命名空间下的 pod，默认注入 javaagent
所有版本支持，待废弃，使用polarismesh.cn/inject 代替
具体yaml示例
apiVersion: v1
kind: Namespace
metadata:
  name: java-agent-test
  labels:
    polarismesh.cn/inject: enabled
黑名单功能，不注入java agent。
apiVersion: apps/v1
kind: Deployment
metadata:
  name: label-block
  namespace: java-agent-test
spec:
  selector:
    matchLabels:
      app: label-block
  template:
    metadata:
      labels:
        app: label-block
        polarismesh.cn/inject: disabled
      annotations:
        polarismesh.cn/javaagent: "true"
    spec:
    ......
白名单功能，命名空间未开启自动注入的情况下，实现指定 pod 按需注入。
apiVersion: apps/v1
kind: Deployment
metadata:
  name: label-allow
spec:
  selector:
    matchLabels:
      app: label-allow
  template:
    metadata:
      labels:
        app: label-allow
        polarismesh.cn/inject: enabled
      annotations:
        polarismesh.cn/javaagent: "true"
    spec:
    ......

步骤3：SpringCloud 应用 yaml 文件中声明 Java Agent 标签

找到需要注入 Java Agent 的应用（一般是 deployment 或者 statefulset），编辑 yaml 并增加以下标签：
Annotation键
Annotation值
含义
polaris-controller版本
polarismesh.cn/javaagent
支持："true"、"false"，必填
声明需要往这个 POD 中注入 Java A gent
所有版本支持
polarismesh.cn/workloadNamespaceAsServiceNamespace
支持："true"、"false"，缺省
声明使用 k8s 命名空间作为服务命名空间注册到北极星，若和polarismesh.cn/javaagentConfig 中的配置冲突，此配置不生效
v1.7.3及以上版本
polarismesh.cn/workloadNameAsServiceName
支持："true"、"false"，缺省
声明使用 k8s 工作负载名称作为服务名注册到北极星，若和polarismesh.cn/javaagentConfig 中的配置冲突，此配置不生效
v1.7.3及以上版本
polarismesh.cn/javaagentFrameworkName
缺省，则自动识别应用框架的类型。
支持：spring-cloud
声明应用的框架类型，对于 SpringCloud 应用则填写 spring-cloud，目前仅支持 SpringCloud 类型。
所有版本支持
polarismesh.cn/javaagentFrameworkVersion
缺省，则自动识别应用框架的版本。
也支持手动声明框架版本，例如：2023、2022、hoxton 等。
声明应用的框架版本。
所有版本支持
polarismesh.cn/javaagentVersion
如：2.0.1.0。
注意：
生产环境请指定验证后的版本，若不填则自动会在每次实例发生重启时自动注入最新的版本，可能会有新版本的兼容性问题，导致实例启动异常。
声明 java-agent 包的镜像版本。
所有版本支持
polarismesh.cn/javaagentConfig
如指定命名空间、服务名并配置无损上线:
'{"spring.cloud.polaris.lossless.enabled":"true","spring.cloud.polaris.lossless.delay-register-interval":"30000","spring.cloud.polaris.discovery.namespace":"custom-ns","spring.application.name":"custom-service"}'
支持用户自定义的 Java Agent 配置，支持指定命名空间、服务名、服务实例元数据、无损上线配置等。格式为JSON。
不填写的配置则使用默认配置。
所有版本支持
配置 yaml 样例：
默认配置：${spring.application.name}的值作为服务名，default作为北极星命名空间。
apiVersion: apps/v1
kind: Deployment
metadata:
  name: default-ns-name
  namespace: java-agent-test
spec:
  selector:
    matchLabels:
      app: default-ns-name
  template:
    metadata:
      labels:
        app: default-ns-name
      annotations:
        polarismesh.cn/javaagent: "true"
    spec:
        ......

使用 k8s 工作负载名称作为服务名，k8s 命名空间作为北极星服务命名空间注册。
apiVersion: apps/v1
kind: Deployment
metadata:
  name: k8s-info-inject
  namespace: java-agent-test
spec:
  selector:
    matchLabels:
      app: k8s-info-inject
  template:
    metadata:
      labels:
        app: k8s-info-inject
      annotations:
        polarismesh.cn/javaagent: "true"
        polarismesh.cn/workloadNamespaceAsServiceNamespace: "true"
        polarismesh.cn/workloadNameAsServiceName: "true"
    spec:
        ......

使用自定义配置，下面的例子为使用 config 里面的配置，使用 custom-service 作为服务名，custom-ns 作为北极星服务命名空间注册。
apiVersion: apps/v1
kind: Deployment
metadata:
  name: custom-ns-name
  namespace: java-agent-test
spec:
  selector:
    matchLabels:
      app: custom-ns-name
  template:
    metadata:
      labels:
        app: custom-ns-name
      annotations:
        polarismesh.cn/javaagent: "true"
        polarismesh.cn/javaagentConfig: '{"spring.cloud.polaris.discovery.namespace": "custom-ns","spring.application.name":"custom-service"}'
    spec:
        ......

修改 yaml 后，需要重新部署应用。重新部署后，会自动完成 java-agent 的注入，可以观察应用日志，如果启动的时候出现以下关键字，则证明 java-agent 注入成功。
......
2024-02-01 21:19:16 [INFO ](PolarisAgentBootStrap) [Bootstrap] start bootStrapStarter:default
......
2024-02-01 21:19:16 [INFO ](PluginCreator) [BootStrap] plugin spring-cloud-hoxton-plugin has been loading

步骤1：下载 java agent

获取最新的 polaris-java-agent 的版本，并下载二进制 zip 包。点击下载。

步骤2：修改配置文件

1. 解压下载后到的 zip 包，进入 polaris-java-agent 的目录，并修改 conf/polaris-agent.conf 文件，填写需要使用的插件名称（需要按照应用的 spring-cloud 版本进行填写），内容示例如下：
plugins.enable=spring-cloud-2023-plugin
2. 进入 conf/plugin/spring-cloud-2023（不同插件有不同目录，需要按照上一步填写的插件来选择目录）目录中，修改 application.properties 文件：
2.1 填写正确的应用名（spring.application.name）。
2.2 填写您购买的北极星服务端的地址信息。服务端地址查看详细参见：引擎管理 > 客户端访问地址。
# 应用名称(必填)
spring.application.name=testSvcName
# 配置北极星服务端地址
spring.cloud.polaris.address=grpc\\://9.134.5.52\\:8091

步骤3：添加应用的启动参数

在应用的启动参数中，添加 -javaagent:<java-agent安装目录>/polaris-agent-core-bootstrap.jar，然后重启应用，即可完成 java-agent 的注入。
说明：
如果使用 IDEA 进行本地调试，则需要在 VM Option 下添加 -javaagent 的参数。

中国站
目录