java edot skip certificate doc (#358)

* java edot skip certificate doc

* Update docs/reference/edot-sdks/java/configuration.md

Co-authored-by: jackshirazi <[email protected]>

* add migration doc for new config option

* add version to config options

* Apply suggestions from code review

Co-authored-by: Colleen McGinnis <[email protected]>

---------

Co-authored-by: jackshirazi <[email protected]>
Co-authored-by: Colleen McGinnis <[email protected]>

Author: 3 people

docs/reference/edot-sdks/java/configuration.md

@@ -55,26 +55,27 @@ configuration options:
 
 EDOT Java uses different defaults than the OpenTelemetry Java instrumentation for the following configuration options:
 
-| Option                                                               | EDOT Java default | OpenTelemetry Java agent default                                                                                                             |
-|----------------------------------------------------------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
-| `OTEL_RESOURCE_PROVIDERS_AWS_ENABLED`                                | `true`            | `false` ([docs](https://opentelemetry.io/docs/zero-code/java/agent/configuration/#enable-resource-providers-that-are-disabled-by-default))   |
-| `OTEL_RESOURCE_PROVIDERS_GCP_ENABLED`                                | `true`            | `false` ([docs](https://opentelemetry.io/docs/zero-code/java/agent/configuration/#enable-resource-providers-that-are-disabled-by-default))   |
-| `OTEL_RESOURCE_PROVIDERS_AZURE_ENABLED`                              | `true`            | `false` ([docs](https://opentelemetry.io/docs/zero-code/java/agent/configuration/#enable-resource-providers-that-are-disabled-by-default))   |
-| `OTEL_INSTRUMENTATION_RUNTIME-TELEMETRY_EMIT-EXPERIMENTAL-TELEMETRY` | `true`            | `false` ([docs](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/runtime-telemetry/README.md)) |
-| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`                  | `delta` (*)       | `cumulative` ([docs](https://opentelemetry.io/docs/specs/otel/metrics/sdk_exporters/otlp/#additional-environment-variable-configuration))    |
+| Option                                                               | EDOT Java default | OpenTelemetry Java agent default                                                                                                             | EDOT Java version |
+|----------------------------------------------------------------------|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------|-------------------|
+| `OTEL_RESOURCE_PROVIDERS_AWS_ENABLED`                                | `true`            | `false` ([docs](https://opentelemetry.io/docs/zero-code/java/agent/configuration/#enable-resource-providers-that-are-disabled-by-default))   | 1.0.0+            |
+| `OTEL_RESOURCE_PROVIDERS_GCP_ENABLED`                                | `true`            | `false` ([docs](https://opentelemetry.io/docs/zero-code/java/agent/configuration/#enable-resource-providers-that-are-disabled-by-default))   | 1.0.0+            |
+| `OTEL_RESOURCE_PROVIDERS_AZURE_ENABLED`                              | `true`            | `false` ([docs](https://opentelemetry.io/docs/zero-code/java/agent/configuration/#enable-resource-providers-that-are-disabled-by-default))   | 1.4.0+            |
+| `OTEL_INSTRUMENTATION_RUNTIME-TELEMETRY_EMIT-EXPERIMENTAL-TELEMETRY` | `true`            | `false` ([docs](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/runtime-telemetry/README.md)) | 1.4.0+            |
+| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`                  | `delta` (*)       | `cumulative` ([docs](https://opentelemetry.io/docs/specs/otel/metrics/sdk_exporters/otlp/#additional-environment-variable-configuration))    | 1.0.0+            |
 
 (*) default value set to `delta` only if not already explicitly set.
 
 The EDOT Java instrumentation agent also provides configuration options for each of the [supported features](/reference/edot-sdks/java/features.md).
 This table only contains minimal configuration, see each respective feature for exhaustive configuration options documentation.
 
-| Option                                                 | Default | Feature                                                                                          |
-|--------------------------------------------------------|---------|--------------------------------------------------------------------------------------------------|
-| `OTEL_INFERRED_SPANS_ENABLED`                          | `false` | [Inferred spans](/reference/edot-sdks/java/features.md#inferred-spans)                                                   |
-| `OTEL_JAVA_EXPERIMENTAL_SPAN_STACKTRACE_MIN_DURATION`  | `5ms`   | [Span stacktrace](/reference/edot-sdks/java/features.md#span-stacktrace)                                                 |
-| `ELASTIC_OTEL_UNIVERSAL_PROFILING_INTEGRATION_ENABLED` | `auto`  | [Elastic Universal profiling integration](/reference/edot-sdks/java/features.md#elastic-universal-profiling-integration) |
-| `OTEL_INSTRUMENTATION_OPENAI_CLIENT_ENABLED`           | `true`  | [OpenAI client instrumentation](/reference/edot-sdks/java/supported-technologies.md#openai-client-instrumentation)       |
-| `ELASTIC_OTEL_JAVAAGENT_LOG_LEVEL`                     | `INFO`  | [Agent logging](/reference/edot-sdks/java/configuration.md#agent-logging)                                                |
+| Option                                                 | Default | Feature                                                                                                                  | EDOT Java version |
+|--------------------------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------|-------------------|
+| `OTEL_INFERRED_SPANS_ENABLED`                          | `false` | [Inferred spans](/reference/edot-sdks/java/features.md#inferred-spans)                                                   | 1.0.0+            |
+| `OTEL_JAVA_EXPERIMENTAL_SPAN_STACKTRACE_MIN_DURATION`  | `5ms`   | [Span stacktrace](/reference/edot-sdks/java/features.md#span-stacktrace)                                                 | 1.0.0+            |
+| `ELASTIC_OTEL_UNIVERSAL_PROFILING_INTEGRATION_ENABLED` | `auto`  | [Elastic Universal profiling integration](/reference/edot-sdks/java/features.md#elastic-universal-profiling-integration) | 1.0.0+            |
+| `OTEL_INSTRUMENTATION_OPENAI_CLIENT_ENABLED`           | `true`  | [OpenAI client instrumentation](/reference/edot-sdks/java/supported-technologies.md#openai-client-instrumentation)       | 1.4.0+            |
+| `ELASTIC_OTEL_JAVAAGENT_LOG_LEVEL`                     | `INFO`  | [Agent logging](#agent-logging)                                                                                          | 1.5.0+            |
+| `ELASTIC_OTEL_VERIFY_SERVER_CERT`                      | `true`  | [Exporter certificate verification](#exporter-certificate-verification)                                                  | 1.5.0+            |
 
 ## OpenAI Client settings
 
@@ -157,4 +158,18 @@ Setting `OTEL_JAVAAGENT_LOGGING=none` or `ELASTIC_OTEL_JAVAAGENT_LOG_LEVEL=OFF`
 
 Setting `OTEL_JAVAAGENT_LOGGING=application` will disable EDOT agent logging feature and attempt to use the application logger.
 As [documented here in the upstream documentation](https://opentelemetry.io/docs/zero-code/java/agent/configuration/#java-agent-logging-output),
-support for this depends on the application and logging libraries used.
+support for this depends on the application and logging libraries used.
+
+## Exporter certificate verification
+
+The EDOT Java agent provides the ability to toggle the exporter endpoint certificate verification with the `ELASTIC_OTEL_VERIFY_SERVER_CERT` configuration option (`true` by default).
+
+When the endpoint certificate is not trusted by the JVM where the agent runs, the common symptom is security-related exceptions with the following message: `unable to find valid certification path to requested target`.
+
+This is common in the following scenarios:
+- When endpoint uses a self-signed certificate not trusted by the JVM
+- When the certificate authority used by the endpoint certificate is not trusted by the JVM
+
+One solution is to add the certificate or certificate authority to the JVM trust store, which requires modifying the JVM trust store.
+
+If trust store modification is not possible or not practical, for example when troubleshooting or working with a local deployment, certificate verification can be disabled by setting `ELASTIC_OTEL_VERIFY_SERVER_CERT` to `false`. This however need to be evaluated carefully as it lowers the communication security and could allow for man-in-the-middle attacks where the data could be intercepted between the agent and the collector endpoint.

docs/reference/edot-sdks/java/migration.md

@@ -180,6 +180,12 @@ With EDOT, application logs are automatically captured and sent by default.
 
 This feature is controlled by `otel.logs.exporter`, which is set to `otlp` by default. You can turn it off by setting `otel.logs.exporter` to `none`.
 
+### `verify_server_cert`
+
+The Elastic [`verify_server_cert`](apm-agent-java://reference/config-reporter.md#config-verify-server-cert) option allows you to disable server certificate validation.
+
+With EDOT, the equivalent configuration option is `ELASTIC_OTEL_VERIFY_SERVER_CERT` (default `true`), see [configuration](./configuration.md#exporter-certificate-verification) for details.
+
 ## Limitations
 
 The following limitations apply to EDOT Java.