open-telemetry · haveheartt · Dec 28, 2024
@@ -0,0 +1,16 @@
+---
+title: Java
+description: >-
+  <img width="35" class="img-initial" src="/img/logos/32x32/Java_SDK.svg"
+  alt="Java"> Implementação específica do OpenTelemetry em Java. 
+aliases: [/java, /java/metrics, /java/tracing]
+cascade:
+  vers:
+    instrumentation: 2.11.0
+    otel: 1.45.0
+    contrib: 1.42.0
+    semconv: 1.29.0
+weight: 18
+---
+
+{{% docs/languages/index-intro java /%}}
@@ -0,0 +1,269 @@
+---
+title: Começando com um Exemplo
+description: Obtenha telemetria para sua aplicação em menos de 5 minutos!
+weight: 10
+---
+
+<!-- markdownlint-disable blanks-around-fences -->
+<?code-excerpt path-base="examples/java/getting-started"?>
+
+Esta página mostrará como começar a usar OpenTelemetry em Java.
+
+Você aprenderá como instrumentalizar automaticamente uma aplicação Java simples,
+de modo que [traces][], [métricas][], e [logs][] sejam emitidos para o
+console.
+
+## Pré-requisitos
+
+Certifique-se de ter instalado localmente:
+
+- Java JDK 17+ devido ao uso do Spring Boot 3; [Java 8+ para outros casos][java-vers]
+- [Gradle](https://gradle.org/)
+
+## Exemplo de Aplicação
+
+O exemplo a seguir utiliza uma aplicação básica [Spring Boot]. Você pode usar
+outros frameworks web, como Apache Wicket ou Play. Para uma lista completa das
+bibliotecas e frameworks suportados, consulte o
+[registro](/ecosystem/registry/?component=instrumentation&language=java).
+
+Para exemplos mais elaborados, veja [exemplos](../examples/).
+
+### Dependências
+
+Para começar, crie um ambiente em um novo diretório chamado `java-simple`. Dentro
+dele, crie um arquivo chamado `build.gradle.kts` com o seguinte
+conteúdo:
+
+```kotlin
+plugins {
+  id("java")
+  id("org.springframework.boot") version "3.0.6"
+  id("io.spring.dependency-management") version "1.1.0"
+}
+
+sourceSets {
+  main {
+    java.setSrcDirs(setOf("."))
+  }
+}
+
+repositories {
+  mavenCentral()
+}
+
+dependencies {
+  implementation("org.springframework.boot:spring-boot-starter-web")
+}
+```
+
+### Criando e iniciando um servidor HTTP
+
+Na mesma pasta, crie um arquivo chamado `DiceApplication.java` e adicione o
+seguinte código:
+
+<!-- prettier-ignore-start -->
+<?code-excerpt "src/main/java/otel/DiceApplication.java"?>
+```java
+package otel;
+
+import org.springframework.boot.Banner;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class DiceApplication {
+  public static void main(String[] args) {
+    SpringApplication app = new SpringApplication(DiceApplication.class);
+    app.setBannerMode(Banner.Mode.OFF);
+    app.run(args);
+  }
+}
+```
+<!-- prettier-ignore-end -->
+
+Crie outro arquivo chamado `RollController.java` e adicione o seguinte código 
+ao arquivo:
+
+<!-- prettier-ignore-start -->
+<?code-excerpt "src/main/java/otel/RollController.java"?>
+```java
+package otel;
+
+import java.util.Optional;
+import java.util.concurrent.ThreadLocalRandom;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+public class RollController {
+  private static final Logger logger = LoggerFactory.getLogger(RollController.class);
+
+  @GetMapping("/rolldice")
+  public String index(@RequestParam("player") Optional<String> player) {
+    int result = this.getRandomNumber(1, 6);
+    if (player.isPresent()) {
+      logger.info("{} está jogando o dado: {}", player.get(), result);
+    } else {
+      logger.info("Jogador anônimo está jogando o dado: {}", result);
+    }
+    return Integer.toString(result);
+  }
+
+  public int getRandomNumber(int min, int max) {
+    return ThreadLocalRandom.current().nextInt(min, max + 1);
+  }
+}
+```
+<!-- prettier-ignore-end -->
+
+Compile e execute a aplicação com o seguinte comando, e então abra
+<http://localhost:8080/rolldice> no seu navegador para ter certeza que está funcionando
+
+```sh
+gradle assemble
+java -jar ./build/libs/java-simple.jar
+```
+
+## Instrumentação
+
+Em seguida, você usará um [agente Java] para instrumentalizar
+automaticamente a aplicação durante sua inicialização. Embora seja possível [configurar o agente Java][] 
+de várias maneiras, os passos abaixo utilizam variáveis de ambiente.
+
+1. Faça o download do [opentelemetry-javaagent.jar][] na página de [Releases][] do repositório
+   `opentelemetry-java-instrumentation`. O arquivo JAR contém o
+   agente e todos os pacotes de instrumentação automática:
+
+   ```console
+   curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
+   ```
+
+   {{% alert color="info" %}}<i class="fas fa-edit"></i> Anote o caminho
+   para o arquivo JAR.{{% /alert %}}
+
+2. Configure e exporte as variáveis que especificam o JAR do agente Java e um [exportador de console][], utilizando a notação adequada para seu ambiente
+   &mdash; aqui demonstramos a notação para shells do tipo bash:
+
+   ```sh
+   export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar" \
+     OTEL_TRACES_EXPORTER=logging \
+     OTEL_METRICS_EXPORTER=logging \
+     OTEL_LOGS_EXPORTER=logging \
+     OTEL_METRIC_EXPORT_INTERVAL=15000
+   ```
+
+   {{% alert title="Importante" color="warning" %}}
+
+   - Substitua `PATH/TO` acima pelo caminho correto até o arquivo JAR.
+   - Configure `OTEL_METRIC_EXPORT_INTERVAL` com um valor significativamente menor que o padrão, 
+     como mostrado acima, **apenas durante testes** para verificar mais rapidamente se
+     as métricas estão sendo geradas corretamente.
+
+   {{% /alert %}}
+
+3. Rode sua **aplicação** mais uma vez:
+
+   ```console
+   $ java -jar ./build/libs/java-simple.jar
+   ...
+   ```
+
+   Observe a saida do `otel.javaagent`.
+
+4. De _outro_ terminal, envie uma requisição utilizando `curl`:
+
+   ```sh
+   curl localhost:8080/rolldice
+   ```
+
+5. Pare o processo do servidor.
+
+No passo 4, você deve ter visto o trace e a saída de log do servidor e cliente 
+que se parece com algo assim (a saída do trace está quebrada em linhas para melhor visualização):
+
+```sh
+[otel.javaagent 2023-04-24 17:33:54:567 +0200] [http-nio-8080-exec-1] INFO
+io.opentelemetry.exporter.logging.LoggingSpanExporter - 'RollController.index' :
+ 70c2f04ec863a956e9af975ba0d983ee 7fd145f5cda13625 INTERNAL [tracer:
+ io.opentelemetry.spring-webmvc-6.0:1.25.0-alpha] AttributesMap{data=
+ {thread.id=39, thread.name=http-nio-8080-exec-1}, capacity=128,
+ totalAddedValues=2}
+[otel.javaagent 2023-04-24 17:33:54:568 +0200] [http-nio-8080-exec-1] INFO
+io.opentelemetry.exporter.logging.LoggingSpanExporter - 'GET /rolldice' :
+70c2f04ec863a956e9af975ba0d983ee 647ad186ad53eccf SERVER [tracer:
+io.opentelemetry.tomcat-10.0:1.25.0-alpha] AttributesMap{
+  data={user_agent.original=curl/7.87.0, net.host.name=localhost,
+  net.transport=ip_tcp, http.target=/rolldice, net.sock.peer.addr=127.0.0.1,
+  thread.name=http-nio-8080-exec-1, net.sock.peer.port=53422,
+  http.route=/rolldice, net.sock.host.addr=127.0.0.1, thread.id=39,
+  net.protocol.name=http, http.status_code=200, http.scheme=http,
+  net.protocol.version=1.1, http.response_content_length=1,
+  net.host.port=8080, http.method=GET}, capacity=128, totalAddedValues=17}
+```
+
+No passo 5, ao parar o servidor, você verá uma saída com todas as métricas
+coletadas (a saída das métricas está quebrada em linhas e resumida para melhor visualização):
+
+```sh
+[otel.javaagent 2023-04-24 17:34:25:347 +0200] [PeriodicMetricReader-1] INFO
+io.opentelemetry.exporter.logging.LoggingMetricExporter - Received a collection
+ of 19 metrics for export.
+[otel.javaagent 2023-04-24 17:34:25:347 +0200] [PeriodicMetricReader-1] INFO
+io.opentelemetry.exporter.logging.LoggingMetricExporter - metric:
+ImmutableMetricData{resource=Resource{schemaUrl=
+https://opentelemetry.io/schemas/1.19.0, attributes={host.arch="aarch64",
+host.name="OPENTELEMETRY", os.description="Mac OS X 13.3.1", os.type="darwin",
+process.command_args=[/bin/java, -jar, java-simple.jar],
+process.executable.path="/bin/java", process.pid=64497,
+process.runtime.description="Homebrew OpenJDK 64-Bit Server VM 20",
+process.runtime.name="OpenJDK Runtime Environment",
+process.runtime.version="20", service.name="java-simple",
+telemetry.auto.version="1.25.0", telemetry.sdk.language="java",
+telemetry.sdk.name="opentelemetry", telemetry.sdk.version="1.25.0"}},
+instrumentationScopeInfo=InstrumentationScopeInfo{name=io.opentelemetry.runtime-metrics,
+version=1.25.0, schemaUrl=null, attributes={}},
+name=process.runtime.jvm.buffer.limit, description=Total capacity of the buffers
+in this pool, unit=By, type=LONG_SUM, data=ImmutableSumData{points=
+[ImmutableLongPointData{startEpochNanos=1682350405319221000,
+epochNanos=1682350465326752000, attributes=
+{pool="mapped - 'non-volatile memory'"}, value=0, exemplars=[]},
+ImmutableLongPointData{startEpochNanos=1682350405319221000,
+epochNanos=1682350465326752000, attributes={pool="mapped"},
+value=0, exemplars=[]},
+ImmutableLongPointData{startEpochNanos=1682350405319221000,
+epochNanos=1682350465326752000, attributes={pool="direct"},
+value=8192, exemplars=[]}], monotonic=false, aggregationTemporality=CUMULATIVE}}
+...
+```
+
+## O que vem depois?
+Para mais:
+
+- Execute este exemplo com outro [exportador][] para dados de telemetria.
+- Experimente a [instrumentação zero-code](/docs/zero-code/java/agent/) em uma de suas próprias aplicações.
+- Para telemetria levemente personalizada, experimente [annotations][].
+- Aprenda sobre [instrumentação manual][] e experimente mais [exemplos](../examples/).
+- Dê uma olhada no [OpenTelemetry Demo](/docs/demo/), que inclui o [Serviço de Anúncios](/docs/demo/services/ad/) baseado em Java
+ e o [Serviço de Detecção de Fraude](/docs/demo/services/fraud-detection/) baseado em Kotlin
+
+[traces]: /docs/concepts/signals/traces/
+[metricas]: /docs/concepts/signals/metrics/
+[logs]: /docs/concepts/signals/logs/
+[annotations]: /docs/zero-code/java/agent/annotations/
+[configurar o agente Java]: /docs/zero-code/java/agent/configuration/
+[exportador de console]:
+  https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md#logging-exporter
+[exportador]:
+  https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md#exporters
+[java-vers]:
+  https://github.com/open-telemetry/opentelemetry-java/blob/main/VERSIONING.md#language-version-compatibility
+[manual instrumentation]: ../instrumentation
+[opentelemetry-javaagent.jar]:
+  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
+[releases]:
+  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases
+[Spring Boot]: https://spring.io/guides/gs/spring-boot/