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 Splunk Observability Cloud.

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

   1. In the navigation menu, select Data Management.

   2. Go to the Available integrations tab, or select Add Integration in the Deployed integrations tab.

   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 the Splunk Distribution of OpenTelemetry JS manually

If you don’t use the guided setup, follow these instructions to manually install the Splunk Distribution of OpenTelemetry JS:

• Install and activate the Node.js instrumentation

  • Activate AlwaysOn Profiling

  • Activate metrics collection

• Configure the Node.js distribution

• Instrument your application programmatically

Install and activate 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:

   Linux

   export OTEL_SERVICE_NAME=<yourServiceName>

   Windows PowerShell

   $env:OTEL_SERVICE_NAME=<yourServiceName>

3. (Optional) Set the endpoint URL if the Splunk Distribution of OpenTelemetry Collector is running on a different host:

   Linux

   export OTEL_EXPORTER_OTLP_ENDPOINT=<yourCollectorEndpoint>:<yourCollectorPort>

   Windows PowerShell

   $env:OTEL_EXPORTER_OTLP_ENDPOINT=<yourCollectorEndpoint>:<yourCollectorPort>

4. (Optional) Set the deployment environment and service version:

   Linux

   export OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'

   Windows PowerShell

   $env:OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'

5. (Optional) Activate metric collection. See Activate metrics collection.

6. To run your Node.js application, enter the following command:

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

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

Activate AlwaysOn Profiling

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

To activate memory profiling, set the SPLUNK_PROFILER_MEMORY_ENABLED environment variable to true after activating AlwaysOn Profiling.

The following example shows how to activate the profiler from your application code:

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

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

Activate metrics collection

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

Linux

export SPLUNK_METRICS_ENABLED='true'

Windows PowerShell

$env:SPLUNK_METRICS_ENABLED='true'

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.

Instrument your application programmatically

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

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

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 activate 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 start() 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(),
      ],
   },
});

For a list of supported instrumentations, see https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/metapackages/auto-instrumentations-node#supported-instrumentations on GitHub.

Deploy the Node.js distribution in Kubernetes

To deploy the Collector for Node.js in a Kubernetes environment, follow these steps:

1. Edit the Dockerfile for your application image to add the following commands:

   # Install the @splunk/otel package
   RUN npm install @splunk/otel
   # Set appropriate permissions
   RUN chmod -R go+r /node_modules/@splunk/otel

2. 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
           image: your-app-image
           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>"
           command:
            - node
            - -r @splunk/otel/instrument
            - <your-app>.js

Send data directly to Splunk 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 Splunk Observability Cloud, set the following environment variables:

Linux

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

Windows PowerShell

$env:SPLUNK_ACCESS_TOKEN=<access_token>
$env:SPLUNK_REALM=<realm>

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

To find your Splunk realm, see Note about realms.

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

Specify the source host

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.