Managed Service for OpenTelemetry, Java uygulamalarından izleme verilerini toplar; uygulama topolojisi, izlemeler, anormal ve yavaş işlem analizi ile SQL analizi sunar. Sıfır kodlu aracı kurulumundan tam SDK kontrolüne kadar üç farklı enstrümantasyon yaklaşımı mevcuttur.
| Yaklaşım | Çaba | Ne zaman kullanılır |
|---|---|---|
| OpenTelemetry Java aracı (önerilen) | Minimal -- bir JAR dosyası ekleyin, kod değişikliği gerekmez | Çoğu uygulama için uygundur. Buradan başlayın. |
| Java için OpenTelemetry SDK | Orta düzey -- enstrümantasyon kodu yazmanız gerekir | Özel span'ler, nitelikler veya desteklenmeyen çerçeveler |
| Aracı + SDK birleşimi | Orta düzey -- aracı temel işlemleri halleder, SDK özel span'ler ekler | Otomatik kapsama alanına ek olarak hedefe yönelik özel enstrümantasyon |
Örnek kod
Çalışan bir referans için örnek projeyi klonlayın veya göz atın:
git clone https://github.com/alibabacloud-observability/java-demo.git
cd java-demo/opentelemetry-demoYöntem 1: OpenTelemetry Java aracı ile otomatik enstrümantasyon
OpenTelemetry Java aracı, JVM'nize başlangıçta bağlanır ve herhangi bir kod değişikliği gerektirmeden yüzlerce kitaplığı ve çerçeveyi enstrümante eder. Bu, çoğu uygulama için önerilen başlangıç noktasıdır.
Adım 1: Aracıyı indirin
En son aracı JAR dosyasını GitHub Releases sayfasından indirin:
# wget
wget -O opentelemetry-javaagent.jar \
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
# or curl
curl -Lo opentelemetry-javaagent.jar \
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jarAdım 2: JVM parametrelerini yapılandırın ve uygulamayı başlatın
-javaagent bayrağını -jar bağımsız değişkeninden önce ekleyin. HTTP veya gRPC protokolünden birini seçin.
HTTP
java -javaagent:/path/to/opentelemetry-javaagent.jar \
-Dotel.resource.attributes=service.name=<your-service-name>,service.version=<your-version>,deployment.environment=<your-env> \
-Dotel.exporter.otlp.protocol=http/protobuf \
-Dotel.exporter.otlp.traces.endpoint=<traces-endpoint> \
-Dotel.exporter.otlp.metrics.endpoint=<metrics-endpoint> \
-Dotel.logs.exporter=none \
-jar /path/to/your/app.jarYer tutucuları gerçek değerlerinizle değiştirin:
| Yer tutucu | Açıklama | Örnek |
|---|---|---|
<your-service-name> |
Uygulamanızı tanımlayan bir ad | order-service |
<your-version> |
Uygulama sürümü | 1.0.0 |
<your-env> |
Dağıtım ortamı | production |
<traces-endpoint> |
Ön koşullar bölümündeki izleme uç noktası | http://tracing-analysis-dc-hz-internal.aliyuncs.com/adapt_ggxw4l****@7323a5caae3****_ggxw4l****@53df7ad2afe****/api/otlp/traces |
<metrics-endpoint> |
Ön koşullar bölümündeki ölçüm uç noktası | http://tracing-analysis-dc-hz-internal.aliyuncs.com/adapt_ggxw4l****@7323a5caae3****_ggxw4l****@53df7ad2afe****/api/otlp/metrics |
Örnek:
java -javaagent:/path/to/opentelemetry-javaagent.jar \
-Dotel.resource.attributes=service.name=order-service,service.version=1.0.0,deployment.environment=production \
-Dotel.exporter.otlp.protocol=http/protobuf \
-Dotel.exporter.otlp.traces.endpoint=http://tracing-analysis-dc-hz-internal.aliyuncs.com/adapt_ggxw4l****@7323a5caae3****_ggxw4l****@53df7ad2afe****/api/otlp/traces \
-Dotel.exporter.otlp.metrics.endpoint=http://tracing-analysis-dc-hz-internal.aliyuncs.com/adapt_ggxw4l****@7323a5caae3****_ggxw4l****@53df7ad2afe****/api/otlp/metrics \
-Dotel.logs.exporter=none \
-jar /path/to/your/app.jargRPC
java -javaagent:/path/to/opentelemetry-javaagent.jar \
-Dotel.resource.attributes=service.name=<your-service-name>,service.version=<your-version>,deployment.environment=<your-env> \
-Dotel.exporter.otlp.protocol=grpc \
-Dotel.exporter.otlp.headers=Authentication=<token> \
-Dotel.exporter.otlp.endpoint=<endpoint> \
-Dotel.logs.exporter=none \
-jar /path/to/your/app.jarYer tutucuları gerçek değerlerinizle değiştirin:
| Yer tutucu | Açıklama | Örnek |
|---|---|---|
<token> |
Ön koşullar bölümündeki kimlik doğrulama belirteci | ggxw4l****@7323a5caae3****_ggxw4l****@53df7ad2afe**** |
<endpoint> |
Ön koşullar bölümündeki gRPC uç noktası | http://tracing-analysis-dc-hz-internal.aliyuncs.com:8090 |
Örnek:
java -javaagent:/path/to/opentelemetry-javaagent.jar \
-Dotel.resource.attributes=service.name=order-service,service.version=1.0.0,deployment.environment=production \
-Dotel.exporter.otlp.protocol=grpc \
-Dotel.exporter.otlp.headers=Authentication=ggxw4l****@7323a5caae3****_ggxw4l****@53df7ad2afe**** \
-Dotel.exporter.otlp.endpoint=http://tracing-analysis-dc-hz-internal.aliyuncs.com:8090 \
-Dotel.logs.exporter=none \
-jar /path/to/your/app.jarİzleme verilerini bir OpenTelemetry Collector üzerinden iletmek için-Dotel.exporter.otlp.headers=Authentication=<token>satırını kaldırın ve<endpoint>değerini yerel makinenizdeki Collector adresine ayarlayın.
Adım 3: İzleme verilerini doğrulayın
Applications sayfasında uygulama adınıza tıklayın.
Uygulama ayrıntıları sayfasında izlemelerin göründüğünü onaylayın.
Sorun giderme:
Veri görünmüyorsa uç nokta ve belirtecin doğru olduğunu doğrulayın.
-
Aracı davranışını incelemek için hata ayıklama günlüğünü etkinleştirin:
-Dotel.javaagent.debug=true -
Aracıyı başlangıç komutundan kaldırmadan geçici olarak devre dışı bırakın:
-Dotel.javaagent.enabled=false
Yöntem 2: Java için OpenTelemetry SDK ile manuel enstrümantasyon
Hangi işlemlerin span üreteceği ve hangi nitelikleri taşıyacağı üzerinde tam kontrole ihtiyacınız olduğunda veya otomatik aracı çerçevenizi kapsamadığında Java için OpenTelemetry SDK kullanın.
Adım 1: Maven bağımlılıklarını ekleyin
Aşağıdakileri pom.xml dosyanıza ekleyin:
<dependencies>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-api</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk-trace</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-semconv</artifactId>
<version>1.30.0-alpha</version>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-bom</artifactId>
<version>1.30.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>Adım 2: İzleyiciyi başlatın
Dışa aktarıcıyı, kaynak niteliklerini ve izleyiciyi yapılandıran bir yardımcı sınıf oluşturun. Ortamınıza uygun protokolü seçin.
HTTP
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator;
import io.opentelemetry.context.propagation.ContextPropagators;
import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.semconv.resource.attributes.ResourceAttributes;
public class OpenTelemetrySupport {
static {
// Define the resource that describes this service
Resource resource = Resource.getDefault()
.merge(Resource.create(Attributes.of(
ResourceAttributes.SERVICE_NAME, "<your-service-name>",
ResourceAttributes.SERVICE_VERSION, "<your-version>",
ResourceAttributes.DEPLOYMENT_ENVIRONMENT, "<your-env>",
ResourceAttributes.HOST_NAME, "<your-host-name>"
)));
// Build a tracer provider with the OTLP HTTP exporter
SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
.addSpanProcessor(BatchSpanProcessor.builder(OtlpHttpSpanExporter.builder()
.setEndpoint("<endpoint>") // Trace endpoint from the Prerequisites section
.build()).build())
.setResource(resource)
.build();
// Register the SDK globally
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
.setTracerProvider(sdkTracerProvider)
.setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
.buildAndRegisterGlobal();
tracer = openTelemetry.getTracer("OpenTelemetry Tracer", "1.0.0");
}
private static Tracer tracer;
public static Tracer getTracer() {
return tracer;
}
}gRPC
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator;
import io.opentelemetry.context.propagation.ContextPropagators;
import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.semconv.resource.attributes.ResourceAttributes;
public class OpenTelemetrySupport {
static {
// Define the resource that describes this service
Resource resource = Resource.getDefault()
.merge(Resource.create(Attributes.of(
ResourceAttributes.SERVICE_NAME, "<your-service-name>",
ResourceAttributes.SERVICE_VERSION, "<your-version>",
ResourceAttributes.DEPLOYMENT_ENVIRONMENT, "<your-env>",
ResourceAttributes.HOST_NAME, "<your-host-name>"
)));
// Build a tracer provider with the OTLP gRPC exporter
SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
.addSpanProcessor(BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder()
.setEndpoint("<endpoint>") // gRPC endpoint from the Prerequisites section
.addHeader("Authentication", "<token>") // Authentication token from the Prerequisites section
.build()).build())
.setResource(resource)
.build();
// Register the SDK globally
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
.setTracerProvider(sdkTracerProvider)
.setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
.buildAndRegisterGlobal();
tracer = openTelemetry.getTracer("OpenTelemetry Tracer", "1.0.0");
}
private static Tracer tracer;
public static Tracer getTracer() {
return tracer;
}
}Adım 3: Span'ler oluşturun
Üst ve alt span'ler oluşturmak için izleyiciyi kullanın. Her span, ilgili nitelikler ve hata durumuyla birlikte bir iş birimini yakalar.
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.context.Scope;
public class Main {
public static void parentMethod() {
// Start a parent span
Span span = OpenTelemetrySupport.getTracer().spanBuilder("parent span").startSpan();
try (Scope scope = span.makeCurrent()) {
span.setAttribute("good", "job");
childMethod();
} catch (Throwable t) {
span.setStatus(StatusCode.ERROR, "handle parent span error");
} finally {
span.end();
}
}
public static void childMethod() {
// Start a child span -- automatically linked to the parent through Context
Span span = OpenTelemetrySupport.getTracer().spanBuilder("child span").startSpan();
try (Scope scope = span.makeCurrent()) {
span.setAttribute("hello", "world");
} catch (Throwable t) {
span.setStatus(StatusCode.ERROR, "handle child span error");
} finally {
span.end();
}
}
public static void main(String[] args) {
parentMethod();
}
}Adım 4: Uygulamayı başlatın ve doğrulayın
Uygulamayı başlatın, ardından Managed Service for OpenTelemetry konsolunu açın. Applications sayfasında uygulama adınıza tıklayın ve izlemelerin göründüğünü onaylayın.
Yöntem 3: Java aracısını SDK ile birleştirin
Geniş otomatik kapsama alanı için aracıyı, hedefe yönelik özel span'ler için SDK'yı kullanın. Aracı, opentelemetry-sdk-extension-autoconfigure bağımlılığı aracılığıyla SDK'yı başlangıçta otomatik olarak yapılandırır; bu nedenle Yöntem 2'deki OpenTelemetrySupport yardımcı sınıfına ihtiyacınız yoktur.
Adım 1: Aracıyı indirin
Yöntem 1, Adım 1 bölümünde açıklandığı gibi OpenTelemetry Java aracısını indirin.
Adım 2: Maven bağımlılıklarını ekleyin
Yöntem 2, Adım 1 bölümündeki bağımlılıklara ek olarak aşağıdakileri ekleyin:
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-extension-annotations</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk-extension-autoconfigure</artifactId>
<version>1.23.0-alpha</version>
</dependency> opentelemetry-sdk-extension-autoconfigure bağımlılığı, aracı ayarlarını otomatik olarak SDK'ya aktarır; bu nedenle dışa aktarıcıyı veya kaynak niteliklerini kodda yapılandırmanız gerekmez.
Adım 3: Bir izleyici edinin
Aracı SDK başlatma işlemini hallettiğinden genel izleyiciyi doğrudan edinin:
OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();
Tracer tracer = openTelemetry.getTracer("instrumentation-library-name", "1.0.0");Adım 4: Özel enstrümantasyon ekleyin
Aracının üzerine enstrümantasyon eklemek için üç teknik:
Teknik 1: Otomatik oluşturulan bir span'e nitelik ekleyin
İş niteliklerini eklemek için zaten enstrümante edilmiş bir yöntem içinde Span.current() çağrısı yapın:
@RequestMapping("/async")
public String async() {
Span span = Span.current();
span.setAttribute("user.id", "123456");
userService.async();
child("vip");
return "async";
}Teknik 2: Ek tabanlı enstrümantasyon için @WithSpan kullanın
Bir span'i otomatik olarak oluşturmak için bir yöntemi @WithSpan ile işaretleyin. Parametreleri kaydetmek için @SpanAttribute kullanın:
@WithSpan
private void child(@SpanAttribute("user.type") String userType) {
System.out.println(userType);
biz();
}Teknik 3: Bir izleyici ile span'leri manuel olarak oluşturun
Tam kontrol için span'leri izleyici API'si ile oluşturun. Bu örnek ayrıca bağlamı eşzamanlı olmayan bir iş parçacığına yaymaktadır:
private void biz() {
Tracer tracer = GlobalOpenTelemetry.get().getTracer("tracer");
Span span = tracer.spanBuilder("biz (manual)")
.setParent(Context.current().with(Span.current())) // optional -- set automatically
.startSpan();
try (Scope scope = span.makeCurrent()) {
span.setAttribute("biz-id", "111");
// Propagate context into an async task
es.submit(() -> {
Span asyncSpan = tracer.spanBuilder("async")
.setParent(Context.current().with(span))
.startSpan();
try {
Thread.sleep(1000L); // simulate async work
} catch (Throwable e) {
// handle error
}
asyncSpan.end();
});
Thread.sleep(1000); // simulate business logic
} catch (Throwable t) {
span.setStatus(StatusCode.ERROR, "handle biz error");
} finally {
span.end();
}
}Tam denetleyici ve hizmet kodu
Denetleyici (com.alibaba.arms.brightroar.console.controller):
package com.alibaba.arms.brightroar.console.controller;
import com.alibaba.arms.brightroar.console.service.UserService;
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;
import io.opentelemetry.context.Scope;
import io.opentelemetry.extension.annotations.SpanAttribute;
import io.opentelemetry.extension.annotations.WithSpan;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
@RestController
@RequestMapping("/user")
public class UserController {
@Autowired
private UserService userService;
private ExecutorService es = Executors.newFixedThreadPool(5);
// Technique 1: Add attributes to an auto-created span
@RequestMapping("/async")
public String async() {
System.out.println("UserController.async -- " + Thread.currentThread().getId());
Span span = Span.current();
span.setAttribute("user.id", "123456");
userService.async();
child("vip");
return "async";
}
// Technique 2: Annotation-based instrumentation
@WithSpan
private void child(@SpanAttribute("user.type") String userType) {
System.out.println(userType);
biz();
}
// Technique 3: Manual span creation
private void biz() {
Tracer tracer = GlobalOpenTelemetry.get().getTracer("tracer");
Span span = tracer.spanBuilder("biz (manual)")
.setParent(Context.current().with(Span.current()))
.startSpan();
try (Scope scope = span.makeCurrent()) {
span.setAttribute("biz-id", "111");
es.submit(new Runnable() {
@Override
public void run() {
Span asyncSpan = tracer.spanBuilder("async")
.setParent(Context.current().with(span))
.startSpan();
try {
Thread.sleep(1000L); // simulate async work
} catch (Throwable e) {
}
asyncSpan.end();
}
});
Thread.sleep(1000); // simulate business logic
System.out.println("biz done");
OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();
openTelemetry.getPropagators();
} catch (Throwable t) {
span.setStatus(StatusCode.ERROR, "handle biz error");
} finally {
span.end();
}
}
}Hizmet (com.alibaba.arms.brightroar.console.service):
package com.alibaba.arms.brightroar.console.service;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;
@Service
public class UserService {
@Async
public void async() {
System.out.println("UserService.async -- " + Thread.currentThread().getId());
System.out.println("my name is async");
System.out.println("UserService.async -- ");
}
}Adım 5: JVM parametrelerini yapılandırın ve uygulamayı başlatın
java -javaagent:/path/to/opentelemetry-javaagent.jar \
-Dotel.resource.attributes=service.name=<your-service-name> \
-Dotel.exporter.otlp.headers=Authentication=<token> \
-Dotel.exporter.otlp.endpoint=<endpoint> \
-jar /path/to/your/app.jarÖrnek:
java -javaagent:/path/to/opentelemetry-javaagent.jar \
-Dotel.resource.attributes=service.name=ot-java-agent-sample \
-Dotel.exporter.otlp.headers=Authentication=b590xxxxuqs@3a75d95xxxxx9b_b59xxxxguqs@53dxxxx2afe8301 \
-Dotel.exporter.otlp.endpoint=http://tracing-analysis-dc-bj:8090 \
-jar /path/to/your/app.jarİzleme verilerini bir OpenTelemetry Collector üzerinden iletmek için-Dotel.exporter.otlp.headers=Authentication=<token>satırını kaldırın ve<endpoint>değerini yerel makinenizdeki Collector adresine ayarlayın.
Managed Service for OpenTelemetry konsolunu açın. Applications sayfasında uygulama adınıza tıklayın ve izlemelerin göründüğünü onaylayın.
Desteklenen Java çerçeveleri
OpenTelemetry Java aracı aşağıdaki çerçeveleri otomatik olarak enstrümante eder. Güncel ve eksiksiz liste için bkz. Desteklenen kitaplıklar, çerçeveler, uygulama sunucuları ve JVM'ler.