更新时间:2023.03.21 14:33:52
Java应用在不同场景下有不同的接入方式,本文介绍不同场景下Java应用的详细接入操作,接入后可以实现自动收集Trace信息、自动生成Metric指标、以及调用链检索、日志检索等功能。
APMPlus监控组件包括Server Agent和JavaAgent。
Server Agent是APMPlus自主研发的数据采集工具,负责采集JavaAgent上报的数据,然后把数据上报到APM服务端用于查询分析。
JavaAgent基于SkyWalking二次开发。
JavaAgent基于SkyWalking修改,包含的开源软件声明如下:
Skywalking https://github.com/apache/skywalking
Apache SkyWalking
Copyright 2017-2022 The Apache Software Foundation
This product includes software developed at The Apache Software Foundation http://www.apache.org/.
SPDX-License-Identifier: Apache- 2.0
URL to the license definition page: http://www.apache.org/licenses/LICENSE-2.0
为方便快速接入验证应用监控的基础功能,可选择暂时跳过Server Agent接入。快速接入请按照以下流程接入APM服务端。
若要完整体验APM功能,请按照容器部署或者主机部署进行完整方式接入。
JavaAgent用于采集应用的Trace、日志检索等数据,将数据上报到Server Agent。更多JavaAgent采集的数据,请参见Jav a应用功能。
下载JavaAgent。
https://apmplus-dl-cn-beijing.volces.com/server_warehouse/assets/java-agent/apminsight-java-agent_latest.tar.gz
执行以下命令,解压下载的apminsight-java-agent_latest.tar.gz
文件。
tar -zxvf apminsight-java-agent_latest.tar.gz
解压后的目录结构如下所示:
. |-- apmplus-agent.jar #agent的jar包 |-- config #配置文件目录 | `-- agent.config #配置文件 |-- logs #agent默认日志目录 | `-- apmplus-agent.log #agent默认日志文件 `-- plugins #插件目录,放置支持的插件的jar包 |-- apm-feign-default-http-9.x-plugin-1.0.0-stable.jar |-- apm-httpClient-4.x-plugin-1.0.0-stable.jar |-- apm-jdbc-commons-1.0.0-stable.jar `-- ...jar
执行以下命令,集成并启动JavaAgent。
java -javaagent:{apmplus-agent.jar} -Dapmplus.{配置参数}=xxx -jar {您的应用jar包}
参数说明如下:
apmplus-agent.jar:JavaAgent的jar包路径。
-D:启动时,-D指定agent相关的配置参数,配置参数的key为agent.config
中的配置项。例如,指定配置项agent.service_name时,配置为-Dapmplus.agent.service_name=xxx
。agent.config
中的配置项说明:
配置项 | 是否必填 | 说明 |
---|---|---|
agent.service_name | 是 | 服务名。 |
agent.service_type | 是 | 服务类型。http或rpc。 |
agent.endpoint | 是 | 上报端点,格式为 |
agent.app_key | 是 | appkey是用户的唯一标识。 |
logging.dir | 否 | 日志文件目录。默认为logs。 |
logging.file_name | 否 | 日志文件名。默认为 |
logging.level | 否 | 日志级别。
|
您的应用jar包:您的应用jar包路径。
如果没有上报数据,请通过以下操作逐步排查:
-Dapmplus.logging.level=DEBUG
,开启debug日志,查看logs目录下的agent日志是否有异常。如果您的应用是基于Kubernetes集群部署,请参见以下流程接入APMPlus服务端。
方式1:通过kubectl命令行接入(推荐)
进入接入中心,选择Java语言 > APMPlus > 容器部署,获取如下安装命令,需要区分您的开服区域(region)与网络接入方式(network),appkey是用户的唯一标识。
kubectl apply -f "http://apmplus-dl-{region}.ivolces.com/server_warehouse/generate_assets/download/apmplus-agent-k8s/apmplus-operator.yaml?appkey={appkey}&network={network}"
说明
完整安装命令请到接入中心查看,详情请参见如何使用接入中心?。
方式2:通过容器服务控制台接入
下面以火山引擎VKE为例,介绍如何在控制台上通过配置Yaml接入Server Agent。操作前,请确保您已创建集群。具体请参见创建集群。
浏览器打开apmplus-operator.yaml
文件。
文件链接如下,与方式1中kubectl使用的链接相同。
http://apmplus-dl-{region}.ivolces.com/server_warehouse/generate_assets/download/apmplus-agent-k8s/apmplus-operator.yaml?appkey={appkey}&network={network}
登录容器服务管理控制台。
单击左侧导航栏中的集群。
选择工作负载 > 守护进程,单击使用Yaml创建。
在使用Yaml创建页面,类型选择自定义,复制步骤1打开的yaml文件的所有内容粘贴到Yaml中,然后单击确定。
JavaAgent用于采集应用的Trace、日志检索等数据,将数据上报到Server Agent。更多JavaAgent采集的数据,请参见Jav a应用功能。
方式1:在pod上添加label(推荐)
在pod上添加label,开启JavaAgent自动注入。
apmplus.volcengine.com/java-agent.version: 'latest'
添加完成后,yaml配置如下所示:
--- apiVersion: apps/v1 kind: Deployment metadata: ... spec: template: metadata: labels: apmplus.volcengine.com/java-agent.version: 'latest' spec: containers: - name: xxx image: dockerhub.com:5000/xxx:latest imagePullPolicy: Always --- apiVersion: v1 kind: Service ...
方式2:接入JavaAgent并挂载UDS
下载JavaAgent。
https://apmplus-dl-cn-beijing.volces.com/server_warehouse/assets/java-agent/apminsight-java-agent_latest.tar.gz
执行以下命令,解压下载的apminsight-java-agent_latest.tar.gz
文件。
tar -zxvf apminsight-java-agent_latest.tar.gz
解压后的目录结构如下所示:
. |-- apmplus-agent.jar #agent的jar包 |-- config #配置文件目录 | `-- agent.config #配置文件 |-- logs #agent默认日志目录 | `-- apmplus-agent.log #agent默认日志文件 `-- plugins #插件目录,放置支持的插件的jar包 |-- apm-feign-default-http-9.x-plugin-1.0.0-stable.jar |-- apm-httpClient-4.x-plugin-1.0.0-stable.jar |-- apm-jdbc-commons-1.0.0-stable.jar `-- ...jar
执行以下命令,集成并启动JavaAgent。
java -javaagent:{apmplus-agent.jar} -Dapmplus.{配置参数}=xxx -jar {您的应用jar包}
参数说明如下:
apmplus-agent.jar:JavaAgent的jar包路径。
-D:启动时,-D指定agent相关的配置参数,配置参数的key为agent.config
中的配置项。例如,指定配置项agent.service_name时,配置为-Dapmplus.agent.service_name=xxx
。agent.config
中的配置项说明:
配置项 | 是否必填 | 说明 |
---|---|---|
agent.service_name | 是 | 服务名。 |
agent.service_type | 是 | 服务类型。http或rpc。 |
logging.dir | 否 | 日志文件目录。默认为logs。 |
logging.file_name | 否 | 日志文件名。默认为 |
logging.level | 否 | 日志级别。
|
collector.apm_server_agent_run_path | 否 | Agent运行时路径。默认为 |
collector.apm_agent_trace_sock | 否 | trace的sock文件。默认为 |
collector.apm_agent_comm_sock | 否 | settings、服务注册的sock文件。默认为 |
collector.apm_agent_log_sock | 否 | 日志上报的sock文件。默认为 |
collector.apm_agent_runtime_sock | 否 | 运行时数据上报的sock文件。默认为 |
您的应用jar包:您的应用jar包路径。
配置挂载目录。
方式1:在应用程序的k8s.yaml文件中配置挂载目录
--- apiVersion: apps/v1 kind: Deployment metadata: ... spec: template: spec: containers: - name: xxx image: dockerhub.com:5000/xxx:latest imagePullPolicy: Always volumeMounts: - name: agent-sock mountPath: /var/run/apminsight volumes: - name: agent-sock hostPath: path: /var/run/apminsight --- apiVersion: v1 kind: Service ...
方式2:在容器服务控制台上配置挂载目录
具体操作,请参见 创建无状态负载 。添加agent-sock配置:
方式3:docker测试挂载
docker启动时添加挂载目录,一般仅用于单个docker本地测试。
docker run -d -v /var/run/apminsight:/var/run/apminsight image_name
重新启动应用,让配置生效。
如果没有上报数据,请通过以下操作逐步排查:
/var/run/apminsight/
目录是否挂载成功,目录下是否有xxx.sock
文件。-Dapmplus.logging.level=DEBUG
,开启debug日志,查看logs目录下的agent日志是否有异常。/var/log/apminsight
下查看是否有异常日志。方式1:通过kubectl命令行
kubectl delete -f "http://apmplus-dl-{region}.ivolces.com/server_warehouse/generate_assets/download/apmplus-agent-k8s/apmplus-operator.yaml?appkey={appkey}&network={network}"
方式2:通过容器服务控制台
依次删除通过容器服务控制台创建的资源。
如果您的应用是基于虚拟机或者物理机部署,请参见以下流程接入APMPlus服务端。
安装Server Agent。
Server Agent运行于主机上,采集主机信息,接收并转发该主机上应用的上报数据。
进入接入中心,选择 Java语言 > APMPlus > 主机部署 ,获取如下安装命令,需要区分您的开服区域(region)与网络接入方式(network),appkey是用户的唯一标识。
bash -c "$(curl -L 'http://apmplus-dl-{region}.volces.com/server_warehouse/generate_assets/download/apmplus-agent-ecs/install.sh?appkey={appkey}&network={network}')"
说明
完整安装命令请到接入中心查看,详情请参见如何使用接入中心?。
安装后会创建如下目录和文件:
/var/log/apminsight
:运行时日志。/etc/apminsight.v1
:配置文件。/opt/apminsight
:二进制文件。/lib/systemd/system/apminsight-agent.service
:探针核心进程。/lib/systemd/system/apminsight-system-probe.service
:system-probe,用于监控网络和进程退出。启动Server Agent。
sudo systemctl start apminsight-agent sudo systemctl start apminsight-system-probe
JavaAgent用于采集应用的Trace、日志检索等数据,将数据上报到Server Agent。更多JavaAgent采集的数据,请参见Jav a应用功能。
下载JavaAgent。
https://apmplus-dl-cn-beijing.volces.com/server_warehouse/assets/java-agent/apminsight-java-agent_latest.tar.gz
执行以下命令,解压下载的apminsight-java-agent_latest.tar.gz
文件。
tar -zxvf apminsight-java-agent_latest.tar.gz
解压后的目录结构:
. |-- apmplus-agent.jar #agent的jar包 |-- config #配置文件目录 | `-- agent.config #配置文件 |-- logs #agent默认日志目录 | `-- apmplus-agent.log #agent默认日志文件 `-- plugins #插件目录,放置支持的插件的jar包 |-- apm-feign-default-http-9.x-plugin-1.0.0-stable.jar |-- apm-httpClient-4.x-plugin-1.0.0-stable.jar |-- apm-jdbc-commons-1.0.0-stable.jar `-- ...jar
执行以下命令,集成并启动JavaAgent。
java -javaagent:{apmplus-agent.jar} -Dapmplus.{配置参数}=xxx -jar {您的应用jar包}
参数说明如下:
apmplus-agent.jar:JavaAgent的jar包路径。
-D:启动时,-D指定JavaAgent相关的配置参数,配置参数的key为agent.config
中的配置项。例如,指定配置项agent.service_name时,配置为-Dapmplus.agent.service_name=xxx
。agent.config
中的配置项说明:
配置项 | 是否必填 | 说明 |
---|---|---|
agent.service_name | 是 | 服务名。 |
agent.service_type | 是 | 服务类型。http或rpc。 |
logging.dir | 否 | 日志文件目录。默认为logs。 |
logging.file_name | 否 | 日志文件名。默认为 |
logging.level | 否 | 日志级别。
|
collector.apm_server_agent_run_path | 否 | Agent运行时路径。默认为 |
collector.apm_agent_trace_sock | 否 | trace的sock文件。默认为 |
collector.apm_agent_comm_sock | 否 | settings、服务注册的sock文件。默认为 |
collector.apm_agent_log_sock | 否 | 日志上报的sock文件。默认为 |
collector.apm_agent_runtime_sock | 否 | 运行时数据上报的sock文件。默认为 |
您的应用jar包:您的应用jar包路径。
(可选)启动后,如果您需要修改配置,请修改/config/agent.config
文件,然后重新启动应用使配置生效。
配置文件内容:
# The service name in UI agent.service_name=${APMPLUS_AGENT_NAME:Your_ApplicationName} # The service type of http/rpc agent.service_type=http # The max amount of spans in a single segment. # agent.span_limit_per_segment=${APMPLUS_AGENT_SPAN_LIMIT:300} # Ignore the segments if their operation names end with these suffix. # agent.ignore_suffix=${APMPLUS_AGENT_IGNORE_SUFFIX:.jpg,.jpeg,.js,.css,.png,.bmp,.gif,.ico,.mp3,.mp4,.html,.svg} # The operationName max length # agent.operation_name_threshold=${APMPLUS_AGENT_OPERATION_NAME_THRESHOLD:500} # server agent run path #collector.apm_server_agent_run_path=/var/run/apminsight/ # unix domain socket path of trace #collector.apm_agent_trace_sock=trace.sock # unix domain socket path of comm #collector.apm_agent_comm_sock=settings.sock # unix domain socket path of log #collector.apm_agent_log_sock=log.sock # unix domain socket path of runtime #collector.apm_agent_runtime_sock=runtime.sock # Logging file_name logging.file_name=${APMPLUS_LOGGING_FILE_NAME:apmplus-agent.log} # Logging level logging.level=${APMPLUS_LOGGING_LEVEL:WARN} # Logging dir # logging.dir=${APMPLUS_LOGGING_DIR:""} # Logging max_file_size, default: 300 * 1024 * 1024 = 314572800 # logging.max_file_size=${APMPLUS_LOGGING_MAX_FILE_SIZE:314572800} # The max history log files. When rollover happened, if log files exceed this number, # then the oldest file will be delete. Negative or zero means off, by default. # logging.max_history_files=${APMPLUS_LOGGING_MAX_HISTORY_FILES:-1}
如果没有上报数据,请通过以下操作逐步排查:
/var/run/apminsight/
目录是否挂载成功,目录下是否有xxx.sock
文件。-Dapmplus.logging.level=DEBUG
,开启debug日志,查看logs目录下的agent日志是否有异常。/var/log/apminsight
下查看是否有异常日志。bash -c "$(curl -L 'http://apmplus-dl-{region}.volces.com/server_warehouse/generate_assets/download/apmplus-agent-ecs/install.sh?appkey={appkey}&network={network}')" -- uninstall
OpenTelemetry是CNCF的一个可观测性项目,旨在提供可观测性领域的标准化方案,解决观测数据的数据模型、采集、处理、导出等的标准化问题,提供与三方vendor无关的服务。
如果您的应用已经接入了OpenTelemetry的SDK,APMPlus服务端可以接收OpenTelemetry上报的数据。接入APMPlus后,您将获得RED指标生成能力、Trace多维检索、单链路检索、拓扑生成等多项能力。
SDK将数据上报到Collector,Collector采集数据上报到APMPlus服务端。
配置应用,开启数据上报。
下载OpenTelemetry JavaAgent。
wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
修改应用启动参数,设置JavaAgent和otel.service.name。
代码示例:
java -javaagent:<path/to/opentelemetry-javaagent.jar> \ -Dotel.exporter.otlp.endpoint=<your-ot-collector-endpoint> \ -Dotel.exporter.otlp.protocol=<your-ot-collector-protocal> \ -Dotel.service.name=java-opentelemetry-otlp-instrumentation \ -jar myapp.jar
配置collector,修改上报端点。
进入接入中心,选择 Java语言 > OpenTelemetry > Collector ,获取如下配置。需要区分您的开服区域(region)与网络接入方式(network),appkey是用户的唯一标识。
exporters: otlp: endpoint: apmplus-{region}.volces.com:4317 compression: gzip headers: X-ByteAPM-AppKey: {appkey} tls: insecure: true
说明
完整配置命令请到接入中心查看,详情请参见如何使用接入中心?。
重新启动应用。
SDK采集数据,直接上报到APMPlus服务端。
下载OpenTelemetry JavaAgent。
wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
修改应用启动参数,设置JavaAgent和otel.service.name。
示例代码:
java -javaagent:<path/to/opentelemetry-javaagent.jar> \ -Dotel.exporter.otlp.endpoint=http://apmplus-{region}.ivolces.com:4317 \ -Dotel.exporter.otlp.headers=X-ByteAPM-AppKey={appkey} \ -Dotel.exporter.otlp.protocol=grpc \ -Dotel.service.name=java-opentelemetry-otlp-instrumentation \ -jar myapp.jar
说明
完整配置命令请到接入中心查看,详情请参见如何使用接入中心?。
APMPlus OpenTelemetry Collector是APMPlus基于OpenTelemetry Collector二次开发的数据采集器,遵守Apache2.0协议,支持采集OpenTelemetry监控数据,同时支持采集Prometheus指标、应用监控数据和K8s资源指标。
安装APMPlus OpenTelemetry Collector。
kubectl apply -f "http://apmplus-dl-{region}.ivolces.com/server_warehouse/generate_assets/download/apmplus-opentelemetry-k8s/apmplus-opentelemetry-operator-v0.0.13.yaml?appkey={appkey}&network={network}&promReplicas=1"
您可以通过修改url中 promReplicas 的值来扩展prom副本数。
说明
完整安装命令请到接入中心查看,详情请参见如何使用接入中心?。
在服务的k8s deployment配置中增加指定annotation。
instrumentation.apmplus.volcengine.com/inject-java: 'true'
示例代码:
apiVersion: apps/v1 kind: Deployment metadata: name: simple-java labels: app: simple-java spec: replicas: 1 selector: matchLabels: app: simple-java template: metadata: labels: app: simple-java annotations: instrumentation.apmplus.volcengine.com/inject-java: 'true' spec: containers: - name: simple-java image: java_demo_simple imagePullPolicy: Always env: - name: CONTAINER_RUNTIME value: "k8s"
重新启动应用。
Prometheus是一个最初由SoundCloud建设的开源监控和报警系统,目前已经是一个独立的开源项目,并且于2016年加入CNCF,成为CNCF的第二个项目。
APMPlus OpenTelemetry Collector是APMPlus基于OpenTelemetry Collector二次开发的数据采集器,遵守Apache2.0协议,支持采集OpenTelemetry监控数据,同时支持采集Prometheus指标,和K8s资源指标。
您可以使用Prometheus满足对于自定义打点的需求。对于已经集成了Prometheus的已有系统,可以将应用的自定义打点数据上报到APMPlus,进行指标存储、查询与展示,同时支持看板和报警等功能。
如果您的应用是基于Kubernetes集群部署,请参见以下步骤安装APMPlus数据采集器,接入APMPlus服务端。
安装APMPlus OpenTelemetry Collector。
进入接入中心,选择 Java语言 > Prometheus > 容器部署 ,获取如下配置。需要区分您的开服区域(region)与网络接入方式(network),appkey是用户的唯一标识。
kubectl apply -f "https://apmplus-dl-{region}.volces.com/server_warehouse/generate_assets/download/apmplus-opentelemetry-k8s/apmplus-opentelemetry-operator-v0.0.13.yaml?appkey={appkey}&network={network}&promReplicas=1"
说明
完整安装命令请到接入中心查看,详情请参见如何使用接入中心?。
配置应用,开启数据打点。
添加Java依赖。
<dependency> <groupId>io.prometheus</groupId> <artifactId>simpleclient</artifactId> <version>0.15.0</version> </dependency> <dependency> <groupId>io.prometheus</groupId> <artifactId>simpleclient_hotspot</artifactId> <version>0.15.0</version> </dependency> <dependency> <groupId>io.prometheus</groupId> <artifactId>simpleclient_httpserver</artifactId> <version>0.15.0</version> </dependency> <dependency> <groupId>io.prometheus</groupId> <artifactId>simpleclient_pushgateway</artifactId> <version>0.15.0</version> </dependency>
添加打点信息。详情请参见Instrumenting。
配置prometheus导出点。详情请参见Exporting。
在K8S场景下,通过配置pod annotation实现服务发现。
apiVersion: apps/v1 kind: Deployment ... spec: ... template: metadata: annotations: prometheus.io/path: /metrics # your path prometheus.io/port: "30002" # your port prometheus.io/scrape: "true"
重新启动应用。
如果您的应用是基于虚拟机或者物理机部署,请参见以下步骤安装APMPlus数据采集器,接入APMPlus服务端。
安装APMPlus OpenTelemetry Collector。
进入接入中心,选择 Java语言 > Prometheus > 主机部署 ,获取如下配置。需要区分您的开服区域(region)与网络接入方式(network),appkey是用户的唯一标识。
bash -c "$(curl -L 'http://apmplus-dl-{region}.ivolces.com/server_warehouse/generate_assets/download/apmplus-opentelemetry-ecs/install-otel_0.0.9.sh?appkey={appkey}&network={network}')"
说明
完整安装命令请到接入中心查看,详情请参见如何使用接入中心?。
配置应用,开启数据打点。
添加Java依赖。
<dependency> <groupId>io.prometheus</groupId> <artifactId>simpleclient</artifactId> <version>0.15.0</version> </dependency> <dependency> <groupId>io.prometheus</groupId> <artifactId>simpleclient_hotspot</artifactId> <version>0.15.0</version> </dependency> <dependency> <groupId>io.prometheus</groupId> <artifactId>simpleclient_httpserver</artifactId> <version>0.15.0</version> </dependency> <dependency> <groupId>io.prometheus</groupId> <artifactId>simpleclient_pushgateway</artifactId> <version>0.15.0</version> </dependency>
添加打点信息。详情请参见Instrumenting。
配置prometheus导出点。详情请参见Exporting。
在ECS场景下,支持通过文件进行服务发现,配置文件地址为/usr/local/apmplus-opentelemetry-collector/targets.json
。
[ { "targets": [ "localhost:8888" ] } ]
重新启动应用。
Jaeger是一款由Uber研发的开源分布式链路追踪系统。
对于已经集成Jaeger的已有系统,可以将jaeger的Trace数据上报到APMPlus,完成整体的全链路监控能力。
接入APMPlus后,您将获得RED指标生成能力、Trace多维检索、单链路检索、拓扑生成等多项能力。
SDK将数据上报到Agent,Agent将数据上报到APMPlus服务端。
修改jaeger-agent启动参数,配置如下:
./jaeger-agent --reporter.grpc.host-port=apmplus-{region}.ivolces.com:4317 \ --reporter.grpc.tls.enabled=false \ --agent.tags=app_key={appkey}
说明
完整配置命令请到接入中心查看,详情请参见如何使用接入中心?。
SDK采集数据,直接上报到APMPlus服务端。
配置reporter。示例代码如下所示:
io.jaegertracing.Configuration.SenderConfiguration sender = new io.jaegertracing.Configuration.SenderConfiguration(); sender.withEndpoint("http://apmplus-{region}.ivolces.com/server_collect/third_party/jaeger/v2/{appkey}/api/trace")
说明
完整配置命令请到接入中心查看,详情请参见如何使用接入中心?。
Zipkin是一款由Twitter开源的分布式链路追踪系统,通过Zipkin可以帮助您收集Trace数据。
对于已经集成Zipkin的系统,可以将已有的Trace数据上报到APMPlus,完成整体的全链路监控能力。
接入APMPlus后,您将获得RED指标生成能力、Trace多维检索、单链路检索、拓扑生成等多项APMPlus能力。
SDK采集数据,直接上报到APMPlus服务端。
获取zipkin上报点。
http://apmplus-{region}.ivolces.com/server_collect/third_party/zipkin/v2/{appkey}/api/v2/spans
说明
完整配置命令请到接入中心查看,详情请参见如何使用接入中心?。
接入服务并配置上报点。具体请参见zipkin示例代码。
SkyWalking Agent采集数据,直接上报到APMPlus服务端。当前支持SkyWalking Trace、Meter、Log、JVM、CLR数据接入。
配置应用,开启数据上报。
java -javaagent:path/to/skywalking-agent.jar -Dskywalking.collector.backend_service=apmplus-{region}.ivolces.com:4317 -Dskywalking.agent.authentication={appkey} -Dskywalking.agent.service_name={YOUR_SERVICE_NAME} -jar YOUR_SERVICE.jar
重新启动应用。
验证数据上报。