Skip to content

Clean up OpenTelemetry content #4880

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Clean up OpenTelemetry content #4880

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 2 additions & 6 deletions docs/en/apm-server/redirects.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -753,9 +753,7 @@ Refer to {observability-guide}/apm-open-telemetry-with-elastic.html[OpenTelemetr
[role="exclude",id="open-telemetry-direct"]
=== OpenTelemetry native support

{move-notice}

Refer to {observability-guide}/apm-open-telemetry-direct.html[OpenTelemetry native support].
For information on using OpenTelemetry with Elastic, refer to https://elastic.github.io/opentelemetry/[Elastic Distributions of OpenTelemetry (EDOT)].

[role="exclude",id="open-telemetry-other-env"]
=== AWS Lambda Support
Expand All @@ -781,9 +779,7 @@ Refer to {observability-guide}/apm-open-telemetry-known-limitations.html[Limitat
[role="exclude",id="open-telemetry-resource-attributes"]
=== Resource attributes

{move-notice}

Refer to {observability-guide}/apm-open-telemetry-resource-attributes.html[Resource attributes].
For information on using OpenTelemetry with Elastic, refer to https://elastic.github.io/opentelemetry/[Elastic Distributions of OpenTelemetry (EDOT)].

[role="exclude",id="manage-storage"]
=== Manage storage
Expand Down
4 changes: 1 addition & 3 deletions docs/en/observability/apm/api/apm-server/api-otlp.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,4 @@ APM Server supports two OTLP communication protocols on the same port:
|OTLP logs intake |`/v1/logs`
|====

TIP: See our OpenTelemetry documentation to learn how to send data to the APM Server from an
<<apm-instrument-apps-otel,OpenTelemetry agent>> or
<<apm-connect-open-telemetry-collector,OpenTelemetry collector>>.
TIP: See our https://elastic.github.io/opentelemetry/[OpenTelemetry documentation] to learn how to send data to the APM Server.
26 changes: 12 additions & 14 deletions docs/en/observability/apm/collect-application-data/index.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,7 @@
Use Elastic APM agents or an OpenTelemetry language SDK to instrument a service in the language its written in:

* <<apm-agents,*Elastic APM agents*>>: Elastic APM agents are instrumentation libraries written in the same language as your service.
* <<apm-open-telemetry,*OpenTelemetry*>>: OpenTelemetry is an open source set of APIs, SDKs, tooling, and integrations that enable the capture and management of telemetry data from your services and applications.
** This option includes Elastic Distributions of OpenTelemetry, which are customized versions of https://opentelemetry.io/docs/languages/[OpenTelemetry language SDKs] that are optimized to work with an Elastic backend.
* <<apm-open-telemetry,*OpenTelemetry*>>: OpenTelemetry is an open source set of APIs, SDKs, tooling, and integrations that enable the capture and management of telemetry data from your services and applications. Elastic offers https://elastic.github.io/opentelemetry/edot-sdks/index.html[Elastic Distributions of OpenTelemetry (EDOT)], which are customized versions of https://opentelemetry.io/docs/languages/[OpenTelemetry language SDKs] that are optimized to work with an Elastic backend.

*Not sure which method is right for you?* Compare the available options below.

Expand All @@ -21,12 +20,11 @@ Is this table even helpful?
Is it missing anything that would make it more helpful?
////
|===
| | Elastic APM agent | Elastic Distribution of OpenTelemetry
| | Elastic APM agent | Elastic Distributions of OpenTelemetry (EDOT)

| *Support level*
| Fully supported
| Mixed support +
_Refer to the_ <<apm-collect-data-availability,_availability table_>>
| Fully supported for available languages

| *Data protocol*
| Elastic protocol
Expand All @@ -52,15 +50,15 @@ Are we ok with the gaps it exposes?
[cols="<,^,^"]
|===
| *Language* | *Elastic APM agent* | *Elastic Distributions of OpenTelemetry (EDOT)*
| *Android* | Android agent | {not-available}
| *Go* | Go agent | {not-available}
| *iOS* | iOS agent | {not-available}
| *Java* | Java agent | EDOT Java
| *.NET* | .NET agent | preview:[] EDOT .NET
| *Node.js* | Node.js agent | preview:[] EDOT Node.js
| *PHP* | PHP agent | preview:[] EDOT PHP
| *Python* | Python agent | preview:[] EDOT Python
| *Ruby* | Ruby agent | {not-available}
| *Android* | {not-available} | Elastic OTel Android Agent
| *Go* | Go agent | {not-available}
| *iOS* | {not-available} | Elastic APM iOS Agent
| *Java* | Java agent | EDOT Java
| *.NET* | .NET agent | EDOT .NET
| *Node.js* | Node.js agent | EDOT Node.js
| *PHP* | PHP agent | EDOT PHP
| *Python* | Python agent | EDOT Python
| *Ruby* | Ruby agent | {not-available}
Comment on lines +53 to +61
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As mentioned in elastic/docs-content#1099, I'm not sure what to do about Android and iOS. They are listed in the Elastic OpenTelemetry docs as EDOT SDKs, but those links go back to the APM agent docs where they are called Elastic OTel Android Agent and Elastic APM iOS Agent (not EDOT SDKs). Any guidance would be appreciated!

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Those distros currently lack documentation. I'd say let's link to the GH repos for now.

|===

[discrete]
Expand Down
104 changes: 6 additions & 98 deletions docs/en/observability/apm/collect-application-data/open-telemetry/index.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,21 +13,15 @@
https://opentelemetry.io/docs/concepts/what-is-opentelemetry/[OpenTelemetry] is a set of APIs, SDKs, tooling,
and integrations that enable the capture and management of telemetry data from your services and applications.

Elastic integrates with OpenTelemetry, allowing you to reuse your existing instrumentation
to easily send observability data to the {stack}.
There are several ways to integrate OpenTelemetry with the {stack}:
Elastic integrates with OpenTelemetry, allowing you to reuse your existing instrumentation to easily send observability data to the {stack}. You can integrate OpenTelemetry with the {stack} the following ways:

* <<apm-otel-elastic-distros,Elastic Distributions of OpenTelemetry language SDKs>>
* <<apm-otel-api-sdk-elastic-agent,Upstream OpenTelemetry API/SDK + Elastic APM agent>>
* <<apm-otel-upstream,Upstream OpenTelemetry Collector and language SDKs>>
* <<apm-otel-lambda,Lambda collector exporter>>

[float]
[[apm-otel-elastic-distros]]
== Elastic Distributions of OpenTelemetry language SDKs

preview::["Some Elastic Distributions of OpenTelemetry are 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."]

Elastic offers several distributions of OpenTelemetry language SDKs.
A _distribution_ is a customized version of an upstream OpenTelemetry repository.
Each Elastic Distribution of OpenTelemetry is a customized version of an https://opentelemetry.io/docs/languages/[OpenTelemetry language SDK].
Expand All @@ -47,84 +41,18 @@ such as which sources are collected by default.
// Where to go next
Get started with an Elastic Distribution of OpenTelemetry language SDK:

* https://github.com/elastic/elastic-otel-java[*Elastic Distribution of OpenTelemetry Java →*]
* preview:["The Elastic Distribution of OpenTelemetry .NET 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."] https://github.com/elastic/elastic-otel-dotnet[*Elastic Distribution of OpenTelemetry .NET →*]
* preview:["The Elastic Distribution of OpenTelemetry Node.js 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."] https://github.com/elastic/elastic-otel-node[*Elastic Distribution of OpenTelemetry Node.js →*]
* preview:["The Elastic Distribution of OpenTelemetry Python 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."] https://github.com/elastic/elastic-otel-python[*Elastic Distribution of OpenTelemetry Python →*]
* preview:["The Elastic Distribution of OpenTelemetry PHP 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."] https://github.com/elastic/elastic-otel-php[*Elastic Distribution of OpenTelemetry PHP →*]
* https://elastic.github.io/opentelemetry/edot-sdks/java/index.html[**Elastic Distribution of OpenTelemetry Java →**]
* https://elastic.github.io/opentelemetry/edot-sdks/dotnet/index.html[**Elastic Distribution of OpenTelemetry .NET →**]
* https://elastic.github.io/opentelemetry/edot-sdks/nodejs/index.html[**Elastic Distribution of OpenTelemetry Node.js →**]
* https://elastic.github.io/opentelemetry/edot-sdks/python/index.html[**Elastic Distribution of OpenTelemetry Python →**]
* https://elastic.github.io/opentelemetry/edot-sdks/php/index.html[**Elastic Distribution of OpenTelemetry PHP →**]

[NOTE]
====
For more details about OpenTelemetry distributions in general,
visit the https://opentelemetry.io/docs/concepts/distributions[OpenTelemetry documentation].
====

[float]
[[apm-otel-api-sdk-elastic-agent]]
== Upstream OpenTelemetry API/SDK + Elastic APM agent

Use the OpenTelemetry API/SDKs with <<_step_3_install_apm_agents,Elastic APM agents>> to translate OpenTelemetry API calls to Elastic APM API calls.

image::images/apm-otel-api-sdk-elastic-agent.png[]

// Why you _would_ choose this method
This allows you to reuse your existing OpenTelemetry instrumentation to create Elastic APM transactions and spans--avoiding
vendor lock-in and having to redo manual instrumentation.

// Why you would _not_ choose this method
However, not all features of the OpenTelemetry API are supported when using this approach, and
not all Elastic APM agents support this approach.

// Where to go next
Find more details about how to use an OpenTelemetry API or SDK with an Elastic APM agent and
which OpenTelemetry API features are supported in the APM agent documentation:

* {apm-java-ref}/opentelemetry-bridge.html[*APM Java agent →*]
* {apm-dotnet-ref}/opentelemetry-bridge.html[*APM .NET agent →*]
* {apm-node-ref}/opentelemetry-bridge.html[*APM Node.js agent →*]
* {apm-py-ref}/opentelemetry-bridge.html[*APM Python agent →*]

[float]
[[apm-otel-upstream]]
== Upstream OpenTelemetry Collector and language SDKs

The {stack} natively supports the OpenTelemetry protocol (OTLP).
This means trace data and metrics collected from your applications and infrastructure by an
OpenTelemetry Collector or OpenTelemetry language SDK can be sent to the {stack}.

You can set up an https://opentelemetry.io/docs/collector/[OpenTelemetry Collector], instrument your
application with an https://opentelemetry.io/docs/languages/[OpenTelemetry language SDK] that sends
data to the collector, and use the collector to process and export the data to APM Server.

image::images/apm-otel-api-sdk-collector.png[]

[NOTE]
====
It's also possible to send data directly to APM Server from an upstream OpenTelemetry SDK.
You might do this during development or if you're monitoring a small-scale application.
Read more about when to use a collector in the https://opentelemetry.io/docs/collector/#when-to-use-a-collector[OpenTelemetry documentation].
====

// Why you _would_ choose this approach
This approach works well when you need to instrument a technology that Elastic doesn't
provide a solution for. For example, if you want to instrument C or C++ you could use the
https://github.com/open-telemetry/opentelemetry-cpp[OpenTelemetry C{plus}{plus} client].
// Other languages include erlang, lua, perl.

// Why you would _not_ choose this approach
However, there are some limitations when using collectors and language SDKs built and maintained
by OpenTelemetry, including:

* Elastic can't provide implementation support on how to use upstream OpenTelemetry tools.
* You won't have access to Elastic enterprise APM features.
* You may experience problems with performance efficiency.

For more on the limitations associated with using upstream OpenTelemetry tools,
refer to <<apm-open-telemetry-known-limitations>>.

// Where to go next
<<apm-open-telemetry-direct,*Get started with upstream OpenTelemetry Collectors and language SDKs →*>>

[float]
[[apm-otel-lambda]]
== AWS Lambda collector exporter
Expand All @@ -138,23 +66,3 @@ AWS Lambda functions can be instrumented with OpenTelemetry and monitored with E
To get started, follow the official AWS Distro for OpenTelemetry Lambda documentation, and configure the OpenTelemetry Collector to output traces and metrics to your Elastic cluster:

https://aws-otel.github.io/docs/getting-started/lambda[*Get started with the AWS Distro for OpenTelemetry Lambda*^] image:images/icons/popout.svg[]

////
Subsections
////

include::./otel-direct.asciidoc[leveloffset=+1]
include::./otel-metrics.asciidoc[leveloffset=+1]
include::./otel-limitations.asciidoc[leveloffset=+1]
include::./otel-attrs.asciidoc[leveloffset=+1]

// ****
// The text below is used in the Quick start guide
// tag::otel-get-started[]
Elastic integrates with OpenTelemetry, allowing you to reuse your existing instrumentation
to easily send observability data to the {stack}.

For more information on how to combine Elastic and OpenTelemetry,
see {observability-guide}/apm-open-telemetry.html[OpenTelemetry integration].
// end::otel-get-started[]
// ****
42 changes: 0 additions & 42 deletions ...n/observability/apm/collect-application-data/open-telemetry/otel-attrs.asciidoc
View file
Open in desktop

This file was deleted.

Loading