[Playground] OTLP-Mapper - instana to otlp span mapper by abhilash-sivan · Pull Request #2534 · instana/nodejs

abhilash-sivan · 2026-05-04T17:37:09Z

Summary

Introduces the Instana-to-OTLP Converter Playground.

Adds support for exporting traces via OTLP (4318/v1/traces).
Supports OpenTelemetry Semantic Conventions (SemConv) v1.23.

Out of Scope

Metrics export
Logs export

TODO

Core Implementation

Span Data Mapping

Testing

Unit Tests

Single-span scenarios
Multi-span scenarios

End-to-End Testing (@abhilash-sivan)

SemConv v1.23 validation with the current design
SemConv v1.41 compatibility validation
OpenTelemetry wrapper instrumentation testing
Metadata validation with SemConv v1.23 and span data validation with v1.43

Performance Testing

Performance testing

Special Cases

Fix type definitions

Issue Tracking

UI Issues: https://ibm.box.com/s/0v5wli0pgvrlg8jqpkhi59mb52o28u75
Results: https://ibm.box.com/s/0v5wli0pgvrlg8jqpkhi59mb52o28u75

Validation Checklist

Before merging, verify the following:

Traces are successfully exported through the OTLP endpoint (4318/v1/traces).
Metrics continue to be exported through the existing endpoint.
The UI correctly identifies and displays applications.

Future Enhancements/TODO

Support the agent announcement cycle disablement use case.
Evaluate exporting logs to the OTLP /v1/logs endpoint.
Implement metrics mapping.
Refactor the current dual transformation flow in span data (internal mapping and OTLP mapping).

References

kirrg001 · 2026-05-12T09:05:34Z

test: send traces via otlp port and metrics via standard port - Idenfies 2 diff apps 1. Otel and 2. Node.js

This needs to be communicated in the next WG. Traces & Metrics mapping is required.

aryamohanan · 2026-06-10T15:25:05Z

@@ -0,0 +1,145 @@
+/*


This is the future design in my mind now

└── otlp/ ├── index.js ← Entry point (exports transform()) ├── converter.js ← Core conversion logic ├── constants.js ← Metric types, aggregation types ├── util.js ← Helper functions ├── transformers/ │ ├── index.js │ ├── resourceAttributes.js ← Service name, SDK info, host, PID │ └── metricData.js ← Metric value transformation └── mappers/ └── metricAttributes.js

Share your thoughts 💭

abhilash-sivan · 2026-06-12T05:55:27Z


-  downstreamConnection.sendMetrics(payload, onMetricsHaveBeenSent.bind(null, isFullTransmission, newValueToTransmit));
+  // Convert to OTLP format if needed (before sending to agentConnection)
+  const isOtlpFormat = process.env.INSTANA_OTLP_FORMAT === 'true';


abhilash-sivan · 2026-06-12T05:58:41Z

+ * @param {number} instanaSpanKind
+ */
+function convertSpanKind(instanaSpanKind) {
+  if (instanaSpanKind === 1) return SPAN_KINDS.SERVER;


In future maybe we need to check if the span is any messaging lib, and map to producer/consumer span kind

Todo: we can extend later, no urgency

aryamohanan · 2026-06-12T07:34:54Z

+  const isOtlpFormat = options.isOtlpFormat;
+
+  if (isOtlpFormat) {
+    sendData('/v1/metrics', data, err => {


It's not still clean approach. I will come up with a better approach later

kirrg001 · 2026-06-12T09:51:17Z

  spans = [];
  batchingBuckets.clear();

+  const payload = prepareSpansForExport(spansToSend);


issue: we still transform twice for OTLP. I can't find the TODO in the list.

Oops 😃, I thought we had agreed to leave the internal mapping refactoring for later.

Its not a refacotring?
Its only:

internal format -> spanBuffer -> isOTLP ? transform internal to otlp : transform internal to be/instana

kirrg001 · 2026-06-12T09:53:22Z

+ * @returns {any}
+ */
+function prepareSpansForExport(spansToSend) {
+  if (process.env.INSTANA_OTLP_FORMAT === 'true') {


Lets add a TODO to read the configs in the config area.
I only found a verify task

The configuration option to enable the OTLP format, INSTANA_OTLP_ENABLED or?

It was the config support task after all. I'll tidy up the task list and remove any confusion there.

kirrg001 · 2026-06-12T10:06:30Z

@@ -0,0 +1,170 @@
+# OTLP (OpenTelemetry Protocol) Converter


qs: Why is the OTLP module not part of the tracing folder?

This module handles all telemetry signals- Traces, Metrics, and Logs. Placing it under the tracing folder would unnecessarily couple it to tracing-specific concepts such as spans. Keeping it at the root allows the logic to remain shared and signal-agnostic. It also provides flexibility for future enhancements, such as extending the OTLP implementation to emit additional telemetry signals like logs.

IMO it belongs to core/tracing/exporters

We can discuss this before merging. No big topic

kirrg001 · 2026-06-13T05:59:19Z

+      };
+
+      const originFrom = rawSpan.data?.resource || null;
+      const rKey = resourceFactory.getResourceKey(originFrom);


const originFrom = rawSpan.data?.resource || null; const rKey = resourceFactory.getResourceKey(originFrom);

This looks wrong to me? 🤔

This must be rawSpan.f?

Any instana span has .f - doesn't matter if its coming from ours instrumentations or from otel integration.

kirrg001 · 2026-06-13T06:13:08Z

+
+      let group = resourceGroupMap.get(rKey);
+
+      if (!group) {


I can't follow this whole logic 🤔
Why do we need to group the spans by resource?
What is the actual case? The spans are generated on the same process.

kirrg001 · 2026-06-13T06:17:42Z

+  const resourceGroupMap = new Map();
+
+  spans.forEach(rawSpan => {
+    if (isLogSpan(rawSpan)) {


Suggested change

if (isLogSpan(rawSpan)) {

// TODO: Add log span converter

if (isLogSpan(rawSpan)) {

kirrg001 · 2026-06-13T07:09:43Z

+
+// 1.23 matches baseline parameters identically. No overrides required.
+
+const LOOKUP_OVERRIDES = {};


// base loopup based on v1.23 with some common mappings as well

Okay I understood the current sem conv structure. So yeah the base mappings are secretly from v1.23.

I'd like to suggest this:

index.js

const VERSIONS = { '1.23': require('./v1.23'), // explicit version '1.42': require('./v1.42') // explicit version };

Three folders

base/

mappings.js

v1.23/

index.js

mappings.js

v1.43/

index.js

mappings.js

merge.js

base/mappings.js

module.exports = require('../v1.23/mappings');

v1.23/mappings.js

const MAPPINGS = { metadata: { TRACE_ID: 'traceId', ...

v1.23/index.js

const { merge } = require('../merge'); const base = require('../base/mappings').MAPPINGS; const { MAPPINGS } = require('./mappings'); module.exports = merge(base, MAPPINGS);

v1.41/index.js

const { merge } = require('../merge'); const base = require('../base/mappings').MAPPINGS; const { MAPPINGS } = require('./mappings'); module.exports = merge(base, MAPPINGS);

v1.41/mappings.js

const MAPPINGS = { http: { REQUEST_METHOD: 'http.request.method', RESPONSE_STATUS: 'http.response.status_code', ...

The concept of overrides === merge.

kirrg001 added 2 commits April 9, 2026 12:21

chore: playground done

7a5da5a

chore: infra cor

a046abc

abhilash-sivan force-pushed the chore-otel-span-mapper branch from 4490ab0 to f1c0d6f Compare May 4, 2026 18:07

abhilash-sivan changed the base branch from main to chore-otlp-playground May 7, 2026 06:42

abhilash-sivan added 3 commits May 7, 2026 18:08

chore: phase 1

378f117

chore: phase 2

c1ef77d

chore: phase 3

d261bc5

abhilash-sivan force-pushed the chore-otel-span-mapper branch from 53e1fcc to d261bc5 Compare May 7, 2026 12:45

abhilash-sivan added 5 commits May 7, 2026 18:20

chore: cleanup

17710d0

chore: rewrite

0a6ec17

chore: test

8a89eef

chore: a

c78331c

chore: new fields

bcb034e

abhilash-sivan commented May 7, 2026

View reviewed changes

chore: test

980a1c0

abhilash-sivan changed the title ~~Chore otel span mapper~~ chore: instana-otlp span mapper May 7, 2026

abhilash-sivan changed the title ~~chore: instana-otlp span mapper~~ [Playground] OTLP-Mapper - instana to otlp span mapper May 8, 2026

abhilash-sivan added 2 commits May 10, 2026 17:17

test: fixed failing test

5aebc15

chore: cleanup

8c6cc88

kirrg001 reviewed May 11, 2026

View reviewed changes

Comment thread packages/collector/src/agentConnection.js Outdated

kirrg001 reviewed May 11, 2026

View reviewed changes

Comment thread packages/core/src/tracing/backend_mappers/index.js Outdated

kirrg001 reviewed May 12, 2026

View reviewed changes

Comment thread packages/core/src/tracing/otlp_mapper/mapper.js Outdated

abhilash-sivan added 4 commits May 13, 2026 15:39

chore: ui corrected

c3179eb

chore: added kafka and pg, generalize

21c211d

chore: update

fcd7622

chore: fix

c1253b0

abhilash-sivan force-pushed the chore-otel-span-mapper branch from 08a2757 to e827e9c Compare May 15, 2026 05:57

chore: clean

d6c01a6

abhilash-sivan force-pushed the chore-otel-span-mapper branch from e827e9c to d6c01a6 Compare May 15, 2026 05:58

aryamohanan added 2 commits June 10, 2026 20:12

chore: added some cleanup

7173c4d

chore: metrics

0a4399d

aryamohanan reviewed Jun 10, 2026

View reviewed changes

abhilash-sivan and others added 12 commits June 11, 2026 14:42

chore: fixed timestap and duration

d493a59

chore: restructure

38f046e

chore: deleted unwanted files

ec0522f

chore: more cleanup

81677c4

test: updated

5058d0b

chore: moved examples

085d486

chore: fine tuning

0a5ede8

chore: metrics

609d88b

chore: agentconnection

0d51bee

chore: agentconnection

7e56007

chore: metrics handled

8474cfe

chore: trcaes handled

f8a9eb1

abhilash-sivan commented Jun 12, 2026

View reviewed changes

aryamohanan reviewed Jun 12, 2026

View reviewed changes

kirrg001 reviewed Jun 12, 2026

View reviewed changes

Comment thread packages/core/src/otlp/index.js Outdated

kirrg001 reviewed Jun 12, 2026

View reviewed changes

Comment thread packages/core/src/otlp/metrics/index.js Outdated

aryamohanan added 4 commits June 12, 2026 18:00

chore: review comments

79fbc96

chore: resource

adadaed

chore: updated

4670a74

chore: updated

85aa6ed

kirrg001 reviewed Jun 13, 2026

View reviewed changes

	if (isLogSpan(rawSpan)) {
	// TODO: Add log span converter
	if (isLogSpan(rawSpan)) {


		// 1.23 matches baseline parameters identically. No overrides required.

		const LOOKUP_OVERRIDES = {};

Conversation

abhilash-sivan commented May 4, 2026 • edited by aryamohanan Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Out of Scope

TODO

Core Implementation

Span Data Mapping

Testing

Unit Tests

End-to-End Testing (@abhilash-sivan)

Performance Testing

Special Cases

Issue Tracking

Validation Checklist

Future Enhancements/TODO

References

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kirrg001 commented May 12, 2026

Uh oh!

aryamohanan Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

abhilash-sivan commented May 4, 2026 •

edited by aryamohanan

Loading

aryamohanan Jun 10, 2026 •

edited

Loading