This guide demonstrates how to configure OpenTelemetry in a Node.js app to send telemetry data to Axiom.
app.ts
sample.app.ts
is the core of the app. It uses Express.js to create a simple web server. The server has an endpoint /rolldice
that returns a random number, simulating a basic API. It also demonstrates the usage of span links to establish relationships between spans across different traces.
instrumentation.ts
sets up the OpenTelemetry instrumentation. It configures the OTLP (OpenTelemetry Protocol) exporters for traces and initializes the Node SDK with automatic instrumentation capabilities.
API_TOKEN
with the Axiom API token you have generated. For added security, store the API token in an environment variable.Replace DATASET_NAME
with the name of the Axiom dataset where you want to send data.Replace AXIOM_DOMAIN
with api.axiom.co
if your organization uses the US region, and with api.eu.axiom.co
if your organization uses the EU region. For more information, see Regions.package.json
below
package.json
file to manage your project’s dependencies and scripts, and a tsconfig.json
file to manage TypeScript compiler options.
package.json
package.json
file in the root of your project with the following content:
tsconfig.json
tsconfig.json
file in the root of your project with the following content:
instrumentation.ts
file.
ts-node-dev
. It sets up the exporter for tracing and restarts the server automatically whenever you make changes to the files.
tsconfig.json
. Once the build process is complete, you can start your app in production mode with:
/rolldice
endpoint.
Observing the telemetry data in Axiom
Dynamic OpenTelemetry traces dashboard
Field Category | Field Name | Description |
---|---|---|
Unique Identifiers | ||
_rowid | Unique identifier for each row in the trace data. | |
span_id | Unique identifier for the span within the trace. | |
trace_id | Unique identifier for the entire trace. | |
Timestamps | ||
_systime | System timestamp when the trace data was recorded. | |
_time | Timestamp when the actual event being traced occurred. | |
HTTP Attributes | ||
attributes.custom[“http.host”] | Host information where the HTTP request was sent. | |
attributes.custom[“http.server_name”] | Server name for the HTTP request. | |
attributes.http.flavor | HTTP protocol version used. | |
attributes.http.method | HTTP method used for the request. | |
attributes.http.route | Route accessed during the HTTP request. | |
attributes.http.scheme | Protocol scheme (HTTP/HTTPS). | |
attributes.http.status_code | HTTP response status code. | |
attributes.http.target | Specific target of the HTTP request. | |
attributes.http.user_agent | User agent string of the client. | |
Network Attributes | ||
attributes.net.host.port | Port number on the host receiving the request. | |
attributes.net.peer.port | Port number on the peer (client) side. | |
attributes.custom[“net.peer.ip”] | IP address of the peer in the network interaction. | |
Operational Details | ||
duration | Time taken for the operation. | |
kind | Type of span (for example,, server, client). | |
name | Name of the span. | |
scope | Instrumentation scope. | |
service.name | Name of the service generating the trace. | |
Resource Process Attributes | ||
resource.process.command | Command line string used to start the process. | |
resource.process.command_args | List of command line arguments used in starting the process. | |
resource.process.executable.name | Name of the executable running the process. | |
resource.process.executable.path | Path to the executable running the process. | |
resource.process.owner | Owner of the process. | |
resource.process.pid | Process ID. | |
resource.process.runtime.description | Description of the runtime environment. | |
resource.process.runtime.name | Name of the runtime environment. | |
resource.process.runtime.version | Version of the runtime environment. | |
Telemetry SDK Attributes | ||
telemetry.sdk.language | Language of the telemetry SDK. | |
telemetry.sdk.name | Name of the telemetry SDK. | |
telemetry.sdk.version | Version of the telemetry SDK. |
instrumentation.ts
file imports the following libraries:
@opentelemetry/sdk-node
@opentelemetry/auto-instrumentations-node
@opentelemetry/exporter-trace-otlp-proto
@opentelemetry/exporter-trace-otlp-proto
package provides an exporter that sends trace data using the OpenTelemetry Protocol (OTLP). OTLP is the standard protocol for transmitting telemetry data in the OpenTelemetry ecosystem. This exporter allows Node.js apps to send their collected traces to any backend that supports OTLP, such as Axiom. The use of OTLP ensures broad compatibility and a standardized way of transmitting telemetry data.
@opentelemetry/sdk-trace-base
BatchSpanProcessor
, among other foundational elements for tracing in OpenTelemetry. The BatchSpanProcessor
is a component that collects and processes spans (individual units of trace data). As the name suggests, it batches these spans before sending them to the configured exporter (in this case, the OTLPTraceExporter
). This batching mechanism is efficient as it reduces the number of outbound requests by aggregating multiple spans into fewer batches. It helps in the performance and scalability of trace data export in an OpenTelemetry-instrumented app.