documentationTutorial: Getting Started with the OpenTelemetry Astronomy Shop¶
The OpenTelemetry Astronomy Shop, a microservice-based distributed system designed to illustrate the implementation of OpenTelemetry in a near real-world environment. This tutorial walks you through installing the OpenTelemetry Astronomy Shop, sending OpenTelemetry metrics, logs, and traces to Observe, and then enabling you to work with metrics, logs, and traces in Observe.
This tutorial helps you perform the following tasks:
Install the OpenTelemetry Astronomy Shop demo on your Kubernetes or Docker.
Install the Observe OpenTelemetry App.
Deploy the OpenTelemetry collector with the Observe traces Helm chart. (for Kubernetes only)
Explore your OpeTelemetry metrics, logs, and traces in Observe and start creating dashboards and monitors.
The OpenTelemetry Astronomy Shop on Kubernetes¶
Prerequisites¶
Kubernetes 1.24 or higher
6 GB of free RAM for the application
Helm 3.9 or higher
Note
This tutorial derives information from a Google Kubernetes Engine (GKE) (5-node standard cluster).
Installing the OpenTelemetry Astronomy Shop on Kubernetes¶
Add the OpenTelemetry Helm repository.
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
2. To install the chart with the release name my-otel-demo, run the following command:
helm install my-otel-demo open-telemetry/opentelemetry-demo
3. Confirm that the OpenTelemetry Astronomy Shop installed and has data.
$ helm install my-otel-demo open-telemetry/opentelemetry-demo
NAME: my-otel-demo
LAST DEPLOYED: Mon Nov 13 21:01:01 2023
NAMESPACE: default
STATUS: deployed
REVISION: 1
NOTES:
=======================================================================================
██████╗ ████████╗███████╗██╗ ██████╗ ███████╗███╗ ███╗ ██████╗
██╔═══██╗╚══██╔══╝██╔════╝██║ ██╔══██╗██╔════╝████╗ ████║██╔═══██╗
██║ ██║ ██║ █████╗ ██║ ██║ ██║█████╗ ██╔████╔██║██║ ██║
██║ ██║ ██║ ██╔══╝ ██║ ██║ ██║██╔══╝ ██║╚██╔╝██║██║ ██║
╚██████╔╝ ██║ ███████╗███████╗ ██████╔╝███████╗██║ ╚═╝ ██║╚██████╔╝
╚═════╝ ╚═╝ ╚══════╝╚══════╝ ╚═════╝ ╚══════╝╚═╝ ╚═╝ ╚═════╝
- All services are available via the Frontend proxy: http://localhost:8080
by running these commands:
kubectl --namespace default port-forward svc/my-otel-demo-frontendproxy 8080:8080
The following services are available at these paths once the proxy is exposed:
Webstore http://localhost:8080/
Grafana http://localhost:8080/grafana/
Feature Flags UI http://localhost:8080/feature/
Load Generator UI http://localhost:8080/loadgen/
Jaeger UI http://localhost:8080/jaeger/ui/
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
my-otel-demo-accountingservice-d8b7dcff7-pt46v 1/1 Running 0 5m36s
my-otel-demo-adservice-974f5d564-4h2tn 1/1 Running 0 5m36s
my-otel-demo-cartservice-5b66cbf69-bwqhn 1/1 Running 0 5m37s
my-otel-demo-checkoutservice-55c9fb986b-fsnxn 1/1 Running 0 5m37s
my-otel-demo-currencyservice-7bd94fdd96-hn7g6 1/1 Running 0 5m36s
my-otel-demo-emailservice-59978dff46-6lgqn 1/1 Running 0 5m35s
my-otel-demo-featureflagservice-784c546fc8-xxkrv 1/1 Running 0 5m38s
my-otel-demo-ffspostgres-7b5b8798f-9hwsn 1/1 Running 0 5m38s
my-otel-demo-frauddetectionservice-cd897f5c-dh4px 1/1 Running 0 5m38s
my-otel-demo-frontend-5d4d9b6978-qwxq4 1/1 Running 0 5m34s
my-otel-demo-frontendproxy-76d8fbfc85-thxlb 1/1 Running 0 5m36s
my-otel-demo-grafana-76df8f98dc-5l85v 1/1 Running 0 5m38s
my-otel-demo-jaeger-7b684ffb44-bz79j 1/1 Running 0 5m37s
my-otel-demo-kafka-7966444458-n92hz 1/1 Running 0 5m35s
my-otel-demo-loadgenerator-d4d4cf949-fn8fq 1/1 Running 0 5m36s
my-otel-demo-otelcol-684466546b-4kwxq 1/1 Running 0 5m34s
my-otel-demo-paymentservice-99845c4c7-jww22 1/1 Running 0 5m37s
my-otel-demo-productcatalogservice-647777c648-4c9ks 1/1 Running 0 5m35s
my-otel-demo-prometheus-server-7fff9597c5-crkc9 1/1 Running 0 5m35s
my-otel-demo-quoteservice-7d6676c4c7-wn75v 1/1 Running 0 5m35s
my-otel-demo-recommendationservice-5ff6c6d877-gdwgq 1/1 Running 0 5m36s
my-otel-demo-redis-5878b4b9d4-hjbtd 1/1 Running 0 5m37s
my-otel-demo-shippingservice-7bf84b8444-z6htd 1/1 Running 0 5m38s
Installing the OpenTelemetry App¶
Log into your Observe instance, and locate the Applications page using the Applications icon on the Navigation bar.
Select Install new.
Locate the OpenTelemetry app and select the app.
Select the most recent version and then click Install.
Select Advanced and then select the Datastream to send metrics. Use the default value. Turn off Enable Legacy Events, and turn on Enable Logs and Enable Metrics. Then select Continue.
Figure 1 - The OpenTelemetry app configuration
After the installation completes, under Connections > Data connection requirements > Create otel Token, select Get started.
Create a name and description for your OpenTelemetry Token, and click Continue.
Copy the token and save it for later use, and click Continue.
Copy the Helm instructions, and save them to use later. Click Close
Configuring the OpenTelemetry Collector¶
Next, you configure the OpenTelemetry Collector using the following steps:
Create
traces-values-xs.yamlbased on the following config. It runs on small clusters such as development environments, where resources may be scarce, and reliability may be less of a concern. See Mode Details for more information.
opentelemetry-collector:
resources:
limits:
cpu: 50m
memory: 128Mi
requests:
cpu: 50m
memory: 128Mi
2. Ensure the observe namespace exists, with a human-readable cluster name annotation. See namespace requirements for more details.
CLUSTER_NAME="My Cluster"
kubectl create namespace observe && \
kubectl annotate namespace observe observeinc.com/cluster-name="$CLUSTER_NAME"
3. To add the Observe Helm repository, run the following commands:
helm repo add observe https://observeinc.github.io/helm-charts
helm repo update
4. Then create a release for the traces chart in the observe namespace, using helm install.
helm install --namespace=observe observe-traces observe/traces \
-f traces-values-xs.yaml \
--set global.observe.collectionEndpoint="${OBSERVE_COLLECTION_ENDPOINT?}" \
--set observe.token.value="${OBSERVE_TOKEN?}"
5. Save the values to a file, and keep it in a secure location for further configuration and upgrades.
helm -n observe get values observe-traces -o yaml > observe-traces-values.yaml
6. Check whether the OpenTelemetry collector is up and running.
$ kubectl get pods -n observe
NAME READY STATUS RESTARTS AGE
kube-cluster-info-job-r9vio-r28cf 0/1 Completed 0 39s
observe-traces-agent-6rvbx 1/1 Running 0 39s
observe-traces-agent-8pf8p 1/1 Running 0 39s
observe-traces-agent-lv2lr 1/1 Running 0 39s
7. Point the OpenTelemetry Astronomy Shop to the configured OpenTelemetry collector.
Create values.yaml based on the following configuration:
default:
envOverrides:
- name: OTEL_COLLECTOR_NAME
value: 'observe-traces.observe.svc.cluster.local'
Point the OpenTelemetry Astronomy Shop (my-otel-demo) to the OpenTelemetry collector
helm upgrade --reset-values -f values.yaml my-otel-demo open-telemetry/opentelemetry-demo
8. Check whether the OpenTelemetry Astronomy Shop (my-otel-demo) is upgraded.
$ helm upgrade --reset-values -f values.yaml my-otel-demo open-telemetry/opentelemetry-demo
Release "my-otel-demo" has been upgraded. Happy Helming!
NAME: my-otel-demo
LAST DEPLOYED: Tue Nov 14 17:56:53 2023
NAMESPACE: default
STATUS: deployed
REVISION: 3
NOTES:
=======================================================================================
██████╗ ████████╗███████╗██╗ ██████╗ ███████╗███╗ ███╗ ██████╗
██╔═══██╗╚══██╔══╝██╔════╝██║ ██╔══██╗██╔════╝████╗ ████║██╔═══██╗
██║ ██║ ██║ █████╗ ██║ ██║ ██║█████╗ ██╔████╔██║██║ ██║
██║ ██║ ██║ ██╔══╝ ██║ ██║ ██║██╔══╝ ██║╚██╔╝██║██║ ██║
╚██████╔╝ ██║ ███████╗███████╗ ██████╔╝███████╗██║ ╚═╝ ██║╚██████╔╝
╚═════╝ ╚═╝ ╚══════╝╚══════╝ ╚═════╝ ╚══════╝╚═╝ ╚═╝ ╚═════╝
- All services are available via the Frontend proxy: http://localhost:8080
by running these commands:
kubectl --namespace default port-forward svc/my-otel-demo-frontendproxy 8080:8080
The following services are available at these paths once the proxy is exposed:
Webstore http://localhost:8080/
Grafana http://localhost:8080/grafana/
Feature Flags UI http://localhost:8080/feature/
Load Generator UI http://localhost:8080/loadgen/
Jaeger UI http://localhost:8080/jaeger/ui/
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
my-otel-demo-accountingservice-5669d65d75-974c8 1/1 Running 0 2m11s
my-otel-demo-adservice-c7fffdfbb-tnh45 1/1 Running 0 2m11s
my-otel-demo-cartservice-55db868f95-wcllg 1/1 Running 0 2m10s
my-otel-demo-checkoutservice-5744dd6bbd-7rthc 1/1 Running 0 2m10s
my-otel-demo-currencyservice-5469fcd678-mgvx5 1/1 Running 0 2m10s
my-otel-demo-emailservice-76c48578c6-mrg6q 1/1 Running 0 2m10s
my-otel-demo-featureflagservice-59ff68656d-pxgps 1/1 Running 1 (114s ago) 2m9s
my-otel-demo-ffspostgres-77794956f9-xwtkv 1/1 Running 0 2m9s
my-otel-demo-frauddetectionservice-5d574dbfc5-qfv2b 1/1 Running 0 2m8s
my-otel-demo-frontend-79dddd7bb8-98jp7 1/1 Running 0 2m7s
my-otel-demo-frontendproxy-794b8c75c5-ldjq6 1/1 Running 0 2m7s
my-otel-demo-grafana-76df8f98dc-s7p4d 1/1 Running 0 8m2s
my-otel-demo-jaeger-7b684ffb44-jb5tp 1/1 Running 0 8m3s
my-otel-demo-kafka-657f7d6bd4-6w9zp 1/1 Running 0 2m7s
my-otel-demo-loadgenerator-58588b4d4c-6bb7j 1/1 Running 0 2m6s
my-otel-demo-otelcol-684466546b-bzfqb 1/1 Running 0 8m3s
my-otel-demo-paymentservice-7c98f6b8f9-fsw4q 1/1 Running 0 2m6s
my-otel-demo-productcatalogservice-5fb5cc6fcd-pbgtg 1/1 Running 0 2m5s
my-otel-demo-prometheus-server-7fff9597c5-gbn7p 1/1 Running 0 7m59s
my-otel-demo-quoteservice-6fbc95cd7-tr4sd 1/1 Running 0 2m5s
my-otel-demo-recommendationservice-6f49fddb59-r4pmr 1/1 Running 0 2m5s
my-otel-demo-redis-7bd58b6ffd-hqscz 1/1 Running 0 2m4s
my-otel-demo-shippingservice-5fbd695958-dlw59 1/1 Running 0 2m4s
$ kubectl get pods -n observe
NAME READY STATUS RESTARTS AGE
kube-cluster-info-job-r9vio-r28cf 0/1 Completed 0 6m36s
observe-traces-agent-6rvbx 1/1 Running 0 6m36s
observe-traces-agent-8pf8p 1/1 Running 0 6m36s
observe-traces-agent-lv2lr 1/1 Running 0 6m36s
$ kubectl -n default get deployment/my-otel-demo-frontend -o yaml | grep -A 4 -B 4 OTEL_COLLECTOR_NAME
valueFrom:
fieldRef:
apiVersion: v1
fieldPath: metadata.labels['app.kubernetes.io/component']
- name: OTEL_COLLECTOR_NAME
value: observe-traces.observe.svc.cluster.local
- name: OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE
value: cumulative
- name: FRONTEND_PORT
--
value: my-otel-demo-recommendationservice:8080
- name: SHIPPING_SERVICE_ADDR
value: my-otel-demo-shippingservice:8080
- name: OTEL_EXPORTER_OTLP_ENDPOINT
value: http://$(OTEL_COLLECTOR_NAME):4317
- name: WEB_OTEL_SERVICE_NAME
value: frontend-web
- name: PUBLIC_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
value: http://localhost:8080/otlp-http/v1/traces
The OpenTelemetry Astronomy Shop on Docker¶
Prerequisites¶
Docker
Docker Compose v2.0.0+
Make (optional)
6 GB of RAM for the application
Installing the OpenTelemetry App¶
Log into your Observe instance, and locate the Applications page using the Applications icon on the Navigation bar.
Select Install new.
Locate the OpenTelemetry app and select the app.
Select the most recent version and then click Install.
Select Advanced and then select the Datastream to send metrics. Use the default value. Turn off Enable Legacy Events, and turn on Enable Logs and Enable Metrics. Then select Continue.
Figure 1 - The OpenTelemetry app configuration
6. After the installation completes, under Connections > Data connection requirements > Create otel Token, select Get started.
7. Create a name and description for your OpenTelemetry Token, and click Continue.
8. Copy the token and save it for later use, and click Continue.
9. Copy the following information, and save them to use later. Click Close. global.observe.collectionEndpoint will replace endpoint, and traces.observe.token.value will replace ${OBSERVE_TOKEN} later.
--set global.observe.collectionEndpoint="https://${OBSERVE_CUSTOMER}.collect.observeinc.com/" \
--set observe.token.value="${OBSERVE_TOKEN}" \
Preparing the OpenTelemetry Astronomy Shop for Docker¶
Clone the Demo repository:
git clone https://github.com/open-telemetry/opentelemetry-demo.git
2. Change to the demo folder:
cd opentelemetry-demo/
3. Edit otelcol-config-extras.yml, located at src/otelcollector/otelcol-config-extras.yml based on the following config. See Mode Details for more information.
exporters:
otlphttp/example:
endpoint: "https://${OBSERVE_CUSTOMER}.collect.observeinc.com/v1/otel"
headers:
X-Observe-Ignore-Empty-Datapoints: true
authorization: "Bearer ${OBSERVE_TOKEN}"
service:
pipelines:
traces:
exporters: [spanmetrics, otlphttp/example]
metrics:
exporters: [otlphttp/example]
logs:
exporters: [otlphttp/example]
4. Run the OpenTelemetry Astronomy Shop.
$ make start
docker compose up --force-recreate --remove-orphans --detach
[+] Building 0.0s (0/0) docker:desktop-linux
[+] Running 27/27
✔ Network opentelemetry-demo Created 0.0s
✔ Container postgres Healthy 0.0s
✔ Container grafana Started 0.0s
✔ Container jaeger Started 0.0s
✔ Container opentelemetry-demo-dataprepper-1 St... 0.0s
✔ Container redis-cart Started 0.0s
✔ Container prometheus Started 0.0s
✔ Container opensearch Started 0.0s
✔ Container kafka Healthy 0.1s
! dataprepper The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s
✔ Container otel-col Started 0.0s
✔ Container feature-flag-service Started 0.0s
✔ Container ad-service Started 0.0s
✔ Container shipping-service Started 0.0s
✔ Container currency-service Started 0.0s
✔ Container accounting-service Started 0.0s
✔ Container email-service Started 0.0s
✔ Container quote-service Started 0.0s
✔ Container cart-service Started 0.0s
✔ Container frauddetection-service Started 0.0s
✔ Container payment-service Started 0.0s
✔ Container product-catalog-service Started 0.0s
✔ Container recommendation-service Started 0.0s
✔ Container checkout-service Started 0.0s
✔ Container frontend Started 0.0s
✔ Container load-generator Started 0.0s
✔ Container frontend-proxy Started 0.0s
OpenTelemetry Demo is running.
Go to http://localhost:8080 for the demo UI.
Go to http://localhost:8080/jaeger/ui for the Jaeger UI.
Go to http://localhost:8080/grafana/ for the Grafana UI.
Go to http://localhost:8080/loadgen/ for the Load Generator UI.
Go to http://localhost:8080/feature/ for the Feature Flag UI.
Viewing the OpenTelemetry data¶
Go to Datastream and select the OpenTelemetry datastream.
Click Open dataset and check OBSERVATION_KIND to see if
otellogs,otelmetrics, andotelspanexist.
Figure 2 - The OpenTelemetry data
Viewing OpenTelemetry Logs¶
From the Navigation bar, click Logs.
The left panel displays the list of Log datasets. Search for and select Logs (OpenTelemetry).
Select Actions to create a worksheet for exploring the data, and then save your visualization to a dashboard or start drafting a monitor for alerts.
Figure 3 - The OpenTelemetry logs
Viewing OpenTelemetry Metrics¶
From the Navigation bar, click Metrics.
The left panel displays the list of metrics matching your search term, displayed as the Metric Dataset name. To find all OpenTelemetry metrics, you can search for
OpenTelemetry, which focuses on the metrics within the OpenTelemetry Metrics dataset.For example, you can search for and select the metric,
app_currency_counter.After creating a graph with visualizations, select Actions at the top-right and either save your visualization to a dashboard or use it to start drafting a monitor for alerts.
Figure 4 - The OpenTelemetry metrics
Viewing OpenTelemetry Traces¶
From the Navigation bar, click Datasets.
Search for and select the Span dataset.
Select a trace and open that trace from the right panel.
Figure 5 - OpenTelemetry spans
Figure 6 - OpenTelemetry traces
Removing the Tutorial Data¶
Uninstalling the OpenTelemetry Collector¶
helm uninstall -n observe observe-traces
docker compose down
Uninstalling the OpenTelemetry Astronomy Shop Demo¶
helm uninstall -n default my-otel-demo
Uninstalling the OpenTelemetry App in Observe¶
To uninstall the OpenTelemetry app from your Observe workspace, follow the instructions located at Apps page.
Delete any created data connections and tokens as described here.