Set up production instrumentation for Node.js
Follow these steps set up production Application Observability with a telemetry collector:
- Install the instrumentation library
- Configure an application
- Set up a telemetry data collector
- Run the application
- Observe the service in Application Observability
Note
For a quick and easy local development setup, consult the quickstart documentation.
Install the instrumentation library
Ensure that you have the following installed locally:
The following commands install the Node.js API, SDK, and auto-instrumentation tools:
npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node
Configure an application
Next, customize the following shell script to configure an application:
<authentication environment variables from step 3>
export OTEL_SERVICE_NAME=<Service Name>
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
# To setup your own Service Instance ID
export OTEL_RESOURCE_ATTRIBUTES="service.instance.id=my-service-instance-id"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
# To have a Service Instance ID generated using a random UUID
# Requires auto-instrumentations-node version 0.46.0+
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os,serviceinstance"
node app.js
More details on setting up the app.js
file can be found on the auto-instrumentation-node documentation.
If your application uses a cloud provider, add it to the list of detectors on the environment variable OTEL_NODE_RESOURCE_DETECTORS
from above:
# Alibaba Cloud
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os,serviceinstance,alibaba"
# Amazon Web Services
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os,serviceinstance,aws"
# Azure
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os,serviceinstance,azure"
# Google Cloud Platform
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os,serviceinstance,gcp"
More details on available resource attributes for each provider can be found on their documentation.
Follow these steps to get necessary information for the shell script:
Sign in to Grafana Cloud, register for a Free Grafana Cloud account if required, the browser will navigate to the Grafana Cloud Portal page https://grafana.com/profile/org.
If the account has access to multiple Grafana Cloud Organizations, select an organization from the top left organization dropdown.
If the organization has access to multiple Grafana Cloud Stacks, navigate to a stack from the left side bar or the main Stacks list.
With a stack selected, or in the single stack scenario, below Manage your Grafana Cloud Stack, click Configure in the OpenTelemetry section:
In the Password / API Token section, click on Generate now to create a new API token:
- Give the API token a name, for example
cart-service
- Click on Create token
- Click on Close without copying the token
- Click on Copy to Clipboard to copy the environment variables to the clipboard
- Give the API token a name, for example
- Pick a Service Name to identify the service, for example
cart
- Replace
app.js
with the path to the application to instrument or usenpm start
if you have thestart
script configured onpackage.json
.
Set up a telemetry data collector
In production environments, a robust and flexible observability setup needs to process telemetry data before ingestion into databases. Follow the collector setup documentation to set up a collector to process and send telemetry data to Application Observability.
Finally, set the following environment variables from the exporter configuration:
Configuration | Options | Result |
---|---|---|
export OTEL_EXPORTER_OTLP_ENDPOINT=<host> | http://localhost:4317 , remote host address | The default local host address, or a remote host address. |
export OTEL_EXPORTER_OTLP_PROTOCOL=<protocol> | grpc , http/protobuf | The default grpc protocol or http/protobuf |
For example, for a local Grafana Alloy:
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
Run the application
Finally, run the application with the shell script and make some requests to the service to send data to Grafana Cloud.
Observe the service in Application Observability
Open Application observability:
- Navigate to a stack
https://<your-stack-name.>grafana.net
- Expand the top left menu below the Grafana logo
- Click on Application
Activate metrics generation
Application Observability relies on metrics generated from traces already sent to Grafana Cloud Traces.
Metrics generation is self-serve, and can be enabled during onboarding and disabled from Application Observability configuration.
To complete the setup, click Activate Application Observability to enable metrics generation.
Note
After activating Application Observability and enabling metrics generation, it might take up to five minutes to generate metrics and show graphs.
Visualize and discover
Discover more about Application Observability in the documentation:
- Service Inventory: filter, and search services and view RED metrics.
- Service Overview: traces, logs, RED metrics, operations, and runtime information.
- Service Map: graph of connected services, service dependencies, and data flow.