Instrumenting NodeJS with an OTLP

Instrumenting NodeJS

As software infrastructures become increasingly complex, understanding their inner workings has become more difficult, especially at scale and with the emergence of more sophisticated architectures. Coupled with the adoption of distributed frameworks like microservices and cloud-native designs, while beneficial for scalability and agility, it makes identifying and correcting system anomalies more complicated. Traditional error-tracking approaches are insufficient in these intricate setups, making issue diagnosis like searching for a needle in a haystack. The focus has changed from ensuring the smooth operation of standalone applications to achieving a comprehensive view of an entire suite of interconnected services.

This is where OpenTelemetry’s OpenSource libraries come in handy. They can be instrumented with industry-standard component deployments and connected to OTLP endpoints like the Lumigo OTLP endpoint.

Understanding OpenTelemetry

At its core, OpenTelemetry is designed to redefine the approach to observing and managing the complex interplay of modern distributed systems. At its heart, OpenTelemetry is a collection of tools, APIs, and SDKs that forge a comprehensive framework for gathering, processing, and transmitting telemetry data — metrics and logs. It traces the behavior and performance of software applications. This initiative emerges from the confluence of two pioneering projects, OpenCensus and OpenTracing, merging their strengths to establish a unified, community-driven standard for application instrumentation.

OpenTelemetry is an initiative that promotes an open-source philosophy, encouraging collaboration and innovation in a vendor-agnostic framework. This approach democratizes the process of software instrumentation, allowing developers to integrate telemetry within their applications without being tied to proprietary systems. The OpenTelemetry Protocol (OTLP) is a key innovation that facilitates a universal interchange format for telemetry data. It embodies the agnostic spirit of OpenTelemetry, enabling seamless communication between different systems and tools regardless of their underlying technology stacks. Once collected, this protocol ensures that telemetry data can be effortlessly transmitted to and processed by various monitoring, analysis, and observability platforms.

It's important to understand the OTLP protocol and how it can help you comprehend the practicality and versatility of OpenTelemetry. OTLP is a highly efficient, gRPC-based protocol that ensures seamless telemetry data transmission across network boundaries. It ensures data integrity and minimizes latency, acting as a universal language for telemetry data. This ensures that the data can be universally understood and utilized by any supporting backend or service, regardless of the source or nature of the data. Interoperability provided by OTLP is a key aspect of OpenTelemetry’s objective of providing a standardized approach to observability.

Let’s look at some code

OpenTelemetry for Node.js is a collection of libraries that work together to provide the basic elements necessary for seamless telemetry data collection and export. The main library acts as the gateway for access to tracing functionality. It provides essential constructs such as trace that brings the ability to define and manage spans representing work units within an application.

const { trace } = require('@opentelemetry/api');

Accompanying this, the @opentelemetry/resources library provides the Resource class, a means to enrich telemetry data with metadata about the application or environment, such as the service name. This enrichment facilitates clearer identification and analysis of data within complex distributed systems.

const { Resource } = require('@opentelemetry/resources');

To orchestrate the tracing process, the @opentelemetry/sdk-trace-base introduces vital components like the BasicTracerProvider and SimpleSpanProcessor. The BasicTracerProvider establishes a foundation for tracing and managing how telemetry data is collected while SimpleSpanProcessor ensuring that spans are processed and ready for export in a straightforward manner.

const { BasicTracerProvider, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');

The library constructs the bridge to external observability platforms through the OTLPTraceExporter. This exporter is adept at packaging and transmitting telemetry data per the OTLP standard, facilitating the flow of information to backends like Lumigo for further analysis.

const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');

Guided by the principles outlined in @opentelemetry/semantic-conventions, the code adheres to a set of standardized attributes, ensuring consistency and predictability in how telemetry data is described and understood across various platforms.

In practice, the orchestration of these components within a Node.js application begins with setting up a tracerProvider, enriched with application-specific metadata via a Resource instance. The OTLPTraceExporter is then configured with the necessary credentials and endpoint details for Lumigo and attached to the tracerProvider using a SimpleSpanProcessor.

const tracerProvider = new BasicTracerProvider({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: "your-service-name",
  }),
});
const otlpExporter = new OTLPTraceExporter({
  headers: {
    "Authorization": `LumigoToken ${lumigoToken}`,
  },
});
tracerProvider.addSpanProcessor(new SimpleSpanProcessor(otlpExporter));

This setup culminates in the retrieval of a tracer instance, ready to mark the beginning and end of operations within the application as spans. These spans, encapsulated work units, are then seamlessly exported to Lumigo through the OTLP pipeline, offering a glimpse into the application's runtime behavior.

const tracer = trace.getTracer("example-tracer");
const main = () => {
  const span = tracer.startSpan("example-span");
  // Work simulation
  setTimeout(() => {
    span.end(); // Concludes the tracing of this particular operation
  }, 1000);
};
main();

This streamlined integration of OpenTelemetry components, leveraging the OTLP for data export to Lumigo, exemplifies a practical approach to instrumenting Node.js applications for enhanced observability.

Give it a try

If you’re interested in NodeJS instrumentation with OpenTelemetry and the Lumigo OTLP endpoint, then you should know that this is just the beginning. For those eager to explore this setup's intricacies, the blog post NodeJS Instrumentation with the Lumigo OTLP Endpoint has more information, including additional code and setup steps.

Sign up for a Lumigo account today and get access to observability tools with auto-instrumentation capabilities, simplifying integrating OpenTelemetry into your Node.js applications.