OpenTelemetry

Важно знать: Эта функция находится в стадии экспериментальной разработки, вам нужно явно включить её, предоставив experimental.instrumentationHook = true; в вашем next.config.js.

Наблюдаемость имеет решающее значение для понимания и оптимизации поведения и производительности вашего приложения Next.js.

По мере усложнения приложений все сложнее становится выявлять и диагностировать возникающие проблемы. Используя инструменты наблюдаемости, такие как логирование и метрики, разработчики могут получить представление о поведении своего приложения и определить области для оптимизации. С помощью наблюдаемости разработчики могут проактивно решать проблемы, прежде чем они станут серьезными, и обеспечить лучший пользовательский опыт. Поэтому настоятельно рекомендуется использовать наблюдаемость в ваших приложениях Next.js для повышения производительности, оптимизации ресурсов и улучшения пользовательского опыта.

Мы рекомендуем использовать OpenTelemetry для инструментирования ваших приложений. Это платформенно-нейтральный способ инструментировать приложения, который позволяет вам изменять поставщика наблюдаемости, не изменяя код. Для получения дополнительной информации об OpenTelemetry и его работе ознакомьтесь с официальной документацией OpenTelemetry.

В данной документации используются такие термины, как Span, Trace или Exporter, которые можно найти в вводном руководстве по наблюдаемости OpenTelemetry.

Next.js поддерживает инструментирование OpenTelemetry «из коробки», что означает, что мы уже инструментировали сам Next.js. При включении OpenTelemetry мы автоматически обернём весь ваш код, например getStaticProps, в spans с полезными атрибутами.

Начало работы

OpenTelemetry расширяем, но его правильная настройка может быть довольно громоздкой. Именно поэтому мы подготовили пакет @vercel/otel, который поможет вам быстро начать работу.

Использование @vercel/otel

Для начала работы необходимо установить @vercel/otel:

npm install @vercel/otel

Далее создайте пользовательский instrumentation.ts (или .js) файл в корневой директории проекта (или в папке src, если вы её используете):

import { registerOTel } from '@vercel/otel'
 
export function register() {
  registerOTel({ serviceName: 'next-app' })
}

Дополнительные параметры конфигурации см. в @vercel/otel документации.

Важно знать

• Файл instrumentation должен находиться в корне вашего проекта, а не внутри папок app или pages. Если вы используете папку src, поместите файл в папку src рядом с pages и app.
• Если вы используете опцию конфигурации pageExtensions для добавления суффикса, вам также необходимо обновить имя файла instrumentation для соответствия.
• Мы создали пример with-opentelemetry, который вы можете использовать.

Ручная настройка OpenTelemetry

Пакет @vercel/otel предоставляет множество параметров конфигурации и должен удовлетворять большинству общих случаев использования. Но если он не подходит для ваших потребностей, вы можете настроить OpenTelemetry вручную.

Сначала вам необходимо установить пакеты OpenTelemetry:

npm install @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http

Теперь вы можете инициализировать NodeSDK в вашем instrumentation.ts. В отличие от @vercel/otel, NodeSDK несовместим с выполнением в режиме edge, поэтому вам нужно убедиться, что вы импортируете их только тогда, когда process.env.NEXT_RUNTIME === 'nodejs'. Мы рекомендуем создать новый файл instrumentation.node.ts, который вы импортируете условно только при использовании Node.js:

export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation.node.ts')
  }
}

import { NodeSDK } from '@opentelemetry/sdk-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { Resource } from '@opentelemetry/resources'
import { SEMRESATTRS_SERVICE_NAME } from '@opentelemetry/semantic-conventions'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node'
 
const sdk = new NodeSDK({
  resource: new Resource({
    [SEMRESATTRS_SERVICE_NAME]: 'next-app',
  }),
  spanProcessor: new SimpleSpanProcessor(new OTLPTraceExporter()),
})
sdk.start()

Это эквивалентно использованию @vercel/otel, но позволяет изменять и расширять некоторые функции, которые не доступны через @vercel/otel. Если поддержка режима edge необходима, вам придётся использовать @vercel/otel.

Тестирование вашей интеграции

Для тестирования локальных трасс OpenTelemetry вам нужен OpenTelemetry коллектор с совместимым бэкендом. Мы рекомендуем использовать нашу среду разработки OpenTelemetry.

Если всё работает правильно, вы должны увидеть корневой сервер span с меткой GET /requested/pathname. Все остальные span этой конкретной трассы будут вложены под ним.

Next.js отслеживает больше span, чем генерируется по умолчанию. Для отображения большего количества span необходимо установить NEXT_OTEL_VERBOSE=1.

Развёртывание

Использование OpenTelemetry Collector

При развёртывании с OpenTelemetry Collector вы можете использовать @vercel/otel. Он будет работать как на Vercel, так и при самостоятельном размещении.

Развёртывание на Vercel

Мы позаботились о том, чтобы OpenTelemetry работал «из коробки» на Vercel.

Следуйте документации Vercel для подключения вашего проекта к поставщику наблюдаемости.

Самостоятельное размещение

Развёртывание на других платформах также просто. Вам потребуется запустить собственный OpenTelemetry Collector для получения и обработки данных телеметрии из вашего приложения Next.js.

Для этого следуйте руководству OpenTelemetry Collector по началу работы, которое поможет вам настроить коллектор и настроить его для получения данных из вашего приложения Next.js.

После запуска коллектора вы можете развернуть ваше приложение Next.js на выбранной платформе, следуя соответствующим руководствам по развёртыванию.

Пользовательские экспортеры

OpenTelemetry Collector не обязателен. Вы можете использовать пользовательский экспортер OpenTelemetry с @vercel/otel или ручной настройкой OpenTelemetry.

Пользовательские Span

Вы можете добавить пользовательский span с помощью API OpenTelemetry.

npm install @opentelemetry/api

Следующий пример демонстрирует функцию, которая получает звёзды GitHub и добавляет пользовательский fetchGithubStars span для отслеживания результата запроса:

import { trace } from '@opentelemetry/api'
 
export async function fetchGithubStars() {
  return await trace
    .getTracer('nextjs-example')
    .startActiveSpan('fetchGithubStars', async (span) => {
      try {
        return await getValue()
      } finally {
        span.end()
      }
    })
}

Функция register будет выполняться перед запуском вашего кода в новой среде. Вы можете начать создание новых span, и они должны быть корректно добавлены в экспортируемую трассу.

Span по умолчанию в Next.js

Next.js автоматически инструментирует несколько span для предоставления полезных данных о производительности вашего приложения.

Атрибуты span следуют семантическим соглашениям OpenTelemetry. Мы также добавляем некоторые пользовательские атрибуты в пространство имён next:

• next.span_name - дублирует имя span
• next.span_type - каждый тип span имеет уникальный идентификатор
• next.route - шаблон маршрута запроса (например, /[param]/user).
• next.rsc (true/false) - Является ли запрос запросом RSC, например, префеч.
• next.page
  • Это внутреннее значение, используемое маршрутизатором приложения.
  • Вы можете рассматривать его как маршрут к специальному файлу (например, page.ts, layout.ts, loading.ts и др.)
  • Его можно использовать в качестве уникального идентификатора только в сочетании с next.route, поскольку /layout может использоваться для идентификации как /(groupA)/layout.ts, так и /(groupB)/layout.ts.

[http.method] [next.route]

• next.span_type: BaseServer.handleRequest

Этот span представляет собой корневой span для каждого входящего запроса в ваше приложение Next.js. Он отслеживает HTTP-метод, маршрут, целевой адрес и код состояния запроса.

Атрибуты:

• Общие атрибуты HTTP
  • http.method
  • http.status_code
• Атрибуты сервера HTTP
  • http.route
  • http.target
• next.span_name
• next.span_type
• next.route

render route (app) [next.route]

• next.span_type: AppRender.getBodyResult.

Этот span представляет процесс рендеринга маршрута в маршрутизаторе приложения.

Атрибуты:

• next.span_name
• next.span_type
• next.route

fetch [http.method] [http.url]

• next.span_type: AppRender.fetch

Этот span представляет запрос fetch, выполненный в вашем коде.

Атрибуты:

• Общие атрибуты HTTP
  • http.method
• Атрибуты HTTP-клиента
  • http.url
  • net.peer.name
  • net.peer.port (только если указано)
• next.span_name
• next.span_type

Этот блок можно отключить, задав NEXT_OTEL_FETCH_DISABLED=1 в вашей среде. Это полезно, когда вы хотите использовать пользовательскую библиотеку инструментирования fetch.

выполнение маршрута API (приложение) [next.route]

• next.span_type: AppRouteRouteHandlers.runHandler.

Этот span представляет выполнение обработчика маршрута API в маршрутизаторе приложения.

Атрибуты:

• next.span_name
• next.span_type
• next.route

getServerSideProps [next.route]

• next.span_type: Render.getServerSideProps.

Этот span представляет выполнение getServerSideProps для определенного маршрута.

Атрибуты:

• next.span_name
• next.span_type
• next.route

getStaticProps [next.route]

• next.span_type: Render.getStaticProps.

Этот span представляет выполнение getStaticProps для определенного маршрута.

Атрибуты:

• next.span_name
• next.span_type
• next.route

рендеринг маршрута (страницы) [next.route]

• next.span_type: Render.renderDocument.

Этот span представляет процесс рендеринга документа для определенного маршрута.

Атрибуты:

• next.span_name
• next.span_type
• next.route

generateMetadata [next.page]

• next.span_type: ResolveMetadata.generateMetadata.

Этот span представляет процесс генерации метаданных для определенной страницы (один маршрут может содержать несколько таких span).

Атрибуты:

• next.span_name
• next.span_type
• next.page

разрешение компонентов страницы

• next.span_type: NextNodeServer.findPageComponents.

Этот span представляет процесс разрешения компонентов страницы для определенной страницы.

Атрибуты:

• next.span_name
• next.span_type
• next.route

разрешение модулей сегмента

• next.span_type: NextNodeServer.getLayoutOrPageModule.

Этот span представляет загрузку модулей кода для макета или страницы.

Атрибуты:

• next.span_name
• next.span_type
• next.segment

начало ответа

• next.span_type: NextNodeServer.startResponse.

Этот span нулевой длины представляет момент, когда первый байт отправлен в ответе.