From a08feaf058e9199a45c054ed40c60f94c663bd0c Mon Sep 17 00:00:00 2001
From: Thomas Cardonne <thomas.cardonne@adevinta.com>
Date: Fri, 8 Dec 2023 11:54:24 +0100
Subject: [PATCH] docs(tutorials): add Setup OpenTelemetry tutorial

Adds a simple tutorial to setup OpenTelemetry in a Backstage project using simple Console exporters

Signed-off-by: Thomas Cardonne <thomas.cardonne@adevinta.com>
---
 docs/tutorials/setup-opentelemetry.md | 69 +++++++++++++++++++++++++++
 mkdocs.yml                            |  1 +
 2 files changed, 70 insertions(+)
 create mode 100644 docs/tutorials/setup-opentelemetry.md

diff --git a/docs/tutorials/setup-opentelemetry.md b/docs/tutorials/setup-opentelemetry.md
new file mode 100644
index 0000000000..b85cbd4398
--- /dev/null
+++ b/docs/tutorials/setup-opentelemetry.md
@@ -0,0 +1,69 @@
+---
+id: setup-opentelemetry
+title: Setup OpenTelemetry
+description: Tutorial to setup OpenTelemetry metrics and traces exporters in Backstage
+---
+
+Backstage uses [OpenTelemetery](https://opentelemetry.io/) to instrument its components by reporting traces and metrics.
+
+This tutorial shows how to setup exporters in your Backstage backend package. For demonstration purposes we will use the simple console exporters.
+
+## Install dependencies
+
+We will use the OpenTelemetry Node SDK and the `auto-instrumentations-node` packages.
+
+Backstage packages, such as the catalog, uses the OpenTelemetry API to send custom traces and metrics.
+The `auto-instrumentations-node` will automatically create spans for code called in libraries like Express.
+
+```bash
+yarn --cwd packages/backend add @opentelemetry/sdk-node \
+    @opentelemetry/auto-instrumentations-node \
+    @opentelemetry/sdk-metrics
+```
+
+## Configure
+
+In your `packages/backend/src` folder, create an `instrumentation.ts` file.
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import {
+  PeriodicExportingMetricReader,
+  ConsoleMetricExporter,
+} from '@opentelemetry/sdk-metrics';
+
+const sdk = new NodeSDK({
+  traceExporter: new ConsoleSpanExporter(),
+  metricReader: new PeriodicExportingMetricReader({
+    exporter: new ConsoleMetricExporter(),
+  }),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+```
+
+In the `index.ts`, import this file **at the beginning**:
+
+```typescript
+import './instrumentation'; // Setup the OpenTelemetry instrumentation
+
+// other imports and backend init...
+```
+
+It's important to setup the NodeSDK and the automatic instrumentation **before** importing any library.
+
+## Run Backstage
+
+You can now start your Backstage instance as usual, using `yarn dev`.
+
+When the backend is started, you should see in your console traces and metrics emitted by OpenTelemetry.
+
+Of course in production you probably won't use the console exporters but instead send traces and metrics to an OpenTelemetry Collector using [OTLP exporters](https://opentelemetry.io/docs/instrumentation/js/exporters/).
+
+## References
+
+- [Getting started with OpenTelemetry Node.js](https://opentelemetry.io/docs/instrumentation/js/getting-started/nodejs/)
+- [OpenTelemetry NodeSDK API](https://open-telemetry.github.io/opentelemetry-js/classes/_opentelemetry_sdk_node.NodeSDK.html)
diff --git a/mkdocs.yml b/mkdocs.yml
index d4735c63fc..4642ab9ba3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -194,6 +194,7 @@ nav:
       - Using the Backstage Proxy from Within a Plugin: 'tutorials/using-backstage-proxy-within-plugin.md'
       - Migration to Yarn 3: 'tutorials/yarn-migration.md'
       - Migration to Material UI v5: 'tutorials/migrate-to-mui5.md'
+      - Setup OpenTelemetry: 'tutorials/setup-opentelemetry.md'
   - Architecture Decision Records (ADRs):
       - Overview: 'architecture-decisions/index.md'
       - ADR001 - Architecture Decision Record (ADR) log: 'architecture-decisions/adr001-add-adr-log.md'