[docs] Prepare docs (#328)

* initial outline * align with other distro docs * align with other languages * clean up code comments, align with other distro docs * reframe generated guide as migration guide * update intro, add questions * update getting started * update configuration file * lint content * address feedback from @bmorelli25 * translate from asciidoc to markdown * merge intro content and README content, link to docs from README * adjust for github audience * fix some formatting * update docs automation * update reference to automation * Update README.md Co-authored-by: jackshirazi <[email protected]> * update naming * address feedback from @mdbirnstiehl * update link text * one more for to of * fix ConfigurationExporterTest to generate markdown instead of asciidoc * apply suggestions from code review Co-authored-by: jackshirazi <[email protected]> * update download section Co-authored-by: jackshirazi <[email protected]> * apply suggestions from code review Co-authored-by: Jonas Kunz <[email protected]> --------- Co-authored-by: jackshirazi <[email protected]> Co-authored-by: Jack Shirazi <[email protected]> Co-authored-by: Jonas Kunz <[email protected]>
elastic · Aug 15, 2024 · add6be8 · add6be8
1 parent d39b0ed
commit add6be8
Show file tree

Hide file tree

Showing 15 changed files with 414 additions and 264 deletions.
diff --git a/NOTICE b/NOTICE
@@ -1,4 +1,4 @@
-Elastic Distribution for OpenTelemetry Java
+Elastic Distribution of OpenTelemetry Java
 Copyright 2023-2024 Elasticsearch B.V.
 
 This project is licensed under the Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0

diff --git a/README.md b/README.md
@@ -1,11 +1,21 @@
-# Elastic Distribution for OpenTelemetry Java
+# Elastic Distribution of OpenTelemetry Java
 
 [![Snapshot status](https://badge.buildkite.com/e527255a5d6e7f5a940bc71911d8bc2be25d16702d7642c0d6.svg)](https://buildkite.com/elastic/elastic-otel-java-snapshot)
 [![Release status](https://badge.buildkite.com/8bac74f475ea0d5d17ea3ea2ecf2c27a319414b97ce03dbd21.svg)](https://buildkite.com/elastic/elastic-otel-java-release)
 
-This project is the Elastic distribution of the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation).
+> [!WARNING]
+> The Elastic Distribution of OpenTelemetry Java is not yet recommended for production use. Functionality may be changed or removed in future releases. Alpha releases are not subject to the support SLA of official GA features.
+>
+> We welcome your feedback! You can reach us by [opening a GitHub issue](https://github.com/elastic/elastic-otel-java/issues) or starting a discussion thread on the [Elastic Discuss forum](https://discuss.elastic.co/tags/c/observability/apm/58/java).
 
-This is currently an early alpha release and should be used mostly for testing.
+The Elastic Distribution of OpenTelemetry Java (EDOT Java) is a customized version of the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation). Use EDOT Java to start the OpenTelemetry SDK with your Java application, and automatically capture tracing data, performance metrics, and logs. Traces, metrics, and logs can be sent to any OpenTelemetry Protocol (OTLP) collector you choose.
+
+With EDOT Java you have access to all the features of the OpenTelemetry Java agent plus:
+
+* Access to SDK improvements and bug fixes contributed by the Elastic team _before_ the changes are available upstream in OpenTelemetry repositories.
+* Access to optional features that can enhance OpenTelemetry data that is being sent to Elastic (for example, [inferred spans](#inferred-spans) and [span stacktrace](#span-stacktrace)).
+
+**Ready to try out EDOT Java?** Follow the step-by-step instructions in [Get started](./docs/get-started.md).
 
 ## Download
 
@@ -21,6 +31,13 @@ Use the `-javaagent:` JVM argument with the path to agent jar.
 java -javaagent:/path/to/agent.jar \
 -jar myapp.jar
 ```
+
+## Read the docs
+
+* [Get started](./docs/get-started.md)
+* [Configure the Elastic Distribution of OpenTelemetry Java](./docs/configure.md)
+* [Migrate to the Elastic Distribution of OpenTelemetry Java](./docs/migrate.md) from the [Elastic APM Java agent](https://github.com/elastic/apm-agent-java)
+
 ## Build and Test
 
 Execute `./gradlew assemble`, the agent binary will be in `./agent/build/libs/elastic-otel-javaagent-${VERSION}.jar`
@@ -111,5 +128,5 @@ if(ctx.numeric_labels != null && ctx.numeric_labels.elastic_span_self_time != nu
 
 # License
 
-The Elastic Distribution for OpenTelemetry Java is licensed under [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
+The Elastic Distribution of OpenTelemetry Java is licensed under [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
 
diff --git a/agent/build.gradle.kts b/agent/build.gradle.kts
@@ -11,7 +11,7 @@ plugins {
   alias(catalog.plugins.licenseReport)
 }
 
-description = "Elastic Distribution for OpenTelemetry Java Agent"
+description = "Elastic Distribution of OpenTelemetry Java Agent"
 
 base.archivesName.set("elastic-otel-javaagent")
 
@@ -92,7 +92,7 @@ tasks {
       var year = Calendar.getInstance().get(Calendar.YEAR)
       var lines = ArrayList<String>(
         listOf(
-          "Elastic Distribution for OpenTelemetry Java",
+          "Elastic Distribution of OpenTelemetry Java",
           "Copyright 2023-${year} Elasticsearch B.V.",
           "",
           "This project is licensed under the Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0",

diff --git a/build.gradle.kts b/build.gradle.kts
@@ -12,7 +12,7 @@ versionProperties.load(FileInputStream(file("version.properties")))
 
 group = "co.elastic.otel"
 version = versionProperties.get("version").toString()
-description = "Elastic Distribution for OpenTelemetry Java"
+description = "Elastic Distribution of OpenTelemetry Java"
 
 defaultTasks("agent:assemble")
 

diff --git a/custom/src/main/java/co/elastic/otel/config/LegacyConfigurations.java b/custom/src/main/java/co/elastic/otel/config/LegacyConfigurations.java
@@ -49,31 +49,31 @@ public LegacyConfigurations() {
   private void addAllOptions() {
     addDocumentationOption(
         "server_url",
-        "The Elastic https://www.elastic.co/guide/en/apm/agent/java/current/config-reporter.html#config-server-url[`server_url`] option corresponds to the OpenTelemetry https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint[`OTEL_EXPORTER_OTLP_ENDPOINT`] option.");
+        "The Elastic [`server_url`](https://www.elastic.co/guide/en/apm/agent/java/current/config-reporter.html#config-server-url) option corresponds to the OpenTelemetry [`OTEL_EXPORTER_OTLP_ENDPOINT`](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint) option.");
     addDocumentationOption(
         "server_urls",
-        "The Elastic https://www.elastic.co/guide/en/apm/agent/java/current/config-reporter.html#config-server-urls[`server_urls`] option has no equivalent OpenTelemetry option - you can only specify one endpoint. Use https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint[OTEL_EXPORTER_OTLP_ENDPOINT] instead.");
+        "The Elastic [`server_urls`](https://www.elastic.co/guide/en/apm/agent/java/current/config-reporter.html#config-server-urls) option has no equivalent OpenTelemetry option - you can only specify one endpoint. Use [OTEL_EXPORTER_OTLP_ENDPOINT](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint) instead.");
     addDocumentationOption(
         "secret_token",
-        "The Elastic https://www.elastic.co/guide/en/apm/agent/java/current/config-reporter.html#config-secret-token[`secret_token`] option corresponds to the OpenTelemetry https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers[OTEL_EXPORTER_OTLP_HEADERS] option. For example: `OTEL_EXPORTER_OTLP_HEADERS=\"Authorization=Bearer an_apm_secret_token\"`.");
+        "The Elastic [`secret_token`](https://www.elastic.co/guide/en/apm/agent/java/current/config-reporter.html#config-secret-token) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option. For example: `OTEL_EXPORTER_OTLP_HEADERS=\"Authorization=Bearer an_apm_secret_token\"`.");
     addDocumentationOption(
         "api_key",
-        "The Elastic https://www.elastic.co/guide/en/apm/agent/java/current/config-reporter.html#config-api-key[`api_key`] option corresponds to the OpenTelemetry https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers[OTEL_EXPORTER_OTLP_HEADERS] option. For example:`OTEL_EXPORTER_OTLP_HEADERS=\"Authorization=ApiKey an_api_key\"`.");
+        "The Elastic [`api_key`](https://www.elastic.co/guide/en/apm/agent/java/current/config-reporter.html#config-api-key) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option. For example:`OTEL_EXPORTER_OTLP_HEADERS=\"Authorization=ApiKey an_api_key\"`.");
     addDocumentationOption(
         "service_name",
-        "The Elastic https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-service-name[`service_name`] option corresponds to the OpenTelemetry https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_service_name[OTEL_SERVICE_NAME] option. The service name value can also be set using https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes[OTEL_RESOURCE_ATTRIBUTES], for example, `OTEL_RESOURCE_ATTRIBUTES=service.name=myservice`. If `OTEL_SERVICE_NAME` is set, it takes precedence over the resource attribute.");
+        "The Elastic [`service_name`](https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-service-name) option corresponds to the OpenTelemetry [OTEL_SERVICE_NAME](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_service_name) option. The service name value can also be set using [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). For example: `OTEL_RESOURCE_ATTRIBUTES=service.name=myservice`. If `OTEL_SERVICE_NAME` is set, it takes precedence over the resource attribute.");
     addDocumentationOption(
         "enabled",
-        "The Elastic https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-enabled[`enabled`] option corresponds to the OpenTelemetry https://opentelemetry.io/docs/languages/java/automatic/agent-config/#suppressing-specific-auto-instrumentation[OTEL_JAVAAGENT_ENABLED] option.");
+        "The Elastic [`enabled`](https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-enabled) option corresponds to the OpenTelemetry [OTEL_JAVAAGENT_ENABLED](https://opentelemetry.io/docs/languages/java/automatic/agent-config/#suppressing-specific-auto-instrumentation) option.");
     addDocumentationOption(
         "service_version",
-        "The Elastic https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-service-version[`service_version`] option corresponds to setting the `service.version` key in https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes[OTEL_RESOURCE_ATTRIBUTES]. For example: `OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3`.");
+        "The Elastic [`service_version`](https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-service-version) option corresponds to setting the `service.version` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). For example: `OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3`.");
     addDocumentationOption(
         "environment",
-        "The Elastic https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-environment[`environment`] option corresponds to setting the `deployment.environment` key in https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes[OTEL_RESOURCE_ATTRIBUTES]. For example: `OTEL_RESOURCE_ATTRIBUTES=deployment.environment=testing`.");
+        "The Elastic [`environment`](https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-environment) option corresponds to setting the `deployment.environment` key in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). For example: `OTEL_RESOURCE_ATTRIBUTES=deployment.environment=testing`.");
     addDocumentationOption(
         "global_labels",
-        "The Elastic https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-global-labels[`global_labels`] option corresponds to adding `key=value` comma separated pairs in https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes[OTEL_RESOURCE_ATTRIBUTES]. For example: `OTEL_RESOURCE_ATTRIBUTES=alice=first,bob=second`. Such labels will result in labels.key=value attributes on the server, eg labels.alice=first");
+        "The Elastic [`global_labels`](https://www.elastic.co/guide/en/apm/agent/java/current/config-core.html#config-global-labels) option corresponds to adding `key=value` comma separated pairs in [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes). For example: `OTEL_RESOURCE_ATTRIBUTES=alice=first,bob=second`. Such labels will result in labels.key=value attributes on the server, e.g. labels.alice=first");
     addUnspecifiedOption("log_level");
     addUnspecifiedOption("log_file");
     addUnspecifiedOption("log_file_size");

diff --git a/custom/src/test/java/co/elastic/otel/config/ConfigurationExporterTest.java b/custom/src/test/java/co/elastic/otel/config/ConfigurationExporterTest.java
@@ -43,7 +43,7 @@ public class ConfigurationExporterTest {
 
   @BeforeEach
   void setUp() {
-    currentDocumentationPath = Paths.get("../docs/configure.asciidoc");
+    currentDocumentationPath = Paths.get("../docs/migrate.md");
   }
 
   /**
@@ -69,7 +69,7 @@ void testGeneratedConfigurationDocsAreUpToDate() throws IOException, TemplateExc
 
     assertThat(renderedDocumentation)
         .withFailMessage(
-            "The rendered configuration documentation (/docs/configure.asciidoc) is not up-to-date.\n"
+            "The rendered configuration documentation (/docs/migrate.md) is not up-to-date.\n"
                 + "If you see this error, it means you have to execute the tests locally with overwrite enabled "
                 + "(gradlew.bat clean :custom:test --tests \"*ConfigurationExporterTest\" -Pelastic.otel.overwrite.config.docs=true) "
                 + "which will update the rendered docs (and then you probably need to commit the change).\n")
@@ -84,14 +84,13 @@ static String renderDocumentation(List<ConfigurationOption> configurationRegistr
     cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
     cfg.setLogTemplateExceptions(false);
 
-    Template temp = cfg.getTemplate("configure.asciidoc.ftl");
+    Template temp = cfg.getTemplate("migrate.md.ftl");
     StringWriter tempRenderedFile = new StringWriter();
     tempRenderedFile.write(
-        "[[configure]]\n"
-            + "== Configure\n\n"
-            + "////\n"
-            + "This file is auto generated. Please only make changes in `configure.asciidoc.ftl`\n"
-            + "////\n");
+        "# Migrate to the Elastic distribution\n\n"
+            + "<!--\n"
+            + "This file is auto generated. Please only make changes in `migrate.md.ftl`\n"
+            + "-->\n");
     final Map<String, List<ConfigurationOption>> optionsByCategory = new HashMap<>();
     optionsByCategory.put("Elastic to OpenTelemetry mapping", configurationRegistry);
     Map<String, Object> map = new HashMap<>();

diff --git a/custom/src/test/resources/configure.asciidoc.ftl b/custom/src/test/resources/configure.asciidoc.ftl
diff --git a/custom/src/test/resources/migrate.md.ftl b/custom/src/test/resources/migrate.md.ftl
@@ -0,0 +1,38 @@
+<#-- @ftlvariable name="config" type="java.util.Map<java.lang.String,java.util.List<co.elastic.otel.config.ConfigurationOption>>" -->
+<#-- @ftlvariable name="keys" type="java.util.Collection<java.lang.String>" -->
+
+This documentation describes how to update applications using the [Elastic APM Java agent](https://www.elastic.co/guide/en/apm/agent/java/current/index.html) to use the Elastic Distribution of OpenTelemetry Java (EDOT Java).
+
+Start by installing EDOT Java following the steps outlined in [Get started](./get-started.md). Then update existing APM Java agent configuration options in your application with the equivalent [OpenTelemetry SDK configuration variables](https://opentelemetry.io/docs/languages/sdk-configuration/general/) (listed below).
+
+## Option reference
+
+This is a list of all APM Java agent configuration options grouped by their category.
+Select one of the following for more information.
+
+<#list config as category, options>
+    <#list options as option>
+* [${option.key}](#${option.key})
+    </#list>
+</#list>
+
+<#list config as category, options>
+## ${category}
+
+    <#list options as option>
+### `${option.key}`${option.tags?has_content?then(" (${option.tags?join(' ')})", '')}
+
+${option.description}
+
+<!--
+This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter.
+-->
+
+    </#list>
+</#list>
+
+<#macro defaultValue option>${option.defaultValueAsString?has_content?then("${option.defaultValueAsString?replace(',([^\\\\s])', ', $1', 'r')}", '<none>')}</#macro>
+
+<#list config as category, options>
+<!-- ${category} -->
+</#list>