Skip to content

Commit 06c58bf

Browse files
bmorelli25bmorelli25
authored
docs: OpenTelemetry Elastic exporter (#3845) (#3860)
1 parent 54029f0 commit 06c58bf

3 files changed

Lines changed: 182 additions & 0 deletions

File tree

‎docs/guide/images/open-telemetry-elastic-arch.png‎

117 KB
Loading

‎docs/guide/index.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ include::./rum.asciidoc[]
2323

2424
include::./opentracing.asciidoc[]
2525

26+
include::./opentelemetry-elastic.asciidoc[]
27+
2628
include::./obs-integrations.asciidoc[]
2729

2830
include::./cross-cluster-search.asciidoc[]

‎docs/guide/opentelemetry-elastic.asciidoc‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
[[open-telemetry-elastic]]
2+
== OpenTelemetry integration
3+
4+
:ot-spec: https://github.com/open-telemetry/opentelemetry-specification/blob/master/README.md
5+
:ot-repo: https://github.com/open-telemetry/opentelemetry-collector
6+
:ot-pipelines: {ot-repo}/blob/master/docs/pipelines.md
7+
:ot-extension: {ot-repo}/blob/master/extension/README.md
8+
:ot-scaling: {ot-repo}/blob/master/docs/performance.md
9+
10+
:ot-collector: https://opentelemetry.io/docs/collector/about/
11+
:ot-dockerhub: https://hub.docker.com/r/otel/opentelemetry-collector-contrib-dev
12+
13+
Elastic's OpenTelemetry integration allows you to reuse your existing OpenTelemetry
14+
instrumentation to quickly analyze distributed traces and metrics with the Elastic Stack.
15+
16+
[float]
17+
[[what-is-opentelemetry]]
18+
=== What is OpenTelemetry?
19+
20+
> OpenTelemetry is a set of APIs, SDKs, tooling, and integrations that enable the creation and
21+
management of telemetry data. It formed through a merger of the OpenTracing and OpenCensus projects.
22+
23+
OpenTelemetry is an open-source project that provides the components necessary to observe your applications and services.
24+
If you're unfamiliar with the project, see the {ot-spec}[spec] for more information.
25+
26+
[float]
27+
[[open-telemetry-elastic-exporter]]
28+
=== Elastic exporter
29+
30+
Elastic's integration is designed to drop into your current OpenTelemetry setup.
31+
We've done this by extending the "contrib" OpenTelemetry collector and adding an Elastic exporter.
32+
This exporter translates the OpenTelemetry trace data collected from your services to Elastic's protocol,
33+
before sending the data to the Elastic Stack.
34+
By extending the OpenTelemetry collector,
35+
no changes are needed in your instrumented services in order to begin using the Elastic Stack.
36+
37+
image::images/open-telemetry-elastic-arch.png[OpenTelemetry Elastic architecture diagram]
38+
39+
[float]
40+
[[open-telemetry-elastic-works]]
41+
=== How the OpenTelemetry Collector works
42+
43+
The OpenTelemetry collector uses three different types of components to handle data: `receivers`, `processors`, and `exporters`.
44+
45+
* `receivers`: Configure how data gets to the collector. At least one receiver must be configured.
46+
* `processors`: Defines optional transformations that occurs between receiving and exporting data.
47+
* `exporters`: Configures how data is sent to its destination--in this case, the Elastic Stack.
48+
49+
Once a `receiver`, `processor`, and `exporter` is defined, `pipelines` can be configured in the `services` section of your configuration. Specifically, a `traces` pipeline will define the path of trace data through your collector, and bring all three of these components together.
50+
51+
TIP: More information is available in the
52+
{ot-pipelines}[OpenTelemetry pipeline docs]
53+
54+
A final note: `extensions` can also be enabled for tasks like monitoring your collectors health.
55+
See the {ot-extension}[OpenTelemetry extension readme]
56+
for a list of supported extensions.
57+
58+
[[open-telemetry-elastic-get-started]]
59+
=== Get started
60+
61+
NOTE: This guide assumes you've already instrumented your services with the OpenTelemetry API and/or SDK.
62+
If you haven't, see the Elastic APM <<install-and-run,install and run guide>> to get started with Elastic APM Agents instead.
63+
64+
[[open-telemetry-elastic-deployment-planning]]
65+
==== Plan your deployment
66+
67+
OpenTelemetry Collectors can be run as an Agent, or as standalone collectors.
68+
They can be deployed as often as necessary and scaled up or out.
69+
70+
Deployment planning resources are available in OpenTelemetry's {ot-collector}[Getting Started]
71+
documentation, and {ot-scaling}[Collector Performance] research.
72+
73+
[[open-telemetry-elastic-download]]
74+
==== Download the collector
75+
76+
The Elastic exporter lives in the {ot-repo}[`opentelemetry-collector-contrib repository`],
77+
and the latest release can be downloaded from {ot-repo}/releases[GitHub releases page].
78+
79+
Docker images are available on {ot-dockerhub}[dockerhub]:
80+
81+
[source,bash]
82+
----
83+
docker pull otel/opentelemetry-collector-contrib-dev
84+
----
85+
86+
You can also build the collector-contrib repository by cloning it and running:
87+
88+
[source,bash]
89+
----
90+
make otelcontribcol
91+
----
92+
93+
[[open-telemetry-elastic-configure]]
94+
==== Configure the collector
95+
96+
Create a `yaml` configuration file.
97+
98+
At a minimum, you must define the URL of the APM Server instance you are sending data to.
99+
For example:
100+
101+
[source,yml]
102+
----
103+
exporters:
104+
elastic:
105+
apm_server_url: "https://elasticapm.example.com"
106+
----
107+
108+
See the <<open-telemetry-elastic-config-ref,configuration reference>> for additional configuration options,
109+
like specifying an API key, secret token, or TLS settings.
110+
111+
The Elastic exporter must also be defined in `service.pipelines.traces.exporters`.
112+
For example:
113+
114+
[source,yml]
115+
----
116+
service:
117+
pipelines:
118+
traces:
119+
exporters: [elastic]
120+
----
121+
122+
If we put everything together, here's an example configuration file that accepts input from an OpenTelemetry Agent,
123+
processes the data, and sends it to an {ess} instance.
124+
125+
[source,yml]
126+
----
127+
receivers:
128+
otlp:
129+
endpoint: localhost:55680
130+
processors:
131+
batch:
132+
timeout: 1s
133+
send_batch_size: 1024
134+
exporters:
135+
elastic:
136+
apm_server_url: "https://elasticapm.example.com"
137+
secret_token: "ESS_TOKEN"
138+
service:
139+
pipelines:
140+
traces:
141+
receivers: [otlp]
142+
processors: [batch]
143+
exporters: [elastic]
144+
----
145+
146+
NOTE: For more information about getting started with an OpenTelemetry Collector,
147+
see the {ot-collector}[OpenTelemetry collector] docs.
148+
149+
[[open-telemetry-elastic-config-ref]]
150+
=== Elastic exporter configuration reference
151+
152+
[[open-telemetry-config-url]]
153+
==== `apm_server_url`
154+
Elastic APM Server URL. (required)
155+
156+
[[open-telemetry-config-api-key]]
157+
==== `api_key`
158+
Credential for {apm-server-ref-v}/api-key.html[API key authorization].
159+
Must also be enabled in Elastic APM Server. (optional)
160+
161+
[[open-telemetry-config-secret-token]]
162+
==== `secret_token`
163+
Credential for {apm-server-ref-v}/secret-token.html[secret token authorization].
164+
Must also be enabled in Elastic APM Server. (optional)
165+
166+
[[open-telemetry-config-ca-file]]
167+
==== `ca_file`
168+
Root Certificate Authority (CA) certificate, for verifying the server's identity if TLS is enabled. (optional)
169+
170+
[[open-telemetry-config-cert-file]]
171+
==== `cert_file`
172+
Client TLS certificate. (optional)
173+
174+
[[open-telemetry-config-key-file]]
175+
==== `key_file`
176+
Client TLS key. (optional)
177+
178+
[[open-telemetry-config-insecure]]
179+
==== `insecure`
180+
Disable verification of the server's identity if TLS is enabled. (optional)

0 commit comments

Comments
 (0)