JBoss 与 WildFly OpenTelemetry 配置指南
本指南将指导你如何为 JBoss EAP 或 WildFly 应用服务器集成 OpenTelemetry,并将 Trace 数据发送至 SigNoz。由于 JBoss 和 WildFly 使用 standalone.conf(Linux/Mac)或 standalone.conf.bat(Windows)来配置 JVM 选项,因此挂载 OpenTelemetry Java Agent 非常简单直接。
大部分步骤相同。要适配本指南,请更新 endpoint 并移除 ingest key 请求头,具体操作参见 云到自托管。
前置条件
- Java 8 及以上版本
- 支持的 WildFly 版本 或兼容的 JBoss EAP
- SigNoz Cloud 账户或自托管 SigNoz 实例
将 Trace 发送至 SigNoz
VMKubernetesWindowsDocker什么算作虚拟机?虚拟机(VM)是运行在物理硬件上的虚拟计算机。包括:
- 云虚拟机:AWS EC2、Google Compute Engine、Azure VM、DigitalOcean Droplets
- 本地虚拟机:VMware、VirtualBox、Hyper-V、KVM
- 裸金属服务器:直接运行 Linux/Unix 的物理服务器
如果你直接在服务器或虚拟机上部署 JBoss/WildFly 且未使用容器化技术,请使用此章节。
步骤 1. 下载 OpenTelemetry Java Agent
复制wget -P /opt/jboss/lib/ https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar步骤 2. 编辑 standalone.conf
打开你的 JBoss/WildFly 配置文件:
- JBoss EAP:
/opt/jboss-eap-7.x/bin/standalone.conf - WildFly:
/opt/wildfly/bin/standalone.conf
添加以下行:
CopyJAVA_OPTS="$JAVA_OPTS -javaagent:/opt/jboss/lib/opentelemetry-javaagent.jar"
JAVA_OPTS="$JAVA_OPTS -Dotel.service.name=<service-name>"
JAVA_OPTS="$JAVA_OPTS -Dotel.resource.attributes=service.version=<service-version>"
JAVA_OPTS="$JAVA_OPTS -Dotel.exporter.otlp.endpoint=https://ingest.<region>.signoz.cloud:443"
JAVA_OPTS="$JAVA_OPTS -Dotel.exporter.otlp.headers=signoz-ingestion-key=<your-ingestion-key>"
JAVA_OPTS="$JAVA_OPTS -Dotel.metrics.exporter=none"
JAVA_OPTS="$JAVA_OPTS -Dotel.logs.exporter=none"为何要显式禁用 Metrics 和 Logs?
OpenTelemetry Java agent 默认会启用全部三种信号(Traces、Metrics 和 Logs)。由于本指南专注于 Traces,我们禁用了 Metrics 和 Logs,以避免向 SigNoz 发送无用数据。
如果日后需要收集 Metrics 或 Logs,可将对应的 exporter 改为 otlp,或直接删除该行。
请核对以下参数值:
<region>:您的 SigNoz Cloud 区域<your-ingestion-key>:您的 SigNoz Ingestion Key<service-name>:服务描述性名称(如jboss-app)<service-version>(可选):发布版本、镜像标签或 git SHA(如1.4.2、a01dbef8)
将 service.version 设为每次构建的动态值,而非静态字符串。每当该值发生变化时,SigNoz 即会识别为一次部署。常见来源包括:
- Bash / shell:
service.version=$(git rev-parse --short HEAD) - GitHub Actions:
service.version=${{ github.sha }} - GitLab CI:
service.version=$CI_COMMIT_SHORT_SHA - Kubernetes:从 Helm Chart 镜像标签或 CI 变量中注入
步骤 3:重启 JBoss/WildFly
Copy# For JBoss EAP
/opt/jboss-eap-7.x/bin/standalone.sh
# For WildFly
/opt/wildfly/bin/standalone.sh
以后台模式运行
若要后台运行 JBoss/WildFly 并记录日志:
Copy/opt/jboss-eap-7.x/bin/standalone.sh > /opt/jboss/nohup.out 2>&1 &
或使用 nohup 命令:
nohup /opt/jboss-eap-7.x/bin/standalone.sh &查看日志:
Copytail -f /opt/jboss/nohup.outDirectOTel Operator管理多个服务?如果需要集中管理插桩,或想在不改代码的情况下自动注入,请查看 OTel Operator 标签页。
第 1 步:创建包含 agent 的 Dockerfile
DockerfileFROM jboss/wildfly:latest
WORKDIR /opt/jboss
# Download the OpenTelemetry Java agent
RUN curl -L https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar -o /opt/jboss/opentelemetry-javaagent.jar
# Copy your application
COPY target/<my-app>.war /opt/jboss/wildfly/standalone/deployments/
# Set JAVA_OPTS for OpenTelemetry
ENV JAVA_OPTS="-javaagent:/opt/jboss/opentelemetry-javaagent.jar"
EXPOSE 8080
CMD ["/opt/jboss/wildfly/bin/standalone.sh", "-b", "0.0.0.0"]将 <my-app>.war 替换为你的应用 WAR 文件。
第 2 步:部署到 Kubernetes
在部署清单中添加以下环境变量:
Copyenv:
- name: OTEL_RESOURCE_ATTRIBUTES
value: 'service.name=<service-name>,service.version=<service-version>'
- name: OTEL_EXPORTER_OTLP_ENDPOINT
value: 'https://ingest.<region>.signoz.cloud:443'
- name: OTEL_EXPORTER_OTLP_HEADERS
value: 'signoz-ingestion-key=<your-ingestion-key>'
- name: OTEL_METRICS_EXPORTER
value: 'none'
- name: OTEL_LOGS_EXPORTER
value: 'none'为什么要显式禁用 metrics 和 logs?OpenTelemetry Java agent 默认开启全部三种信号(traces、metrics 和 logs)。由于本指南只关注 traces,禁用 metrics 和 logs 可以避免向 SigNoz 发送不必要的数据。
之后如果想采集 metrics 或 logs,把对应的 exporter 改为 otlp,或直接删除该变量即可。
请确认以下值:
<region>:你的 SigNoz Cloud 区域<your-ingestion-key>:你的 SigNoz ingestion key。<service-name>:服务的描述性名称(例如jboss-app)。<service-version>(可选):发布版本、镜像标签或 Git SHA(例如1.4.2、a01dbef8)。
将 service.version 设置为每次构建的动态值,而非静态字符串。每次该值变更时,SigNoz 都会检测到一次新部署。常见来源:
- Bash / shell:
service.version=$(git rev-parse --short HEAD) - GitHub Actions:
service.version=${{ github.sha }} - GitLab CI:
service.version=$CI_COMMIT_SHORT_SHA - Kubernetes:从 Helm chart 镜像标签或 CI 变量中注入
OpenTelemetry Operator 会自动将 Java Agent 注入到你的 Pod 中,无需修改容器镜像。
步骤 1:安装 OpenTelemetry Operator
按照K8s OTel Operator 安装指南安装 Operator 和 Collector。
步骤 2:创建 Instrumentation 资源
创建 instrumentation.yaml 以配置 Java 自动埋点:
instrumentation.yaml
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
name: java-instrumentation
spec:
exporter:
endpoint: http://<collector-service>:4318
propagators:
- tracecontext
- baggage
env:
- name: OTEL_METRICS_EXPORTER
value: "none"
- name: OTEL_LOGS_EXPORTER
value: "none"
java:
image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:latest
将 <collector-service> 替换为接收应用遥测数据的 Collector Service 地址。如果你是通过 OpenTelemetry Operator 指南安装 Collection Agent 的,请参见从应用向 Collector 发送数据以获取其 Service 配置。
OpenTelemetry Java Agent 默认启用所有三种信号(traces、metrics 和 logs)。由于本指南专注于 traces,我们禁用了 metrics 和 logs,以避免向 Collector 发送不必要的数据。
如需后续收集指标或日志,请将相应的导出器更改为 otlp,或者直接移除该变量。
将此资源部署到集群中:
Copykubectl apply -f instrumentation.yaml第 3 步. 在部署中添加注解
在 Pod 模板的 metadata.annotations 中添加以下注解:
apiVersion: apps/v1
kind: Deployment
metadata:
name: jboss-app
spec:
replicas: 1
selector:
matchLabels:
app: jboss-app
template:
metadata:
labels:
app: jboss-app
annotations:
instrumentation.opentelemetry.io/inject-java: "true"
resource.opentelemetry.io/service.name: "<service-name>"
resource.opentelemetry.io/service.version: "<service-version>"
spec:
containers:
- name: jboss
image: jboss/wildfly:latest
ports:
- containerPort: 8080应用该部署:
Copykubectl apply -f deployment.yaml请确认以下值:
<service-name>:服务的描述性名称(例如jboss-app)。<service-version>(可选):您的发布版本、镜像标签或 git SHA(例如1.4.2、a01dbef8)。
将 service.version 设置为每次构建特有的值,而非静态字符串。SigNoz 会在该值每次变化时检测一次部署。常见取值来源:
- Bash / shell:
service.version=$(git rev-parse --short HEAD) - GitHub Actions:
service.version=${{ github.sha }} - GitLab CI:
service.version=$CI_COMMIT_SHORT_SHA - Kubernetes:从 Helm chart 的镜像标签或 CI 变量注入
第 1 步. 下载 OpenTelemetry Java 代理
CopyInvoke-WebRequest -Uri "https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar" -OutFile "C:\jboss\lib\opentelemetry-javaagent.jar"第 2 步. 编辑 standalone.conf.bat
打开您的 JBoss/WildFly 配置文件:
- JBoss EAP:
C:\jboss-eap-7.x\bin\standalone.conf.bat - WildFly:
C:\wildfly\bin\standalone.conf.bat
添加以下几行:
Copyset "JAVA_OPTS=%JAVA_OPTS% -javaagent:C:\jboss\lib\opentelemetry-javaagent.jar"
set "JAVA_O