From 9b38831b2049b1cc26306eb49c80f46e387e1f23 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 10 Jul 2024 17:56:44 -0500 Subject: [PATCH 01/25] initial outline --- docs/configuration.asciidoc | 41 +++++++++++++++++++++++++++++++++ docs/configure.asciidoc | 12 ++++++++++ docs/get-started.asciidoc | 30 ++++++++++++++++++++---- docs/index.asciidoc | 3 ++- docs/intro.asciidoc | 46 +++++++++++++++++++++++++++++++++++++ docs/landing-page.asciidoc | 28 ---------------------- 6 files changed, 127 insertions(+), 33 deletions(-) create mode 100644 docs/configuration.asciidoc create mode 100644 docs/intro.asciidoc delete mode 100644 docs/landing-page.asciidoc diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc new file mode 100644 index 00000000..13939e3b --- /dev/null +++ b/docs/configuration.asciidoc @@ -0,0 +1,41 @@ +[[configuration-options]] +== Configuration options + +//// +Are there Elastic-specific custom configuration options +in addition to the general OpenTelemetry SDK +configuration options? Or are all the customizations +"behind the scenes"? + +If there are custom configuration options, +use the following outline... +//// + +//// +Is this true? Is the distro a wrapper around the OpenTelemetry Java agent +which is a wrapper around the general OpenTelemetry SDK? πŸŒ€ +//// +Because the Elastic Distribution for OpenTelemetry Java (the distro) is a wrapper around the https://github.com/open-telemetry/opentelemetry-java-instrumentation[OpenTelemetry Java agent], it supports both: + +* General OpenTelemetry SDK configuration options +* Elastic-specific configuration options that are only available when using the distro + +[discrete] +[[configure-otel-sdk-options]] +=== OpenTelemetry SDK configuration options + +//// +Is this true? Are there any options that aren't supported? +Any options that shouldn't be used? +//// +The distro supports all configuration options listed in the https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry General SDK Configuration documentation]. + +[discrete] +[[configure-distro-options]] +=== Elastic-specific configuration options + +The distro supports the following custom options: + +//// +List of configuration options? +//// diff --git a/docs/configure.asciidoc b/docs/configure.asciidoc index 524274ca..da04145e 100644 --- a/docs/configure.asciidoc +++ b/docs/configure.asciidoc @@ -1,3 +1,15 @@ +//// +I'm confused about the goal of this doc. + +With a title like "Configure" I expected to see a list of the +valid configuration options. Instead it seems to be a list of +APM Java agent configuration options, and how to update them +to migrate from the agent to the distro. + +Is that the intention of this doc? To be a migration guide from +the APM Java agent to the Elastic Distribution for OpenTelemetry Java? +//// + [[configure]] == Configure diff --git a/docs/get-started.asciidoc b/docs/get-started.asciidoc index 8fc57109..dd5a7fe8 100644 --- a/docs/get-started.asciidoc +++ b/docs/get-started.asciidoc @@ -3,12 +3,21 @@ This guide shows you how to use the Elastic Distribution for OpenTelemetry Java to instrument your Java application and send OpenTelemetry data to an Elastic Observability deployment. +//// +[discrete] +[[get-started-prereq]] +=== Prerequisites + +Do they need anything else before they install? +An Elastic Observability deployment? +//// + [discrete] [[get-started-install]] === Install -. Download the latest release https://mvnrepository.com/artifact/co.elastic.otel/elastic-otel-javaagent/latest[here]. -. Run the distro by using the `-javaagent:` JVM argument with the path to the distro jar: +. Download the https://mvnrepository.com/artifact/co.elastic.otel/elastic-otel-javaagent/latest[latest release]. +. Run the distro using the `-javaagent:` JVM argument with the path to the distro jar: + [source,bash] ---- @@ -16,8 +25,21 @@ java -javaagent:/path/to/agent.jar \ -jar myapp.jar ---- +//// +What should they expect to see after running this? +How do they know it worked as expected? +//// + +//// +Are there any configuration options that are required? +If yes, should we call those out here in "getting started" +in addition to having them in the generated configuration +reference page? +//// + [discrete] [[get-started-configure]] -=== Configure +=== Next steps -See <>. +* <> to send data to Elastic. +* Learn more about viewing and interpreting data in the {observability-guide}/apm.html[Observability guide]. diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 87f98036..6f085baa 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -9,7 +9,8 @@ endif::[] = Elastic Distribution for OpenTelemetry Java ifndef::env-github[] -include::./landing-page.asciidoc[] +include::./intro.asciidoc[] include::./get-started.asciidoc[] +include::./configuration.asciidoc[] include::./configure.asciidoc[] endif::[] diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc new file mode 100644 index 00000000..98f2d01b --- /dev/null +++ b/docs/intro.asciidoc @@ -0,0 +1,46 @@ +[[intro]] +== Elastic Distribution for OpenTelemetry Java + +++++ +Introduction +++++ + +:language: Java +:language_lc: java + +.Alpha release +[WARNING] +==== +This project 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 https://github.com/elastic/elastic-otel-{language_lc}/issues[opening a GitHub issue] or starting a discussion thread on the https://discuss.elastic.co/tags/c/observability/apm/58/{language_lc}[Elastic Discuss forum]. +==== + +//// +What is it? +//// +The Elastic Distribution for OpenTelemetry {language} ("the distro") is a {language} package that provides: + +* An easy way to instrument your application with OpenTelemetry. +* Configuration defaults for best usage. + +A _distribution_ is a wrapper around an upstream OpenTelemetry repository with some customizations. In the Elastic Distribution for OpenTelemetry {language}, customizations include: +//// +Why use it? +//// +* Using Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like Elastic APM server. +* Preconfiguring the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. +* Ensuring that the OpenTelemetry protocol (OTLP) exporter is enabled by default. + +NOTE: For more details about OpenTelemetry distributions in general, visit the https://opentelemetry.io/docs/concepts/distributions[OpenTelemetry documentation]. + +//// +How to use it? +//// +Use the Distro to start the OpenTelemetry SDK with your {language} application to automatically capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent to any OTLP collector you choose. + +Start with helpful defaults to begin collecting and exporting OpenTelemetry signals quickly. Then, further refine how you use the Distro using extension methods that allow you to fully control the creation of the underlying tracer and metric providers. + +After you start sending data to Elastic, use an {observability-guide}/index.html[Elastic Observability] deployment -- hosted on Elastic Cloud or on-premises -- to monitor your applications, create alerts, and quickly identify root causes of service issues. \ No newline at end of file diff --git a/docs/landing-page.asciidoc b/docs/landing-page.asciidoc deleted file mode 100644 index ca7b0996..00000000 --- a/docs/landing-page.asciidoc +++ /dev/null @@ -1,28 +0,0 @@ -[[landing-page]] -== Elastic Distribution for OpenTelemetry Java - -++++ -Introduction -++++ - -.Alpha release -[WARNING] -==== -This project 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 https://github.com/elastic/elastic-otel-java/issues[opening an issue] or starting a discussion thread on the https://discuss.elastic.co/tags/c/observability/apm/58/java[Elastic Discuss forum]. -==== - -The Elastic Distribution for OpenTelemetry Java (the "Distro") is a Java -package that provides: - -* an easy way to instrument your application with OpenTelemetry -* configuration defaults for best usage - -Use the Distro to start the OpenTelemetry SDK with your Java application to automatically -capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent -to any OTLP collector you choose. Use an https://www.elastic.co/observability[Elastic Observability] -deployment–hosted in Elastic's cloud or on-premises–to monitor your applications, create alerts, -and quickly identify root causes of service issues. \ No newline at end of file From e44e2a2ee2315976ca3b00b730ab112e9249879f Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 12 Jul 2024 13:29:07 -0500 Subject: [PATCH 02/25] align with other distro docs --- docs/configuration.asciidoc | 10 +++++++ docs/configure.asciidoc | 11 ++++++++ docs/get-started.asciidoc | 55 +++++++++++++++++++++++++++++++----- docs/index.asciidoc | 2 +- docs/intro.asciidoc | 35 +++++++++++------------ docs/release-status.asciidoc | 9 ++++++ 6 files changed, 96 insertions(+), 26 deletions(-) create mode 100644 docs/release-status.asciidoc diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc index 13939e3b..f797a5d5 100644 --- a/docs/configuration.asciidoc +++ b/docs/configuration.asciidoc @@ -1,6 +1,12 @@ [[configuration-options]] == Configuration options +:language: Java +:language_lc: java +:distro_name: Elastic Distribution for OpenTelemetry {language} + +include::release-status.asciidoc[] + //// Are there Elastic-specific custom configuration options in addition to the general OpenTelemetry SDK @@ -39,3 +45,7 @@ The distro supports the following custom options: //// List of configuration options? //// + +:!language: +:!language_lc: +:!distro_name: diff --git a/docs/configure.asciidoc b/docs/configure.asciidoc index da04145e..09a0afe7 100644 --- a/docs/configure.asciidoc +++ b/docs/configure.asciidoc @@ -13,6 +13,17 @@ the APM Java agent to the Elastic Distribution for OpenTelemetry Java? [[configure]] == Configure +// I'll add this to the automation if we're sure we want this on every page. +:language: Java +:language_lc: java +:distro_name: Elastic Distribution for OpenTelemetry {language} + +include::release-status.asciidoc[] + +:!language: +:!language_lc: +:!distro_name: + //// This file is auto generated. Please only make changes in `configure.asciidoc.ftl` //// diff --git a/docs/get-started.asciidoc b/docs/get-started.asciidoc index dd5a7fe8..46dad86f 100644 --- a/docs/get-started.asciidoc +++ b/docs/get-started.asciidoc @@ -1,21 +1,44 @@ [[get-started]] == Get started -This guide shows you how to use the Elastic Distribution for OpenTelemetry Java to instrument your Java application and send OpenTelemetry data to an Elastic Observability deployment. +:language: Java +:language_lc: java +:distro_name: Elastic Distribution for OpenTelemetry {language} +include::release-status.asciidoc[] + +This guide shows you how to use the Elastic Distribution for OpenTelemetry {language} ("the distro") to instrument your {language} application and send OpenTelemetry data to an Elastic Observability deployment. + +//// +What does a user need to know and/or do before they install the distro? //// [discrete] [[get-started-prereq]] === Prerequisites -Do they need anything else before they install? -An Elastic Observability deployment? +Before getting started: + +// Familiarity with OpenTelemetry +* *Familiarize yourself with the OpenTelemetry SDK.* The distro is a lightweight wrapper around the OpenTelemetry SDK. You should be broadly familiar with the OpenTelemetry SDK concepts and instrumenting applications using the Microsoft diagnostic APIs. If you are not familiar with this, start with the https://opentelemetry.io/docs/languages/net[OpenTelemetry SDK documentation]. + +//// +// Examples: +// +// Any dependencies (including supported versions) +// Elastic Observability deployment +// Other //// +//// +How does a user install the distro? +//// [discrete] [[get-started-install]] === Install +//// +Step-by-step instructions +//// . Download the https://mvnrepository.com/artifact/co.elastic.otel/elastic-otel-javaagent/latest[latest release]. . Run the distro using the `-javaagent:` JVM argument with the path to the distro jar: + @@ -26,20 +49,38 @@ java -javaagent:/path/to/agent.jar \ ---- //// -What should they expect to see after running this? -How do they know it worked as expected? +Any additional info related to installation //// +[NOTE] +.The Elastic distro and the OpenTelemetry SDK +==== +The distro includes a transitive dependency on the OpenTelemetry SDK, so you do not _need_ to add the +OpenTelemetry SDK package to your project directly. However, you _can_ explicitly add the OpenTelemetry SDK as a dependency if you want to opt into newer SDK versions. If you do this, the OpenTelemetry SDK dependency must +be defined _before_ the Elastic OpenTelemetry Distribution for .NET is defined. +==== //// -Are there any configuration options that are required? +Are there any configuration options that are _required_? If yes, should we call those out here in "getting started" in addition to having them in the generated configuration reference page? //// +//// +What should they expect to see after running this? +How do they know it worked as expected? +//// + +//// +What should they do next? +//// [discrete] -[[get-started-configure]] +[[get-started-next-steps]] === Next steps * <> to send data to Elastic. * Learn more about viewing and interpreting data in the {observability-guide}/apm.html[Observability guide]. + +:!language: +:!language_lc: +:!distro_name: diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 6f085baa..905697fe 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -3,7 +3,7 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[] ifdef::env-github[] NOTE: For the best reading experience, -please view this documentation at https://www.elastic.co/guide/en/apm/agent/java[elastic.co] +please view this documentation at https://www.elastic.co/guide/en/apm/open-telemetry/java[elastic.co] endif::[] = Elastic Distribution for OpenTelemetry Java diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc index 98f2d01b..b84b4a53 100644 --- a/docs/intro.asciidoc +++ b/docs/intro.asciidoc @@ -7,40 +7,39 @@ :language: Java :language_lc: java +:distro_name: Elastic Distribution for OpenTelemetry {language} -.Alpha release -[WARNING] -==== -This project 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 https://github.com/elastic/elastic-otel-{language_lc}/issues[opening a GitHub issue] or starting a discussion thread on the https://discuss.elastic.co/tags/c/observability/apm/58/{language_lc}[Elastic Discuss forum]. -==== +include::release-status.asciidoc[] //// -What is it? +Intro //// -The Elastic Distribution for OpenTelemetry {language} ("the distro") is a {language} package that provides: +The {distro_name} ("the distro") is a {language} package that provides: * An easy way to instrument your application with OpenTelemetry. * Configuration defaults for best usage. -A _distribution_ is a wrapper around an upstream OpenTelemetry repository with some customizations. In the Elastic Distribution for OpenTelemetry {language}, customizations include: //// +What is it? Why use it? //// -* Using Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like Elastic APM server. -* Preconfiguring the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. -* Ensuring that the OpenTelemetry protocol (OTLP) exporter is enabled by default. +A _distribution_ is a wrapper around an upstream OpenTelemetry repository with some customizations. The {distro_name} is a wrapper around the https://opentelemetry.io/docs/languages/{language_lc}[OpenTelemetry SDK for {language}] and includes the following customizations: + +* Uses Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like Elastic APM server. +* Preconfigures the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. +* Ensures that the OpenTelemetry protocol (OTLP) exporter is enabled by default. NOTE: For more details about OpenTelemetry distributions in general, visit the https://opentelemetry.io/docs/concepts/distributions[OpenTelemetry documentation]. //// How to use it? //// -Use the Distro to start the OpenTelemetry SDK with your {language} application to automatically capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent to any OTLP collector you choose. +Use the distro to start the OpenTelemetry SDK with your {language} application to automatically capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent to any OTLP collector you choose. + +Start with helpful defaults to begin collecting and exporting OpenTelemetry signals quickly. Then, further refine how you use the distro using extension methods that allow you to fully control the creation of the underlying tracer and metric providers. -Start with helpful defaults to begin collecting and exporting OpenTelemetry signals quickly. Then, further refine how you use the Distro using extension methods that allow you to fully control the creation of the underlying tracer and metric providers. +After you start sending data to Elastic, use an {observability-guide}/index.html[Elastic Observability] deployment -- hosted on Elastic Cloud or on-premises -- to monitor your applications, create alerts, and quickly identify root causes of service issues. -After you start sending data to Elastic, use an {observability-guide}/index.html[Elastic Observability] deployment -- hosted on Elastic Cloud or on-premises -- to monitor your applications, create alerts, and quickly identify root causes of service issues. \ No newline at end of file +:!language: +:!language_lc: +:!distro_name: diff --git a/docs/release-status.asciidoc b/docs/release-status.asciidoc new file mode 100644 index 00000000..4d99f5aa --- /dev/null +++ b/docs/release-status.asciidoc @@ -0,0 +1,9 @@ +.Alpha release +[WARNING] +==== +The {distro_name} 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 https://github.com/elastic/elastic-otel-{language_lc}/issues[opening a GitHub issue] or starting a discussion thread on the https://discuss.elastic.co/tags/c/observability/apm/58/{language_lc}[Elastic Discuss forum]. +==== From 24a80bb35b36432aaec9f32afc2305cf9f6823b4 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Mon, 15 Jul 2024 17:08:19 -0500 Subject: [PATCH 03/25] align with other languages --- docs/configuration.asciidoc | 104 ++++++++++++++++++++++++++++++----- docs/configure.asciidoc | 6 +- docs/get-started.asciidoc | 106 ++++++++++++++++++++++++++++++++---- docs/intro.asciidoc | 9 +++ 4 files changed, 198 insertions(+), 27 deletions(-) diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc index f797a5d5..d4b8eba8 100644 --- a/docs/configuration.asciidoc +++ b/docs/configuration.asciidoc @@ -1,5 +1,14 @@ -[[configuration-options]] -== Configuration options +//// +Goal of this doc: +Provide a complete reference of all available configuration options and where/how they can be set. (Any Elastic-specific configuration options are listed directly. General OpenTelemetry configuration options are linked.) + +Assumptions we're comfortable making about the reader: +* They are familiar with Elastic +* They are familiar with OpenTelemetry +//// + +[[configuration]] +== Configure :language: Java :language_lc: java @@ -8,15 +17,28 @@ include::release-status.asciidoc[] //// -Are there Elastic-specific custom configuration options -in addition to the general OpenTelemetry SDK -configuration options? Or are all the customizations -"behind the scenes"? +How do users set configuration options? +//// +[discrete] +[[configure-methods]] +=== Configuration methods -If there are custom configuration options, -use the following outline... +//// +Are there multiple ways to set configuration options? +For example, can they use environment variables OR a config file? +If there are, what are they and why would you use each method? +Where/how do you use each method? +Provide an example to illustrate the syntax. //// +//// +If configuration options are defined using multiple methods, which one takes precedence over the other(s)? +//// + +[discrete] +[[configuration-options]] +=== Configuration options + //// Is this true? Is the distro a wrapper around the OpenTelemetry Java agent which is a wrapper around the general OpenTelemetry SDK? πŸŒ€ @@ -28,24 +50,80 @@ Because the Elastic Distribution for OpenTelemetry Java (the distro) is a wrappe [discrete] [[configure-otel-sdk-options]] -=== OpenTelemetry SDK configuration options +==== OpenTelemetry SDK configuration options //// -Is this true? Are there any options that aren't supported? +Is this true? +Are there any options that aren't supported? Any options that shouldn't be used? //// The distro supports all configuration options listed in the https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry General SDK Configuration documentation]. +//// +Are there Elastic-specific custom configuration options +in addition to the general OpenTelemetry SDK +configuration options? Or are all the customizations +"behind the scenes"? +If not, you can delete this section. +//// [discrete] [[configure-distro-options]] -=== Elastic-specific configuration options +==== Elastic-specific configuration options + +The distro supports the following Elastic-specific options: + +//// +List config options +//// + +//// +Are there multiple authentication methods when sending data to Elastic? +If not, delete this section. +//// +[discrete] +[[configure-auth-methods]] +=== Authentication methods + +When sending data to Elastic, there are two ways you can authenticate: using a secret token or using an APM agent key. + +[discrete] +[[configure-secret-token]] +==== Use a secret token + +// What is this? +// ?? + +// Why would you choose this method? +// ?? + +// How do you authenticate using this method? +// ?? + +[discrete] +[[configure-api-key]] +==== Use an APM agent key (API key) -The distro supports the following custom options: +// What is this? +It is also possible to authenticate to an Elastic Observability endpoint using +an _APM agent key_. These are revocable API keys. + +// Why would you choose this method? +// ?? + +// How do you authenticate using this method? +To create and manage APM Agent keys in Kibana: + +. Go to *APM Settings*. +. Select the *Agent Keys* tab. + +When using an APM Agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using a +different auth schema (`ApiKey` rather than `Bearer`). For example: //// -List of configuration options? +Code example //// + :!language: :!language_lc: :!distro_name: diff --git a/docs/configure.asciidoc b/docs/configure.asciidoc index 09a0afe7..27a6826f 100644 --- a/docs/configure.asciidoc +++ b/docs/configure.asciidoc @@ -6,12 +6,12 @@ valid configuration options. Instead it seems to be a list of APM Java agent configuration options, and how to update them to migrate from the agent to the distro. -Is that the intention of this doc? To be a migration guide from -the APM Java agent to the Elastic Distribution for OpenTelemetry Java? +Is the intention of this doc to be a migration guide from the APM Java +agent to the Elastic Distribution for OpenTelemetry Java? //// [[configure]] -== Configure +== Migrate? // I'll add this to the automation if we're sure we want this on every page. :language: Java diff --git a/docs/get-started.asciidoc b/docs/get-started.asciidoc index 46dad86f..f73a3a37 100644 --- a/docs/get-started.asciidoc +++ b/docs/get-started.asciidoc @@ -1,3 +1,13 @@ +//// +Goal of this doc: +The user is able to successfully see data from their Java application make it to the Elastic UI via the Elastic Distribution for OpenTelemetry Java + +Assumptions we're comfortable making about the reader: +* They are familiar with Elastic +* They are familiar with OpenTelemetry +* They have Java installed +//// + [[get-started]] == Get started @@ -9,24 +19,42 @@ include::release-status.asciidoc[] This guide shows you how to use the Elastic Distribution for OpenTelemetry {language} ("the distro") to instrument your {language} application and send OpenTelemetry data to an Elastic Observability deployment. +//// +Is this true? +//// +[NOTE] +==== +As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint (for example, an https://opentelemetry.io/docs/collector/[OpenTelemetry Collector]). +==== + //// What does a user need to know and/or do before they install the distro? //// [discrete] -[[get-started-prereq]] +[[get-started-prerequisites]] === Prerequisites Before getting started: // Familiarity with OpenTelemetry * *Familiarize yourself with the OpenTelemetry SDK.* The distro is a lightweight wrapper around the OpenTelemetry SDK. You should be broadly familiar with the OpenTelemetry SDK concepts and instrumenting applications using the Microsoft diagnostic APIs. If you are not familiar with this, start with the https://opentelemetry.io/docs/languages/net[OpenTelemetry SDK documentation]. ++ +* *Set up Elastic Observability*. You'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an https://www.elastic.co/observability[Elastic Observability] cloud deployment. You can use an existing one or set up a new one. ++ +[[elastic-observability-setup]] +[%collapsible] +.*Expand for setup instructions* +==== +This section shows how to create an https://www.elastic.co/observability[Elastic Observability] cloud deployment and get the data you need to configure the distro to send data to it. + +. Register at https://cloud.elastic.co/registration[cloud.elastic.co], if you haven't already. This supports starting **free trial**. +. After registering, click *Create deployment* at ``. +. Once that is created, click *Open* to visit your Kibana home page, e.g. `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`. +==== //// -// Examples: -// -// Any dependencies (including supported versions) -// Elastic Observability deployment -// Other +// Other examples of prereqs: +// Any dependencies (including specific supported Java versions)? //// //// @@ -39,6 +67,8 @@ How does a user install the distro? //// Step-by-step instructions //// +To get started with the distro: + . Download the https://mvnrepository.com/artifact/co.elastic.otel/elastic-otel-javaagent/latest[latest release]. . Run the distro using the `-javaagent:` JVM argument with the path to the distro jar: + @@ -56,20 +86,74 @@ Any additional info related to installation ==== The distro includes a transitive dependency on the OpenTelemetry SDK, so you do not _need_ to add the OpenTelemetry SDK package to your project directly. However, you _can_ explicitly add the OpenTelemetry SDK as a dependency if you want to opt into newer SDK versions. If you do this, the OpenTelemetry SDK dependency must -be defined _before_ the Elastic OpenTelemetry Distribution for .NET is defined. +be defined _before_ the {distro_name} is defined. ==== //// +What does the user need to do in their application to prepare to send data to Elastic? +//// +[discrete] +[[get-started-send-data]] +=== Send data to Elastic + +After installing the distro, configure and initialize it to start +sending data to Elastic. + +//// +Are there any dependencies that need to be installed in addition to the distro? +If yes, does it matter in what order dependencies are defined? +If no, delete this section. +//// +[discrete] +[[get-started-add-dependencies]] +==== Add dependencies + +//// +Step-by-step instructions +//// + +//// +What does the _minimal_ configuration / setup look like? Are there any configuration options that are _required_? -If yes, should we call those out here in "getting started" -in addition to having them in the generated configuration -reference page? +//// +[discrete] +[[get-started-configure]] +==== Configure the distro + +//// +Step-by-step instructions +//// + +//// +Does the user need to do something after configuring the distro +for data to start being sent Elastic? +If no, delete this section. +//// +[discrete] +[[get-started-initialization]] +==== Initialize the distro + +//// +Step-by-step instructions +//// + +//// +Optional: Add an image //// //// What should they expect to see after running this? How do they know it worked as expected? //// +[discrete] +[[get-started-view-traces]] +=== View traces + +To view the traces, you can use the Elastic APM UI: + +//// +Step-by-step instructions +//// //// What should they do next? @@ -78,7 +162,7 @@ What should they do next? [[get-started-next-steps]] === Next steps -* <> to send data to Elastic. +* <> to send data to Elastic. * Learn more about viewing and interpreting data in the {observability-guide}/apm.html[Observability guide]. :!language: diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc index b84b4a53..49466901 100644 --- a/docs/intro.asciidoc +++ b/docs/intro.asciidoc @@ -1,3 +1,12 @@ +//// +Goal of this doc: +Provide all the information a user needs to determine if the product is a good enough fit for their use case to merit further exploration + +Assumptions we're comfortable making about the reader: +* They are familiar with Elastic +* They are familiar with OpenTelemetry +//// + [[intro]] == Elastic Distribution for OpenTelemetry Java From ca8fc23de2cf0536276b37f7d7de57188afc3ba8 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 17 Jul 2024 14:55:27 -0500 Subject: [PATCH 04/25] clean up code comments, align with other distro docs --- docs/configuration.asciidoc | 30 ++++++++++++++++-------------- docs/get-started.asciidoc | 26 ++++++++++++++------------ docs/intro.asciidoc | 8 ++++---- 3 files changed, 34 insertions(+), 30 deletions(-) diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc index d4b8eba8..b32772e8 100644 --- a/docs/configuration.asciidoc +++ b/docs/configuration.asciidoc @@ -17,13 +17,14 @@ Assumptions we're comfortable making about the reader: include::release-status.asciidoc[] //// -How do users set configuration options? +TO DO: How do users set configuration options? //// [discrete] [[configure-methods]] === Configuration methods //// +TO DO: Are there multiple ways to set configuration options? For example, can they use environment variables OR a config file? If there are, what are they and why would you use each method? @@ -32,18 +33,16 @@ Provide an example to illustrate the syntax. //// //// -If configuration options are defined using multiple methods, which one takes precedence over the other(s)? +TO DO: +If configuration options are defined using multiple methods, +which one takes precedence over the other(s)? //// [discrete] [[configuration-options]] === Configuration options -//// -Is this true? Is the distro a wrapper around the OpenTelemetry Java agent -which is a wrapper around the general OpenTelemetry SDK? πŸŒ€ -//// -Because the Elastic Distribution for OpenTelemetry Java (the distro) is a wrapper around the https://github.com/open-telemetry/opentelemetry-java-instrumentation[OpenTelemetry Java agent], it supports both: +Because the Elastic Distribution for OpenTelemetry Java ("the distro") is an extension of the https://github.com/open-telemetry/opentelemetry-java-instrumentation[OpenTelemetry Java agent], it supports both: * General OpenTelemetry SDK configuration options * Elastic-specific configuration options that are only available when using the distro @@ -53,6 +52,7 @@ Because the Elastic Distribution for OpenTelemetry Java (the distro) is a wrappe ==== OpenTelemetry SDK configuration options //// +TO DO: Is this true? Are there any options that aren't supported? Any options that shouldn't be used? @@ -60,6 +60,7 @@ Any options that shouldn't be used? The distro supports all configuration options listed in the https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry General SDK Configuration documentation]. //// +TO DO: Are there Elastic-specific custom configuration options in addition to the general OpenTelemetry SDK configuration options? Or are all the customizations @@ -77,6 +78,7 @@ List config options //// //// +TO DO: Are there multiple authentication methods when sending data to Elastic? If not, delete this section. //// @@ -90,27 +92,27 @@ When sending data to Elastic, there are two ways you can authenticate: using a s [[configure-secret-token]] ==== Use a secret token -// What is this? +// TO DO: What is this? // ?? -// Why would you choose this method? +// TO DO:Why would you choose this method? // ?? -// How do you authenticate using this method? +// TO DO:How do you authenticate using this method? // ?? [discrete] [[configure-api-key]] ==== Use an APM agent key (API key) -// What is this? +// βœ… What is this? It is also possible to authenticate to an Elastic Observability endpoint using an _APM agent key_. These are revocable API keys. -// Why would you choose this method? +// TO DO: Why would you choose this method? // ?? -// How do you authenticate using this method? +// βœ… How do you authenticate using this method? To create and manage APM Agent keys in Kibana: . Go to *APM Settings*. @@ -120,7 +122,7 @@ When using an APM Agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using a different auth schema (`ApiKey` rather than `Bearer`). For example: //// -Code example +TO DO: Code example //// diff --git a/docs/get-started.asciidoc b/docs/get-started.asciidoc index f73a3a37..e8e293e2 100644 --- a/docs/get-started.asciidoc +++ b/docs/get-started.asciidoc @@ -19,16 +19,13 @@ include::release-status.asciidoc[] This guide shows you how to use the Elastic Distribution for OpenTelemetry {language} ("the distro") to instrument your {language} application and send OpenTelemetry data to an Elastic Observability deployment. -//// -Is this true? -//// [NOTE] ==== -As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint (for example, an https://opentelemetry.io/docs/collector/[OpenTelemetry Collector]). +As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint (https://opentelemetry.io/docs/collector/[OpenTelemetry Collector]), but this guide assumes you are sending data to Elastic. ==== //// -What does a user need to know and/or do before they install the distro? +βœ… What the user needs to know and/or do before they install the distro //// [discrete] [[get-started-prerequisites]] @@ -53,19 +50,20 @@ This section shows how to create an https://www.elastic.co/observability[Elastic ==== //// -// Other examples of prereqs: -// Any dependencies (including specific supported Java versions)? +TO DO: +Anything else they need to do/have/know? +For example, any dependencies (including specific supported Java versions)? //// //// -How does a user install the distro? +βœ… How to install the distro //// [discrete] [[get-started-install]] === Install //// -Step-by-step instructions +βœ… Step-by-step instructions //// To get started with the distro: @@ -79,7 +77,7 @@ java -javaagent:/path/to/agent.jar \ ---- //// -Any additional info related to installation +βœ… Any additional info related to installation //// [NOTE] .The Elastic distro and the OpenTelemetry SDK @@ -90,7 +88,7 @@ be defined _before_ the {distro_name} is defined. ==== //// -What does the user need to do in their application to prepare to send data to Elastic? +βœ… Start-to-finish operation //// [discrete] [[get-started-send-data]] @@ -100,6 +98,7 @@ After installing the distro, configure and initialize it to start sending data to Elastic. //// +TO DO: Are there any dependencies that need to be installed in addition to the distro? If yes, does it matter in what order dependencies are defined? If no, delete this section. @@ -113,6 +112,7 @@ Step-by-step instructions //// //// +TO DO: What does the _minimal_ configuration / setup look like? Are there any configuration options that are _required_? //// @@ -125,6 +125,7 @@ Step-by-step instructions //// //// +TO DO: Does the user need to do something after configuring the distro for data to start being sent Elastic? If no, delete this section. @@ -142,6 +143,7 @@ Optional: Add an image //// //// +TO DO: What should they expect to see after running this? How do they know it worked as expected? //// @@ -156,7 +158,7 @@ Step-by-step instructions //// //// -What should they do next? +βœ… What they should do next //// [discrete] [[get-started-next-steps]] diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc index 49466901..8537520c 100644 --- a/docs/intro.asciidoc +++ b/docs/intro.asciidoc @@ -21,7 +21,7 @@ Assumptions we're comfortable making about the reader: include::release-status.asciidoc[] //// -Intro +βœ… Intro //// The {distro_name} ("the distro") is a {language} package that provides: @@ -29,8 +29,8 @@ The {distro_name} ("the distro") is a {language} package that provides: * Configuration defaults for best usage. //// -What is it? -Why use it? +βœ… What is it? +βœ… Why use it? //// A _distribution_ is a wrapper around an upstream OpenTelemetry repository with some customizations. The {distro_name} is a wrapper around the https://opentelemetry.io/docs/languages/{language_lc}[OpenTelemetry SDK for {language}] and includes the following customizations: @@ -41,7 +41,7 @@ A _distribution_ is a wrapper around an upstream OpenTelemetry repository with s NOTE: For more details about OpenTelemetry distributions in general, visit the https://opentelemetry.io/docs/concepts/distributions[OpenTelemetry documentation]. //// -How to use it? +βœ… How to use it? //// Use the distro to start the OpenTelemetry SDK with your {language} application to automatically capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent to any OTLP collector you choose. From ce09010c1e825024a4d17665305c4cfc0df307f6 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Mon, 22 Jul 2024 10:41:27 -0500 Subject: [PATCH 05/25] reframe generated guide as migration guide --- .../config/ConfigurationExporterTest.java | 12 +- ...gure.asciidoc.ftl => migrate.asciidoc.ftl} | 18 +- docs/configuration.asciidoc | 131 ------------- docs/configure.asciidoc | 173 ++++++++---------- docs/index.asciidoc | 2 +- docs/migrate.asciidoc | 135 ++++++++++++++ 6 files changed, 232 insertions(+), 239 deletions(-) rename custom/src/test/resources/{configure.asciidoc.ftl => migrate.asciidoc.ftl} (58%) delete mode 100644 docs/configuration.asciidoc create mode 100644 docs/migrate.asciidoc diff --git a/custom/src/test/java/co/elastic/otel/config/ConfigurationExporterTest.java b/custom/src/test/java/co/elastic/otel/config/ConfigurationExporterTest.java index f6ab5708..8ae16e04 100644 --- 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.asciidoc"); } /** @@ -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.asciidoc) 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,13 +84,13 @@ static String renderDocumentation(List configurationRegistr cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER); cfg.setLogTemplateExceptions(false); - Template temp = cfg.getTemplate("configure.asciidoc.ftl"); + Template temp = cfg.getTemplate("migrate.asciidoc.ftl"); StringWriter tempRenderedFile = new StringWriter(); tempRenderedFile.write( - "[[configure]]\n" - + "== Configure\n\n" + "[[migrate]]\n" + + "== Migrate to the Elastic distro\n\n" + "////\n" - + "This file is auto generated. Please only make changes in `configure.asciidoc.ftl`\n" + + "This file is auto generated. Please only make changes in `migrate.asciidoc.ftl`\n" + "////\n"); final Map> optionsByCategory = new HashMap<>(); optionsByCategory.put("Elastic to OpenTelemetry mapping", configurationRegistry); diff --git a/custom/src/test/resources/configure.asciidoc.ftl b/custom/src/test/resources/migrate.asciidoc.ftl similarity index 58% rename from custom/src/test/resources/configure.asciidoc.ftl rename to custom/src/test/resources/migrate.asciidoc.ftl index 8fb4cf6b..f49696af 100644 --- a/custom/src/test/resources/configure.asciidoc.ftl +++ b/custom/src/test/resources/migrate.asciidoc.ftl @@ -1,17 +1,25 @@ <#-- @ftlvariable name="config" type="java.util.Map>" --> <#-- @ftlvariable name="keys" type="java.util.Collection" --> -The Elastic Distribution for OpenTelemetry Java (the distro) supports the -https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry SDK configuration variables]. +:language: Java +:language_lc: java +:distro_name: Elastic Distribution for OpenTelemetry {language} -This documentation describes how the https://www.elastic.co/guide/en/apm/agent/java/current/index.html[Elastic APM Java agent configuration options] -map to the OpenTelemetry options. +include::release-status.asciidoc[] + +:!language: +:!language_lc: +:!distro_name: + +This documentation describes how applications using the {apm-java-ref}/index.html[Elastic APM Java agent] can be updated to use the Elastic Distribution for OpenTelemetry Java ("the distro"). + +Start by installing the distro following the steps outlined in <>. Then update existing APM Java agent configuration options in your application with the equivalent https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry SDK configuration variables] (listed below). [discrete] [[option-reference]] === Option reference -This is a list of all configuration options grouped by their category. +This is a list of all APM Java agent configuration options grouped by their category. Click on a key to get more information. <#list config as category, options> diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc deleted file mode 100644 index b32772e8..00000000 --- a/docs/configuration.asciidoc +++ /dev/null @@ -1,131 +0,0 @@ -//// -Goal of this doc: -Provide a complete reference of all available configuration options and where/how they can be set. (Any Elastic-specific configuration options are listed directly. General OpenTelemetry configuration options are linked.) - -Assumptions we're comfortable making about the reader: -* They are familiar with Elastic -* They are familiar with OpenTelemetry -//// - -[[configuration]] -== Configure - -:language: Java -:language_lc: java -:distro_name: Elastic Distribution for OpenTelemetry {language} - -include::release-status.asciidoc[] - -//// -TO DO: How do users set configuration options? -//// -[discrete] -[[configure-methods]] -=== Configuration methods - -//// -TO DO: -Are there multiple ways to set configuration options? -For example, can they use environment variables OR a config file? -If there are, what are they and why would you use each method? -Where/how do you use each method? -Provide an example to illustrate the syntax. -//// - -//// -TO DO: -If configuration options are defined using multiple methods, -which one takes precedence over the other(s)? -//// - -[discrete] -[[configuration-options]] -=== Configuration options - -Because the Elastic Distribution for OpenTelemetry Java ("the distro") is an extension of the https://github.com/open-telemetry/opentelemetry-java-instrumentation[OpenTelemetry Java agent], it supports both: - -* General OpenTelemetry SDK configuration options -* Elastic-specific configuration options that are only available when using the distro - -[discrete] -[[configure-otel-sdk-options]] -==== OpenTelemetry SDK configuration options - -//// -TO DO: -Is this true? -Are there any options that aren't supported? -Any options that shouldn't be used? -//// -The distro supports all configuration options listed in the https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry General SDK Configuration documentation]. - -//// -TO DO: -Are there Elastic-specific custom configuration options -in addition to the general OpenTelemetry SDK -configuration options? Or are all the customizations -"behind the scenes"? -If not, you can delete this section. -//// -[discrete] -[[configure-distro-options]] -==== Elastic-specific configuration options - -The distro supports the following Elastic-specific options: - -//// -List config options -//// - -//// -TO DO: -Are there multiple authentication methods when sending data to Elastic? -If not, delete this section. -//// -[discrete] -[[configure-auth-methods]] -=== Authentication methods - -When sending data to Elastic, there are two ways you can authenticate: using a secret token or using an APM agent key. - -[discrete] -[[configure-secret-token]] -==== Use a secret token - -// TO DO: What is this? -// ?? - -// TO DO:Why would you choose this method? -// ?? - -// TO DO:How do you authenticate using this method? -// ?? - -[discrete] -[[configure-api-key]] -==== Use an APM agent key (API key) - -// βœ… What is this? -It is also possible to authenticate to an Elastic Observability endpoint using -an _APM agent key_. These are revocable API keys. - -// TO DO: Why would you choose this method? -// ?? - -// βœ… How do you authenticate using this method? -To create and manage APM Agent keys in Kibana: - -. Go to *APM Settings*. -. Select the *Agent Keys* tab. - -When using an APM Agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using a -different auth schema (`ApiKey` rather than `Bearer`). For example: - -//// -TO DO: Code example -//// - - -:!language: -:!language_lc: -:!distro_name: diff --git a/docs/configure.asciidoc b/docs/configure.asciidoc index 27a6826f..4f5194f5 100644 --- a/docs/configure.asciidoc +++ b/docs/configure.asciidoc @@ -1,150 +1,131 @@ //// -I'm confused about the goal of this doc. +Goal of this doc: +Provide a complete reference of all available configuration options and where/how they can be set. (Any Elastic-specific configuration options are listed directly. General OpenTelemetry configuration options are linked.) -With a title like "Configure" I expected to see a list of the -valid configuration options. Instead it seems to be a list of -APM Java agent configuration options, and how to update them -to migrate from the agent to the distro. - -Is the intention of this doc to be a migration guide from the APM Java -agent to the Elastic Distribution for OpenTelemetry Java? +Assumptions we're comfortable making about the reader: +* They are familiar with Elastic +* They are familiar with OpenTelemetry //// [[configure]] -== Migrate? +== Configure -// I'll add this to the automation if we're sure we want this on every page. :language: Java :language_lc: java :distro_name: Elastic Distribution for OpenTelemetry {language} include::release-status.asciidoc[] -:!language: -:!language_lc: -:!distro_name: - //// -This file is auto generated. Please only make changes in `configure.asciidoc.ftl` +TO DO: How do users set configuration options? //// - -The Elastic Distribution for OpenTelemetry Java (the distro) supports the -https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry SDK configuration variables]. - -This documentation describes how the https://www.elastic.co/guide/en/apm/agent/java/current/index.html[Elastic APM Java agent configuration options] -map to the OpenTelemetry options. - -[discrete] -[[option-reference]] -=== Option reference - -This is a list of all configuration options grouped by their category. -Click on a key to get more information. - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - [discrete] -[[category]] -=== Elastic to OpenTelemetry mapping - -[discrete] -[[server_url]] -==== `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. +[[configure-methods]] +=== Configuration methods //// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +TO DO: +Are there multiple ways to set configuration options? +For example, can they use environment variables OR a config file? +If there are, what are they and why would you use each method? +Where/how do you use each method? +Provide an example to illustrate the syntax. //// -[discrete] -[[server_urls]] -==== `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. - //// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +TO DO: +If configuration options are defined using multiple methods, +which one takes precedence over the other(s)? //// [discrete] -[[secret_token]] -==== `secret_token` +[[configuration-options]] +=== Configuration options -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"`. +Because the Elastic Distribution for OpenTelemetry Java ("the distro") is an extension of the https://github.com/open-telemetry/opentelemetry-java-instrumentation[OpenTelemetry Java agent], it supports both: -//// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. -//// +* General OpenTelemetry SDK configuration options +* Elastic-specific configuration options that are only available when using the distro [discrete] -[[api_key]] -==== `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"`. +[[configure-otel-sdk-options]] +==== OpenTelemetry SDK configuration options //// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +TO DO: +Is this true? +Are there any options that aren't supported? +Any options that shouldn't be used? //// +The distro supports all configuration options listed in the https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry General SDK Configuration documentation]. +//// +TO DO: +Are there Elastic-specific custom configuration options +in addition to the general OpenTelemetry SDK +configuration options? Or are all the customizations +"behind the scenes"? +If not, you can delete this section. +//// [discrete] -[[service_name]] -==== `service_name` +[[configure-distro-options]] +==== Elastic-specific configuration options -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 distro supports the following Elastic-specific options: //// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +List config options //// -[discrete] -[[enabled]] -==== `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. - //// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +TO DO: +Are there multiple authentication methods when sending data to Elastic? +If not, delete this section. //// +[discrete] +[[configure-auth-methods]] +=== Authentication methods + +When sending data to Elastic, there are two ways you can authenticate: using a secret token or using an APM agent key. [discrete] -[[service_version]] -==== `service_version` +[[configure-secret-token]] +==== Use a secret token -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`. +// TO DO: What is this? +// ?? -//// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. -//// +// TO DO:Why would you choose this method? +// ?? + +// TO DO:How do you authenticate using this method? +// ?? [discrete] -[[environment]] -==== `environment` +[[configure-api-key]] +==== Use an APM agent key (API key) -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`. +// βœ… What is this? +It is also possible to authenticate to an Elastic Observability endpoint using +an _APM agent key_. These are revocable API keys. -//// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. -//// +// TO DO: Why would you choose this method? +// ?? -[discrete] -[[global_labels]] -==== `global_labels` +// βœ… How do you authenticate using this method? +To create and manage APM Agent keys in Kibana: + +. Go to *APM Settings*. +. Select the *Agent Keys* tab. -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 +When using an APM Agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using a +different auth schema (`ApiKey` rather than `Bearer`). For example: //// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +TO DO: Code example //// - -// Elastic to OpenTelemetry mapping +:!language: +:!language_lc: +:!distro_name: diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 905697fe..a7b59302 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -11,6 +11,6 @@ endif::[] ifndef::env-github[] include::./intro.asciidoc[] include::./get-started.asciidoc[] -include::./configuration.asciidoc[] include::./configure.asciidoc[] +include::./migrate.asciidoc[] endif::[] diff --git a/docs/migrate.asciidoc b/docs/migrate.asciidoc new file mode 100644 index 00000000..37ba4ca8 --- /dev/null +++ b/docs/migrate.asciidoc @@ -0,0 +1,135 @@ +[[migrate]] +== Migrate to the Elastic distro + +//// +This file is auto generated. Please only make changes in `migrate.asciidoc.ftl` +//// + +:language: Java +:language_lc: java +:distro_name: Elastic Distribution for OpenTelemetry {language} + +include::release-status.asciidoc[] + +:!language: +:!language_lc: +:!distro_name: + +This documentation describes how applications using the {apm-java-ref}/index.html[Elastic APM Java agent] can be updated to use the Elastic Distribution for OpenTelemetry Java ("the distro"). + +Start by installing the distro following the steps outlined in <>. Then update existing APM Java agent configuration options in your application with the equivalent https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry SDK configuration variables] (listed below). + +[discrete] +[[option-reference]] +=== Option reference + +This is a list of all APM Java agent configuration options grouped by their category. +Click on a key to get more information. + +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> + +[discrete] +[[category]] +=== Elastic to OpenTelemetry mapping + +[discrete] +[[server_url]] +==== `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. + +//// +This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +//// + +[discrete] +[[server_urls]] +==== `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. + +//// +This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +//// + +[discrete] +[[secret_token]] +==== `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"`. + +//// +This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +//// + +[discrete] +[[api_key]] +==== `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"`. + +//// +This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +//// + +[discrete] +[[service_name]] +==== `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. + +//// +This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +//// + +[discrete] +[[enabled]] +==== `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. + +//// +This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +//// + +[discrete] +[[service_version]] +==== `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`. + +//// +This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +//// + +[discrete] +[[environment]] +==== `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`. + +//// +This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +//// + +[discrete] +[[global_labels]] +==== `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 + +//// +This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. +//// + + + +// Elastic to OpenTelemetry mapping From 0ad50097256ada17e696470040b6d4b21ecda4cb Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 24 Jul 2024 11:00:25 -0500 Subject: [PATCH 06/25] update intro, add questions --- docs/intro.asciidoc | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc index 8537520c..f88b37cc 100644 --- a/docs/intro.asciidoc +++ b/docs/intro.asciidoc @@ -32,12 +32,30 @@ The {distro_name} ("the distro") is a {language} package that provides: βœ… What is it? βœ… Why use it? //// -A _distribution_ is a wrapper around an upstream OpenTelemetry repository with some customizations. The {distro_name} is a wrapper around the https://opentelemetry.io/docs/languages/{language_lc}[OpenTelemetry SDK for {language}] and includes the following customizations: +A _distribution_ is customized version of an upstream OpenTelemetry repository with some customizations. The {distro_name} is an extension of the https://opentelemetry.io/docs/languages/{language_lc}[OpenTelemetry SDK for {language}]. With the Elastic distro you have access to all the features of the OpenTelemetry SDK for {language} plus: -* Uses Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like Elastic APM server. +//// +TO DO: +These are true for the Node distro, +are then also true for the Java distro? +//// +* Access to SDK improvements and bug fixes contributed by the Elastic team _before_ the changes are available upstream in OpenTelemetry repositories. +* A single package that includes several OpenTelemetry packages as dependencies, so you only need to install and update a single package (for most use cases). +//// +TO DO: +These are true for the .NET distro, +are they also true for the Java distro? +//// +* Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like Elastic APM server. * Preconfigures the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. * Ensures that the OpenTelemetry protocol (OTLP) exporter is enabled by default. +//// +TO DO: +Is there anything else the Elastic distro adds to the OpenTelemetry SDK for Java +that we should highlight here? +//// + NOTE: For more details about OpenTelemetry distributions in general, visit the https://opentelemetry.io/docs/concepts/distributions[OpenTelemetry documentation]. //// @@ -45,10 +63,20 @@ NOTE: For more details about OpenTelemetry distributions in general, visit the h //// Use the distro to start the OpenTelemetry SDK with your {language} application to automatically capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent to any OTLP collector you choose. +//// +TO DO: +This is true for the .NET distro, +is it also true for the Java distro? +//// Start with helpful defaults to begin collecting and exporting OpenTelemetry signals quickly. Then, further refine how you use the distro using extension methods that allow you to fully control the creation of the underlying tracer and metric providers. After you start sending data to Elastic, use an {observability-guide}/index.html[Elastic Observability] deployment -- hosted on Elastic Cloud or on-premises -- to monitor your applications, create alerts, and quickly identify root causes of service issues. +//// +βœ… What they should do next +//// +*Ready to try out the distro?* Follow the step-by-step instructions in <>. + :!language: :!language_lc: :!distro_name: From bcd70537a6db29cfefa272d8ef0723c814e321f7 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 25 Jul 2024 08:42:48 -0500 Subject: [PATCH 07/25] update getting started --- docs/get-started.asciidoc | 89 +++++++++++++-------------------------- 1 file changed, 30 insertions(+), 59 deletions(-) diff --git a/docs/get-started.asciidoc b/docs/get-started.asciidoc index e8e293e2..d5af1a23 100644 --- a/docs/get-started.asciidoc +++ b/docs/get-started.asciidoc @@ -19,6 +19,10 @@ include::release-status.asciidoc[] This guide shows you how to use the Elastic Distribution for OpenTelemetry {language} ("the distro") to instrument your {language} application and send OpenTelemetry data to an Elastic Observability deployment. +This doc will guide you through the minimal configuration options to get the Elastic distro set up in your application. +You do _not_ need any existing experience with OpenTelemetry to set up the Elastic distro initially. +If you need more control over your configuration after getting set up, you can learn more in https://opentelemetry.io/docs/languages/net[OpenTelemetry SDK documentation]. + [NOTE] ==== As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint (https://opentelemetry.io/docs/collector/[OpenTelemetry Collector]), but this guide assumes you are sending data to Elastic. @@ -31,13 +35,7 @@ As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry p [[get-started-prerequisites]] === Prerequisites -Before getting started: - -// Familiarity with OpenTelemetry -* *Familiarize yourself with the OpenTelemetry SDK.* The distro is a lightweight wrapper around the OpenTelemetry SDK. You should be broadly familiar with the OpenTelemetry SDK concepts and instrumenting applications using the Microsoft diagnostic APIs. If you are not familiar with this, start with the https://opentelemetry.io/docs/languages/net[OpenTelemetry SDK documentation]. -+ -* *Set up Elastic Observability*. You'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an https://www.elastic.co/observability[Elastic Observability] cloud deployment. You can use an existing one or set up a new one. -+ +Before getting started, you'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an https://www.elastic.co/observability[Elastic Observability] cloud deployment. You can use an existing one or set up a new one. [[elastic-observability-setup]] [%collapsible] .*Expand for setup instructions* @@ -49,12 +47,6 @@ This section shows how to create an https://www.elastic.co/observability[Elastic . Once that is created, click *Open* to visit your Kibana home page, e.g. `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`. ==== -//// -TO DO: -Anything else they need to do/have/know? -For example, any dependencies (including specific supported Java versions)? -//// - //// βœ… How to install the distro //// @@ -77,8 +69,9 @@ java -javaagent:/path/to/agent.jar \ ---- //// -βœ… Any additional info related to installation -//// +This is true for the .NET distro, +is it also true for the Java distro? + [NOTE] .The Elastic distro and the OpenTelemetry SDK ==== @@ -86,6 +79,7 @@ The distro includes a transitive dependency on the OpenTelemetry SDK, so you do OpenTelemetry SDK package to your project directly. However, you _can_ explicitly add the OpenTelemetry SDK as a dependency if you want to opt into newer SDK versions. If you do this, the OpenTelemetry SDK dependency must be defined _before_ the {distro_name} is defined. ==== +//// //// βœ… Start-to-finish operation @@ -98,64 +92,41 @@ After installing the distro, configure and initialize it to start sending data to Elastic. //// -TO DO: -Are there any dependencies that need to be installed in addition to the distro? -If yes, does it matter in what order dependencies are defined? -If no, delete this section. -//// -[discrete] -[[get-started-add-dependencies]] -==== Add dependencies - -//// -Step-by-step instructions -//// - -//// -TO DO: -What does the _minimal_ configuration / setup look like? -Are there any configuration options that are _required_? +βœ… Provide _minimal_ configuration/setup //// [discrete] [[get-started-configure]] ==== Configure the distro //// -Step-by-step instructions -//// - -//// -TO DO: -Does the user need to do something after configuring the distro -for data to start being sent Elastic? -If no, delete this section. +βœ… Step-by-step instructions //// -[discrete] -[[get-started-initialization]] -==== Initialize the distro +To configure the distro, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and +authorization data to set the appropriate `OTLP_*` environment variables: -//// -Step-by-step instructions -//// +* `OTEL_EXPORTER_OTLP_ENDPOINT`: The full URL of the endpoint where data will be sent. +* `OTEL_EXPORTER_OTLP_HEADERS`: A comma-separated list of `key=value` pairs that will +be added to the headers of every request. This is typically this is used for +<>. -//// -Optional: Add an image -//// +include::./configure.asciidoc[tag=get-auth] //// -TO DO: -What should they expect to see after running this? -How do they know it worked as expected? +βœ… What success looks like //// [discrete] -[[get-started-view-traces]] -=== View traces +[[get-started-confirm]] +=== Confirm that the distro is working -To view the traces, you can use the Elastic APM UI: +To confirm that the distro has successfully connected to Elastic: -//// -Step-by-step instructions -//// +. Go to *APM* β†’ *Traces*. +. You should see the name of the service to which you just added the distro. +It can take several minutes after initializing the distro for the service to show up in this list. +. Click on the name in the list to see trace data. ++ +NOTE: There may be no trace data to visualize unless you have _used_ your application since +initializing the distro. //// βœ… What they should do next @@ -164,7 +135,7 @@ Step-by-step instructions [[get-started-next-steps]] === Next steps -* <> to send data to Elastic. +* <> to send data to Elastic. * Learn more about viewing and interpreting data in the {observability-guide}/apm.html[Observability guide]. :!language: From 16435f0ba9bcf6097f3488be0d97c6b586a389d6 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 25 Jul 2024 08:51:12 -0500 Subject: [PATCH 08/25] update configuration file --- docs/configure.asciidoc | 162 +++++++++++++++++++++++++++------------- 1 file changed, 110 insertions(+), 52 deletions(-) diff --git a/docs/configure.asciidoc b/docs/configure.asciidoc index 4f5194f5..537e554e 100644 --- a/docs/configure.asciidoc +++ b/docs/configure.asciidoc @@ -17,26 +17,72 @@ Assumptions we're comfortable making about the reader: include::release-status.asciidoc[] //// -TO DO: How do users set configuration options? +βœ… How users set configuration options //// [discrete] [[configure-methods]] === Configuration methods -//// -TO DO: -Are there multiple ways to set configuration options? -For example, can they use environment variables OR a config file? -If there are, what are they and why would you use each method? -Where/how do you use each method? -Provide an example to illustrate the syntax. -//// +OpenTelemetry configuration options should be set using one of the mechanisms listed in the +https://opentelemetry.io/docs/zero-code/java/agent/configuration/[OpenTelemetry documentation], +including: -//// -TO DO: -If configuration options are defined using multiple methods, -which one takes precedence over the other(s)? -//// +* <> +* <> +* <> + +// βœ… Order of precedence +Configuration options set using environment variables take precedence over system properties, and +system properties take precedence over configuration options set using file properties. + +[discrete] +[[configure-environment-variables]] +==== Environment variables + +// βœ… What and why +The distro can be configured using environment variables. +This is a cross-platform way to configure the distro and is especially useful in containerized environments. + +// βœ… How +Define environment variables before the start of the JVM: + +[source,sh] +---- +export OTEL_SERVICE_NAME=my-service +java ... +---- + +[discrete] +[[configure-system-properties]] +==== System properties + +// βœ… What and why +The distro can be configured using system properties. +These configuration options can be seen by anything that can see the executed command-line. + +// βœ… How +Define system properties need at the JVM start, usually on the command-line: + +[source,sh] +---- +java -Dotel.service.name=my-service ... +---- + +[discrete] +[[configure-configuration-file]] +==== Configuration file + +// βœ… What and why +The distro can be configured using a configuration file. + +// βœ… How +Create and populate the configuration file before the JVM is started, and specify where properties are defined at the JVM start: + +[source,sh] +---- +echo otel.service.name=my-service > my.properties +java -Dotel.javaagent.configuration-file=my.properties ... +---- [discrete] [[configuration-options]] @@ -51,66 +97,48 @@ Because the Elastic Distribution for OpenTelemetry Java ("the distro") is an ext [[configure-otel-sdk-options]] ==== OpenTelemetry SDK configuration options -//// -TO DO: -Is this true? -Are there any options that aren't supported? -Any options that shouldn't be used? -//// The distro supports all configuration options listed in the https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry General SDK Configuration documentation]. //// TO DO: -Are there Elastic-specific custom configuration options -in addition to the general OpenTelemetry SDK -configuration options? Or are all the customizations -"behind the scenes"? -If not, you can delete this section. +Does this approach and language make sense? //// [discrete] [[configure-distro-options]] -==== Elastic-specific configuration options +==== Elastic distro configuration options -The distro supports the following Elastic-specific options: +In addition to general OpenTelemetry SDK configuration options, there are two kinds +of configuration options that are only available in the {distro_name}: + +* Additional `OTEL_` options that Elastic plans to contribute upstream to the https://opentelemetry.io/docs/languages/{language_lc}[OpenTelemetry SDK for {language}], but are not yet available in the OpenTelemetry SDK for {language}. +* `ELASTIC_OTEL_` options that are specific to Elastic and will always live in the {distro_name} (in other words, it will _not_ be added upstream). //// -List config options +TO DO: +List config options instead of linking to the README //// +Read more about configuration options that are only available in the distro in [the elastic/elastic-otel-java README](https://github.com/elastic/elastic-otel-java?tab=readme-ov-file#features). //// -TO DO: -Are there multiple authentication methods when sending data to Elastic? -If not, delete this section. +βœ… List auth methods //// [discrete] [[configure-auth-methods]] === Authentication methods -When sending data to Elastic, there are two ways you can authenticate: using a secret token or using an APM agent key. - -[discrete] -[[configure-secret-token]] -==== Use a secret token - -// TO DO: What is this? -// ?? +When sending data to Elastic, there are two ways you can authenticate: using an APM agent key or using a secret token. -// TO DO:Why would you choose this method? -// ?? - -// TO DO:How do you authenticate using this method? -// ?? +Both the distro and APM Server must be configured with the same secret token for the request to be accepted. [discrete] [[configure-api-key]] ==== Use an APM agent key (API key) -// βœ… What is this? +// βœ… What and why It is also possible to authenticate to an Elastic Observability endpoint using -an _APM agent key_. These are revocable API keys. - -// TO DO: Why would you choose this method? -// ?? +an {observability-guide}/apm-api-key.html[APM agent key]. +APM agent keys are revocable, you can have more than one of them, and +you can add or remove them without restarting APM Server. // βœ… How do you authenticate using this method? To create and manage APM Agent keys in Kibana: @@ -121,10 +149,40 @@ To create and manage APM Agent keys in Kibana: When using an APM Agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using a different auth schema (`ApiKey` rather than `Bearer`). For example: -//// -TO DO: Code example -//// +// βœ… Code example +[source,sh] +---- +export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io +export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey TkpXUkx...dVZGQQ==" +---- + +[discrete] +[[configure-secret-token]] +==== Use a secret token +// βœ… What and why +{observability-guide}/apm-secret-token.html[Secret tokens] are used to authorize requests to the APM Server. + +// βœ… How do you authenticate using this method? +// tag::get-auth[] +You can find the values of these variables in {kib}'s APM tutorial. +In {kib}: + +. Go to *Setup guides*. +. Select *Observability*. +. Select *Monitor my application performance*. +. Scroll down and select the *OpenTelemetry* option. +. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and +`OTEL_EXPORTER_OTLP_HEADERS` are shown there. ++ +For example: ++ +[source,sh] +---- +export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io +export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l" +---- +// end::get-auth[] :!language: :!language_lc: From df5d7d2535c04a80e3cf86cadee84705d0a12834 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 25 Jul 2024 08:59:30 -0500 Subject: [PATCH 09/25] lint content --- .../co/elastic/otel/config/LegacyConfigurations.java | 2 +- docs/configure.asciidoc | 4 ++-- docs/get-started.asciidoc | 9 +++++---- docs/migrate.asciidoc | 2 +- 4 files changed, 9 insertions(+), 8 deletions(-) diff --git a/custom/src/main/java/co/elastic/otel/config/LegacyConfigurations.java b/custom/src/main/java/co/elastic/otel/config/LegacyConfigurations.java index a9f8a3dd..1c331ee9 100644 --- a/custom/src/main/java/co/elastic/otel/config/LegacyConfigurations.java +++ b/custom/src/main/java/co/elastic/otel/config/LegacyConfigurations.java @@ -73,7 +73,7 @@ private void addAllOptions() { "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`."); 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 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, e.g. labels.alice=first"); addUnspecifiedOption("log_level"); addUnspecifiedOption("log_file"); addUnspecifiedOption("log_file_size"); diff --git a/docs/configure.asciidoc b/docs/configure.asciidoc index 537e554e..7cb9d897 100644 --- a/docs/configure.asciidoc +++ b/docs/configure.asciidoc @@ -117,7 +117,7 @@ of configuration options that are only available in the {distro_name}: TO DO: List config options instead of linking to the README //// -Read more about configuration options that are only available in the distro in [the elastic/elastic-otel-java README](https://github.com/elastic/elastic-otel-java?tab=readme-ov-file#features). +Read more about configuration options that are only available in the distro in https://github.com/elastic/elastic-otel-java?tab=readme-ov-file#features[the elastic/elastic-otel-java README]. //// βœ… List auth methods @@ -141,7 +141,7 @@ APM agent keys are revocable, you can have more than one of them, and you can add or remove them without restarting APM Server. // βœ… How do you authenticate using this method? -To create and manage APM Agent keys in Kibana: +To create and manage APM Agent keys in {kib}: . Go to *APM Settings*. . Select the *Agent Keys* tab. diff --git a/docs/get-started.asciidoc b/docs/get-started.asciidoc index d5af1a23..d6de8e48 100644 --- a/docs/get-started.asciidoc +++ b/docs/get-started.asciidoc @@ -40,11 +40,12 @@ Before getting started, you'll need somewhere to send the gathered OpenTelemetry [%collapsible] .*Expand for setup instructions* ==== -This section shows how to create an https://www.elastic.co/observability[Elastic Observability] cloud deployment and get the data you need to configure the distro to send data to it. +To create your first Elastic Observability deployment: -. Register at https://cloud.elastic.co/registration[cloud.elastic.co], if you haven't already. This supports starting **free trial**. -. After registering, click *Create deployment* at ``. -. Once that is created, click *Open* to visit your Kibana home page, e.g. `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`. +. Sign up for a https://cloud.elastic.co/registration[free Elastic Cloud trial] or sign into an existing account. +. Go to https://cloud.elastic.co/home. +. Click *Create deployment*. +. When the deployment is ready, click *Open* to visit your {kib} home page (for example, `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`). ==== //// diff --git a/docs/migrate.asciidoc b/docs/migrate.asciidoc index 37ba4ca8..957aa473 100644 --- a/docs/migrate.asciidoc +++ b/docs/migrate.asciidoc @@ -124,7 +124,7 @@ This file is auto-generated. Please make changes in *Configuration.java (for exa [[global_labels]] ==== `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 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, e.g. labels.alice=first //// This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. From b448968df55dea3e986f82e528d7b20666fcb7ac Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 25 Jul 2024 09:06:10 -0500 Subject: [PATCH 10/25] address feedback from @bmorelli25 --- docs/intro.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc index f88b37cc..4097ed07 100644 --- a/docs/intro.asciidoc +++ b/docs/intro.asciidoc @@ -46,7 +46,7 @@ TO DO: These are true for the .NET distro, are they also true for the Java distro? //// -* Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like Elastic APM server. +* Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like Elastic Observability deployment. * Preconfigures the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. * Ensures that the OpenTelemetry protocol (OTLP) exporter is enabled by default. From 22c264d7d4c4975623eade772358be62b279c721 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 31 Jul 2024 11:43:31 -0500 Subject: [PATCH 11/25] translate from asciidoc to markdown --- .../otel/config/LegacyConfigurations.java | 18 +- .../src/test/resources/migrate.asciidoc.ftl | 54 ----- custom/src/test/resources/migrate.md.ftl | 38 ++++ docs/configure.asciidoc | 189 ------------------ docs/configure.md | 150 ++++++++++++++ docs/get-started.asciidoc | 144 ------------- docs/get-started.md | 114 +++++++++++ docs/index.asciidoc | 16 -- docs/index.md | 6 + docs/intro.asciidoc | 82 -------- docs/intro.md | 67 +++++++ docs/migrate.asciidoc | 135 ------------- docs/migrate.md | 102 ++++++++++ docs/release-status.asciidoc | 9 - 14 files changed, 486 insertions(+), 638 deletions(-) delete mode 100644 custom/src/test/resources/migrate.asciidoc.ftl create mode 100644 custom/src/test/resources/migrate.md.ftl delete mode 100644 docs/configure.asciidoc create mode 100644 docs/configure.md delete mode 100644 docs/get-started.asciidoc create mode 100644 docs/get-started.md delete mode 100644 docs/index.asciidoc create mode 100644 docs/index.md delete mode 100644 docs/intro.asciidoc create mode 100644 docs/intro.md delete mode 100644 docs/migrate.asciidoc create mode 100644 docs/migrate.md delete mode 100644 docs/release-status.asciidoc diff --git a/custom/src/main/java/co/elastic/otel/config/LegacyConfigurations.java b/custom/src/main/java/co/elastic/otel/config/LegacyConfigurations.java index 1c331ee9..a278ec47 100644 --- 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, e.g. 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/resources/migrate.asciidoc.ftl b/custom/src/test/resources/migrate.asciidoc.ftl deleted file mode 100644 index f49696af..00000000 --- a/custom/src/test/resources/migrate.asciidoc.ftl +++ /dev/null @@ -1,54 +0,0 @@ -<#-- @ftlvariable name="config" type="java.util.Map>" --> -<#-- @ftlvariable name="keys" type="java.util.Collection" --> - -:language: Java -:language_lc: java -:distro_name: Elastic Distribution for OpenTelemetry {language} - -include::release-status.asciidoc[] - -:!language: -:!language_lc: -:!distro_name: - -This documentation describes how applications using the {apm-java-ref}/index.html[Elastic APM Java agent] can be updated to use the Elastic Distribution for OpenTelemetry Java ("the distro"). - -Start by installing the distro following the steps outlined in <>. Then update existing APM Java agent configuration options in your application with the equivalent https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry SDK configuration variables] (listed below). - -[discrete] -[[option-reference]] -=== Option reference - -This is a list of all APM Java agent configuration options grouped by their category. -Click on a key to get more information. - -<#list config as category, options> - <#list options as option> -* <<${option.key}>> - - - -<#list config as category, options> -[discrete] -[[category]] -=== ${category} - - <#list options as option> -[discrete] -[[${option.key}]] -==== `${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. -//// - - - - -<#macro defaultValue option>${option.defaultValueAsString?has_content?then("${option.defaultValueAsString?replace(',([^\\\\s])', ', $1', 'r')}", '')} - -<#list config as category, options> -// ${category} - diff --git a/custom/src/test/resources/migrate.md.ftl b/custom/src/test/resources/migrate.md.ftl new file mode 100644 index 00000000..3fdba99c --- /dev/null +++ b/custom/src/test/resources/migrate.md.ftl @@ -0,0 +1,38 @@ +<#-- @ftlvariable name="config" type="java.util.Map>" --> +<#-- @ftlvariable name="keys" type="java.util.Collection" --> + +This documentation describes how applications using the [Elastic APM Java agent](https://www.elastic.co/guide/en/apm/agent/java/current/index.html) can be updated to use the Elastic Distribution for OpenTelemetry Java ("the distro"). + +Start by installing the distro 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. +Click on a key to get more information. + +<#list config as category, options> + <#list options as option> +* [${option.key}](#${option.key}) + + + +<#list config as category, options> +## ${category} + + <#list options as option> +### `${option.key}`${option.tags?has_content?then(" (${option.tags?join(' ')})", '')} + +${option.description} + + + + + + +<#macro defaultValue option>${option.defaultValueAsString?has_content?then("${option.defaultValueAsString?replace(',([^\\\\s])', ', $1', 'r')}", '')} + +<#list config as category, options> + + diff --git a/docs/configure.asciidoc b/docs/configure.asciidoc deleted file mode 100644 index 7cb9d897..00000000 --- a/docs/configure.asciidoc +++ /dev/null @@ -1,189 +0,0 @@ -//// -Goal of this doc: -Provide a complete reference of all available configuration options and where/how they can be set. (Any Elastic-specific configuration options are listed directly. General OpenTelemetry configuration options are linked.) - -Assumptions we're comfortable making about the reader: -* They are familiar with Elastic -* They are familiar with OpenTelemetry -//// - -[[configure]] -== Configure - -:language: Java -:language_lc: java -:distro_name: Elastic Distribution for OpenTelemetry {language} - -include::release-status.asciidoc[] - -//// -βœ… How users set configuration options -//// -[discrete] -[[configure-methods]] -=== Configuration methods - -OpenTelemetry configuration options should be set using one of the mechanisms listed in the -https://opentelemetry.io/docs/zero-code/java/agent/configuration/[OpenTelemetry documentation], -including: - -* <> -* <> -* <> - -// βœ… Order of precedence -Configuration options set using environment variables take precedence over system properties, and -system properties take precedence over configuration options set using file properties. - -[discrete] -[[configure-environment-variables]] -==== Environment variables - -// βœ… What and why -The distro can be configured using environment variables. -This is a cross-platform way to configure the distro and is especially useful in containerized environments. - -// βœ… How -Define environment variables before the start of the JVM: - -[source,sh] ----- -export OTEL_SERVICE_NAME=my-service -java ... ----- - -[discrete] -[[configure-system-properties]] -==== System properties - -// βœ… What and why -The distro can be configured using system properties. -These configuration options can be seen by anything that can see the executed command-line. - -// βœ… How -Define system properties need at the JVM start, usually on the command-line: - -[source,sh] ----- -java -Dotel.service.name=my-service ... ----- - -[discrete] -[[configure-configuration-file]] -==== Configuration file - -// βœ… What and why -The distro can be configured using a configuration file. - -// βœ… How -Create and populate the configuration file before the JVM is started, and specify where properties are defined at the JVM start: - -[source,sh] ----- -echo otel.service.name=my-service > my.properties -java -Dotel.javaagent.configuration-file=my.properties ... ----- - -[discrete] -[[configuration-options]] -=== Configuration options - -Because the Elastic Distribution for OpenTelemetry Java ("the distro") is an extension of the https://github.com/open-telemetry/opentelemetry-java-instrumentation[OpenTelemetry Java agent], it supports both: - -* General OpenTelemetry SDK configuration options -* Elastic-specific configuration options that are only available when using the distro - -[discrete] -[[configure-otel-sdk-options]] -==== OpenTelemetry SDK configuration options - -The distro supports all configuration options listed in the https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry General SDK Configuration documentation]. - -//// -TO DO: -Does this approach and language make sense? -//// -[discrete] -[[configure-distro-options]] -==== Elastic distro configuration options - -In addition to general OpenTelemetry SDK configuration options, there are two kinds -of configuration options that are only available in the {distro_name}: - -* Additional `OTEL_` options that Elastic plans to contribute upstream to the https://opentelemetry.io/docs/languages/{language_lc}[OpenTelemetry SDK for {language}], but are not yet available in the OpenTelemetry SDK for {language}. -* `ELASTIC_OTEL_` options that are specific to Elastic and will always live in the {distro_name} (in other words, it will _not_ be added upstream). - -//// -TO DO: -List config options instead of linking to the README -//// -Read more about configuration options that are only available in the distro in https://github.com/elastic/elastic-otel-java?tab=readme-ov-file#features[the elastic/elastic-otel-java README]. - -//// -βœ… List auth methods -//// -[discrete] -[[configure-auth-methods]] -=== Authentication methods - -When sending data to Elastic, there are two ways you can authenticate: using an APM agent key or using a secret token. - -Both the distro and APM Server must be configured with the same secret token for the request to be accepted. - -[discrete] -[[configure-api-key]] -==== Use an APM agent key (API key) - -// βœ… What and why -It is also possible to authenticate to an Elastic Observability endpoint using -an {observability-guide}/apm-api-key.html[APM agent key]. -APM agent keys are revocable, you can have more than one of them, and -you can add or remove them without restarting APM Server. - -// βœ… How do you authenticate using this method? -To create and manage APM Agent keys in {kib}: - -. Go to *APM Settings*. -. Select the *Agent Keys* tab. - -When using an APM Agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using a -different auth schema (`ApiKey` rather than `Bearer`). For example: - -// βœ… Code example -[source,sh] ----- -export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io -export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey TkpXUkx...dVZGQQ==" ----- - -[discrete] -[[configure-secret-token]] -==== Use a secret token - -// βœ… What and why -{observability-guide}/apm-secret-token.html[Secret tokens] are used to authorize requests to the APM Server. - -// βœ… How do you authenticate using this method? -// tag::get-auth[] -You can find the values of these variables in {kib}'s APM tutorial. -In {kib}: - -. Go to *Setup guides*. -. Select *Observability*. -. Select *Monitor my application performance*. -. Scroll down and select the *OpenTelemetry* option. -. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and -`OTEL_EXPORTER_OTLP_HEADERS` are shown there. -+ -For example: -+ -[source,sh] ----- -export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io -export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l" ----- -// end::get-auth[] - -:!language: -:!language_lc: -:!distro_name: diff --git a/docs/configure.md b/docs/configure.md new file mode 100644 index 00000000..8cbb29c5 --- /dev/null +++ b/docs/configure.md @@ -0,0 +1,150 @@ + + +# Configure + +> [!WARNING] +> The Elastic Distribution for 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). + + +## Configuration methods + +OpenTelemetry configuration options should be set using one of the mechanisms listed in the +[OpenTelemetry documentation](https://opentelemetry.io/docs/zero-code/java/agent/configuration/), +including: + +* [Environment variables](#environment-variables) +* [System properties](#system-properties) +* [Configuration file](#configuration-file) + + +Configuration options set using environment variables take precedence over system properties, and +system properties take precedence over configuration options set using file properties. + +### Environment variables + + +The distro can be configured using environment variables. +This is a cross-platform way to configure the distro and is especially useful in containerized environments. + + +Define environment variables before the start of the JVM: + +```sh +export OTEL_SERVICE_NAME=my-service +java ... +``` + +### System properties + + +The distro can be configured using system properties. +These configuration options can be seen by anything that can see the executed command-line. + + +Define system properties need at the JVM start, usually on the command-line: + +```sh +java -Dotel.service.name=my-service ... +``` + +### Configuration file + + +The distro can be configured using a configuration file. + + +Create and populate the configuration file before the JVM is started, and specify where properties are defined at the JVM start: + +```sh +echo otel.service.name=my-service > my.properties +java -Dotel.javaagent.configuration-file=my.properties ... +``` + +## Configuration options + +Because the Elastic Distribution for OpenTelemetry Java ("the distro") is an extension of the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation), it supports both: + +* General OpenTelemetry SDK configuration options +* Elastic-specific configuration options that are only available when using the distro + +### OpenTelemetry SDK configuration options + +The distro supports all configuration options listed in the [OpenTelemetry General SDK Configuration documentation](https://opentelemetry.io/docs/languages/sdk-configuration/general/). + + +### Elastic distro configuration options + +In addition to general OpenTelemetry SDK configuration options, there are two kinds +of configuration options that are only available in the Elastic Distribution for OpenTelemetry Java: + +* Additional `OTEL_` options that Elastic plans to contribute upstream to the [OpenTelemetry SDK for Java](https://opentelemetry.io/docs/languages/java), but are not yet available in the OpenTelemetry SDK for Java. +* `ELASTIC_OTEL_` options that are specific to Elastic and will always live in the Elastic Distribution for OpenTelemetry Java (in other words, it will _not_ be added upstream). + + +Read more about configuration options that are only available in the distro in [the elastic/elastic-otel-java README](https://github.com/elastic/elastic-otel-java?tab=readme-ov-file#features). + + +## Authentication methods + +When sending data to Elastic, there are two ways you can authenticate: using an APM agent key or using a secret token. + +Both the distro and APM Server must be configured with the same secret token for the request to be accepted. + +### Use an APM agent key (API key) + + +It is also possible to authenticate to an Elastic Observability endpoint using +an {observability-guide}/apm-api-key.html[APM agent key]. +APM agent keys are revocable, you can have more than one of them, and +you can add or remove them without restarting APM Server. + + +To create and manage APM Agent keys in Kibana: + +. Go to *APM Settings*. +. Select the *Agent Keys* tab. + +When using an APM Agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using a +different auth schema (`ApiKey` rather than `Bearer`). For example: + + +```sh +export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io +export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey TkpXUkx...dVZGQQ==" +``` + +### Use a secret token + + +[Secret tokens](https://www.elastic.co/guide/en/observability/current/apm-secret-token.html) are used to authorize requests to the APM Server. + + +You can find the values of these variables in Kibana's APM tutorial. +In Kibana: + +1. Go to **Setup guides**. +1. Select **Observability**. +1. Select **Monitor my application performance**. +1. Scroll down and select the **OpenTelemetry** option. +1. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` are shown there. + For example: + + ```sh + export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io + export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l" + ``` diff --git a/docs/get-started.asciidoc b/docs/get-started.asciidoc deleted file mode 100644 index d6de8e48..00000000 --- a/docs/get-started.asciidoc +++ /dev/null @@ -1,144 +0,0 @@ -//// -Goal of this doc: -The user is able to successfully see data from their Java application make it to the Elastic UI via the Elastic Distribution for OpenTelemetry Java - -Assumptions we're comfortable making about the reader: -* They are familiar with Elastic -* They are familiar with OpenTelemetry -* They have Java installed -//// - -[[get-started]] -== Get started - -:language: Java -:language_lc: java -:distro_name: Elastic Distribution for OpenTelemetry {language} - -include::release-status.asciidoc[] - -This guide shows you how to use the Elastic Distribution for OpenTelemetry {language} ("the distro") to instrument your {language} application and send OpenTelemetry data to an Elastic Observability deployment. - -This doc will guide you through the minimal configuration options to get the Elastic distro set up in your application. -You do _not_ need any existing experience with OpenTelemetry to set up the Elastic distro initially. -If you need more control over your configuration after getting set up, you can learn more in https://opentelemetry.io/docs/languages/net[OpenTelemetry SDK documentation]. - -[NOTE] -==== -As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint (https://opentelemetry.io/docs/collector/[OpenTelemetry Collector]), but this guide assumes you are sending data to Elastic. -==== - -//// -βœ… What the user needs to know and/or do before they install the distro -//// -[discrete] -[[get-started-prerequisites]] -=== Prerequisites - -Before getting started, you'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an https://www.elastic.co/observability[Elastic Observability] cloud deployment. You can use an existing one or set up a new one. -[[elastic-observability-setup]] -[%collapsible] -.*Expand for setup instructions* -==== -To create your first Elastic Observability deployment: - -. Sign up for a https://cloud.elastic.co/registration[free Elastic Cloud trial] or sign into an existing account. -. Go to https://cloud.elastic.co/home. -. Click *Create deployment*. -. When the deployment is ready, click *Open* to visit your {kib} home page (for example, `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`). -==== - -//// -βœ… How to install the distro -//// -[discrete] -[[get-started-install]] -=== Install - -//// -βœ… Step-by-step instructions -//// -To get started with the distro: - -. Download the https://mvnrepository.com/artifact/co.elastic.otel/elastic-otel-javaagent/latest[latest release]. -. Run the distro using the `-javaagent:` JVM argument with the path to the distro jar: -+ -[source,bash] ----- -java -javaagent:/path/to/agent.jar \ --jar myapp.jar ----- - -//// -This is true for the .NET distro, -is it also true for the Java distro? - -[NOTE] -.The Elastic distro and the OpenTelemetry SDK -==== -The distro includes a transitive dependency on the OpenTelemetry SDK, so you do not _need_ to add the -OpenTelemetry SDK package to your project directly. However, you _can_ explicitly add the OpenTelemetry SDK as a dependency if you want to opt into newer SDK versions. If you do this, the OpenTelemetry SDK dependency must -be defined _before_ the {distro_name} is defined. -==== -//// - -//// -βœ… Start-to-finish operation -//// -[discrete] -[[get-started-send-data]] -=== Send data to Elastic - -After installing the distro, configure and initialize it to start -sending data to Elastic. - -//// -βœ… Provide _minimal_ configuration/setup -//// -[discrete] -[[get-started-configure]] -==== Configure the distro - -//// -βœ… Step-by-step instructions -//// -To configure the distro, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and -authorization data to set the appropriate `OTLP_*` environment variables: - -* `OTEL_EXPORTER_OTLP_ENDPOINT`: The full URL of the endpoint where data will be sent. -* `OTEL_EXPORTER_OTLP_HEADERS`: A comma-separated list of `key=value` pairs that will -be added to the headers of every request. This is typically this is used for -<>. - -include::./configure.asciidoc[tag=get-auth] - -//// -βœ… What success looks like -//// -[discrete] -[[get-started-confirm]] -=== Confirm that the distro is working - -To confirm that the distro has successfully connected to Elastic: - -. Go to *APM* β†’ *Traces*. -. You should see the name of the service to which you just added the distro. -It can take several minutes after initializing the distro for the service to show up in this list. -. Click on the name in the list to see trace data. -+ -NOTE: There may be no trace data to visualize unless you have _used_ your application since -initializing the distro. - -//// -βœ… What they should do next -//// -[discrete] -[[get-started-next-steps]] -=== Next steps - -* <> to send data to Elastic. -* Learn more about viewing and interpreting data in the {observability-guide}/apm.html[Observability guide]. - -:!language: -:!language_lc: -:!distro_name: diff --git a/docs/get-started.md b/docs/get-started.md new file mode 100644 index 00000000..2bfa88a7 --- /dev/null +++ b/docs/get-started.md @@ -0,0 +1,114 @@ + + +# Get started + +> [!WARNING] +> The Elastic Distribution for 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 guide shows you how to use the Elastic Distribution for OpenTelemetry Java ("the distro") to instrument your Java application and send OpenTelemetry data to an Elastic Observability deployment. + +This doc will guide you through the minimal configuration options to get the Elastic distro set up in your application. +You do _not_ need any existing experience with OpenTelemetry to set up the Elastic distro initially. +If you need more control over your configuration after getting set up, you can learn more in [OpenTelemetry SDK documentation](https://opentelemetry.io/docs/languages/java/). + +> [!NOTE] +> As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint ([OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)), but this guide assumes you are sending data to Elastic. + + +## Prerequisites + +Before getting started, you'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an [Elastic Observability](https://www.elastic.co/observability) cloud deployment. You can use an existing one or set up a new one. + +
+Expand for setup instructions + +To create your first Elastic Observability deployment: + +1. Sign up for a [free Elastic Cloud trial](https://cloud.elastic.co/registration) or sign into an existing account. +1. Go to . +1. Click **Create deployment**. +1. When the deployment is ready, click **Open** to visit your Kibana home page (for example, `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`). +
+ + +## Install + + +To get started with the distro: + +1. Download the [latest release](https://mvnrepository.com/artifact/co.elastic.otel/elastic-otel-javaagent/latest). +1. Run the distro using the `-javaagent:` JVM argument with the path to the distro jar: + + ```bash + java -javaagent:/path/to/agent.jar \ + -jar myapp.jar + ``` + + + + +## Send data to Elastic + +After installing the distro, configure and initialize it to start +sending data to Elastic. + + +### Configure the distro + + +To configure the distro, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and +authorization data to set the appropriate `OTLP_*` environment variables: + +* `OTEL_EXPORTER_OTLP_ENDPOINT`: The full URL of the endpoint where data will be sent. +* `OTEL_EXPORTER_OTLP_HEADERS`: A comma-separated list of `key=value` pairs that will +be added to the headers of every request. This is typically this is used for authentication information. + +You can find the values of these variables in Kibana's APM tutorial. +In Kibana: + +1. Go to **Setup guides**. +1. Select **Observability**. +1. Select **Monitor my application performance**. +1. Scroll down and select the **OpenTelemetry** option. +1. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` are shown there. + For example: + + ```sh + export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io + export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l" + ``` + + +## Confirm that the distro is working + +To confirm that the distro has successfully connected to Elastic: + +1. Go to **APM** β†’ **Traces**. +1. You should see the name of the service to which you just added the distro. +It can take several minutes after initializing the distro for the service to show up in this list. +1. Click on the name in the list to see trace data. + + > [!NOTE] + > There may be no trace data to visualize unless you have _used_ your application since initializing the distro. + + +## Next steps + +* [Configure the distro](./configure.md) to send data to Elastic. +* Learn more about viewing and interpreting data in the [Observability guide](https://www.elastic.co/guide/en/observability/current/apm.html). diff --git a/docs/index.asciidoc b/docs/index.asciidoc deleted file mode 100644 index a7b59302..00000000 --- a/docs/index.asciidoc +++ /dev/null @@ -1,16 +0,0 @@ -include::{asciidoc-dir}/../../shared/versions/stack/current.asciidoc[] -include::{asciidoc-dir}/../../shared/attributes.asciidoc[] - -ifdef::env-github[] -NOTE: For the best reading experience, -please view this documentation at https://www.elastic.co/guide/en/apm/open-telemetry/java[elastic.co] -endif::[] - -= Elastic Distribution for OpenTelemetry Java - -ifndef::env-github[] -include::./intro.asciidoc[] -include::./get-started.asciidoc[] -include::./configure.asciidoc[] -include::./migrate.asciidoc[] -endif::[] diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..9ec7237e --- /dev/null +++ b/docs/index.md @@ -0,0 +1,6 @@ +# Elastic Distribution for OpenTelemetry Java + +* [Introduction](./intro.md) +* [Get started](./get-started.md) +* [Configuration](./configure.md) +* [Migrate to the Elastic Distro from the Elastic APM agent](./migrate.md) diff --git a/docs/intro.asciidoc b/docs/intro.asciidoc deleted file mode 100644 index 4097ed07..00000000 --- a/docs/intro.asciidoc +++ /dev/null @@ -1,82 +0,0 @@ -//// -Goal of this doc: -Provide all the information a user needs to determine if the product is a good enough fit for their use case to merit further exploration - -Assumptions we're comfortable making about the reader: -* They are familiar with Elastic -* They are familiar with OpenTelemetry -//// - -[[intro]] -== Elastic Distribution for OpenTelemetry Java - -++++ -Introduction -++++ - -:language: Java -:language_lc: java -:distro_name: Elastic Distribution for OpenTelemetry {language} - -include::release-status.asciidoc[] - -//// -βœ… Intro -//// -The {distro_name} ("the distro") is a {language} package that provides: - -* An easy way to instrument your application with OpenTelemetry. -* Configuration defaults for best usage. - -//// -βœ… What is it? -βœ… Why use it? -//// -A _distribution_ is customized version of an upstream OpenTelemetry repository with some customizations. The {distro_name} is an extension of the https://opentelemetry.io/docs/languages/{language_lc}[OpenTelemetry SDK for {language}]. With the Elastic distro you have access to all the features of the OpenTelemetry SDK for {language} plus: - -//// -TO DO: -These are true for the Node distro, -are then also true for the Java distro? -//// -* Access to SDK improvements and bug fixes contributed by the Elastic team _before_ the changes are available upstream in OpenTelemetry repositories. -* A single package that includes several OpenTelemetry packages as dependencies, so you only need to install and update a single package (for most use cases). -//// -TO DO: -These are true for the .NET distro, -are they also true for the Java distro? -//// -* Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like Elastic Observability deployment. -* Preconfigures the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. -* Ensures that the OpenTelemetry protocol (OTLP) exporter is enabled by default. - -//// -TO DO: -Is there anything else the Elastic distro adds to the OpenTelemetry SDK for Java -that we should highlight here? -//// - -NOTE: For more details about OpenTelemetry distributions in general, visit the https://opentelemetry.io/docs/concepts/distributions[OpenTelemetry documentation]. - -//// -βœ… How to use it? -//// -Use the distro to start the OpenTelemetry SDK with your {language} application to automatically capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent to any OTLP collector you choose. - -//// -TO DO: -This is true for the .NET distro, -is it also true for the Java distro? -//// -Start with helpful defaults to begin collecting and exporting OpenTelemetry signals quickly. Then, further refine how you use the distro using extension methods that allow you to fully control the creation of the underlying tracer and metric providers. - -After you start sending data to Elastic, use an {observability-guide}/index.html[Elastic Observability] deployment -- hosted on Elastic Cloud or on-premises -- to monitor your applications, create alerts, and quickly identify root causes of service issues. - -//// -βœ… What they should do next -//// -*Ready to try out the distro?* Follow the step-by-step instructions in <>. - -:!language: -:!language_lc: -:!distro_name: diff --git a/docs/intro.md b/docs/intro.md new file mode 100644 index 00000000..fafac6a1 --- /dev/null +++ b/docs/intro.md @@ -0,0 +1,67 @@ + + +# Introduction + +> [!WARNING] +> The Elastic Distribution for 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). + + +The Elastic Distribution for OpenTelemetry Java ("the distro") is a Java package that provides: + +* An easy way to instrument your application with OpenTelemetry. +* Configuration defaults for best usage. + + +A _distribution_ is customized version of an upstream OpenTelemetry repository with some customizations. The Elastic Distribution for OpenTelemetry Java is an extension of the [OpenTelemetry SDK for Java](https://opentelemetry.io/docs/languages/java). With the Elastic distro you have access to all the features of the OpenTelemetry SDK for Java plus: + + +* Access to SDK improvements and bug fixes contributed by the Elastic team _before_ the changes are available upstream in OpenTelemetry repositories. +* A single package that includes several OpenTelemetry packages as dependencies, so you only need to install and update a single package (for most use cases). + +* Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like Elastic Observability deployment. +* Preconfigures the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. +* Ensures that the OpenTelemetry protocol (OTLP) exporter is enabled by default. + + + +> [!NOTE] +> For more details about OpenTelemetry distributions in general, visit the [OpenTelemetry documentation](https://opentelemetry.io/docs/concepts/distributions). + + +Use the distro to start the OpenTelemetry SDK with your Java application to automatically capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent to any OTLP collector you choose. + + +Start with helpful defaults to begin collecting and exporting OpenTelemetry signals quickly. Then, further refine how you use the distro using extension methods that allow you to fully control the creation of the underlying tracer and metric providers. + +After you start sending data to Elastic, use an [Elastic Observability](https://www.elastic.co/guide/en/observability/current/index.html) deployment — hosted on Elastic Cloud or on-premises — to monitor your applications, create alerts, and quickly identify root causes of service issues. + + +**Ready to try out the distro?** Follow the step-by-step instructions in [Get started](./get-started.md). diff --git a/docs/migrate.asciidoc b/docs/migrate.asciidoc deleted file mode 100644 index 957aa473..00000000 --- a/docs/migrate.asciidoc +++ /dev/null @@ -1,135 +0,0 @@ -[[migrate]] -== Migrate to the Elastic distro - -//// -This file is auto generated. Please only make changes in `migrate.asciidoc.ftl` -//// - -:language: Java -:language_lc: java -:distro_name: Elastic Distribution for OpenTelemetry {language} - -include::release-status.asciidoc[] - -:!language: -:!language_lc: -:!distro_name: - -This documentation describes how applications using the {apm-java-ref}/index.html[Elastic APM Java agent] can be updated to use the Elastic Distribution for OpenTelemetry Java ("the distro"). - -Start by installing the distro following the steps outlined in <>. Then update existing APM Java agent configuration options in your application with the equivalent https://opentelemetry.io/docs/languages/sdk-configuration/general/[OpenTelemetry SDK configuration variables] (listed below). - -[discrete] -[[option-reference]] -=== Option reference - -This is a list of all APM Java agent configuration options grouped by their category. -Click on a key to get more information. - -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> -* <> - -[discrete] -[[category]] -=== Elastic to OpenTelemetry mapping - -[discrete] -[[server_url]] -==== `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. - -//// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. -//// - -[discrete] -[[server_urls]] -==== `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. - -//// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. -//// - -[discrete] -[[secret_token]] -==== `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"`. - -//// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. -//// - -[discrete] -[[api_key]] -==== `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"`. - -//// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. -//// - -[discrete] -[[service_name]] -==== `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. - -//// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. -//// - -[discrete] -[[enabled]] -==== `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. - -//// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. -//// - -[discrete] -[[service_version]] -==== `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`. - -//// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. -//// - -[discrete] -[[environment]] -==== `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`. - -//// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. -//// - -[discrete] -[[global_labels]] -==== `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, e.g. labels.alice=first - -//// -This file is auto-generated. Please make changes in *Configuration.java (for example, CoreConfiguration.java) and execute ConfigurationExporter. -//// - - - -// Elastic to OpenTelemetry mapping diff --git a/docs/migrate.md b/docs/migrate.md new file mode 100644 index 00000000..fa71fd4d --- /dev/null +++ b/docs/migrate.md @@ -0,0 +1,102 @@ +# Migrate to the Elastic distro + + + +This documentation describes how applications using the [Elastic APM Java agent](https://www.elastic.co/guide/en/apm/agent/java/current/index.html) can be updated to use the Elastic Distribution for OpenTelemetry Java ("the distro"). + +Start by installing the distro 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. +Click on a key to get more information. + +* [server_url](#server_url) +* [server_urls](#server_urls) +* [secret_token](#secret_token) +* [api_key](#api_key) +* [service_name](#service_name) +* [enabled](#enabled) +* [service_version](#service_version) +* [environment](#environment) +* [global_labels](#global_labels) + +## Elastic to OpenTelemetry mapping + +### `server_url` + +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. + + + +### `server_urls` + +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. + + + +### `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"`. + + + +### `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"`. + + + +### `service_name` + +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. + + + +### `enabled` + +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. + + + +### `service_version` + +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`. + + + +### `environment` + +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`. + + + +### `global_labels` + +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 + + + + + + diff --git a/docs/release-status.asciidoc b/docs/release-status.asciidoc deleted file mode 100644 index 4d99f5aa..00000000 --- a/docs/release-status.asciidoc +++ /dev/null @@ -1,9 +0,0 @@ -.Alpha release -[WARNING] -==== -The {distro_name} 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 https://github.com/elastic/elastic-otel-{language_lc}/issues[opening a GitHub issue] or starting a discussion thread on the https://discuss.elastic.co/tags/c/observability/apm/58/{language_lc}[Elastic Discuss forum]. -==== From 597a8a1f8e4f5c72168dd9f52e5d183f0ed3ae43 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 2 Aug 2024 15:03:21 -0500 Subject: [PATCH 12/25] merge intro content and README content, link to docs from README --- README.md | 22 +++++++++++++++-- docs/index.md | 6 ----- docs/intro.md | 67 --------------------------------------------------- 3 files changed, 20 insertions(+), 75 deletions(-) delete mode 100644 docs/index.md delete mode 100644 docs/intro.md diff --git a/README.md b/README.md index cbd23aa1..07d301b6 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,20 @@ [![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 for 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 for OpenTelemetry Java (the distro) is an extension of the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation). Use the distro 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 the Elastic distro 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 the distro?** Follow the step-by-step instructions in [Get started](./docs/get-started.md). ## Download @@ -21,6 +32,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) +* [Configuration](./docs/configure.md) +* [Migrate to the distro from the Elastic APM Java agent](./docs/migrate.md) + ## Build and Test Execute `./gradlew assemble`, the agent binary will be in `./agent/build/libs/elastic-otel-javaagent-${VERSION}.jar` diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 9ec7237e..00000000 --- a/docs/index.md +++ /dev/null @@ -1,6 +0,0 @@ -# Elastic Distribution for OpenTelemetry Java - -* [Introduction](./intro.md) -* [Get started](./get-started.md) -* [Configuration](./configure.md) -* [Migrate to the Elastic Distro from the Elastic APM agent](./migrate.md) diff --git a/docs/intro.md b/docs/intro.md deleted file mode 100644 index fafac6a1..00000000 --- a/docs/intro.md +++ /dev/null @@ -1,67 +0,0 @@ - - -# Introduction - -> [!WARNING] -> The Elastic Distribution for 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). - - -The Elastic Distribution for OpenTelemetry Java ("the distro") is a Java package that provides: - -* An easy way to instrument your application with OpenTelemetry. -* Configuration defaults for best usage. - - -A _distribution_ is customized version of an upstream OpenTelemetry repository with some customizations. The Elastic Distribution for OpenTelemetry Java is an extension of the [OpenTelemetry SDK for Java](https://opentelemetry.io/docs/languages/java). With the Elastic distro you have access to all the features of the OpenTelemetry SDK for Java plus: - - -* Access to SDK improvements and bug fixes contributed by the Elastic team _before_ the changes are available upstream in OpenTelemetry repositories. -* A single package that includes several OpenTelemetry packages as dependencies, so you only need to install and update a single package (for most use cases). - -* Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like Elastic Observability deployment. -* Preconfigures the collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default. -* Ensures that the OpenTelemetry protocol (OTLP) exporter is enabled by default. - - - -> [!NOTE] -> For more details about OpenTelemetry distributions in general, visit the [OpenTelemetry documentation](https://opentelemetry.io/docs/concepts/distributions). - - -Use the distro to start the OpenTelemetry SDK with your Java application to automatically capture tracing data, performance metrics, and logs. Traces, metrics, and logs are sent to any OTLP collector you choose. - - -Start with helpful defaults to begin collecting and exporting OpenTelemetry signals quickly. Then, further refine how you use the distro using extension methods that allow you to fully control the creation of the underlying tracer and metric providers. - -After you start sending data to Elastic, use an [Elastic Observability](https://www.elastic.co/guide/en/observability/current/index.html) deployment — hosted on Elastic Cloud or on-premises — to monitor your applications, create alerts, and quickly identify root causes of service issues. - - -**Ready to try out the distro?** Follow the step-by-step instructions in [Get started](./get-started.md). From a7bea62ba8dda30730d98aca48287d675ea04a7d Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 2 Aug 2024 15:18:58 -0500 Subject: [PATCH 13/25] adjust for github audience --- docs/configure.md | 18 ++++-------------- docs/get-started.md | 29 ++++------------------------- 2 files changed, 8 insertions(+), 39 deletions(-) diff --git a/docs/configure.md b/docs/configure.md index 8cbb29c5..2766f14f 100644 --- a/docs/configure.md +++ b/docs/configure.md @@ -1,19 +1,10 @@ # Configure -> [!WARNING] -> The Elastic Distribution for 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). - ## Configuration methods @@ -89,20 +80,19 @@ Does this approach and language make sense? In addition to general OpenTelemetry SDK configuration options, there are two kinds of configuration options that are only available in the Elastic Distribution for OpenTelemetry Java: -* Additional `OTEL_` options that Elastic plans to contribute upstream to the [OpenTelemetry SDK for Java](https://opentelemetry.io/docs/languages/java), but are not yet available in the OpenTelemetry SDK for Java. +* Additional `OTEL_` options that Elastic plans to contribute upstream to the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation), but are not yet available in the OpenTelemetry Java agent. * `ELASTIC_OTEL_` options that are specific to Elastic and will always live in the Elastic Distribution for OpenTelemetry Java (in other words, it will _not_ be added upstream). -Read more about configuration options that are only available in the distro in [the elastic/elastic-otel-java README](https://github.com/elastic/elastic-otel-java?tab=readme-ov-file#features). +Find a list of configuration options that are only available in the Elastic distro in [README](https://github.com/elastic/elastic-otel-java?tab=readme-ov-file#features). ## Authentication methods When sending data to Elastic, there are two ways you can authenticate: using an APM agent key or using a secret token. - Both the distro and APM Server must be configured with the same secret token for the request to be accepted. ### Use an APM agent key (API key) @@ -116,8 +106,8 @@ you can add or remove them without restarting APM Server. To create and manage APM Agent keys in Kibana: -. Go to *APM Settings*. -. Select the *Agent Keys* tab. +1. Go to **APM Settings**. +1. Select the **Agent Keys** tab. When using an APM Agent key, the `OTEL_EXPORTER_OTLP_HEADERS` is set using a different auth schema (`ApiKey` rather than `Bearer`). For example: diff --git a/docs/get-started.md b/docs/get-started.md index 2bfa88a7..f721dcc1 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -1,33 +1,20 @@ # Get started -> [!WARNING] -> The Elastic Distribution for 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 guide shows you how to use the Elastic Distribution for OpenTelemetry Java ("the distro") to instrument your Java application and send OpenTelemetry data to an Elastic Observability deployment. +This guide shows you how to use the Elastic Distribution for OpenTelemetry Java (the distro) to instrument your Java application and send OpenTelemetry data to an Elastic Observability deployment. -This doc will guide you through the minimal configuration options to get the Elastic distro set up in your application. -You do _not_ need any existing experience with OpenTelemetry to set up the Elastic distro initially. -If you need more control over your configuration after getting set up, you can learn more in [OpenTelemetry SDK documentation](https://opentelemetry.io/docs/languages/java/). +**Already familiar with OpenTelemetry?** It's an explicit goal of this distribution to introduce _no new concepts_ outside those defined by the wider OpenTelemetry community. -> [!NOTE] -> As an OpenTelemetry SDK, the distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint ([OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)), but this guide assumes you are sending data to Elastic. +**New to OpenTelemetry?** This section will guide you through the _minimal_ configuration options to get the Elastic distro set up in your application. You do _not_ need any existing experience with OpenTelemetry to set up the Elastic distro initially. If you need more control over your configuration after getting set up, you can learn more in the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation). ## Prerequisites -Before getting started, you'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. This doc assumes you're using an [Elastic Observability](https://www.elastic.co/observability) cloud deployment. You can use an existing one or set up a new one. +Before getting started, you'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. The distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint, but this guide assumes you are sending data to an [Elastic Observability](https://www.elastic.co/observability) cloud deployment. You can use an existing one or set up a new one.
Expand for setup instructions @@ -54,14 +41,6 @@ To get started with the distro: -jar myapp.jar ``` - - ## Send data to Elastic From 907bf1d4b74a0308e8d8bf7b0d0bcdd9a13b7dee Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 2 Aug 2024 15:23:18 -0500 Subject: [PATCH 14/25] fix some formatting --- docs/get-started.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/get-started.md b/docs/get-started.md index f721dcc1..000c2a14 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -9,7 +9,7 @@ This guide shows you how to use the Elastic Distribution for OpenTelemetry Java **Already familiar with OpenTelemetry?** It's an explicit goal of this distribution to introduce _no new concepts_ outside those defined by the wider OpenTelemetry community. -**New to OpenTelemetry?** This section will guide you through the _minimal_ configuration options to get the Elastic distro set up in your application. You do _not_ need any existing experience with OpenTelemetry to set up the Elastic distro initially. If you need more control over your configuration after getting set up, you can learn more in the [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation). +**New to OpenTelemetry?** This section will guide you through the _minimal_ configuration options to get the Elastic distro set up in your application. You do _not_ need any existing experience with OpenTelemetry to set up the Elastic distro initially. If you need more control over your configuration after getting set up, you can learn more in the [OpenTelemetry documentation](https://opentelemetry.io/docs/zero-code/java/agent/). ## Prerequisites @@ -35,7 +35,6 @@ To get started with the distro: 1. Download the [latest release](https://mvnrepository.com/artifact/co.elastic.otel/elastic-otel-javaagent/latest). 1. Run the distro using the `-javaagent:` JVM argument with the path to the distro jar: - ```bash java -javaagent:/path/to/agent.jar \ -jar myapp.jar @@ -67,7 +66,6 @@ In Kibana: 1. Scroll down and select the **OpenTelemetry** option. 1. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` are shown there. For example: - ```sh export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....l" @@ -83,8 +81,8 @@ To confirm that the distro has successfully connected to Elastic: It can take several minutes after initializing the distro for the service to show up in this list. 1. Click on the name in the list to see trace data. - > [!NOTE] - > There may be no trace data to visualize unless you have _used_ your application since initializing the distro. +> [!NOTE] +> There may be no trace data to visualize unless you have _used_ your application since initializing the distro. ## Next steps From c0b561c06ee5ecf8640a5513c07646afae67952b Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 2 Aug 2024 15:26:49 -0500 Subject: [PATCH 15/25] update docs automation --- .../co/elastic/otel/config/ConfigurationExporterTest.java | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/custom/src/test/java/co/elastic/otel/config/ConfigurationExporterTest.java b/custom/src/test/java/co/elastic/otel/config/ConfigurationExporterTest.java index 8ae16e04..99295ec3 100644 --- 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/migrate.asciidoc"); + currentDocumentationPath = Paths.get("../docs/migrate.md"); } /** @@ -69,7 +69,7 @@ void testGeneratedConfigurationDocsAreUpToDate() throws IOException, TemplateExc assertThat(renderedDocumentation) .withFailMessage( - "The rendered configuration documentation (/docs/migrate.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,13 +84,13 @@ static String renderDocumentation(List configurationRegistr cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER); cfg.setLogTemplateExceptions(false); - Template temp = cfg.getTemplate("migrate.asciidoc.ftl"); + Template temp = cfg.getTemplate("migrate.md.ftl"); StringWriter tempRenderedFile = new StringWriter(); tempRenderedFile.write( "[[migrate]]\n" + "== Migrate to the Elastic distro\n\n" + "////\n" - + "This file is auto generated. Please only make changes in `migrate.asciidoc.ftl`\n" + + "This file is auto generated. Please only make changes in `migrate.md.ftl`\n" + "////\n"); final Map> optionsByCategory = new HashMap<>(); optionsByCategory.put("Elastic to OpenTelemetry mapping", configurationRegistry); From 14028dcda45ed1c49a4945101883af15a0bfce84 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 2 Aug 2024 15:28:14 -0500 Subject: [PATCH 16/25] update reference to automation --- docs/migrate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrate.md b/docs/migrate.md index fa71fd4d..4b1ffa57 100644 --- a/docs/migrate.md +++ b/docs/migrate.md @@ -1,7 +1,7 @@ # Migrate to the Elastic distro This documentation describes how applications using the [Elastic APM Java agent](https://www.elastic.co/guide/en/apm/agent/java/current/index.html) can be updated to use the Elastic Distribution for OpenTelemetry Java ("the distro"). From be1578a35d9967067a5c6cbde3ea80c388b49e86 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Thu, 8 Aug 2024 15:28:49 -0500 Subject: [PATCH 17/25] Update README.md Co-authored-by: jackshirazi --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 07d301b6..be7b998b 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,6 @@ The Elastic Distribution for OpenTelemetry Java (the distro) is an extension of the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation). Use the distro 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 the Elastic distro 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. From c651698ad4c2d6295d243f2585377581eb03f8d5 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Tue, 13 Aug 2024 09:59:33 -0500 Subject: [PATCH 18/25] update naming --- NOTICE | 2 +- README.md | 14 ++++---- agent/build.gradle.kts | 4 +-- build.gradle | 2 +- .../config/ConfigurationExporterTest.java | 2 +- custom/src/test/resources/migrate.md.ftl | 4 +-- docs/configure.md | 26 +++++++------- docs/get-started.md | 34 +++++++++---------- docs/migrate.md | 6 ++-- 9 files changed, 48 insertions(+), 46 deletions(-) diff --git a/NOTICE b/NOTICE index bb8d95b9..c43665fd 100644 --- 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 index be7b998b..498c6b37 100644 --- a/README.md +++ b/README.md @@ -1,21 +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) > [!WARNING] -> The Elastic Distribution for 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. +> 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). -The Elastic Distribution for OpenTelemetry Java (the distro) is an extension of the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation). Use the distro 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. +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 the Elastic distro you have access to all the features of the OpenTelemetry Java agent plus: +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 the distro?** Follow the step-by-step instructions in [Get started](./docs/get-started.md). +**Ready to try out EDOT Java?** Follow the step-by-step instructions in [Get started](./docs/get-started.md). ## Download @@ -36,7 +36,7 @@ java -javaagent:/path/to/agent.jar \ * [Get started](./docs/get-started.md) * [Configuration](./docs/configure.md) -* [Migrate to the distro from the Elastic APM Java agent](./docs/migrate.md) +* [Migrate to the Elastic Distribution of OpenTelemetry Java from the Elastic APM Java agent](./docs/migrate.md) ## Build and Test @@ -128,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 index aafee0a9..031943b5 100644 --- 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( 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 b/build.gradle index f1c950e5..96a35326 100644 --- a/build.gradle +++ b/build.gradle @@ -10,7 +10,7 @@ Properties versionProperties = new Properties() versionProperties.load(new FileInputStream(file('version.properties'))) version = versionProperties.get("version") -description = "Elastic Distribution for OpenTelemetry Java" +description = "Elastic Distribution of OpenTelemetry Java" defaultTasks("agent:assemble") diff --git a/custom/src/test/java/co/elastic/otel/config/ConfigurationExporterTest.java b/custom/src/test/java/co/elastic/otel/config/ConfigurationExporterTest.java index 99295ec3..32a35348 100644 --- a/custom/src/test/java/co/elastic/otel/config/ConfigurationExporterTest.java +++ b/custom/src/test/java/co/elastic/otel/config/ConfigurationExporterTest.java @@ -88,7 +88,7 @@ static String renderDocumentation(List configurationRegistr StringWriter tempRenderedFile = new StringWriter(); tempRenderedFile.write( "[[migrate]]\n" - + "== Migrate to the Elastic distro\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"); diff --git a/custom/src/test/resources/migrate.md.ftl b/custom/src/test/resources/migrate.md.ftl index 3fdba99c..f27e7191 100644 --- a/custom/src/test/resources/migrate.md.ftl +++ b/custom/src/test/resources/migrate.md.ftl @@ -1,9 +1,9 @@ <#-- @ftlvariable name="config" type="java.util.Map>" --> <#-- @ftlvariable name="keys" type="java.util.Collection" --> -This documentation describes how applications using the [Elastic APM Java agent](https://www.elastic.co/guide/en/apm/agent/java/current/index.html) can be updated to use the Elastic Distribution for OpenTelemetry Java ("the distro"). +This documentation describes how applications using the [Elastic APM Java agent](https://www.elastic.co/guide/en/apm/agent/java/current/index.html) can be updated to use the Elastic Distribution of OpenTelemetry Java (EDOT Java). -Start by installing the distro 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). +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 diff --git a/docs/configure.md b/docs/configure.md index 2766f14f..2d523120 100644 --- a/docs/configure.md +++ b/docs/configure.md @@ -3,7 +3,9 @@ Goal of this doc: Provide a complete reference of all available configuration options and where/how they can be set. (Any Elastic-specific configuration options are listed directly. General OpenTelemetry configuration options are linked.) --> -# Configure +# Configure the Elastic distribution + +Configure the Elastic Distribution for OpenTelemetry Java (EDOT Java) to send data to Elastic. ## Configuration methods @@ -23,8 +25,8 @@ system properties take precedence over configuration options set using file prop ### Environment variables -The distro can be configured using environment variables. -This is a cross-platform way to configure the distro and is especially useful in containerized environments. +EDOT Java can be configured using environment variables. +This is a cross-platform way to configure EDOT Java and is especially useful in containerized environments. Define environment variables before the start of the JVM: @@ -37,7 +39,7 @@ java ... ### System properties -The distro can be configured using system properties. +EDOT Java can be configured using system properties. These configuration options can be seen by anything that can see the executed command-line. @@ -50,7 +52,7 @@ java -Dotel.service.name=my-service ... ### Configuration file -The distro can be configured using a configuration file. +EDOT Java can be configured using a configuration file. Create and populate the configuration file before the JVM is started, and specify where properties are defined at the JVM start: @@ -62,14 +64,14 @@ java -Dotel.javaagent.configuration-file=my.properties ... ## Configuration options -Because the Elastic Distribution for OpenTelemetry Java ("the distro") is an extension of the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation), it supports both: +Because the Elastic Distribution of OpenTelemetry Java is an extension of the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation), it supports both: * General OpenTelemetry SDK configuration options -* Elastic-specific configuration options that are only available when using the distro +* Elastic-specific configuration options that are only available when using EDOT Java ### OpenTelemetry SDK configuration options -The distro supports all configuration options listed in the [OpenTelemetry General SDK Configuration documentation](https://opentelemetry.io/docs/languages/sdk-configuration/general/). +EDOT Java supports all configuration options listed in the [OpenTelemetry General SDK Configuration documentation](https://opentelemetry.io/docs/languages/sdk-configuration/general/). -Find a list of configuration options that are only available in the Elastic distro in [README](https://github.com/elastic/elastic-otel-java?tab=readme-ov-file#features). +Find a list of configuration options that are only available in EDOT Java in [README](https://github.com/elastic/elastic-otel-java?tab=readme-ov-file#features). ## Authentication methods When sending data to Elastic, there are two ways you can authenticate: using an APM agent key or using a secret token. -Both the distro and APM Server must be configured with the same secret token for the request to be accepted. +Both EDOT Java and APM Server must be configured with the same secret token for the request to be accepted. ### Use an APM agent key (API key) diff --git a/docs/get-started.md b/docs/get-started.md index 000c2a14..36004ab8 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -1,20 +1,20 @@ # Get started -This guide shows you how to use the Elastic Distribution for OpenTelemetry Java (the distro) to instrument your Java application and send OpenTelemetry data to an Elastic Observability deployment. +This guide shows you how to use the Elastic Distribution of OpenTelemetry Java (EDOT Java) to instrument your Java application and send OpenTelemetry data to an Elastic Observability deployment. **Already familiar with OpenTelemetry?** It's an explicit goal of this distribution to introduce _no new concepts_ outside those defined by the wider OpenTelemetry community. -**New to OpenTelemetry?** This section will guide you through the _minimal_ configuration options to get the Elastic distro set up in your application. You do _not_ need any existing experience with OpenTelemetry to set up the Elastic distro initially. If you need more control over your configuration after getting set up, you can learn more in the [OpenTelemetry documentation](https://opentelemetry.io/docs/zero-code/java/agent/). +**New to OpenTelemetry?** This section will guide you through the _minimal_ configuration options to get EDOT Java set up in your application. You do _not_ need any existing experience with OpenTelemetry to set up EDOT Java initially. If you need more control over your configuration after getting set up, you can learn more in the [OpenTelemetry documentation](https://opentelemetry.io/docs/zero-code/java/agent/). - + ## Prerequisites -Before getting started, you'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. The distro supports sending data to any OpenTelemetry protocol (OTLP) endpoint, but this guide assumes you are sending data to an [Elastic Observability](https://www.elastic.co/observability) cloud deployment. You can use an existing one or set up a new one. +Before getting started, you'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. EDOT Java supports sending data to any OpenTelemetry protocol (OTLP) endpoint, but this guide assumes you are sending data to an [Elastic Observability](https://www.elastic.co/observability) cloud deployment. You can use an existing one or set up a new one.
Expand for setup instructions @@ -27,14 +27,14 @@ To create your first Elastic Observability deployment: 1. When the deployment is ready, click **Open** to visit your Kibana home page (for example, `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`).
- + ## Install -To get started with the distro: +To get started with EDOT Java: 1. Download the [latest release](https://mvnrepository.com/artifact/co.elastic.otel/elastic-otel-javaagent/latest). -1. Run the distro using the `-javaagent:` JVM argument with the path to the distro jar: +1. Run EDOT Java using the `-javaagent:` JVM argument with the path to the EDOT Java jar: ```bash java -javaagent:/path/to/agent.jar \ -jar myapp.jar @@ -43,14 +43,14 @@ To get started with the distro: ## Send data to Elastic -After installing the distro, configure and initialize it to start +After installing EDOT Java, configure and initialize it to start sending data to Elastic. -### Configure the distro +### Configure EDOT Java -To configure the distro, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and +To configure EDOT Java, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and authorization data to set the appropriate `OTLP_*` environment variables: * `OTEL_EXPORTER_OTLP_ENDPOINT`: The full URL of the endpoint where data will be sent. @@ -72,20 +72,20 @@ In Kibana: ``` -## Confirm that the distro is working +## Confirm that EDOT Java is working -To confirm that the distro has successfully connected to Elastic: +To confirm that EDOT Java has successfully connected to Elastic: 1. Go to **APM** β†’ **Traces**. -1. You should see the name of the service to which you just added the distro. -It can take several minutes after initializing the distro for the service to show up in this list. +1. You should see the name of the service to which you just added EDOT Java. +It can take several minutes after initializing EDOT Java for the service to show up in this list. 1. Click on the name in the list to see trace data. > [!NOTE] -> There may be no trace data to visualize unless you have _used_ your application since initializing the distro. +> There may be no trace data to visualize unless you have _used_ your application since initializing EDOT Java. ## Next steps -* [Configure the distro](./configure.md) to send data to Elastic. +* [Configure the Elastic distribution](./configure.md) to send data to Elastic. * Learn more about viewing and interpreting data in the [Observability guide](https://www.elastic.co/guide/en/observability/current/apm.html). diff --git a/docs/migrate.md b/docs/migrate.md index 4b1ffa57..339785c6 100644 --- a/docs/migrate.md +++ b/docs/migrate.md @@ -1,12 +1,12 @@ -# Migrate to the Elastic distro +# Migrate to the Elastic distribution -This documentation describes how applications using the [Elastic APM Java agent](https://www.elastic.co/guide/en/apm/agent/java/current/index.html) can be updated to use the Elastic Distribution for OpenTelemetry Java ("the distro"). +This documentation describes how applications using the [Elastic APM Java agent](https://www.elastic.co/guide/en/apm/agent/java/current/index.html) can be updated to use the Elastic Distribution of OpenTelemetry Java (EDOT Java). -Start by installing the distro 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). +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 From 5118a24d775a1898bda862eb8e940649eb7362d7 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Tue, 13 Aug 2024 12:45:45 -0500 Subject: [PATCH 19/25] address feedback from @mdbirnstiehl --- .../co/elastic/otel/config/LegacyConfigurations.java | 2 +- custom/src/test/resources/migrate.md.ftl | 4 ++-- docs/configure.md | 10 +++++----- docs/migrate.md | 6 +++--- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/custom/src/main/java/co/elastic/otel/config/LegacyConfigurations.java b/custom/src/main/java/co/elastic/otel/config/LegacyConfigurations.java index a278ec47..ac58f4e6 100644 --- a/custom/src/main/java/co/elastic/otel/config/LegacyConfigurations.java +++ b/custom/src/main/java/co/elastic/otel/config/LegacyConfigurations.java @@ -61,7 +61,7 @@ private void addAllOptions() { "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 [`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."); + "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 [`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."); diff --git a/custom/src/test/resources/migrate.md.ftl b/custom/src/test/resources/migrate.md.ftl index f27e7191..e6360ed3 100644 --- a/custom/src/test/resources/migrate.md.ftl +++ b/custom/src/test/resources/migrate.md.ftl @@ -1,14 +1,14 @@ <#-- @ftlvariable name="config" type="java.util.Map>" --> <#-- @ftlvariable name="keys" type="java.util.Collection" --> -This documentation describes how applications using the [Elastic APM Java agent](https://www.elastic.co/guide/en/apm/agent/java/current/index.html) can be updated to use the Elastic Distribution of OpenTelemetry Java (EDOT Java). +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. -Click on a key to get more information. +Select one of the following for more information. <#list config as category, options> <#list options as option> diff --git a/docs/configure.md b/docs/configure.md index 2d523120..46897ec9 100644 --- a/docs/configure.md +++ b/docs/configure.md @@ -10,7 +10,7 @@ Configure the Elastic Distribution for OpenTelemetry Java (EDOT Java) to send da ## Configuration methods -OpenTelemetry configuration options should be set using one of the mechanisms listed in the +Set OpenTelemetry configuration options using one of the mechanisms listed in the [OpenTelemetry documentation](https://opentelemetry.io/docs/zero-code/java/agent/configuration/), including: @@ -29,7 +29,7 @@ EDOT Java can be configured using environment variables. This is a cross-platform way to configure EDOT Java and is especially useful in containerized environments. -Define environment variables before the start of the JVM: +Define environment variables before starting the JVM: ```sh export OTEL_SERVICE_NAME=my-service @@ -55,7 +55,7 @@ java -Dotel.service.name=my-service ... EDOT Java can be configured using a configuration file. -Create and populate the configuration file before the JVM is started, and specify where properties are defined at the JVM start: +Before starting the JVM, create and populate the configuration file and specify where to find it: ```sh echo otel.service.name=my-service > my.properties @@ -100,8 +100,8 @@ Both EDOT Java and APM Server must be configured with the same secret token for ### Use an APM agent key (API key) -It is also possible to authenticate to an Elastic Observability endpoint using -an {observability-guide}/apm-api-key.html[APM agent key]. +[APM agent keys](https://www.elastic.co/guide/en/observability/current/apm-api-key.html) are +used to authorize requests to an Elastic Observability endpoint. APM agent keys are revocable, you can have more than one of them, and you can add or remove them without restarting APM Server. diff --git a/docs/migrate.md b/docs/migrate.md index 339785c6..6c771fc7 100644 --- a/docs/migrate.md +++ b/docs/migrate.md @@ -4,14 +4,14 @@ This file is auto generated. Please only make changes in `migrate.md.ftl` --> -This documentation describes how applications using the [Elastic APM Java agent](https://www.elastic.co/guide/en/apm/agent/java/current/index.html) can be updated to use the Elastic Distribution of OpenTelemetry Java (EDOT Java). +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. -Click on a key to get more information. +Select one of the following for more information. * [server_url](#server_url) * [server_urls](#server_urls) @@ -59,7 +59,7 @@ This file is auto-generated. Please make changes in *Configuration.java (for exa ### `service_name` -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. +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. ## Configuration methods From 7b4daff140e753292bf5ec280f5bc7d4cb56f8ef Mon Sep 17 00:00:00 2001 From: Jack Shirazi Date: Wed, 14 Aug 2024 14:49:14 +0100 Subject: [PATCH 22/25] fix ConfigurationExporterTest to generate markdown instead of asciidoc --- .../co/elastic/otel/config/ConfigurationExporterTest.java | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/custom/src/test/java/co/elastic/otel/config/ConfigurationExporterTest.java b/custom/src/test/java/co/elastic/otel/config/ConfigurationExporterTest.java index 32a35348..fffaacf0 100644 --- a/custom/src/test/java/co/elastic/otel/config/ConfigurationExporterTest.java +++ b/custom/src/test/java/co/elastic/otel/config/ConfigurationExporterTest.java @@ -87,11 +87,10 @@ static String renderDocumentation(List configurationRegistr Template temp = cfg.getTemplate("migrate.md.ftl"); StringWriter tempRenderedFile = new StringWriter(); tempRenderedFile.write( - "[[migrate]]\n" - + "== Migrate to the Elastic distribution\n\n" - + "////\n" + "# Migrate to the Elastic distribution\n\n" + + "\n"); final Map> optionsByCategory = new HashMap<>(); optionsByCategory.put("Elastic to OpenTelemetry mapping", configurationRegistry); Map map = new HashMap<>(); From 603fdd3b4076948c7c9fa10ccb784cbebd6d1fb4 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 14 Aug 2024 08:58:40 -0500 Subject: [PATCH 23/25] apply suggestions from code review Co-authored-by: jackshirazi --- README.md | 8 +++++--- docs/configure.md | 20 ++++++++++---------- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 0544d66a..6b532013 100644 --- a/README.md +++ b/README.md @@ -28,15 +28,17 @@ Latest snapshot: [![Sonatype Nexus](https://img.shields.io/nexus/s/co.elastic.ot Use the `-javaagent:` JVM argument with the path to agent jar. ```bash -java -javaagent:/path/to/agent.jar \ --jar myapp.jar +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) + ``` ## 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 +* [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 diff --git a/docs/configure.md b/docs/configure.md index eba0af9b..24d4cc4c 100644 --- a/docs/configure.md +++ b/docs/configure.md @@ -11,7 +11,8 @@ Configure the Elastic Distribution of OpenTelemetry Java (EDOT Java) to send dat ## Configuration methods Set OpenTelemetry configuration options using one of the mechanisms listed in the -[OpenTelemetry documentation](https://opentelemetry.io/docs/zero-code/java/agent/configuration/), +[OpenTelemetry agent documentation](https://opentelemetry.io/docs/zero-code/java/agent/configuration/) +and [OpenTelemetry SDK documentation](https://opentelemetry.io/docs/languages/java/configuration/), including: * [Environment variables](#environment-variables) @@ -67,23 +68,22 @@ java -Dotel.javaagent.configuration-file=my.properties ... Because the Elastic Distribution of OpenTelemetry Java is an extension of the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation), it supports both: * General OpenTelemetry SDK configuration options +* General OpenTelemetry Java agent configuration options * Elastic-specific configuration options that are only available when using EDOT Java -### OpenTelemetry SDK configuration options +### OpenTelemetry configuration options -EDOT Java supports all configuration options listed in the [OpenTelemetry General SDK Configuration documentation](https://opentelemetry.io/docs/languages/sdk-configuration/general/). +EDOT Java supports all configuration options listed in the [OpenTelemetry General SDK Configuration documentation](https://opentelemetry.io/docs/languages/sdk-configuration/general/) and [OpenTelemetry Java agent documentation](https://opentelemetry.io/docs/zero-code/java/agent/configuration/) . - ### Elastic distro configuration options -In addition to general OpenTelemetry SDK configuration options, there are two kinds +In addition to general OpenTelemetry configuration options, there are two kinds of configuration options that are only available in EDOT Java: -* Additional `OTEL_` options that Elastic plans to contribute upstream to the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation), but are not yet available in the OpenTelemetry Java agent. -* `ELASTIC_OTEL_` options that are specific to Elastic and will always live in EDOT Java (in other words, it will _not_ be added upstream). +* Additional `OTEL_` options that Elastic plans to contribute upstream to the [OpenTelemetry Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation), or have been contributed to the +[Java agent contrib repo](https://github.com/open-telemetry/opentelemetry-java-contrib/) and are included +in the EDOT but are not yet available in the OpenTelemetry Java agent. +* `ELASTIC_OTEL_` options that are specific to Elastic and will always live in EDOT Java (in other words, they will _not_ be added upstream). -# Configure the Elastic distribution +# Configure the Elastic Distribution Configure the Elastic Distribution of OpenTelemetry Java (EDOT Java) to send data to Elastic. @@ -44,7 +44,7 @@ EDOT Java can be configured using system properties. These configuration options can be seen by anything that can see the executed command-line. -Define system properties need at the JVM start, usually on the command-line: +Define system properties at the JVM start, usually on the command-line: ```sh java -Dotel.service.name=my-service ... diff --git a/docs/get-started.md b/docs/get-started.md index 36004ab8..063083ee 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -55,7 +55,7 @@ authorization data to set the appropriate `OTLP_*` environment variables: * `OTEL_EXPORTER_OTLP_ENDPOINT`: The full URL of the endpoint where data will be sent. * `OTEL_EXPORTER_OTLP_HEADERS`: A comma-separated list of `key=value` pairs that will -be added to the headers of every request. This is typically this is used for authentication information. +be added to the headers of every request. This is typically used for authentication information. You can find the values of these variables in Kibana's APM tutorial. In Kibana: