From e8ec64ba964da8ad49797e5b88ef52255f51913d Mon Sep 17 00:00:00 2001 From: Antonio Ereiz Date: Thu, 1 Feb 2024 21:37:24 +0100 Subject: [PATCH 1/7] poc Signed-off-by: Antonio Ereiz --- docs/tutorials/setup-opentelemetry.md | 63 +++++++++++++++++++++------ 1 file changed, 49 insertions(+), 14 deletions(-) diff --git a/docs/tutorials/setup-opentelemetry.md b/docs/tutorials/setup-opentelemetry.md index aa96e2ad40..fa1d197e60 100644 --- a/docs/tutorials/setup-opentelemetry.md +++ b/docs/tutorials/setup-opentelemetry.md @@ -24,16 +24,18 @@ yarn --cwd packages/backend add @opentelemetry/sdk-node \ ## Configure -In your `packages/backend/src` folder, create an `instrumentation.ts` file. +In your `packages/backend` 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 { +const { NodeSDK } = require('@opentelemetry/sdk-node'); +const { ConsoleSpanExporter } = require('@opentelemetry/sdk-trace-node'); +const { + getNodeAutoInstrumentations, +} = require('@opentelemetry/auto-instrumentations-node'); +const { PeriodicExportingMetricReader, ConsoleMetricExporter, -} from '@opentelemetry/sdk-metrics'; +} = require('@opentelemetry/sdk-metrics'); const sdk = new NodeSDK({ traceExporter: new ConsoleSpanExporter(), @@ -46,23 +48,56 @@ const sdk = new NodeSDK({ sdk.start(); ``` -In the `index.ts`, import this file **at the beginning**: - -```typescript -import './instrumentation'; // Setup the OpenTelemetry instrumentation - -// other imports and backend init... -``` +Your probably won't need all the instrumentations inside `getNodeAutoInstrumentations()` so make sure to +check the [documentation](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node) and tweak it properly. It's important to setup the NodeSDK and the automatic instrumentation **before** importing any library. +This is why we will use the nodejs [`--require`](https://nodejs.org/api/cli.html#-r---require-module) +flag when we start up the application. + +In your `Dockerfile` add the `--require` flag which points to the `instrumentation.ts` file + +```Dockerfile +FROM node:18-bookworm-slim +... +WORKDIR /app +RUN chown node:node /app +USER node + +ENV NODE_ENV production + +COPY --chown=node:node .yarn ./.yarn +COPY --chown=node:node .yarnrc.yml ./ + +# We need the instrumentation file inside the Docker image so we can use it with --require +// highlight-add-next-line +COPY --chown=node:node packages/backend/instrumentation.ts ./ + +COPY --chown=node:node yarn.lock package.json packages/backend/dist/skeleton.tar.gz ./ +RUN tar xzf skeleton.tar.gz && rm skeleton.tar.gz + +RUN --mount=type=cache,target=/home/node/.yarn/berry/cache,sharing=locked,uid=1000,gid=1000 \ + yarn workspaces focus --all --production + +COPY --chown=node:node packages/backend/dist/bundle.tar.gz app-config*.yaml ./ +RUN tar xzf bundle.tar.gz && rm bundle.tar.gz + +// highlight-remove-next-line +CMD ["node", "packages/backend", "--config", "app-config.yaml"] +// highlight-add-next-line +CMD ["node", "packages/backend", "--require", "./instrumentation.ts" "--config", "app-config.yaml"] +``` + ## 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/). +Of course in production you probably won't use the console exporters but instead send traces and metrics to an OpenTelemetry Collector or other exporter using [OTLP exporters](https://opentelemetry.io/docs/instrumentation/js/exporters/). + +If you need to disable/configure some Opentelemetry feature there are lots of [environment variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) which you can tweak. ## References From 5b8efa4e062e0e507511d9517a3c633b998a1286 Mon Sep 17 00:00:00 2001 From: Antonio Ereiz Date: Fri, 2 Feb 2024 20:37:44 +0100 Subject: [PATCH 2/7] refactor Signed-off-by: Antonio Ereiz --- docs/tutorials/setup-opentelemetry.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/setup-opentelemetry.md b/docs/tutorials/setup-opentelemetry.md index fa1d197e60..ac61f12d33 100644 --- a/docs/tutorials/setup-opentelemetry.md +++ b/docs/tutorials/setup-opentelemetry.md @@ -48,7 +48,7 @@ const sdk = new NodeSDK({ sdk.start(); ``` -Your probably won't need all the instrumentations inside `getNodeAutoInstrumentations()` so make sure to +Your probably won't need all the instrumentation inside `getNodeAutoInstrumentations()` so make sure to check the [documentation](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node) and tweak it properly. It's important to setup the NodeSDK and the automatic instrumentation **before** importing any library. @@ -61,6 +61,8 @@ In your `Dockerfile` add the `--require` flag which points to the `instrumentati ```Dockerfile FROM node:18-bookworm-slim ... +# More functionality goes here +... WORKDIR /app RUN chown node:node /app USER node @@ -86,18 +88,28 @@ RUN tar xzf bundle.tar.gz && rm bundle.tar.gz // highlight-remove-next-line CMD ["node", "packages/backend", "--config", "app-config.yaml"] // highlight-add-next-line -CMD ["node", "packages/backend", "--require", "./instrumentation.ts" "--config", "app-config.yaml"] +CMD ["node", "--require", "./instrumentation.ts", "packages/backend", "--config", "app-config.yaml"] ``` ## Run Backstage +The above configuration will only work in production once your start a Docker container from the image. + +To be able to test locally you can import the `./instrumentation.ts` file at the top (before all imports) of your backend `index.ts` file + +```ts +import '../instrumentation.ts' +// Other imports +... +``` + 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 or other exporter using [OTLP exporters](https://opentelemetry.io/docs/instrumentation/js/exporters/). -If you need to disable/configure some Opentelemetry feature there are lots of [environment variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) which you can tweak. +If you need to disable/configure some OpenTelemetry feature there are lots of [environment variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/) which you can tweak. ## References From 863a4f594130ccb94fc43279e6a42a9e3af8c0a7 Mon Sep 17 00:00:00 2001 From: Antonio Ereiz Date: Sat, 24 Feb 2024 22:08:05 +0100 Subject: [PATCH 3/7] refactor Signed-off-by: Antonio Ereiz --- docs/tutorials/setup-opentelemetry.md | 29 ++++------------------- packages/backend/opentelemetry.js | 34 +++++++++++++++++++++++++++ 2 files changed, 38 insertions(+), 25 deletions(-) create mode 100644 packages/backend/opentelemetry.js diff --git a/docs/tutorials/setup-opentelemetry.md b/docs/tutorials/setup-opentelemetry.md index ac61f12d33..2be81bc719 100644 --- a/docs/tutorials/setup-opentelemetry.md +++ b/docs/tutorials/setup-opentelemetry.md @@ -24,7 +24,7 @@ yarn --cwd packages/backend add @opentelemetry/sdk-node \ ## Configure -In your `packages/backend` folder, create an `instrumentation.ts` file. +In your `packages/backend` folder, create an `instrumentation.js` file. ```typescript const { NodeSDK } = require('@opentelemetry/sdk-node'); @@ -48,7 +48,7 @@ const sdk = new NodeSDK({ sdk.start(); ``` -Your probably won't need all the instrumentation inside `getNodeAutoInstrumentations()` so make sure to +You probably won't need all of the instrumentation inside `getNodeAutoInstrumentations()` so make sure to check the [documentation](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node) and tweak it properly. It's important to setup the NodeSDK and the automatic instrumentation **before** importing any library. @@ -59,31 +59,10 @@ flag when we start up the application. In your `Dockerfile` add the `--require` flag which points to the `instrumentation.ts` file ```Dockerfile -FROM node:18-bookworm-slim -... -# More functionality goes here -... -WORKDIR /app -RUN chown node:node /app -USER node - -ENV NODE_ENV production - -COPY --chown=node:node .yarn ./.yarn -COPY --chown=node:node .yarnrc.yml ./ # We need the instrumentation file inside the Docker image so we can use it with --require // highlight-add-next-line -COPY --chown=node:node packages/backend/instrumentation.ts ./ - -COPY --chown=node:node yarn.lock package.json packages/backend/dist/skeleton.tar.gz ./ -RUN tar xzf skeleton.tar.gz && rm skeleton.tar.gz - -RUN --mount=type=cache,target=/home/node/.yarn/berry/cache,sharing=locked,uid=1000,gid=1000 \ - yarn workspaces focus --all --production - -COPY --chown=node:node packages/backend/dist/bundle.tar.gz app-config*.yaml ./ -RUN tar xzf bundle.tar.gz && rm bundle.tar.gz +COPY --chown=node:node packages/backend/instrumentation.js ./ // highlight-remove-next-line CMD ["node", "packages/backend", "--config", "app-config.yaml"] @@ -98,7 +77,7 @@ The above configuration will only work in production once your start a Docker co To be able to test locally you can import the `./instrumentation.ts` file at the top (before all imports) of your backend `index.ts` file ```ts -import '../instrumentation.ts' +import '../instrumentation.js' // Other imports ... ``` diff --git a/packages/backend/opentelemetry.js b/packages/backend/opentelemetry.js new file mode 100644 index 0000000000..074fcb8713 --- /dev/null +++ b/packages/backend/opentelemetry.js @@ -0,0 +1,34 @@ +/* + * Copyright 2024 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +const { NodeSDK } = require('@opentelemetry/sdk-node'); +const { ConsoleSpanExporter } = require('@opentelemetry/sdk-trace-node'); +const { + getNodeAutoInstrumentations, +} = require('@opentelemetry/auto-instrumentations-node'); +const { + PeriodicExportingMetricReader, + ConsoleMetricExporter, +} = require('@opentelemetry/sdk-metrics'); + +const sdk = new NodeSDK({ + traceExporter: new ConsoleSpanExporter(), + metricReader: new PeriodicExportingMetricReader({ + exporter: new ConsoleMetricExporter(), + }), + instrumentations: [getNodeAutoInstrumentations()], +}); + +sdk.start(); From 82ca334cd44a0da54fd889b2a0f8b58330fefa40 Mon Sep 17 00:00:00 2001 From: Antonio Ereiz Date: Sat, 24 Feb 2024 22:09:02 +0100 Subject: [PATCH 4/7] remove opentelemetry file Signed-off-by: Antonio Ereiz --- packages/backend/opentelemetry.js | 34 ------------------------------- 1 file changed, 34 deletions(-) delete mode 100644 packages/backend/opentelemetry.js diff --git a/packages/backend/opentelemetry.js b/packages/backend/opentelemetry.js deleted file mode 100644 index 074fcb8713..0000000000 --- a/packages/backend/opentelemetry.js +++ /dev/null @@ -1,34 +0,0 @@ -/* - * Copyright 2024 The Backstage Authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -const { NodeSDK } = require('@opentelemetry/sdk-node'); -const { ConsoleSpanExporter } = require('@opentelemetry/sdk-trace-node'); -const { - getNodeAutoInstrumentations, -} = require('@opentelemetry/auto-instrumentations-node'); -const { - PeriodicExportingMetricReader, - ConsoleMetricExporter, -} = require('@opentelemetry/sdk-metrics'); - -const sdk = new NodeSDK({ - traceExporter: new ConsoleSpanExporter(), - metricReader: new PeriodicExportingMetricReader({ - exporter: new ConsoleMetricExporter(), - }), - instrumentations: [getNodeAutoInstrumentations()], -}); - -sdk.start(); From 20cdeebfbe1b82e81975ac47455c22b2ada0cc75 Mon Sep 17 00:00:00 2001 From: Antonio Ereiz <51959110+SonilPro@users.noreply.github.com> Date: Sat, 24 Feb 2024 22:21:03 +0100 Subject: [PATCH 5/7] quick fix Signed-off-by: Antonio Ereiz <51959110+SonilPro@users.noreply.github.com> --- docs/tutorials/setup-opentelemetry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/setup-opentelemetry.md b/docs/tutorials/setup-opentelemetry.md index 2be81bc719..5a229d83d9 100644 --- a/docs/tutorials/setup-opentelemetry.md +++ b/docs/tutorials/setup-opentelemetry.md @@ -74,7 +74,7 @@ CMD ["node", "--require", "./instrumentation.ts", "packages/backend", "--config" The above configuration will only work in production once your start a Docker container from the image. -To be able to test locally you can import the `./instrumentation.ts` file at the top (before all imports) of your backend `index.ts` file +To be able to test locally you can import the `./instrumentation.js` file at the top (before all imports) of your backend `index.ts` file ```ts import '../instrumentation.js' From 1c6667eaf20949ee3b523f01e6653f538a0f981c Mon Sep 17 00:00:00 2001 From: Antonio Ereiz <51959110+SonilPro@users.noreply.github.com> Date: Sat, 24 Feb 2024 22:21:36 +0100 Subject: [PATCH 6/7] Update docs/tutorials/setup-opentelemetry.md Signed-off-by: Antonio Ereiz <51959110+SonilPro@users.noreply.github.com> --- docs/tutorials/setup-opentelemetry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/setup-opentelemetry.md b/docs/tutorials/setup-opentelemetry.md index 5a229d83d9..6718974d6e 100644 --- a/docs/tutorials/setup-opentelemetry.md +++ b/docs/tutorials/setup-opentelemetry.md @@ -67,7 +67,7 @@ COPY --chown=node:node packages/backend/instrumentation.js ./ // highlight-remove-next-line CMD ["node", "packages/backend", "--config", "app-config.yaml"] // highlight-add-next-line -CMD ["node", "--require", "./instrumentation.ts", "packages/backend", "--config", "app-config.yaml"] +CMD ["node", "--require", "./instrumentation.js", "packages/backend", "--config", "app-config.yaml"] ``` ## Run Backstage From b216a9972feacd41781c922befe2b7545f5e39aa Mon Sep 17 00:00:00 2001 From: Antonio Ereiz <51959110+SonilPro@users.noreply.github.com> Date: Sat, 24 Feb 2024 22:22:04 +0100 Subject: [PATCH 7/7] Update docs/tutorials/setup-opentelemetry.md Signed-off-by: Antonio Ereiz <51959110+SonilPro@users.noreply.github.com> --- docs/tutorials/setup-opentelemetry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/setup-opentelemetry.md b/docs/tutorials/setup-opentelemetry.md index 6718974d6e..976ba4ccfb 100644 --- a/docs/tutorials/setup-opentelemetry.md +++ b/docs/tutorials/setup-opentelemetry.md @@ -56,7 +56,7 @@ It's important to setup the NodeSDK and the automatic instrumentation **before** This is why we will use the nodejs [`--require`](https://nodejs.org/api/cli.html#-r---require-module) flag when we start up the application. -In your `Dockerfile` add the `--require` flag which points to the `instrumentation.ts` file +In your `Dockerfile` add the `--require` flag which points to the `instrumentation.js` file ```Dockerfile