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/microsite/sidebars.json b/microsite/sidebars.json index fb513697cb..fd0f57d55b 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -409,7 +409,8 @@ "tutorials/switching-sqlite-postgres", "tutorials/using-backstage-proxy-within-plugin", "tutorials/yarn-migration", - "tutorials/migrate-to-mui5" + "tutorials/migrate-to-mui5", + "tutorials/setup-opentelemetry" ], "Architecture Decision Records (ADRs)": [ "architecture-decisions/adrs-overview", 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'