Docs » Instrument back-end applications to send spans to Splunk APM » Instrument Node.js applications for Splunk Observability Cloud » Instrument a Node application for Splunk Observability Cloud

Instrument a Node application for Splunk Observability Cloud πŸ”—

The Splunk Distribution of OpenTelemetry JS can automatically instrument your Node application and many of the popular node.js libraries your application uses.

To get started, use the guided setup or follow the instructions manually.

Generate customized instructions using the guided setup πŸ”—

To generate all the basic installation commands for your environment and application, use the Node.js guided setup. To access the Node.js guided setup, follow these steps:

  1. Log in to Observability Cloud.

  2. Open the Node.js guided setup. Optionally, you can navigate to the guided setup on your own:

    1. In the left navigation menu, select Data Management.

    2. Select Add Integration to open the Integrate Your Data page.

    3. In the integration filter menu, select By Product.

    4. Select the APM product.

    5. Select the Node.js tile to open the Node.js guided setup.

Install and enable the Node.js instrumentation πŸ”—

To instrument your Node.js application with the Splunk Distribution of OpenTelemetry JS, follow these steps:

  1. Install the @splunk/otel package:

    npm install @splunk/otel
    

    To add custom instrumentations, see Add custom instrumentation.

  2. Set the OTEL_SERVICE_NAME environment variable:

    export OTEL_SERVICE_NAME=<yourServiceName>
    
  3. (Optional) Set the endpoint URL if the Splunk Distribution of OpenTelemetry Collector is running on a different host:

    export OTEL_EXPORTER_OTLP_ENDPOINT=<yourCollectorEndpoint>:<yourCollectorPort>
    
  4. (Optional) Set the deployment environment and service version:

    export OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'
    
  5. To run your Node application, enter the following command:

    node -r @splunk/otel/instrument <your-app.js>
    

If no data appears in Observability > APM, see Troubleshoot Node.js instrumentation for Splunk Observability Cloud.

Note

To instrument applications that use Webpack, see Webpack compatibility issues.

Enable AlwaysOn Profiling πŸ”—

Caution

Memory profiling for Node.js is an experimental feature subject to future changes. See Introduction to AlwaysOn Profiling for Splunk APM.

To enable AlwaysOn Profiling, set the SPLUNK_PROFILER_ENABLED environment variable to true.

To enable memory profiling, set the SPLUNK_PROFILER_MEMORY_ENABLED environment variable to true after enabling AlwaysOn Profiling.

The following example shows how to enable the profiler from your application’s code:

start({
   serviceName: '<service-name>',
   endpoint: 'collectorhost:port',
   profiling: {                       // Enables CPU profiling
      memoryProfilingEnabled: true,   // Enables Memory profiling
   }
});

See Get AlwaysOn Profiling data into Splunk APM for more information. For more settings, see Node.js settings for AlwaysOn Profiling.

Enable metrics collection πŸ”—

To enable automatic runtime metric collection, enable the metrics feature using the SPLUNK_METRICS_ENABLED environment variable. See Metrics configuration for more information.

export SPLUNK_METRICS_ENABLED='true'

Instrument your application programmatically πŸ”—

To have even finer control over the tracing pipeline, instrument your Node application programmatically.

To instrument your application programmatically, add the following lines at the beginning of your entry point script, before any instrumentation function is called:

const { start } = require('@splunk/otel');

start({
   serviceName: 'my-node-service',
   endpoint: 'http://localhost:4317'
});

// Rest of your main module

The start() function accepts configuration settings as arguments. For example, you can use it to enable runtime metrics and memory profiling:

start({
   serviceName: 'my-node-service',
   metrics: { runtimeMetricsEnabled: true },
   profiling: { memoryProfilingEnabled: true }
});

After you add the start() function to your entry point script, run your application by passing the instrumented entry point script using the -r flag:

node -r <entry-point.js> <your-app.js>

Add custom instrumentation πŸ”—

To add custom or third-party instrumentations that implement the OpenTelemetry JS Instrumentation interface, pass them to startTracing() using the following code:

const { start } = require('@splunk/otel');
const { getInstrumentations } = require('@splunk/otel/lib/instrumentations');

start({
   tracing: {
      instrumentations: [
         ...getInstrumentations(), // Adds default instrumentations
         new MyCustomInstrumentation(),
         new AnotherInstrumentation(),
      ],
   },
});

Note

For an example of entry point script, see the sample tracer.js file on GitHub.

Deploy the Node.js distribution in Kubernetes πŸ”—

To deploy the Splunk Distribution of OpenTelemetry JS in Kubernetes, configure the Kubernetes Downward API to expose environment variables to Kubernetes resources.

The following example shows how to update a deployment to expose environment variables by adding the OpenTelemetry configuration under the .spec.template.spec.containers.env section:

apiVersion: apps/v1
kind: Deployment
spec:
  selector:
    matchLabels:
      app: your-application
  template:
    spec:
      containers:
        - name: myapp
          env:
            - name: SPLUNK_OTEL_AGENT
              valueFrom:
                fieldRef:
                  fieldPath: status.hostIP
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "http://$(SPLUNK_OTEL_AGENT):4317"
            - name: OTEL_SERVICE_NAME
              value: "<serviceName>"
            - name: OTEL_RESOURCE_ATTRIBUTES
              value: "deployment.environment=<environmentName>"

Configure the Node.js distribution πŸ”—

In most cases, the only configuration setting you need to enter is the service name. For advanced configuration, like changing trace propagation formats or configuring server trace data, see Configure the Splunk Distribution of OTel JS for Splunk Observability Cloud.

Send data directly to Observability Cloud πŸ”—

By default, all telemetry is sent to the local instance of the Splunk Distribution of OpenTelemetry Collector.

If you need to send data directly to Observability Cloud, set the following environment variables:

export SPLUNK_ACCESS_TOKEN=<access_token>
export SPLUNK_REALM=<realm>

To obtain an access token, see Retrieve and manage user API access tokens using Splunk Observability Cloud.

In the ingest endpoint URL, realm is the Observability Cloud realm, for example, us0. To find the realm name of your account, follow these steps:

  1. Open the left navigation menu in Observability Cloud.

  2. Select Settings.

  3. Select your username.

The realm name appears in the Organizations section.

For more information on the ingest API endpoints, see Send APM traces.

Caution

This procedure applies to spans and traces. To send AlwaysOn Profiling data, you must use the OTel Collector.

Instrument Lambda functions πŸ”—

You can instrument AWS Lambda functions using the Splunk OpenTelemetry Lambda Layer. See Instrument your AWS Lambda function for Splunk Observability Cloud for more information.