revised Java setup docs

Signed-off-by: Alexander Wert <alexander.wert@elastic.co>

Author: AlexanderWert

docs/_edot-sdks/java/setup/index.md

@@ -7,49 +7,76 @@ parent: EDOT Java
 
 # Setting up the EDOT Java Agent
 
+**Kubernetes**
+
+For Kubernetes we recommend using the OTel Kubernetes Operator that also manages the auto-instrumentation of Java applications. Follow the [Quickstart Guide](../../../quickstart/index) for Kubernetes or learn more about [instrumentation details on Kubernetes for Java](./k8s). 
+
+**All other environments**
+
+Follow the Java setup guide below for all other environments.
+
 ## Download
 
-Latest release: [![Maven Central](https://img.shields.io/maven-central/v/co.elastic.otel/elastic-otel-javaagent?label=elastic-otel-javaagent)](https://mvnrepository.com/artifact/co.elastic.otel/elastic-otel-javaagent/latest)
+You can download the latest release version or snapshot version of the EDOT Java Agent from the following links:
 
-Latest snapshot: [![Sonatype Nexus](https://img.shields.io/nexus/s/co.elastic.otel/elastic-otel-javaagent?server=https%3A%2F%2Foss.sonatype.org&label=elastic-otel-javaagent)](https://oss.sonatype.org/service/local/artifact/maven/redirect?r=snapshots&g=co.elastic.otel&a=elastic-otel-javaagent&v=LATEST)
+| Latest Release | Latest Snapshot |
+|:---:|:---:|
+| [![Maven Central](https://img.shields.io/maven-central/v/co.elastic.otel/elastic-otel-javaagent?label=elastic-otel-javaagent&style=for-the-badge)](https://mvnrepository.com/artifact/co.elastic.otel/elastic-otel-javaagent/latest) | [![Sonatype Nexus](https://img.shields.io/nexus/s/co.elastic.otel/elastic-otel-javaagent?server=https%3A%2F%2Foss.sonatype.org&label=elastic-otel-javaagent&style=for-the-badge)](https://oss.sonatype.org/service/local/artifact/maven/redirect?r=snapshots&g=co.elastic.otel&a=elastic-otel-javaagent&v=LATEST) |
 
 ## Prerequisites
 
 You need to have completed the steps in the [Quickstart](/quickstart/) section that corresponds to your Elastic deployment model.
 
-## Run
+## Setting up the Agent
+
+1. **Configure the agent**
+
+    The minimal configuration to send data involves setting the values for `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` environment variables.
+
+    Configuration of those environment values depends on the deployment model:
+
+    *Local EDOT Collector*
+
+    EDOT Collector is accessible with `http://localhost:4318` without authentication, no further configuration is required.
+
+    *Self-managed EDOT Collector*
+
+    `OTEL_EXPORTER_OTLP_ENDPOINT` should be set to the OTLP endpoint of your selfmanaged EDOT Collector.
+
+    *Elastic Managed OTLP endpoint*
+
+    Use [these guides](../../../quickstart/serverless/index) to retrieve the `<ELASTIC_OTLP_ENDPOINT>` and the `<ELASTIC_API_KEY>`.
+
+    - `OTEL_EXPORTER_OTLP_ENDPOINT` should be set to `<ELASTIC_OTLP_ENDPOINT>`
+    - `OTEL_EXPORTER_OTLP_HEADERS` should be set to include `Authorization=ApiKey <ELASTIC_API_KEY>` (comma-separated key=value list).
+
+    *Kubernetes*
+
+    Connection to the EDOT Collector is managed by the OTel Kubernetes Operator, [follow the Quickstart Guides](../../../quickstart/index) for Kubernetes.
+
 
-Use the `-javaagent:` JVM argument with the path to agent jar, this requires to modify the JVM arguments and restart
-the application.
+    We also recommend setting the `service.name` resource attribute explicitly:
 
-```bash
-java \
-  -javaagent:/path/to/agent.jar \
-  -jar myapp.jar
-```
+      TODO
 
-For applications deployed with Kubernetes, we recommend using [OpenTelemetry Operator](./k8s).
+    Set the `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` environment variables. For example:
 
-## Minimal configuration
+    ```bash
+    export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io
+    export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey P....l"
+    ```
 
-The minimal configuration to send data involves setting the values for `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` environment variables.
+    For more advanced configuration, see [Configuration](../configuration) section.
 
-Configuration of those environment values depends on the deployment model:
-- EDOT Collector running on the application host, accessible with `http://localhost:4318` without authentication, no further configuration is required.
-- EDOT Collector managed by the OpenTelemetry Kubernetes Operator
-  - `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` environment variables are automatically provided by the Operator, no further configuration is required.
-- Elastic Managed OTLP endpoint (Elastic Cloud Serverless):
-  - `OTEL_EXPORTER_OTLP_ENDPOINT` should be set to `<ELASTIC_OTLP_ENDPOINT>`
-  - `OTEL_EXPORTER_OTLP_HEADERS` should be set to include `Authorization=ApiKey <ELASTIC_API_KEY>` (comma-separated key=value list).
-- Self-managed EDOT Collector:
-  - `OTEL_EXPORTER_OTLP_ENDPOINT` should be set to the OTLP endpoint of EDOT Collector
-  - `OTEL_EXPORTER_OTLP_HEADERS` should be set to include `Authorization=ApiKey <ELASTIC_API_KEY>` (comma-separated key=value list).
+2. **Run the Java Agent**
 
-For example:
+    Use the `-javaagent:` JVM argument with the path to agent jar, this requires to modify the JVM arguments and restart
+    the application.
 
-```shell
-export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io
-export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey P....l"
-```
+    ```bash
+    java \
+    -javaagent:/path/to/agent.jar \
+    -jar myapp.jar
+    ```
 
-For more advanced configuration, see [Configuration](../configuration) section.
+    For applications deployed with Kubernetes, we recommend using [OpenTelemetry Operator](./k8s).

docs/_edot-sdks/java/setup/k8s.md

@@ -12,7 +12,7 @@ This document focuses on instrumenting Java applications on Kubernetes, using th
 
 - For general knowledge about the EDOT Java SDK, refer to the [EDOT Java Intro page](../index).
 - For Java auto-instrumentation specifics, refer to [OpenTelemetry Operator Java auto-instrumentation](https://opentelemetry.io/docs/kubernetes/operator/automatic/#java).
-- For general information about instrumenting applications on kubernetes, refer to [instrumenting applications on Kubernetes](../../../use-cases/kubernetes/instrumenting-applications).
+- For general information about instrumenting applications on Kubernetes, refer to [instrumenting applications on Kubernetes](../../../use-cases/kubernetes/instrumenting-applications).
 
 ## Java agent extensions consideration