Merge pull request elastic#90 from SylvainJuge/java-setup

document otel java setup

Author: AlexanderWert

docs/_edot-sdks/java/configuration.md

@@ -7,6 +7,11 @@ parent: EDOT Java
 
 # Configuring the EDOT Java Agent
 
+EDOT Java instrumentation agent is based on OpenTelemetry Java [SDK](https://github.com/open-telemetry/opentelemetry-java) and [Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation), and thus supports the following
+configuration options:
+- [OpenTelemetry Java instrumentation configuration options](https://opentelemetry.io/docs/zero-code/java/agent/configuration/)
+- [OpenTelemetry Java SDK configuration options](https://opentelemetry.io/docs/languages/java/configuration/)
+
 TODO: 
 - describe the EDOT Java specific config options
 - describe crucial upstream options

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

@@ -7,7 +7,49 @@ parent: EDOT Java
 
 # Setting up the EDOT Java Agent
 
-TODO:
-- where to download
-- explicit description of basic setup here (even if it overlaps with upstream docs)
-- link to upstream docs for more advanced setup use cases
+## 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)
+
+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)
+
+## Prerequisites
+
+You need to have completed the steps in the [Quickstart](/quickstart/) section that corresponds to your Elastic deployment model.
+
+## Run
+
+Use the `-javaagent:` JVM argument with the path to agent jar, this requires to modify the JVM arguments and restart
+the application.
+
+```bash
+java \
+  -javaagent:/path/to/agent.jar \
+  -jar myapp.jar
+```
+
+For applications deployed with Kubernetes, we recommend using [OpenTelemetry Operator](./k8s).
+
+## Minimal configuration
+
+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:
+- 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).
+
+For example:
+
+```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"
+```
+
+For more advanced configuration, see [Configuration](../configuration) section.

docs/quickstart/serverless/hosts_vms.md

@@ -24,7 +24,7 @@ logs and application traces and send the data through OTLP to your Elastic Serve
 
     Retrieve the `Elastic OTLP Endpoint` and the `Elastic API Key` for your Serverless Project by [following these instructions](./#retrieving-connection-details-for-your-serverless-project).
 
-    Replace `<ELASTIC_OTLP_ENDPOINT>` and `<ELASTIC_API_KEY>` before applying the below command.
+    Replace `<ELASTIC_OTLP_ENDPOINT>` and `<ELASTIC_API_KEY>` before applying the command below.
 
     *Linux*
 
@@ -57,11 +57,12 @@ logs and application traces and send the data through OTLP to your Elastic Serve
     ```
 
 3. **Run the EDOT Collector**
-
-    Execute the following command to run the EDOT Collector. 
 
     {: .note }
-    The Collector will open the ports `4317` and `4318` to receive application data from locally running OTel SDKs.
+    The Collector will open the ports `4317` and `4318` to receive application data from locally running OTel SDKs without authentication.
+    This allows the SDKs to send data without any further configuration needed as they use this endpoint by default.
+
+   Execute the following command to run the EDOT Collector.
 
     *Linux / MacOS*
 

docs/quickstart/serverless/index.md

@@ -24,6 +24,10 @@ parent: Quickstart
         --> https://my-prj-a1b2c3<b>.ingest.</b>eu-west-1.aws.elastic.cloud
         </code></pre>
 
+    This URL will be referred to as `ELASTIC_OTLP_ENDPOINT`, and API key (see below) will be required to use it.
+
 2. **Create an API key** 
 
-    Create an API Key following [these instructions](https://www.elastic.co/guide/en/kibana/current/api-keys.html){:target="_blank"}.
+    Create an API Key following [these instructions](https://www.elastic.co/guide/en/kibana/current/api-keys.html){:target="_blank"}.
+
+    This API key will be referred to as `ELASTIC_API_KEY`.

docs/quickstart/serverless/k8s.md

@@ -46,6 +46,9 @@ logs collection and application monitoring.
     --values 'https://raw.githubusercontent.com/elastic/elastic-agent/refs/tags/v{{ site.edot_versions.collector }}/deploy/helm/edot-collector/kube-stack/managed_otlp/values.yaml' \
     --version '0.3.9'
     ```
+
+    The Operator will provide a deployment of the EDOT Collector and provide the configuration environment variables, thus enabling SDKs and instrumentation to send data to the EDOT Collector without further configuration.
+
 4. **Auto-instrument Applications**
 
     Add a language-specific annotation to your namespace by replacing `<LANGUAGE>` with one of the supported values (`nodejs`, `java`, `python`, `dotnet` or `go`) in the below command. 
@@ -54,6 +57,8 @@ logs collection and application monitoring.
     kubectl annotate namespace YOUR_NAMESPACE instrumentation.opentelemetry.io/inject-<LANGUAGE>="opentelemetry-operator-system/elastic-instrumentation"
     ```
 
+    The OpenTelemetry Operator will automatically provide the OTLP endpoint configuration and authentication to the SDKs through environment variables.
+
     Restart your deployment to ensure the annotations and auto-instrumentations are applied.
 
     For languages where auto-instrumentation is not available, you will need to manually instrument your application. See the [Setup section in the corresponding SDK](../../edot-sdks).