From 47c9b175dbbbab91e2ef7e089d376042bb26832f Mon Sep 17 00:00:00 2001 From: Ferhat Korkmaz Date: Thu, 17 Oct 2024 21:29:44 +0300 Subject: [PATCH] opentelemetry native docs added --- ...elemetry-for-expressjs-with-infrastack.mdx | 165 ++++++++--- ...entelemetry-for-nestjs-with-infrastack.mdx | 110 +++++++- ...entelemetry-for-nextjs-with-infrastack.mdx | 263 ++++++++++++------ 3 files changed, 407 insertions(+), 131 deletions(-) diff --git a/docs/documentation/integrate-opentelemetry-for-expressjs-with-infrastack.mdx b/docs/documentation/integrate-opentelemetry-for-expressjs-with-infrastack.mdx index 3601fc1..2d92ce3 100644 --- a/docs/documentation/integrate-opentelemetry-for-expressjs-with-infrastack.mdx +++ b/docs/documentation/integrate-opentelemetry-for-expressjs-with-infrastack.mdx @@ -14,9 +14,8 @@ twitter:site: "@infrastackai" import { GithubIcon, JsIcon } from '/snippets/custom-icons.mdx' #### What you will learn -- Installing the `@infrastack/otel` NPM package -- Setting up your environment -- Instrumenting your application +- How to set up your environment +- How to **instrument** your application using the infrastack.ai SDK or the official OpenTelemetry SDK #### Prerequisites - An [infrastack.ai](https://app.infrastack.ai) account to get your API key @@ -28,49 +27,132 @@ import { GithubIcon, JsIcon } from '/snippets/custom-icons.mdx' /> ### Getting started + + + You can use the Infrastack SDK to instrument your Express.js application with a single line of code. + + + + ```bash npm + npm install @infrastack/otel + ``` + ```bash yarn + yarn add @infrastack/otel + ``` + ```bash pnpm + pnpm add @infrastack/otel + ``` + + + + Export your API key as an environment variable. + ```bash + export INFRASTACK_API_KEY=sk-1*************************f5af + ``` + Or you can set the environment variables in your `.env` file by using the [dotenv](https://www.npmjs.com/package/dotenv) library. + + + ```javascript instrumentation.ts + import { startOtel } from "@infrastack/otel"; + startOtel({ + serviceName:"YOUR_SERVICE_NAME", + }); + ``` + If you don't provide a service name, we will create a random name for you. + + + Run your Express.js application with the node required command. + ```bash + npx tsc && node -r ./dist/instrumentation.js dist/index.js + ``` + After creating some traffic, you can check your data from the [infrastack.ai](https://app.infrastack.ai) dashboard. + + + + + You can use the [OpenTelemetry Javascript SDK](https://opentelemetry.io/docs/languages/js/) to instrument your Express.js application. + + + + ```bash npm + npm install --save @opentelemetry/sdk-node + npm install --save @opentelemetry/auto-instrumentations-node + npm install --save @opentelemetry/exporter-trace-otlp-grpc + ``` + ```bash yarn + yarn add @opentelemetry/sdk-node + yarn add @opentelemetry/auto-instrumentations-node + yarn add @opentelemetry/exporter-trace-otlp-grpc + ``` + ```bash pnpm + pnpm add @opentelemetry/sdk-node + pnpm add @opentelemetry/auto-instrumentations-node + pnpm add @opentelemetry/exporter-trace-otlp-grpc + ``` + + + + + ```bash + export OTEL_EXPORTER_OTLP_ENDPOINT="https://collector.infrastack.ai" + export OTEL_EXPORTER_OTLP_HEADERS="infrastack-api-key={{YOUR_INFRASTACK_API_KEY}}" + ``` + Or you can set the environment variables in your `.env` file by using the [dotenv](https://www.npmjs.com/package/dotenv) library. + - + + Here, you will create a file that will be used to instrument your application. You will have lower level control over the instrumentation process. + + ```javascript instrumentation.ts + import { NodeSDK } from '@opentelemetry/sdk-node'; + import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'; + import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc'; + import { Resource } from '@opentelemetry/resources'; + import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'; + import { CompressionAlgorithm } from '@opentelemetry/otlp-exporter-base'; + import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions'; - - - ```bash npm - npm install @infrastack/otel - ``` - ```bash yarn - yarn add @infrastack/otel - ``` - ```bash pnpm - pnpm add @infrastack/otel - ``` - - - - Export your API key as an environment variable. - ```bash - export INFRASTACK_API_KEY=sk-1*************************f5af - ``` - + // Exporter options with compression set to Gzip + const exporterOptions = { + compression: CompressionAlgorithm.GZIP, + }; - - ```javascript instrumentation.ts - import { startOtel } from "@infrastack/otel"; - startOtel({ - serviceName:"YOUR_SERVICE_NAME", - }); - ``` - If you don't provide a service name, we will create a random name for you. - + // Trace exporter initialization + const traceExporter = new OTLPTraceExporter(exporterOptions); - - Run your Express.js application with the node required command. - ```bash - npx tsc && node -r ./dist/instrumentation.js dist/index.js - ``` + // SDK initialization with exporter, auto-instrumentation, and resource attributes + const sdk = new NodeSDK({ + traceExporter, + instrumentations: [getNodeAutoInstrumentations()], + resource: new Resource({ + [ATTR_SERVICE_NAME]: "{{YOUR_SERVICE_NAME}}", + [ATTR_SERVICE_VERSION]: "{{YOUR_SERVICE_VERSION}}", + }), + }); - After creating some traffic, you can check your data from the [infrastack.ai](https://app.infrastack.ai) dashboard. - + // Start the SDK and register it with the OpenTelemetry API + sdk.start(); - + // Graceful shutdown of SDK on process exit + process.on("SIGTERM", () => { + sdk + .shutdown() + .then(() => console.log("Tracing terminated")) + .catch((error) => console.log("Error terminating tracing", error)) + .finally(() => process.exit(0)); + }); + ``` + + + Run your Express.js application with the [node required](https://nodejs.org/api/cli.html#cli_r_require_module) command. + ```bash + npx tsc && node -r ./dist/instrumentation.js dist/index.js + ``` + After creating some traffic, you can check your data from the [infrastack.ai](https://app.infrastack.ai) dashboard. + + + + ### Next steps @@ -81,6 +163,3 @@ import { GithubIcon, JsIcon } from '/snippets/custom-icons.mdx' icon={} /> - - - diff --git a/docs/documentation/integrate-opentelemetry-for-nestjs-with-infrastack.mdx b/docs/documentation/integrate-opentelemetry-for-nestjs-with-infrastack.mdx index f8a82ec..384bd63 100644 --- a/docs/documentation/integrate-opentelemetry-for-nestjs-with-infrastack.mdx +++ b/docs/documentation/integrate-opentelemetry-for-nestjs-with-infrastack.mdx @@ -14,10 +14,8 @@ twitter:site: "@infrastackai" import { GithubIcon, JsIcon } from '/snippets/custom-icons.mdx' #### What you will learn -- Installing the `@infrastack/otel` NPM package -- Setting up your environment -- Instrumenting your application - +- How to set up your environment +- How to **instrument** your application using the infrastack.ai SDK or the official OpenTelemetry SDK #### Prerequisites - An [infrastack.ai](https://app.infrastack.ai) account to get your API key - A Nest.js application @@ -30,6 +28,9 @@ import { GithubIcon, JsIcon } from '/snippets/custom-icons.mdx' ### Getting started + + +You can use the Infrastack SDK to instrument your Nest.js application with a single line of code. @@ -51,6 +52,8 @@ import { GithubIcon, JsIcon } from '/snippets/custom-icons.mdx' ```bash export INFRASTACK_API_KEY=sk-1*************************f5af ``` + Or you can set the environment variables in your `.env` file by using the [dotenv](https://www.npmjs.com/package/dotenv) library. + @@ -88,7 +91,106 @@ import { AppModule } from './app.module'; + + + You can use the [OpenTelemetry Javascript SDK](https://opentelemetry.io/docs/languages/js/) to instrument your Nest.js application. + + + + ```bash npm + npm install --save @opentelemetry/sdk-node + npm install --save @opentelemetry/auto-instrumentations-node + npm install --save @opentelemetry/exporter-trace-otlp-grpc + ``` + ```bash yarn + yarn add @opentelemetry/sdk-node + yarn add @opentelemetry/auto-instrumentations-node + yarn add @opentelemetry/exporter-trace-otlp-grpc + ``` + ```bash pnpm + pnpm add @opentelemetry/sdk-node + pnpm add @opentelemetry/auto-instrumentations-node + pnpm add @opentelemetry/exporter-trace-otlp-grpc + ``` + + + + + ```bash + export OTEL_EXPORTER_OTLP_ENDPOINT="https://collector.infrastack.ai" + export OTEL_EXPORTER_OTLP_HEADERS="infrastack-api-key={{YOUR_INFRASTACK_API_KEY}}" + ``` + Or you can set the environment variables in your `.env` file by using the [dotenv](https://www.npmjs.com/package/dotenv) library. + + + + Here, you will create a file that will be used to instrument your application. You will have lower level control over the instrumentation process. + + ```javascript instrumentation.ts + import { NodeSDK } from '@opentelemetry/sdk-node'; + import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'; + import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc'; + import { Resource } from '@opentelemetry/resources'; + import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'; + import { CompressionAlgorithm } from '@opentelemetry/otlp-exporter-base'; + import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions'; + + // Exporter options with compression set to Gzip + const exporterOptions = { + compression: CompressionAlgorithm.GZIP, + }; + + // Trace exporter initialization + const traceExporter = new OTLPTraceExporter(exporterOptions); + + // SDK initialization with exporter, auto-instrumentation, and resource attributes + const sdk = new NodeSDK({ + traceExporter, + instrumentations: [getNodeAutoInstrumentations()], + resource: new Resource({ + [ATTR_SERVICE_NAME]: "{{YOUR_SERVICE_NAME}}", + [ATTR_SERVICE_VERSION]: "{{YOUR_SERVICE_VERSION}}", + }), + }); + + // Start the SDK and register it with the OpenTelemetry API + sdk.start(); + + // Graceful shutdown of SDK on process exit + process.on("SIGTERM", () => { + sdk + .shutdown() + .then(() => console.log("Tracing terminated")) + .catch((error) => console.log("Error terminating tracing", error)) + .finally(() => process.exit(0)); + }); + ``` + + + ```javascript main.ts + import './instrumentation'; + import { NestFactory } from '@nestjs/core'; + import { AppModule } from './app.module'; + + async function bootstrap() { + const app = await NestFactory.create(AppModule); + await app.listen(8081); + console.log('Server is running on port 8081'); + } + bootstrap(); + ``` + + + Run your Nest.js application with the default Nest.js command. + ```bash + npm run start + ``` + After creating some traffic, you can check your data from the [infrastack.ai](https://app.infrastack.ai) dashboard. + + + + ### Next steps **instrument** your application using the infrastack.ai SDK or the official OpenTelemetry SDK #### Prerequisites - An [infrastack.ai](https://app.infrastack.ai) account to get your API key - A Next.js application - } - /> + } + /> ### Getting started - - - - - - ```bash npm - npm install @infrastack/otel - ``` - ```bash yarn - yarn add @infrastack/otel - ``` - ```bash pnpm - pnpm add @infrastack/otel - ``` - - - - - - Create an `.env` file in the root of your project and add your API key. - ```properties .env - INFRASTACK_API_KEY=sk-1*************************f5af - ``` - + + + You can use the Infrastack SDK to instrument your Next.js application with a single line of code. + + + + ```bash npm + npm install @infrastack/otel + ``` + ```bash yarn + yarn add @infrastack/otel + ``` + ```bash pnpm + pnpm add @infrastack/otel + ``` + + + + + Create an `.env` file in the root of your project and add your API key. + ```properties .env + INFRASTACK_API_KEY=sk-1*************************f5af + ``` + - - This is step is required in order to enable instrumentation. Right now, `instrumentationHook` and `serverComponentsExternalPackages` are expermiental. Please follow the [Official Next.js Documentation for instrumentationHook](https://nextjs.org/docs/app/api-reference/next-config-js/instrumentationHook) if this document is outdated. - -```javascript next.config.mjs -const nextConfig = { - experimental: { - instrumentationHook: true, // To enable instrumentation - serverComponentsExternalPackages: [ // To utilize node.js specific features in a next.js environment - "@opentelemetry/auto-instrumentations-node", - "@opentelemetry/sdk-node", - ], - }, -}; - -export default nextConfig; -``` - - - - If you are using a `src` folder in your Next.js application, create an `instrumentation.ts` file there. If not, create the file in the root of your project. - ```javascript instrumentation.ts - export async function register() { - if (process.env.NEXT_RUNTIME === "nodejs") { - const { startOtel } = await import("@infrastack/otel"); - startOtel({ - "serviceName": "YOUR_SERVICE_NAME", - }); - } - } - ``` - If you don't provide a service name, we will create a random name for you. - - - - - Run your Next.js application with the default command. - ```bash - npm run dev - ``` - - You can check your data from the [infrastack.ai](https://app.infrastack.ai) dashboard. - - - - - + + This is step is required in order to enable instrumentation. Right now, `instrumentationHook` and `serverComponentsExternalPackages` are expermiental. Please follow the [Official Next.js Documentation for instrumentationHook](https://nextjs.org/docs/app/api-reference/next-config-js/instrumentationHook) if this document is outdated. + + ```javascript next.config.mjs + const nextConfig = { + experimental: { + instrumentationHook: true, // To enable instrumentation + serverComponentsExternalPackages: [ // To utilize node.js specific features in a next.js environment + "@opentelemetry/auto-instrumentations-node", + "@opentelemetry/sdk-node", + ], + }, + }; + + export default nextConfig; + ``` + + + + If you are using a `src` folder in your Next.js application, create an `instrumentation.ts` file there. If not, create the file in the root of your project. + ```javascript instrumentation.ts + export async function register() { + if (process.env.NEXT_RUNTIME === "nodejs") { + const { startOtel } = await import("@infrastack/otel"); + startOtel({ + "serviceName": "YOUR_SERVICE_NAME", + }); + } + } + ``` + If you don't provide a service name, we will create a random name for you. + + + + Run your Next.js application with the default command. + ```bash + npm run dev + ``` + + You can check your data from the [infrastack.ai](https://app.infrastack.ai) dashboard. + + + + + You can use the [OpenTelemetry Javascript SDK](https://opentelemetry.io/docs/languages/js/) to instrument your Next.js application. + + + + ```bash npm + npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/sdk-trace-node + npm install @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-grpc + npm install @opentelemetry/resources @opentelemetry/semantic-conventions + ``` + ```bash yarn + yarn add @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/sdk-trace-node + yarn add @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-grpc + yarn add @opentelemetry/resources @opentelemetry/semantic-conventions + ``` + ```bash pnpm + pnpm add @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/sdk-trace-node + pnpm add @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-grpc + pnpm add @opentelemetry/resources @opentelemetry/semantic-conventions + ``` + + + + + ```properties .env + OTEL_EXPORTER_OTLP_ENDPOINT="https://collector.infrastack.ai" + OTEL_EXPORTER_OTLP_HEADERS="infrastack-api-key={{YOUR_INFRASTACK_API_KEY}}" + ``` + + + + This is step is required in order to enable instrumentation. Right now, `instrumentationHook` and `serverComponentsExternalPackages` are expermiental. Please follow the [Official Next.js Documentation for instrumentationHook](https://nextjs.org/docs/app/api-reference/next-config-js/instrumentationHook) if this document is outdated. + + ```javascript next.config.mjs + const nextConfig = { + experimental: { + instrumentationHook: true, // To enable instrumentation + serverComponentsExternalPackages: [ // To utilize node.js specific features in a next.js environment + "@opentelemetry/auto-instrumentations-node", + "@opentelemetry/sdk-node", + ], + }, + }; + + export default nextConfig; + ``` + + + + Here, you will create a file that will be used to instrument your application. You will have lower level control over the instrumentation process. + ```javascript instrumentation-node.ts + 'use strict' + import { NodeSDK } from '@opentelemetry/sdk-node'; + import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'; + import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc'; + import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions'; + import { Resource } from '@opentelemetry/resources'; + + const traceExporter = new OTLPTraceExporter(); + + const sdk = new NodeSDK({ + resource: new Resource({ + [ATTR_SERVICE_NAME]: "{{YOUR_SERVICE_NAME}}", + [ATTR_SERVICE_VERSION]: "{{YOUR_SERVICE_VERSION}}", + }), + traceExporter, + instrumentations: [ + getNodeAutoInstrumentations({ + '@opentelemetry/instrumentation-fs': { + requireParentSpan: true, + }, + }) + ], + }); + + sdk.start(); + ``` + + + If you are using a `src` folder in your Next.js application, create an `instrumentation.ts` file there. If not, create the file in the root of your project. + ```javascript instrumentation.ts + export async function register() { + if (process.env.NEXT_RUNTIME === "nodejs") { + await import('./instrumentation-node'); + } + } + ``` + + + + Run your Next.js application with the default command. + ```bash + npm run dev + ``` + + You can check your data from the [infrastack.ai](https://app.infrastack.ai) dashboard. + + + + + ### Next steps - } - /> - } - /> + } + /> + } + /> - -