Tutorial: Use GitLab Observability with a NodeJS application

DETAILS: Tier: Ultimate Offering: GitLab.com Status: Beta

FLAG: The availability of this feature is controlled by a feature flag. For more information, see the history of the Distributed tracing feature.

In this tutorial, you'll learn how to configure, instrument, and monitor a NodeJS application using GitLab Observability features.

Before you begin

Take a moment and make sure you have the following:

• A GitLab Ultimate subscription for GitLab.com
• A local installation of NodeJS
• Basic knowledge of Git, NodeJS, JavaScript, and the core concepts of OpenTelemetry

Create a new GitLab project

First, create a new GitLab project and a corresponding access token. This tutorial uses the project name nodejs-O11y-tutorial.

1. On the left sidebar, at the top, select Create new ({plus}) and New project/repository.
2. Select Create from template.
3. Select Use template for NodeJS Express.
4. Enter the project details.
   • In the Project name field, enter nodejs-O11y-tutorial.
5. Select Create project.
6. In the nodejs-O11y-tutorial project, on the left sidebar, select Settings > Access tokens.
7. Create a new access token with the Owner role and the read_api and write_observability scopes. Store the token value somewhere safe—you'll need it later.

Instrument your NodeJS application

Next, we need to instrument the NodeJS application.

1. Ensure you have NodeJS installed by running the following:

   node -v

2. Clone the nodejs-O11y-tutorial project and cd to the nodejs-O11y-tutorial directory.

3. Install the dependencies by running:

   npm install

4. Run the application:

   PORT=8080 node server.js

5. In a web browser, visit http://localhost:8080 and make sure the application is running correctly.

6. Add the OpenTelemetry packages:

   npm install --save @opentelemetry/api \
     @opentelemetry/auto-instrumentations-node

7. Find your group ID:

   1. On the left sidebar, select Search or go to and find the top-level group with the nodejs-O11y-tutorial project. For example, if your project URL is https://gitlab.com/tankui/observability/nodejs-O11y-tutorial, the top-level group is tanuki.
   2. On the group overview page, in the upper-right corner, select Actions ({ellipsis_v}).
   3. Select Copy group ID. Save the copied ID for later.

8. Find your project ID:

   1. On the nodejs-O11y-tutorial project overview page, in the upper-right corner, select Actions ({ellipsis_v}).
   2. Select Copy project ID. Save the copied ID for later.

9. Configure and run your project with instrumentation:

   env OTEL_TRACES_EXPORTER="otlp" \
   OTEL_EXPORTER_OTLP_ENDPOINT="https://observe.gitlab.com/v3/{{GROUP_ID}}/{{PROJECT_ID}}/ingest" \
   OTEL_EXPORTER_OTLP_HEADERS="PRIVATE-TOKEN={{ACCESS_TOKEN}}" \
   OTEL_SERVICE_NAME="nodejs-O11y-tutorial" \
   OTEL_LOG_LEVEL="debug" \
   NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register" \
   PORT=8080 node server.js

   Be sure to replace the GROUP_ID, PROJECT_ID, and ACCESS_TOKEN with the values you obtained earlier.

View traces

Now that you have an application configured to use Observability tracing, you can view exported traces on GitLab.com.

To view exported traces:

1. Start the nodejs-O11y-tutorial application with instrumentation again.

2. Visit http://localhost:8080/ and perform some actions in the application.

3. In the nodejs-O11y-tutorial project, on the left sidebar, select Monitor > Traces. If everything is working correctly, you should see a trace for each request.

   

4. Optional. Select a trace to view its span.

   

Congratulations! You successfully created an application, configured it to use GitLab Observability features, and examined the traces the application created. You can continue to experiment with this application, or try configuring a more complex application to export traces.

Remember that Observability Tracing is not yet ready for production use. There is no official support for logs or metrics using the OpenTelemetry collector with a NodeJS application.