Splunk OpenTelemetry JS 4.0 breaking changes

Update to Splunk OpenTelemetry JS version 4.0

To update your Splunk Distribution for OpenTelemetry JS agent to version 4.0, see Instrument your Node.js application for Splunk Observability Cloud and install the latest version of the Splunk OpenTelemetry JS agent.

Node.js version requirements

Splunk OTel JS 4.0 introduces updated requirements for supported Node.js versions.

To ensure compatibility:

• For Node.js 18, the minimum supported version is 18.19.0.

• For Node.js 20 and above, the minimum required version is 20.6.0.

Resource initialization change

In version 4.0 of the Splunk Distribution of OpenTelemetry JS, manual resource creation using new Resource({}) is no longer supported.

To define custom resource attributes, use the resourceFromAttributes() helper from @opentelemetry/resources and merge it with the detected resource:

import { start } from '@splunk/otel';
import { resourceFromAttributes } from '@opentelemetry/resources';

start({
  resource: (detectedResource) => {
    return detectedResource.merge(resourceFromAttributes({
      'my.attribute': 'foo',
    }));
  },
});

Span parent reference update

In Splunk OTel JS 4.0, the Span object no longer exposes the parentSpanId field directly.

To access the parent span ID, use span.parentSpanContext.spanId instead:

import { start } from '@splunk/otel';
import { Context } from '@opentelemetry/api';
import { ReadableSpan, Span } from '@opentelemetry/sdk-trace-base';
import { SpanProcessor } from '@opentelemetry/sdk-trace-base';

class MySpanProcessor implements SpanProcessor {
  onStart(span: Span, _parentContext: Context): void {
    console.log(span.parentSpanContext?.spanId);
  }

  onEnd(span: ReadableSpan): void {
    console.log(span.parentSpanContext?.spanId);
  }

  forceFlush(): Promise<void> {
    return Promise.resolve();
  }

  shutdown(): Promise<void> {
    return Promise.resolve();
  }
}

start({
  tracing: {
    spanProcessorFactory: (_opts) => [new MySpanProcessor()],
  },
});

Metrics view configuration update

In Splunk OTel JS 4.0, custom metric views are now defined using plain objects that conform to the ViewOptions interface. Creating views with new View({...}) is no longer supported.

To configure custom views, pass them directly as array elements in the metrics.views field:

import { start } from '@splunk/otel';

start({
  metrics: { views: [{ name: 'clicks', instrumentName: 'my-counter', }], },
})

TypeORM instrumentation update

In Splunk OTel JS 4.0, TypeORM instrumentation has migrated to the upstream OpenTelemetry JS repository.

The new instrumentation replaces legacy attributes with standardized OpenTelemetry span fields:

Redis instrumentation module update

The package @opentelemetry/instrumentation-redis-4 has been removed in Splunk OTel JS 4.0. Its functionality has been merged into the upstream @opentelemetry/instrumentation-redis module.

Troubleshooting

For information about troubleshooting issues with the Splunk OpenTelemetry JS agent, see Troubleshoot Node.js instrumentation for Splunk Observability Cloud.