← 文章 / 云原生与基础设施
signoz 23天前 · 2026-10-30 13:04:33 · 17 阅读

JBoss 与 WildFly OpenTelemetry 配置指南

本指南将指导你如何为 JBoss EAP 或 WildFly 应用服务器集成 OpenTelemetry,并将 Trace 数据发送至 SigNoz。由于 JBoss 和 WildFly 使用 standalone.conf(Linux/Mac)或 standalone.conf.bat(Windows)来配置 JVM 选项,因此挂载 OpenTelemetry Java Agent 非常简单直接。

如果你使用的是自托管 SigNoz?

大部分步骤相同。要适配本指南,请更新 endpoint 并移除 ingest key 请求头,具体操作参见 云到自托管。

前置条件

将 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

添加以下行:

Copy
JAVA_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)
建议:为 Deployment Markers 设置 service.version

将 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 命令:

Copy
nohup /opt/jboss-eap-7.x/bin/standalone.sh &

查看日志:

Copy
tail -f /opt/jboss/nohup.out
DirectOTel Operator管理多个服务?

如果需要集中管理插桩,或想在不改代码的情况下自动注入,请查看 OTel Operator 标签页。

第 1 步:创建包含 agent 的 Dockerfile

Dockerfile
FROM 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

在部署清单中添加以下环境变量:

Copy
env:
- 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

将 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 配置。

为什么显式禁用 metrics 和 logs?

OpenTelemetry Java Agent 默认启用所有三种信号(traces、metrics 和 logs)。由于本指南专注于 traces,我们禁用了 metrics 和 logs,以避免向 Collector 发送不必要的数据。

如需后续收集指标或日志,请将相应的导出器更改为 otlp,或者直接移除该变量。

将此资源部署到集群中:

Copy
kubectl apply -f instrumentation.yaml

第 3 步. 在部署中添加注解

在 Pod 模板的 metadata.annotations 中添加以下注解:

deployment.yaml
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

应用该部署:

Copy
kubectl apply -f deployment.yaml

请确认以下值:

  • <service-name>:服务的描述性名称(例如 jboss-app)。
  • <service-version>(可选):您的发布版本、镜像标签或 git SHA(例如 1.4.2、a01dbef8)。
推荐:为部署标记设置 service.version

将 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 代理

Copy
Invoke-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

添加以下几行:

Copy
set "JAVA_OPTS=%JAVA_OPTS% -javaagent:C:\jboss\lib\opentelemetry-javaagent.jar"
set "JAVA_O
原始来源: signoz

评论 (0)