Tencent Cloud OpenTelemetry Java Agent Enhanced Edition is based on the OpenTelemetry-java-instrumentation from the open-source community and developed further under the Apache License 2.0 protocol. It includes a reference to the OpenTelemetry License within the agent packet. Building on the open source agent, the Tencent Cloud OpenTelemetry Java Agent Enhanced Edition has significantly improved in Event Tracking density, advanced diagnosis, performance protection, and enterprise-level capabilities.
Note:
OpenTelemetry is a collection of tools, APIs, and SDKs for monitoring, generating, collecting, and exporting telemetry data (metrics, logs, and traces) to help users analyze the performance and behavior of the software. For more information about OpenTelemetry, see the OpenTelemetry official website. The OpenTelemetry community is active, with rapid technological changes, and widely compatible with mainstream programming languages, components, and frameworks, making its link-tracing capability highly popular for cloud-native microservices and container architectures.
This document will guide you on how to connect Java applications with the Tencent Cloud OpenTelemetry Agent Enhanced Edition using related operations.
Prerequisites
See Supported Java Versions and Frameworks by OTel Java Agent Enhanced Edition to ensure that your Java version and application server are within the supported range of the agent. For dependency libraries and frameworks supported by automatic Event Tracking, data reporting can be completed upon successful connection without modifying the code. In addition, the Tencent Cloud OpenTelemetry Java Agent Enhanced Edition complies with the OpenTelemetry protocol standards. If automatic Event Tracking does not meet your scenario, or you need to add business layer Event Tracking, see Custom Event Tracking and use the OpenTelemetry API for custom Event Tracking. Step 1. Get the connect point and Token.
1. Log in to the TCOP console. 2. In the left menu column, select Application Performance Management > Application monitoring, and click Application list > Access application.
3. In the Data Access drawer that appears on the right, click Java language.
4. On the Access Java application page, select the region and business system you want to connect.
5. Select Access protocol type as OpenTelemetry.
6. Reporting method Choose your desired reporting method, and obtain your Access Point and Token.
Note:
Private network reporting: Using this reporting method, your service needs to run in the Tencent Cloud VPC. Through VPC connecting directly, you can avoid the security risks of public network communication and save on reporting traffic overhead.
Public network reporting: If your service is deployed locally or in non-Tencent Cloud VPC, you can report data in this method. However, it involves security risks in public network communication and incurs reporting traffic fees.
Step 2: Download the agent.
Go to Agent Version Information to download the agent, it is recommended to download the latest version, named opentelemetry-javaagent.jar
. Step 3: Modify the reporting parameters.
Connecting Java applications requires the following 3 JVM startup parameters:
-javaagent:<javaagent>
-Dotel.resource.attributes=service.name=<serviceName>,token=<token>
-Dotel.exporter.otlp.endpoint=<endpoint>
When you execute the Java command, ensure these 3 JVM startup parameters are placed before the -jar
. For applications that cannot directly specify JVM startup parameters, the system parameter -Dotel.resource.attributes
can be replaced with the environment variable OTEL_RESOURCE_ATTRIBUTES
, and the system parameter -Dotel.exporter.otlp.endpoint
can be replaced with the environment variable OTEL_EXPORTER_OTLP_ENDPOINT
. The corresponding fields are explained as follows:
<javaagent>
: the local file path of the agent.
<serviceName>
: Application name. Processes of connecting using the same application name are displayed as multiple instances under the same application in APM. For Spring Cloud or Dubbo applications, the application name usually matches the service name. It can be up to 63 characters and can only contain lowercase letters, digits, and the separator (-), and it must start with a lowercase letter and end with a digit or lowercase letter.
<token>
: the business system Token obtained in step 1.
<endpoint>
: the connect point obtained in step 1.
The following content uses the agent path /path/to/opentelemetry-javaagent.jar
, the application name myService
, the business system Token myToken, and the connect point http://pl-demo.ap-guangzhou.apm.tencentcs.com:4317
as examples to introduce the complete start-up scripts for different environments:
JAR File or Spring Boot
java -javaagent:/path/to/opentelemetry-javaagent.jar
\\
-Dotel.resource.attributes=service.name=myService
,token=myToken\\
-Dotel.exporter.otlp.endpoint=http://pl-demo.ap-guangzhou.apm.tencentcs.com:4317 \\
-jar SpringCloudApplication.jar
Linux Tomcat 7/Tomcat 8
Add the following content to the {TOMCAT_HOME}/bin/setenv.sh
configuration file:
CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/opentelemetry-javaagent.jar"
export OTEL_RESOURCE_ATTRIBUTES=service.name=myService
,token=myToken
export OTEL_EXPORTER_OTLP_ENDPOINT=http://pl-demo.ap-guangzhou.apm.tencentcs.com:4317
If your Tomcat does not have a setenv.sh configuration file, see the Tomcat official documentation to initialize a setenv.sh configuration file, or use another method to add Java start-up parameters and environment variables. Jetty
Add the following content in the <jetty_home\\>/bin/jetty.sh
start-up script:
JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:/path/to/opentelemetry-javaagent.jar"
export OTEL_RESOURCE_ATTRIBUTES=service.name=myService
,token=myToken
export OTEL_EXPORTER_OTLP_ENDPOINT=http://pl-demo.ap-guangzhou.apm.tencentcs.com:4317
IDEA
When you debug Java applications locally in IDEA, you can configure VM options in the Run Configuration, with parameters as follows:
-javaagent:"/path/to/opentelemetry-javaagent.jar"
-Dotel.resource.attributes=service.name=myService
,token=myToken
-Dotel.exporter.otlp.endpoint=http://pl-demo.ap-guangzhou.apm.tencentcs.com:4317
In this case, ensure network connectivity between the local environment and the connect point. Usually, the public network connect point address can be used for reporting.
Other application servers
See the corresponding configuration standards to mount the agent, and add Java start-up parameters or environment variables.
Connection Verification
After the 3 connect steps are completed, start the Java application. The application will mount the agent and connect to the APM server to report monitoring data. In normal traffic cases, the connected applications will be displayed in the console APM > Application monitoring > Application list , and the connected application instances will be displayed in the console Application details > Instance monitoring. Due to the delay in processing observable data, if the application or instance is not found in the console after connecting, wait for about 30 seconds. Custom Event Tracking (Optional)
When automatic Event Tracking does not meet your scenario, or you need to add business layer Event Tracking, you can see the following content and use the OpenTelemetry API to add custom Event Tracking. This document only showcases the most basic way of custom Event Tracking, and the OpenTelemetry community provides more flexible ways of custom Event Tracking. For specific usage, you can see the OpenTelemetry official documentation. Introducing OpenTelemetry API Dependencies
<dependencies>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-api</artifactId>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-bom</artifactId>
<version>1.9.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Obtaining Tracer
In the code where Event Tracking needs to be implemented, the Tracer object can be obtained with the following code:
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Tracer;
public class AcquireTracerDemo {
public void acquireTracer() {
String scope = this.getClass().getName();
OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();
Tracer tracer = openTelemetry.getTracer(scope);
}
}
Performing Event Tracking for Business Methods
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Scope;
public void doTask(Tracer tracer) {
Span span = tracer.spanBuilder("doTask").startSpan();
span.setAttribute("RequestId", "5fc92ff1-8ca8-45f4-8013-24b4b5257666");
try (Scope scope = span.makeCurrent()) {
doSubTask1();
doSubTask2();
} catch (Throwable t) {
span.recordException(t);
span.setStatus(StatusCode.ERROR);
throw t;
} finally {
span.end();
}
}
Viewing the Results of Custom Event Tracking
In APM > call query, find the related call chain, and click the Span ID to enter the End-to-End Details page, where you can find the newly added Span through custom Event Tracking. Custom Instance Name (Optional)
When multiple application processes connect APM using the same application name, they are displayed in APM as multiple instances under the same application. In most scenarios, the IP address can serve as a unique identifier for the application instance. However, if there are duplicate IP addresses in the system, other unique identifiers need to be used to define the instance name. For example, if the application in the system is launched directly through Docker, without being deployed on Kubernetes, there might be cases of duplicate container IP addresses. Users can set the instance name in the form of host IP + container IP
.
See the following script and add the host.name
field to the JVM startup parameters required for connecting APM with -Dotel.resource.attributes
.
-Dotel.resource.attributes=service.name=my_service,token=my_demo_token,host.name=10.10.1.1_192.168.1.2
Was this page helpful?