Prerequisites
- Create an Axiom account.
- Create a dataset in Axiom where you send your data.
- Create an API token in Axiom with permissions to create, read, update, and delete datasets.
- Install Node.js version 14 or newer.
- An existing Next.js app. Alternatively, create a new app with the default settings using the Next.js documentation.
Send data from new project
Initial setup
- Create a new app with the default settings using the Next.js documentation.
-
Run the following command to install the dependencies:
-
Create an
instrumentation.ts
file in thesrc
folder of your project with the following content:/src/instrumentation.ts -
Add the
AXIOM_DOMAIN
,API_TOKEN
, andDATASET_NAME
environment variables to your.env
file. For example:
Update root layout
In the/src/app/layout.tsx
file, import and call the register
function from the instrumentation
module:
/src/app/layout.tsx
register
function.
Update compiler options
Add the following options to yourtsconfig.json
file to ensure compatibility with OpenTelemetry and Next.js:
/tsconfig.json
Observe traces in Axiom
Use the following command to run your Next.js app with OpenTelemetry instrumentation in development mode:Send data from existing project
Manual instrumentation
Manual instrumentation allows you to create, configure, and manage spans and traces, providing detailed control over telemetry data collection at specific points within the app.- Set up and retrieve a tracer from the OpenTelemetry API. This tracer starts and manages spans within your app components or API routes.
- Manually start a span at the beginning of significant operations or transactions within your Next.js app and ensure you end it appropriately. This approach is for tracing specific custom events or operations not automatically captured by instrumentations.
- Enhance the span with additional information such as user details or operation outcomes, which can provide deeper insights when analyzing telemetry data.
Automatic instrumentation
Automatic instrumentation uses the capabilities of OpenTelemetry to automatically capture telemetry data for standard operations such as HTTP requests and responses.- Use the OpenTelemetry Node SDK to configure your app to automatically instrument supported libraries and frameworks. Set up
NodeSDK
in aninstrumentation.ts
file in your project.
/src/instrumentation.ts
- Include necessary OpenTelemetry instrumentation packages to automatically capture telemetry from Node.js libraries like HTTP and any other middlewares used by Next.js.
-
Call the
register
function from theinstrumentation.ts
within your app startup file or before your app starts handling traffic to initialize the OpenTelemetry instrumentation.
Reference
List of OpenTelemetry trace fields
Field Category | Field Name | Description |
---|---|---|
General Trace Information | ||
_rowId | Unique identifier for each row in the trace data. | |
_sysTime | System timestamp when the trace data was recorded. | |
_time | Timestamp when the actual event being traced occurred. | |
trace_id | Unique identifier for the entire trace. | |
span_id | Unique identifier for the span within the trace. | |
parent_span_id | Unique identifier for the parent span within the trace. | |
HTTP Attributes | ||
attributes.http.method | HTTP method used for the request. | |
attributes.http.status_code | HTTP status code returned in response. | |
attributes.http.route | Route accessed during the HTTP request. | |
attributes.http.target | Specific target of the HTTP request. | |
Custom Attributes | ||
attributes.custom[“next.route”] | Custom attribute defining the Next.js route. | |
attributes.custom[“next.rsc”] | Indicates if React Server Components are used. | |
attributes.custom[“next.span_name”] | Custom name of the span within Next.js context. | |
attributes.custom[“next.span_type”] | Type of the Next.js span, describing the operation context. | |
Resource Process Attributes | ||
resource.process.pid | Process ID of the Node.js app. | |
resource.process.runtime.description | Description of the runtime environment. For example, Node.js. | |
resource.process.runtime.name | Name of the runtime environment. For example, nodejs. | |
resource.process.runtime.version | Version of the runtime environment For example, 18.17.0. | |
resource.process.executable.name | Executable name running the process. For example, next-server. | |
Resource Host Attributes | ||
resource.host.arch | Architecture of the host machine. For example, arm64. | |
resource.host.name | Name of the host machine. For example, MacBook-Pro.local. | |
Operational Details | ||
duration | Time taken for the operation. | |
kind | Type of span (for example, server, internal). | |
name | Name of the span, often a high-level title for the operation. | |
Scope Attributes | ||
scope.name | Name of the scope for the operation. For example, next.js. | |
scope.version | Version of the scope. For example, 0.0.1. | |
Service Attributes | ||
service.name | Name of the service generating the trace. For example, nextjs-app. | |
Telemetry SDK Attributes | ||
telemetry.sdk.language | Language of the telemetry SDK. For example, nodejs. | |
telemetry.sdk.name | Name of the telemetry SDK. For example, opentelemetry. | |
telemetry.sdk.version | Version of the telemetry SDK. For example, 1.23.0. |
List of imported libraries
@opentelemetry/api
The core API for OpenTelemetry in JavaScript, providing the necessary interfaces and utilities for tracing, metrics, and context propagation. In the context of Next.js, it allows developers to manually instrument custom spans, manipulate context, and access the active span if needed.
@opentelemetry/exporter-trace-otlp-http
This exporter enables your Next.js app to send trace data over HTTP to any backend that supports the OTLP (OpenTelemetry Protocol), such as Axiom. Using OTLP ensures compatibility with a wide range of observability tools and standardizes the data export process.
@opentelemetry/resources
This defines the Resource which represents the entity producing telemetry. In Next.js, Resources can be used to describe the app (for example, service name, version) and are attached to all exported telemetry, aiding in identifying data in backend systems.
@opentelemetry/sdk-node
The OpenTelemetry SDK for Node.js which provides a comprehensive set of tools for instrumenting Node.js apps. It includes automatic instrumentation for popular libraries and frameworks, as well as APIs for manual instrumentation. In the Next.js setup, it’s used to configure and initialize the OpenTelemetry SDK.
@opentelemetry/sdk-trace-node
This package provides the Node.js-specific implementation of the OpenTelemetry Tracing SDK. It includes the core components needed to create and manage spans, as well as utilities for automatic and manual instrumentation in Node.js environments. In a Next.js app, it works alongside @opentelemetry/sdk-node
to give finer control over the tracing pipeline. For example, configuring span processors, sampling strategies, or custom span exporters directly for trace data. It’s useful when you need more granular control over tracing behavior beyond the default SDK configuration.
@opentelemetry/semantic-conventions
A set of standard attributes and conventions for describing resources, spans, and metrics in OpenTelemetry. By adhering to these conventions, your Next.js app’s telemetry data becomes more consistent and interoperable with other OpenTelemetry-compatible tools and systems.