Review or Create OpenTelemetry Metric Names
Review or create metric names that follow OTel Semantic Conventions, ensuring correct naming format, instrument selection, unit placement, and attribute separation.
Before applying any rule below, fetch the latest naming guidance to check for updates:
- https://opentelemetry.io/docs/specs/semconv/general/naming/
- https://opentelemetry.io/docs/specs/semconv/general/metrics/
- https://opentelemetry.io/blog/2025/how-to-name-your-metrics/
If the fetched content contradicts any rule in this skill, follow the fetched content and flag the discrepancy.
Core Principle
The metric name identifies what you are measuring. Everything else — who is measuring, where it runs, which version — belongs in attributes or resource attributes.
Metric Name Patterns
The OTel spec defines these patterns for metric names:
Default Pattern: {area}.{metric_name}
Use when the area or metric name already implies the communication side.
Examples: system.memory.usage, kestrel.connection.duration, messaging.process.duration
Client/Server Pattern: {area}.{client|server}.{metric_name}
Use when the communication side is ambiguous for a given {area} and {metric_name}.
- Include
clientorserverwhen both perspectives exist (e.g.,http.server.*vshttp.client.*) - Omit when the system name implies the side (e.g.,
kestrelis always a server) - Omit when the metric name implies the side (e.g.,
messaging.processis always consumer)
Examples: http.server.request.duration, db.client.operation.duration
System-Specific Pattern: {system_name}.*.{metric_name}
Use when a metric is specific to a system, project, or provider.
Examples: azure.cosmosdb.client.operation.request_charge, jvm.gc.duration
How Segments Work
Metric names use dot-delimited namespaces where each dot adds specificity. Namespaces can be nested — there is no fixed number of segments. Real metrics range from 2 segments (system.uptime) to 6 segments (azure.cosmosdb.client.operation.request_charge).
Follow the {object}.{property} principle: be precise. Use system.network.packet.dropped instead of system.network.dropped.
Name vs Attributes
If a dimension changes what is being measured → put it in the metric name. If it changes who/where/when → put it in attributes.
| Dimension | Goes in... | Why |
|---|---|---|
Protocol domain (http, db) | Name | Changes what you're measuring |
Communication side (client, server) | Name (when ambiguous) | Changes the perspective |
Entity and property (request.duration) | Name | Changes what is captured |
| Service name | Resource attribute | Same metric across services |
| Environment | Resource attribute | Same metric across envs |
| Version | Resource attribute | Same metric across versions |
| HTTP method, route | Metric attribute | Filters within the same metric |
| Technology stack | Nowhere in name | Won't survive language migrations |
Unit (ms, bytes) | Unit metadata field | UCUM standard, not in name |
Naming Format
- Lowercase with dot-delimited namespaces
- snake_case within segments:
http.response.status_code - Must start with a letter, end with alphanumeric
- No consecutive delimiters (
..,__,._) - Printable Basic Latin only (U+0021–U+007E)
Measurement Suffixes
| Suffix | Meaning | Example |
|---|---|---|
entity.limit | Known total amount | system.memory.limit |
entity.usage | Amount used from known total | system.memory.usage |
entity.utilization | Fraction of usage/limit (0–1) | system.memory.utilization |
entity.time | Passage of time | system.cpu.time |
entity.io | Bidirectional data flow | system.network.io |
Pluralization Rules
- Pluralize Counters for discrete countable instances:
system.paging.faults,system.disk.operations - Do NOT pluralize utilization, duration, time:
system.filesystem.utilization - UpDownCounter names SHOULD NOT be pluralized:
system.process.countnotsystem.processes - Never append
_total— confuses meaning in delta backends
Unit Conventions (UCUM)
- Units go in metadata, NOT in metric names
- Use non-prefixed units:
BynotMiBy - Durations: use seconds (
s) - Utilization: dimensionless, unit
1 - Curly brace annotations match grammatical number:
{request}not{requests} - Case-sensitive:
Celfor degree Celsius
Attribute Naming
- Pattern:
{object}.{property}with dot separators - Lowercase, snake_case within segments
- Namespace related attributes together:
order.id,order.total,order.status - Keep names stable; let values carry dynamic data
- Do NOT put user IDs, request IDs, or IP addresses as metric attributes — cardinality explosion
Reference Material
Detailed guidance on specific topics is in the references/ directory. Read these when the task requires deeper context:
- namespaces.md — Full catalog of official namespace roots, worked examples showing which pattern each metric uses, custom namespace guidelines
- instruments.md — Instrument selection decision tree, additivity rules, sync vs async, UpDownCounter consistency
- anti-patterns.md — Bad→good naming examples, attribute anti-patterns, cardinality traps
Review Checklist
When reviewing metric definitions, verify:
- Name uses dot-delimited lowercase snake_case
- No unit, service name, environment, or version in the metric name
- Correct instrument type for the measurement
- Unit in metadata field, following UCUM
- Pluralization matches the instrument type
- No
_totalsuffix - Custom names don't collide with
otel.*or existing semantic convention namespaces - Attributes follow
{object}.{property}format - No high-cardinality values in metric attributes
- UpDownCounter increments/decrements use matching attribute values
Output
Provide:
- List of metrics reviewed with pass/fail per checklist item
- Suggested corrections for any violations
- Instrument type recommendation if missing or incorrect
- Attribute placement corrections (name → resource → metric attribute)