Use new OpenTelemetry semantic conventions for database spans

[bgrainger]

https://opentelemetry.io/docs/specs/semconv/database/database-spans/

Changes appear to be:

Removed	Added	Notes
n/a	db.instance.id	The actual DB instance, e.g., if individual nodes in a cluster can be distinguished
net.sock.peer.addr	network.peer.address
net.sock.peer.port	network.peer.port
net.transport	network.transport	Values have changed, e.g., tcp instead of ip_tcp
net.sock.family	network.type	Values have changed, e.g., ipv4 or ipv6 instead of inet or inet6
net.peer.name	server.address	Appears to have some overlap with network.peer.address
net.peer.port	server.port	Some overlap with network.peer.port

An environment variable, OTEL_SEMCONV_STABILITY_OPT_IN "SHOULD" be used to control whether old, new, or both attributes should be emitted.

[Jatkingmodern]

Know telemetry protocols; would like to proceed with this issue, Please assign if you are still interested to affix it

[bgrainger]

@Jatkingmodern If you'd like to work on this issue, please first write up an implementation plan (with details of the span-related changes to be implemented) for review and approval before modifying any code.

[Jatkingmodern]

const stability OptIn = process.env.OTEL_SEMCONV_STABILITY_OPT_IN || 'new';

function setDbSpanAttributes(span: Span, attrs: DbAttrs) {
// Emit legacy (removed) attributes if requested
if (stabilityOptIn === 'old' || stabilityOptIn === 'both') {
span.setAttribute('net.sock.peer.addr', attrs.peerAddr);
span.setAttribute('net.sock.peer.port', attrs.peerPort);
span.setAttribute('net.transport', attrs.transport);
span.setAttribute('net.sock.family', attrs.sockFamily);
span.setAttribute('net.peer.name', attrs.peerName);
span.setAttribute('net.peer.port', attrs.peerPort);
// …add other legacy keys here…
}

// Emit new (added) attributes if requested
if (stabilityOptIn === 'new' || stabilityOptIn === 'both') {
span.setAttribute('network.peer.address', attrs.peerAddr);
span.setAttribute('network.peer.port', attrs.peerPort);
span.setAttribute('network.transport', attrs.transport);
span.setAttribute('network.type', attrs.networkType);
span.setAttribute('server.address', attrs.serverAddress);
span.setAttribute('server.port', attrs.serverPort);
span.setAttribute('db.instance.id', attrs.dbInstanceId);
—add other new keys here…
}
}
Presented above is a rough sketch of code related changes to be performed. Kindly assign this issue.

[bgrainger]

What specification defines the values "old", "new", and "both"?

This plan doesn't look ready for implementation.

[Jatkingmodern]

Implementation Plan: OTEL_SEMCONV_STABILITY_OPT_IN for Database Spans

1. Introduction

This document outlines a proposal to implement the stability opt-in feature for OpenTelemetry semantic conventions changes in database spans. Users will be able to choose between emitting legacy attributes (old), the updated attributes (new), or both (both).

2. Goals

• Enable runtime selection of attribute version via OTEL_SEMCONV_STABILITY_OPT_IN env var.

• Maintain backward compatibility for existing users.

• Provide clear defaults and documentation.

• Cover all affected semantic convention attributes for database spans.

3. Scope & Affected Attributes

Category | Legacy Key | New Key | Notes -- | -- | -- | -- Database instance | n/a | db.instance.id | New attribute for DB instance identifier Peer address | net.sock.peer.addr | network.peer.address |   Peer port | net.sock.peer.port | network.peer.port |   Transport protocol | net.transport | network.transport | Values change: e.g., ip_tcp → tcp Address family | net.sock.family | network.type | Values: inet/inet6 → ipv4/ipv6 Server name | net.peer.name | server.address | Overlaps with network.peer.address Server port | net.peer.port | server.port | Overlaps with network.peer.port

4. Environment Variable

• Name: OTEL_SEMCONV_STABILITY_OPT_IN

• Allowed values: old, new, both

• Default: new

4.1 Specification Origin

No existing spec defines these values; this repository will establish them as part of our stability strategy. A new section in CONTRIBUTING.md will describe semantics.

5. Code Changes

5.1 Configuration Loader

• In core initialization (e.g., src/config/index.ts), read process.env.OTEL_SEMCONV_STABILITY_OPT_IN.

• Normalize to lowercase and fallback to new on invalid or unset.

const stabilityOptIn = (process.env.OTEL_SEMCONV_STABILITY_OPT_IN || 'new').toLowerCase();
if (!['old','new','both'].includes(stabilityOptIn)) {
  logger.warn(...);
  stabilityOptIn = 'new';
}

5.2 Attribute Setter Helper

• Centralize pattern in setDbSpanAttributes(span: Span, attrs: DbAttrs).

• Use branching on stabilityOptIn to emit appropriate keys (see rough sketch).

• Ensure naming matches spec exactly.

6. Backward Compatibility

• Default remains new: users upgrading see only new attributes.

• Users who relied on old keys must opt in with OTEL_SEMCONV_STABILITY_OPT_IN=old.

• both helps transition.

7. Testing Plan

7.1 Unit Tests

• Mock spans and attribute maps.

• Test three modes:

  • old: only legacy keys emitted.

  • new: only new keys.

  • both: both sets.

7.2 Integration Tests

• Generate spans in sample DB client instrumentation.

• Verify exported attributes.

8. Documentation Updates

• README.md: add section on stability opt-in for semantic conventions.

• CONTRIBUTING.md: define OTEL_SEMCONV_STABILITY_OPT_IN values and expected behaviors.

• API docs: update setDbSpanAttributes documentation with new config.

• CHANGELOG.md: note removal of old keys and addition of new keys under opt-in.

9. Examples

# Use legacy attributes only
export OTEL_SEMCONV_STABILITY_OPT_IN=old
# Use new attributes (default)
export OTEL_SEMCONV_STABILITY_OPT_IN=new
# Emit both
export OTEL_SEMCONV_STABILITY_OPT_IN=both

10. Timeline & Milestones

1. Week 1: Finalize plan; merge spec doc updates.

2. Week 2: Implement configuration loader and helper changes; write unit tests.

3. Week 3: Update docs and integration tests; sample applications.

4. Week 4: Review, address feedback, and release.

---

Requesting review and approval.

[bgrainger]

Did ChatGPT write that? It doesn't meet the needs of this project at all. Submitting a bad AI-generated plan is a MySqlConnector Code of Conduct violation. Future violations may result in a ban from this project.

Bad plan notwithstanding, you're welcome to open a PR with the necessary changes for this project. Do note that any contribution needs to be extremely high-quality to be accepted for this project.