fix(metrics): accurate error messages for instrument name and unit validation

[ersalil]

Summary

Use two distinct validation error messages for metrics instrument creation so name and unit failures reflect their different spec constraints.

Changes

• Added _NAME_ERROR_MESSAGE and _UNIT_ERROR_MESSAGE in opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/instrument.py
• Updated instrument validation raises to use the correct message for:
  • invalid instrument names: ASCII name, starts with a letter, allowed chars, max 255 characters
  • invalid units: ASCII-only string, max 63 characters
• Added regression tests in opentelemetry-sdk/tests/metrics/test_instrument_error_message.py

Tests

• test_invalid_name_error_message verifies invalid names mention “start with a letter” and max length 255
• test_invalid_unit_error_message verifies invalid units mention ASCII and max length 63

Notes

• Message-only fix; validation logic and exception type remain unchanged
• Kept exception type as Exception to avoid changing behavior in this small fix; happy to change to ValueError if maintainers prefer

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: ersalil / name: ersalil (ff034b2)

[aabmass]

@ersalil can you please confirm the actual code is doing the validation you expect, and if you're able to link to the spec or spec matrix for this, it would be helpful.

[Copilot]

Pull request overview

This PR updates the SDK metrics instrument construction path to emit distinct, spec-accurate validation error messages for invalid instrument names vs invalid units, and adds regression coverage to prevent message mix-ups in the future.

Changes:

• Introduced dedicated constants for name vs unit validation error messages and used them in synchronous/asynchronous instrument initialization.
• Added regression tests asserting key spec constraints are reflected in the raised exception messages.
• Added a changelog fragment documenting the name error message clarification.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/instrument.py	Split validation error messaging so name/unit failures raise different messages.
opentelemetry-sdk/tests/metrics/test_instrument_error_message.py	New regression tests to assert name/unit validation errors contain correct spec wording.
.changelog/5283.changed	Changelog entry describing the updated name validation error message.

Comments suppressed due to low confidence (1)

.changelog/5283.changed:2

• This changelog fragment has an extra blank line; other fragments in .changelog/*.changed are single-line entries. Please remove the trailing empty line so the fragment is exactly one line.

metrics: clarify instrument name validation error message to reflect spec constraints (start with a letter, allowed chars, max length 255)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ersalil]

@aabmass Thanks for the review! Here's comprehensive validation:

Validation Code

The validation happens in the API layer:
https://github.com/open-telemetry/opentelemetry-python/blob/main/opentelemetry-api/src/opentelemetry/metrics/_internal/instrument.py#L27-L28

_name_regex = re_compile(r"[a-zA-Z][-_./a-zA-Z0-9]{0,254}")
_unit_regex = re_compile(r"[\x00-\x7F]{0,63}")

Spec Reference

OpenTelemetry Metrics API Specification confirms:

Instrument Name: Must start with letter, contain ASCII alphanumerics + _, ., -, /, max 255 chars
Unit: ASCII-only, opaque string, max 63 chars

Test Results

Unit Tests

test_invalid_name_error_message PASSED [ 50%]
test_invalid_unit_error_message PASSED [100%]
============================== 2 passed in 0.08s ===============================

Local verification, name vs unit error-message outputs

Test 1: Invalid name (starts with number)

Error: Instrument name must be an ASCII string, start with a letter, 
contain only letters, digits, '_', '.', '-', '/' and be at most 255 characters; got 1invalid

Test 2: Invalid unit (non-ASCII)

Error: Expected ASCII string of maximum length 63 characters but got Ñ

Test 3: Unit exceeds 63 chars

Error: Expected ASCII string of maximum length 63 characters but got aaa...

All tests passed.

Distinguishes name vs unit validation failures
Reflects actual spec constraints in error messages

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.