Skip to content
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.

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

Quickstart k8s otel doc added #4488

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 2 additions & 0 deletions docs/en/observability/index.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ include::quickstarts/monitor-hosts-with-elastic-agent.asciidoc[leveloffset=+2]

include::quickstarts/monitor-k8s-logs-metrics.asciidoc[leveloffset=+2]

include::quickstarts/monitor-k8s-otel.asciidoc[leveloffset=+2]

include::quickstarts/collect-data-with-aws-firehose.asciidoc[leveloffset=+2]

include::splunk-get-started.asciidoc[leveloffset=+2]
Expand Down
66 changes: 66 additions & 0 deletions docs/en/observability/quickstarts/monitor-k8s-otel.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
[[monitor-k8s-otel-edot]]
= Quickstart: Unified Kubernetes Observability with Elastic Distributions of OpenTelemetry (EDOT)

preview::[]

In this quickstart guide, you will learn how to send Kubernetes logs, metrics, and application traces to Elasticsearch, using the https://github.com/open-telemetry/opentelemetry-operator/[OpenTelemetry Operator] to orchestrate https://github.com/elastic/opentelemetry/tree/main[Elastic Distributions of OpenTelemetry] (EDOT) Collectors and SDK instances.

All the components will be deployed through the https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-kube-stack[opentelemetry-kube-stack] helm chart. They include:

* https://github.com/open-telemetry/opentelemetry-operator/[OpenTelemetry Operator].
* `DaemonSet` EDOT Collector configured for node level metrics.
* `Deployment` EDOT Collector configured for cluster level metrics.
* `Instrumentation` object for applications https://opentelemetry.io/docs/kubernetes/operator/automatic/[auto-instrumentation].

For a more detailed description of the components and advanced configuration refer to the https://github.com/elastic/opentelemetry/blob/main/docs/kubernetes/operator/README.md[elastic/opentelemetry] GitHub repository.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
For a more detailed description of the components and advanced configuration refer to the https://github.com/elastic/opentelemetry/blob/main/docs/kubernetes/operator/README.md[elastic/opentelemetry] GitHub repository.
For a more detailed description of the components and advanced configuration, refer to the https://github.com/elastic/opentelemetry/blob/main/docs/kubernetes/operator/README.md[elastic/opentelemetry] GitHub repository.


[discrete]
== Prerequisites

* A deployment using our hosted {ess} on {ess-trial}[{ecloud}]. The deployment includes an {es} cluster for storing and searching your data, and {kib} for visualizing and managing your data.
* A running Kubernetes cluster (v1.23 or newer).
* https://kubernetes.io/docs/reference/kubectl/[Kubectl].
* https://helm.sh/docs/intro/install/[Helm].
* (optional) https://cert-manager.io/docs/installation/[Cert-manager], if you opt for automatic generation and renewal of TLS certificates.

[discrete]
== Collect your data

. In {kib}, go to the **Observability** UI and click **Add Data**.

. Under the question *`What do you want to monitor?`* select **Kubernetes**, and then select the **OpenTelemetry: Full Observability** option.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
. Under the question *`What do you want to monitor?`* select **Kubernetes**, and then select the **OpenTelemetry: Full Observability** option.
. Under *`What do you want to monitor?`*, select **Kubernetes**, and then select the **OpenTelemetry: Full Observability** option.

+
[role="screenshot"]
image::images/quickstart-k8s-otel-entry-point.png[Kubernetes-OTel entry point]

. Follow the on-screen instructions to perform the installation of all needed components.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
. Follow the on-screen instructions to perform the installation of all needed components.
. Follow the on-screen instructions to install all needed components.

+
[NOTE]
====
The default installation deploys the OpenTelemetry Operator with a self-signed TLS certificate valid for 365 days. This certificate **won't be renewed** unless the Helm Chart release is manually updated. Refer to the https://github.com/elastic/opentelemetry/blob/main/docs/kubernetes/operator/README.md#cert-manager[cert-manager integrated installation] guide to enable automatic certificate generation and renewal using https://cert-manager.io/docs/installation/[cert-manager].
====
+
Deploy the OpenTelemetry Operator and EDOT Collectors using the kube-stack Helm chart with the provided `values.yaml` file. You will run a few commands to:
+
* Add the helm chart repository needed for the installation.
* Create a namespace.
* Create a secret with an API Key and the {es} endpoint to be used by the collectors.
* Install the `opentelemetry-kube-stack` helm chart with the provided `values.yaml`.
* Optionally, for instrumenting applications, apply the corresponding `annotations` as showed in {kib}.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
* Optionally, for instrumenting applications, apply the corresponding `annotations` as showed in {kib}.
* Optionally, for instrumenting applications, apply the corresponding `annotations` as shown in {kib}.


[discrete]
== Visualize your data

After installation is complete and all relevant data is flowing into Elastic,
the **Visualize your data** section provides a link to the *[OTEL][Metrics Kubernetes]Cluster Overview* dashboard used to monitor the health of the cluster.

[role="screenshot"]
image::images/quickstart-k8s-otel-dashboard.png[Kubernetes overview dashboard]

[discrete]
== Troubleshooting and more

* For troubleshooting deployment and installation, refer to https://github.com/elastic/opentelemetry/tree/main/docs/kubernetes/operator#installation-verification[installation verification].
* For applications instrumentation details, refer to https://github.com/elastic/opentelemetry/blob/main/docs/kubernetes/operator/instrumenting-applications.md[Instrumenting applications with EDOT SDKs on Kubernetes].
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
* For applications instrumentation details, refer to https://github.com/elastic/opentelemetry/blob/main/docs/kubernetes/operator/instrumenting-applications.md[Instrumenting applications with EDOT SDKs on Kubernetes].
* For application instrumentation details, refer to https://github.com/elastic/opentelemetry/blob/main/docs/kubernetes/operator/instrumenting-applications.md[Instrumenting applications with EDOT SDKs on Kubernetes].

* For customizing the configuration, refer to https://github.com/elastic/opentelemetry/tree/main/docs/kubernetes/operator#custom-configuration[custom configuration].
* Refer to <<observability-introduction>> for a description of other useful features.