diff --git a/data/blog/opentelemetry-nextjs.mdx b/data/blog/opentelemetry-nextjs.mdx index 0e4f2ee18..8c38c8fda 100644 --- a/data/blog/opentelemetry-nextjs.mdx +++ b/data/blog/opentelemetry-nextjs.mdx @@ -1,9 +1,9 @@ --- title: Monitoring your Nextjs application using OpenTelemetry slug: opentelemetry-nextjs -date: 2024-07-24 +date: 2024-08-20 tags: [OpenTelemetry Instrumentation, JavaScript] -authors: [sai_deepesh] +authors: [sai_deepesh, vishal] description: OpenTelemetry can help instrument Nextjs applications and provide you with end-to-end tracing. In this guide, we will demonstrate how to instrument your Nextjs app with OpenTelemetry... image: /img/blog/2022/04/opentelemetry_nextjs_cover.webp keywords: [opentelemetry,nextjs,opentelemetry nextjs,javascript,apm tools,application performance monitoring] @@ -135,11 +135,83 @@ You can check if your app is up and running on [http://localhost:3000](http://lo ### Instrumenting the Nextjs application with OpenTelemetry -**Step 1: Install OpenTelemetry packages** +#### Using vercel otel -You will need the following OpenTelemetry packages for this sample application. +**Step 1.** Install OpenTelemetry packages -```jsx +```bash +npm install @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation @opentelemetry/exporter-trace-otlp-http +``` + +**Step 2.** Update `next.config.mjs` to include instrumentationHook +```tsx +/** @type {import('next').NextConfig} */ +const nextConfig = { + // include instrumentationHook experimental feature + experimental: { + instrumentationHook: true, + }, +}; + +export default nextConfig; +``` + +**Step 3.** Create `instrumentation.node.ts` file

+You need to configure the endpoint for SigNoz cloud in this file. + +```tsx +'use strict' +import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'; + +// Add otel logging +import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; +diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging + +const exporterOptions = { + url: 'https://ingest.[data_region].signoz.cloud:443/v1/traces', // Set your own data region or set to http://localhost:4318/v1/traces if using selfhost SigNoz + headers: { 'signoz-access-token': 'SIGNOZ_INGESTION_KEY' }, // Set if you are using SigNoz Cloud +} + +export const traceExporter = new OTLPTraceExporter(exporterOptions); +``` + +- `SIGNOZ_INGESTION_KEY` : You can find your ingestion key from SigNoz cloud account details sent on your email. + +Depending on the choice of your region for SigNoz cloud, the ingest endpoint will vary according to this table. + +| Region | Endpoint | +| --- | --- | +| US | ingest.us.signoz.cloud:443/v1/traces | +| IN | ingest.in.signoz.cloud:443/v1/traces | +| EU | ingest.eu.signoz.cloud:443/v1/traces | + + +**Step 4.** Create `instrumentation.ts` file

+```tsx +import { registerOTel } from '@vercel/otel'; +import { traceExporter } from './instrumentation.node'; + +export function register() { + registerOTel({ + serviceName: 'Sample Next.js App', + traceExporter: traceExporter, + }); +} +``` + +**Step 5.** Once you're done configuring the exporter options, try running your application and validate if your application is sending traces to SigNoz cloud [here](#validating-instrumentation-by-checking-for-traces). + + +The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app. + + +You can also check the sample application at this GitHub repo. + +#### Using OpenTelemetry instrument (only works for nodejs runtime) + +**Step 1.** Install the OpenTelemetry packages + +```bash npm i @opentelemetry/sdk-node npm i @opentelemetry/auto-instrumentations-node npm i @opentelemetry/exporter-trace-otlp-http @@ -147,11 +219,6 @@ npm i @opentelemetry/resources npm i @opentelemetry/semantic-conventions ``` - -You can use yarn or npm as per the package manager that you’re using for the project - - - **Step 2.** Update `next.config.mjs` to include instrumentationHook ```tsx /** @type {import('next').NextConfig} */ @@ -165,16 +232,7 @@ const nextConfig = { export default nextConfig; ``` -**Step 3.** Create `instrumentation.ts` file

-```tsx -export async function register() { - if (process.env.NEXT_RUNTIME === 'nodejs') { - await import('./instrumentation.node') - } -} -``` - -**Step 4.** Create `instrumentation.node.ts` file

+**Step 3.** Create `instrumentation.node.ts` file

You need to configure the endpoint for SigNoz cloud in this file. ```tsx @@ -186,12 +244,12 @@ import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http' import { Resource } from '@opentelemetry/resources' import { SEMRESATTRS_SERVICE_NAME } from '@opentelemetry/semantic-conventions' -// Add otel logging when debugging -// import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; -// diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG); +// Add otel logging +import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; +diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging const exporterOptions = { - url: 'https://ingest.[region].signoz.cloud:443/v1/traces', // Use your own data region or set to http://localhost:4318/v1/traces if using selfhost SigNoz + url: 'https://ingest.[region].signoz.cloud:443/v1/traces', // use your own data region headers: { 'signoz-access-token': 'SIGNOZ_INGESTION_KEY' }, // Use if you are using SigNoz Cloud } @@ -200,7 +258,7 @@ const sdk = new NodeSDK({ traceExporter, instrumentations: [getNodeAutoInstrumentations()], resource: new Resource({ - [SEMRESATTRS_SERVICE_NAME]: 'SigNoz-Nextjs-Example', + [SEMRESATTRS_SERVICE_NAME]: 'next-app', }), }); @@ -217,7 +275,30 @@ process.on('SIGTERM', () => { }); ``` -**Step 5: Run the server and monitor the application** +- `SIGNOZ_INGESTION_KEY` : You can find your ingestion key from SigNoz cloud account details sent on your email. + +Depending on the choice of your region for SigNoz cloud, the ingest endpoint will vary according to this table. + +| Region | Endpoint | +| --- | --- | +| US | ingest.us.signoz.cloud:443/v1/traces | +| IN | ingest.in.signoz.cloud:443/v1/traces | +| EU | ingest.eu.signoz.cloud:443/v1/traces | + +**Step 4.** Create `instrumentation.ts` file

+```tsx +export async function register() { + if (process.env.NEXT_RUNTIME === 'nodejs') { + await import('./instrumentation.node') + } +} +``` + +**Step 5.** Once you're done configuring the exporter options, try running your application and validate if your application is sending traces to SigNoz cloud [here](#validating-instrumentation-by-checking-for-traces). + + +The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app. + Run the application, and your application should be available on [http://localhost:8080](http://localhost:8080/) . diff --git a/data/docs/instrumentation/nextjs.mdx b/data/docs/instrumentation/nextjs.mdx index 9ff19aa4f..a40e357e5 100644 --- a/data/docs/instrumentation/nextjs.mdx +++ b/data/docs/instrumentation/nextjs.mdx @@ -1,5 +1,5 @@ --- -date: 2024-06-19 +date: 2024-08-20 id: nextjs title: Nextjs OpenTelemetry Instrumentation description: Learn how to instrument your Nextjs application with OpenTelemetry and send telemetry data to SigNoz @@ -17,42 +17,87 @@ Based on your application environment, you can choose the setup below to send tr From VMs, there are two ways to send data to SigNoz Cloud. - [Send traces directly to SigNoz Cloud](#send-traces-directly-to-signoz-cloud) - - [No Code Automatic Instrumentation](#send-traces-directly-to-signoz-cloud---no-code-automatic-instrumentation-recommended) (recommended) - - [Code Level Automatic Instrumentation](#send-traces-directly-to-signoz-cloud---code-level-automatic-instrumentation) + - [Using vercel otel](#using-vercel-otel) (recommended) + - [OpenTelemetry instrument (only works for nodejs runtime)](#using-opentelemetry-instrument-only-works-for-nodejs-runtime) - [Send traces via OTel Collector binary](#send-traces-via-otel-collector-binary) (recommended) - - [No Code Automatic Instrumentation](#send-traces-via-otel-collector-binary---no-code-automatic-instrumentation) (recommended) - - [Code Level Automatic Instrumentation](#send-traces-via-otel-collector-binary---code-level-automatic-instrumentation) + - [Using vercel otel](#using-vercel-otel-1) (recommended) + - [OpenTelemetry instrument (only works for nodejs runtime)](#using-opentelemetry-instrument-only-works-for-nodejs-runtime-1) -#### Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation (recommended) +### Send traces directly to SigNoz Cloud + +#### Using vercel otel **Step 1.** Install OpenTelemetry packages ```bash -npm install --save @opentelemetry/api -npm install --save @opentelemetry/auto-instrumentations-node +npm install @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation @opentelemetry/exporter-trace-otlp-http ``` -**Step 2.** Run the application +**Step 2.** Update `next.config.mjs` to include instrumentationHook +```tsx +/** @type {import('next').NextConfig} */ +const nextConfig = { + // include instrumentationHook experimental feature + experimental: { + instrumentationHook: true, + }, +}; -```bash -export OTEL_TRACES_EXPORTER="otlp" -export OTEL_EXPORTER_OTLP_ENDPOINT="" -export OTEL_NODE_RESOURCE_DETECTORS="env,host,os" -export OTEL_SERVICE_NAME="" -export OTEL_EXPORTER_OTLP_HEADERS="signoz-access-token=" -export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register" - +export default nextConfig; +``` + +**Step 3.** Create `instrumentation.node.ts` file

+You need to configure the endpoint for SigNoz cloud in this file. + +```tsx +'use strict' +import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'; + +// Add otel logging +import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; +diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging + +const exporterOptions = { + url: 'https://ingest.[data_region].signoz.cloud:443/v1/traces', // Set your own data region or set to http://localhost:4318/v1/traces if using selfhost SigNoz + headers: { 'signoz-access-token': 'SIGNOZ_INGESTION_KEY' }, // Set if you are using SigNoz Cloud +} + +export const traceExporter = new OTLPTraceExporter(exporterOptions); +``` + +- `SIGNOZ_INGESTION_KEY` : You can find your ingestion key from SigNoz cloud account details sent on your email. + +Depending on the choice of your region for SigNoz cloud, the ingest endpoint will vary according to this table. + +| Region | Endpoint | +| --- | --- | +| US | ingest.us.signoz.cloud:443/v1/traces | +| IN | ingest.in.signoz.cloud:443/v1/traces | +| EU | ingest.eu.signoz.cloud:443/v1/traces | + + +**Step 4.** Create `instrumentation.ts` file

+```tsx +import { registerOTel } from '@vercel/otel'; +import { traceExporter } from './instrumentation.node'; + +export function register() { + registerOTel({ + serviceName: 'Sample Next.js App', + traceExporter: traceExporter, + }); +} ``` -| Variable | Description | -|-----------------------|-----------------------------------------------------| -| APP_NAME * | Name you want to give to your rust application | -| SIGNOZ_ENDPOINT * | This is ingestion URL which you must have got in mail after registering on SigNoz cloud | -| SIGNOZ_ACCESS_TOKEN * | This is Ingestion Key which you must have got in mail after registering on SigNoz cloud | +**Step 5.** Once you're done configuring the exporter options, try running your application and validate if your application is sending traces to SigNoz cloud [here](#validating-instrumentation-by-checking-for-traces). + + +The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app. + -replace `` with the run command of your application +You can also check the sample application at this GitHub repo. -#### Send traces directly to SigNoz Cloud - Code Level Automatic Instrumentation +#### Using OpenTelemetry instrument (only works for nodejs runtime) **Step 1.** Install the OpenTelemetry packages @@ -77,16 +122,7 @@ const nextConfig = { export default nextConfig; ``` -**Step 3.** Create `instrumentation.ts` file

-```tsx -export async function register() { - if (process.env.NEXT_RUNTIME === 'nodejs') { - await import('./instrumentation.node') - } -} -``` - -**Step 4.** Create `instrumentation.node.ts` file

+**Step 3.** Create `instrumentation.node.ts` file

You need to configure the endpoint for SigNoz cloud in this file. ```tsx @@ -98,9 +134,9 @@ import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http' import { Resource } from '@opentelemetry/resources' import { SEMRESATTRS_SERVICE_NAME } from '@opentelemetry/semantic-conventions' -// Add otel logging when debugging -// import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; -// diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG); +// Add otel logging +import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; +diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging const exporterOptions = { url: 'https://ingest.[region].signoz.cloud:443/v1/traces', // use your own data region @@ -139,11 +175,24 @@ Depending on the choice of your region for SigNoz cloud, the ingest endpoint wil | IN | ingest.in.signoz.cloud:443/v1/traces | | EU | ingest.eu.signoz.cloud:443/v1/traces | +**Step 4.** Create `instrumentation.ts` file

+```tsx +export async function register() { + if (process.env.NEXT_RUNTIME === 'nodejs') { + await import('./instrumentation.node') + } +} +``` + **Step 5.** Once you're done configuring the exporter options, try running your application and validate if your application is sending traces to SigNoz cloud [here](#validating-instrumentation-by-checking-for-traces). + +The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app. + + You can also check the sample application at this GitHub repo. -#### Send traces via OTel Collector binary - No Code Automatic Instrumentation +### Send traces via OTel Collector binary OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes. It is recommended to install Otel Collector binary to collect and send traces to SigNoz cloud. You can correlate signals and have rich contextual data through this way. @@ -155,34 +204,68 @@ OTel Collector binary helps to collect logs, hostmetrics, resource and infra att -#### Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation (recommended) +#### Using vercel otel **Step 1.** Install OpenTelemetry packages ```bash -npm install --save @opentelemetry/api -npm install --save @opentelemetry/auto-instrumentations-node +npm install @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation @opentelemetry/exporter-trace-otlp-http +``` + +**Step 2.** Update `next.config.mjs` to include instrumentationHook +```tsx +/** @type {import('next').NextConfig} */ +const nextConfig = { + // include instrumentationHook experimental feature + experimental: { + instrumentationHook: true, + }, +}; + +export default nextConfig; ``` -**Step 2.** Run the application +**Step 3.** Create `instrumentation.node.ts` file

+You need to configure the endpoint for SigNoz cloud in this file. -```bash -export OTEL_TRACES_EXPORTER="otlp" -export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318/v1/traces" -export OTEL_NODE_RESOURCE_DETECTORS="env,host,os" -export OTEL_SERVICE_NAME="" -export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register" - +```tsx +'use strict' +import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'; + +// Add otel logging +import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; +diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging + +const exporterOptions = { + url: 'http://localhost:4318/v1/traces', +} + +export const traceExporter = new OTLPTraceExporter(exporterOptions); ``` -| Variable | Description | -|-----------------------|-----------------------------------------------------| -| APP_NAME * | Name you want to give to your rust application | +**Step 4.** Create `instrumentation.ts` file

+```tsx +import { registerOTel } from '@vercel/otel'; +import { traceExporter } from './instrumentation.node'; + +export function register() { + registerOTel({ + serviceName: 'Sample Next.js App', + traceExporter: traceExporter, + }); +} +``` -replace `` with the run command of your application +**Step 5.** Once you're done configuring the exporter options, try running your application and validate if your application is sending traces to SigNoz cloud [here](#validating-instrumentation-by-checking-for-traces). + +The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app. + -#### Send traces via OTel Collector binary - Code Level Automatic Instrumentation +You can also check the sample application at this GitHub repo. + + +#### Using OpenTelemetry instrument (only works for nodejs runtime) **Step 1.** Install OpenTelemetry Collector binary @@ -225,16 +308,7 @@ const nextConfig = { export default nextConfig; ``` -**Step 4.** Create `instrumentation.ts` file

-```tsx -export async function register() { - if (process.env.NEXT_RUNTIME === 'nodejs') { - await import('./instrumentation.node') - } -} -``` - -**Step 5.** Create `instrumentation.node.ts` file

+**Step 4.** Create `instrumentation.node.ts` file

You need to configure the endpoint for SigNoz cloud in this file. ```tsx @@ -246,9 +320,9 @@ import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http' import { Resource } from '@opentelemetry/resources' import { SEMRESATTRS_SERVICE_NAME } from '@opentelemetry/semantic-conventions' -// Add otel logging when debugging -// import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; -// diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG); +// Add otel logging +import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; +diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging const exporterOptions = { url: 'http://localhost:4318/v1/traces', @@ -276,6 +350,15 @@ process.on('SIGTERM', () => { }); ``` +**Step 5.** Create `instrumentation.ts` file

+```tsx +export async function register() { + if (process.env.NEXT_RUNTIME === 'nodejs') { + await import('./instrumentation.node') + } +} +``` + **Step 6.** Once we are done with the above configurations, you can run the collector service with the following command: ```bash ./otelcol-contrib --config ./config.yaml @@ -283,6 +366,10 @@ process.on('SIGTERM', () => { **Step 7.** Start running your application and wait for few seconds to start receiving instrumentation data on the SigNoz Cloud. + +The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app. + + You can also check the sample application at this GitHub repo. @@ -293,39 +380,73 @@ For NextJs application deployed on Kubernetes, you need to install OTel Collecto Once you have set up OTel Collector agent, you can proceed with OpenTelemetry Javascript instrumentation by following either of the two: -1. [No Code Automatic Instrumentation](#no-code-automatic-instrumentation-recommended) (recommended) -2. [Code Level Automatic Instrumentation](#code-level-automatic-instrumentation) +1. [Using Vercel Otel Automatic Instrumentation](#using-vercel-otel-2) (recommended) +2. [Using OpenTelemetry Automatic Instrumentation](#using-opentelemetry-instrument-only-works-for-nodejs-runtime-2) -#### Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation (recommended) +#### Using vercel otel **Step 1.** Install OpenTelemetry packages ```bash -npm install --save @opentelemetry/api -npm install --save @opentelemetry/auto-instrumentations-node +npm install @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation @opentelemetry/exporter-trace-otlp-http ``` -**Step 2.** Run the application +**Step 2.** Update `next.config.mjs` to include instrumentationHook +```tsx +/** @type {import('next').NextConfig} */ +const nextConfig = { + // include instrumentationHook experimental feature + experimental: { + instrumentationHook: true, + }, +}; -```bash -export OTEL_TRACES_EXPORTER="otlp" -export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318/v1/traces" -export OTEL_NODE_RESOURCE_DETECTORS="env,host,os" -export OTEL_SERVICE_NAME="" -export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register" - +export default nextConfig; +``` + +**Step 3.** Create `instrumentation.node.ts` file

+You need to configure the endpoint for SigNoz cloud in this file. + +```tsx +'use strict' +import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'; + +// Add otel logging +import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; +diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging + +const exporterOptions = { + url: 'http://locahost:4318/v1/traces', +} + +export const traceExporter = new OTLPTraceExporter(exporterOptions); +``` + +**Step 4.** Create `instrumentation.ts` file

+```tsx +import { registerOTel } from '@vercel/otel'; +import { traceExporter } from './instrumentation.node'; + +export function register() { + registerOTel({ + serviceName: 'Sample Next.js App', + traceExporter: traceExporter, + }); +} ``` -| Variable | Description | -|-----------------------|-----------------------------------------------------| -| APP_NAME * | Name you want to give to your rust application | +**Step 5.** Once you're done configuring the exporter options, try running your application and validate if your application is sending traces to SigNoz cloud [here](#validating-instrumentation-by-checking-for-traces). + + +The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app. + -replace `` with the run command of your application +You can also check the sample application at this GitHub repo. In case you encounter an issue where all applications do not get listed in the services section then please refer to the [troubleshooting section](#troubleshooting-your-installation). -### Code Level Automatic Instrumentation +#### Using OpenTelemetry instrument (only works for nodejs runtime) **Step 1.** Install OpenTelemetry Collector binary @@ -414,6 +535,10 @@ process.on('SIGTERM', () => { **Step 7.** Start running your application and wait for few seconds to start receiving instrumentation data on the SigNoz Cloud. + +The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app. + + You can also check the sample application at this GitHub repo. @@ -422,43 +547,86 @@ You can also check the sample application at this +export default nextConfig; +``` + +**Step 3.** Create `instrumentation.node.ts` file

+You need to configure the endpoint for SigNoz cloud in this file. + +```tsx +'use strict' +import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'; + +// Add otel logging +import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; +diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging + +const exporterOptions = { + url: 'https://ingest.[data_region].signoz.cloud:443/v1/traces', // Set your own data region or set to http://localhost:4318/v1/traces if using selfhost SigNoz + headers: { 'signoz-access-token': 'SIGNOZ_INGESTION_KEY' }, // Set if you are using SigNoz Cloud +} + +export const traceExporter = new OTLPTraceExporter(exporterOptions); +``` + +- `SIGNOZ_INGESTION_KEY` : You can find your ingestion key from SigNoz cloud account details sent on your email. + +Depending on the choice of your region for SigNoz cloud, the ingest endpoint will vary according to this table. + +| Region | Endpoint | +| --- | --- | +| US | ingest.us.signoz.cloud:443/v1/traces | +| IN | ingest.in.signoz.cloud:443/v1/traces | +| EU | ingest.eu.signoz.cloud:443/v1/traces | + + +**Step 4.** Create `instrumentation.ts` file

+```tsx +import { registerOTel } from '@vercel/otel'; +import { traceExporter } from './instrumentation.node'; + +export function register() { + registerOTel({ + serviceName: 'Sample Next.js App', + traceExporter: traceExporter, + }); +} ``` -| Variable | Description | -|-----------------------|-----------------------------------------------------| -| APP_NAME * | Name you want to give to your rust application | -| SIGNOZ_ENDPOINT * | This is ingestion URL which you must have got in mail after registering on SigNoz cloud | -| SIGNOZ_ACCESS_TOKEN * | This is Ingestion Key which you must have got in mail after registering on SigNoz cloud | +**Step 5.** Once you're done configuring the exporter options, try running your application and validate if your application is sending traces to SigNoz cloud [here](#validating-instrumentation-by-checking-for-traces). -replace `` with the run command of your application + +The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app. + -#### Send traces directly to SigNoz Cloud - Code Level Automatic Instrumentation +You can also check the sample application at this
GitHub repo. + +#### Send traces directly to SigNoz Cloud - OpenTelemetry instrument (only works for nodejs runtime) **Step 1.** Install the OpenTelemetry packages @@ -554,9 +722,13 @@ $env:SIGNOZ_INGESTION_KEY="" **Step 5.** Once you're done configuring the exporter options, try running your application and validate if your application is sending traces to SigNoz cloud [here](#validating-instrumentation-by-checking-for-traces). + +The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app. + + You can also check the sample application at this GitHub repo. -#### Send traces via OTel Collector binary - No Code Automatic Instrumentation +#### Send traces via OTel Collector binary OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes. It is recommended to install Otel Collector binary to collect and send traces to SigNoz cloud. You can correlate signals and have rich contextual data through this way. @@ -568,34 +740,67 @@ OTel Collector binary helps to collect logs, hostmetrics, resource and infra att -#### Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation (recommended) +#### Using vercel otel **Step 1.** Install OpenTelemetry packages ```bash -npm install --save @opentelemetry/api -npm install --save @opentelemetry/auto-instrumentations-node +npm install @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation @opentelemetry/exporter-trace-otlp-http +``` + +**Step 2.** Update `next.config.mjs` to include instrumentationHook +```tsx +/** @type {import('next').NextConfig} */ +const nextConfig = { + // include instrumentationHook experimental feature + experimental: { + instrumentationHook: true, + }, +}; + +export default nextConfig; ``` -**Step 2.** Run the application +**Step 3.** Create `instrumentation.node.ts` file

+You need to configure the endpoint for SigNoz cloud in this file. -```bash -$env:OTEL_TRACES_EXPORTER="otlp" -$env:OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318/v1/traces" -$env:OTEL_NODE_RESOURCE_DETECTORS="env,host,os" -$env:OTEL_SERVICE_NAME="" -$env:NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register" - +```tsx +'use strict' +import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'; + +// Add otel logging +import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; +diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging + +const exporterOptions = { + url: 'http://localhost:4318/v1/traces', +} + +export const traceExporter = new OTLPTraceExporter(exporterOptions); ``` -| Variable | Description | -|-----------------------|-----------------------------------------------------| -| APP_NAME * | Name you want to give to your rust application | +**Step 4.** Create `instrumentation.ts` file

+```tsx +import { registerOTel } from '@vercel/otel'; +import { traceExporter } from './instrumentation.node'; + +export function register() { + registerOTel({ + serviceName: 'Sample Next.js App', + traceExporter: traceExporter, + }); +} +``` + +**Step 5.** Once you're done configuring the exporter options, try running your application and validate if your application is sending traces to SigNoz cloud [here](#validating-instrumentation-by-checking-for-traces). -replace `` with the run command of your application + +The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app. + +You can also check the sample application at this GitHub repo. -#### Send traces via OTel Collector binary - Code Level Automatic Instrumentation +#### Using OpenTelemetry instrument (only works for nodejs runtime) **Step 1.** Install OpenTelemetry Collector binary @@ -697,6 +902,10 @@ process.on('SIGTERM', () => { **Step 7.** Start running your application and wait for few seconds to start receiving instrumentation data on the SigNoz Cloud. + +The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app. + + You can also check the sample application at this GitHub repo. @@ -709,6 +918,79 @@ If you're trying to send instrumentation data to SigNoz self-hosted way, the onl You can find instructions to install OTel Collector binary [here](https://signoz.io/docs/tutorial/kubernetes-infra-metrics/) in your Kubernetes cluster. +### Using vercel otel + +**Step 1.** Install OpenTelemetry packages + +```bash +npm install @vercel/otel @opentelemetry/sdk-logs @opentelemetry/api-logs @opentelemetry/instrumentation @opentelemetry/exporter-trace-otlp-http +``` + +**Step 2.** Update `next.config.mjs` to include instrumentationHook +```tsx +/** @type {import('next').NextConfig} */ +const nextConfig = { + // include instrumentationHook experimental feature + experimental: { + instrumentationHook: true, + }, +}; + +export default nextConfig; +``` + +**Step 3.** Create `instrumentation.node.ts` file

+You need to configure the endpoint for SigNoz cloud in this file. + +```tsx +'use strict' +import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'; + +// Add otel logging +import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'; +diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR); // set diaglog level to DEBUG when debugging + +const exporterOptions = { + url: 'http://localhost:4318/v1/traces', // Endpoint of SigNoz/Otel Collector +} + +export const traceExporter = new OTLPTraceExporter(exporterOptions); +``` + +- `SIGNOZ_INGESTION_KEY` : You can find your ingestion key from SigNoz cloud account details sent on your email. + +Depending on the choice of your region for SigNoz cloud, the ingest endpoint will vary according to this table. + +| Region | Endpoint | +| --- | --- | +| US | ingest.us.signoz.cloud:443/v1/traces | +| IN | ingest.in.signoz.cloud:443/v1/traces | +| EU | ingest.eu.signoz.cloud:443/v1/traces | + + +**Step 4.** Create `instrumentation.ts` file

+```tsx +import { registerOTel } from '@vercel/otel'; +import { traceExporter } from './instrumentation.node'; + +export function register() { + registerOTel({ + serviceName: 'Sample Next.js App', + traceExporter: traceExporter, + }); +} +``` + +**Step 5.** Once you're done configuring the exporter options, try running your application and validate if your application is sending traces to SigNoz cloud [here](#validating-instrumentation-by-checking-for-traces). + + +The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app. + + +You can also check the sample application at this GitHub repo. + +### Using OpenTelemetry instrument (only works for nodejs runtime) + **Step 1.** Install OpenTelemetry packages ```bash @@ -783,6 +1065,10 @@ process.on('SIGTERM', () => { }); ``` + +The instrumentation file should be in the root of your project and not inside the app or pages directory. If you're using the src folder, then place the file inside src alongside pages and app. + + Again, `http://localhost:4318/v1/traces` is the default url for sending your tracing data. We are assuming you have installed SigNoz on your localhost. Based on your environment, you can update it accordingly. It should be in the following format: `http://:4318/v1/traces` @@ -795,7 +1081,7 @@ Once you're done with this, add your required changes including receivers, expor You can also check the sample application at this GitHub repo. -### Validating instrumentation by checking for traces +## Validating instrumentation by checking for traces With your application running, you can verify that you’ve instrumented your application with OpenTelemetry correctly by confirming that tracing data is being reported to SigNoz.