# OpenTelemetry cho Java (Java agent)

> Gắn OpenTelemetry Java agent bằng -javaagent, không sửa code: HTTP server/client, JDBC, log java.util.logging/Logback/Log4j; Spring Boot và container.

OpenTelemetry Java agent gắn instrumentation cho app JVM mà không sửa code: HTTP server và client (Servlet, Spring MVC và WebFlux, JAX-RS, `HttpServer` và `HttpClient` có sẵn của JDK, OkHttp, …), JDBC, client hàng đợi tin nhắn và các thư viện log phổ biến. Agent đọc [bộ biến chuẩn](https://belvador.dev/vi/docs/otel/quickstart#2-dat-cac-bien-chuan) — giao thức mặc định của nó đã là `http/protobuf`.

> **Đã kiểm ngày 2026-10-24** với java 21.0.12.1, opentelemetry-javaagent 2.32.0: traces đạt, logs đạt, log mang trace/span của request.

## Gắn agent

```bash
curl -fsSLO https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
java -javaagent:./opentelemetry-javaagent.jar -jar app.jar
```

`latest` đi theo bản mới nhất; ở production, hãy tải một phiên bản cố định từ [trang phát hành](https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases) và giữ cùng bản build, để không lần deploy nào bất ngờ đổi agent.

- Chạy app đã biên dịch (`-jar`, hoặc `-cp … Main`). Agent từ chối khởi động bên trong công cụ của JDK, kể cả khi chạy thẳng file nguồn bằng `java App.java`.
- **Spring Boot:** cùng cờ `-javaagent` đặt trước `-jar app.jar`.
- **Container và PaaS:** khi không đổi được lệnh chạy, đặt `JAVA_TOOL_OPTIONS="-javaagent:/path/to/opentelemetry-javaagent.jar"`; JVM tự nhận khi khởi động.

## Logs

Agent thu bản ghi của `java.util.logging`, Logback và Log4j 2 và gửi thành bản ghi log OpenTelemetry mang trace ID và span ID đang chạy; appender của bạn vẫn ghi như cũ. Lần chạy của Belvador dùng `java.util.logging`; Logback và Log4j 2 đi qua cùng cơ chế của agent nhưng không nằm trong phần đã kiểm.

## Tắt bớt instrumentation

Mỗi instrumentation có một công tắc, ví dụ:

```bash
export OTEL_INSTRUMENTATION_JDBC_ENABLED=false
```

## Cùng SDK Java của Sentry

Giữ SDK Sentry cho lỗi và tắt tracing của nó, để agent là [bên duy nhất làm chủ tracing](https://belvador.dev/vi/docs/otel/overview#chi-mot-ben-lam-chu-tracing). Event processor của `sentry-opentelemetry-otlp` gắn ID span của agent vào các lỗi đó — xem [Cùng SDK Sentry](https://belvador.dev/vi/docs/otel/sentry-coexistence#java-sentry-java); liên kết đó chưa được ghi là đã kiểm.