tencent cloud

Feedback

Connecting via Tencent Cloud OpenTelemetry Java Agent Enhanced Edition (Recommended)

Last updated: 2024-06-19 16:31:30
    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> <!-- Other 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() { // The scope is used for defining the Event Tracking range. In most cases, the class name can be directly used. For more information about Scope, see the OpenTelemetry official documentation. 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;
    
    // The Trace object can be obtained within business methods or passed into the business method as a parameter.
    public void doTask(Tracer tracer) {
    // Create a Span. Span span = tracer.spanBuilder("doTask").startSpan();
    // Add some Attributes to the Span.
    span.setAttribute("RequestId", "5fc92ff1-8ca8-45f4-8013-24b4b5257666"); // Set this Span as the current Span try (Scope scope = span.makeCurrent()) { doSubTask1(); doSubTask2(); } catch (Throwable t) {
    // Handle the exception. The exception information will be recorded in the corresponding event of the Span. span.recordException(t);
    span.setStatus(StatusCode.ERROR); throw t; } finally {
    // End the Span 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
    
    
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support