Otel Name Metric

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 client or server when both perspectives exist (e.g., http.server.* vs http.client.*)
• Omit when the system name implies the side (e.g., kestrel is always a server)
• Omit when the metric name implies the side (e.g., messaging.process is 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.

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

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.count not system.processes
• Never append `_total` — confuses meaning in delta backends

Unit Conventions (UCUM)

• Units go in metadata, NOT in metric names
• Use non-prefixed units: By not MiBy
• Durations: use seconds (s)
• Utilization: dimensionless, unit 1
• Curly brace annotations match grammatical number: {request} not {requests}
• Case-sensitive: Cel for 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:

1. Name uses dot-delimited lowercase snake_case 2. No unit, service name, environment, or version in the metric name 3. Correct instrument type for the measurement 4. Unit in metadata field, following UCUM 5. Pluralization matches the instrument type 6. No _total suffix 7. Custom names don't collide with otel.* or existing semantic convention namespaces 8. Attributes follow {object}.{property} format 9. No high-cardinality values in metric attributes 10. 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)

Metric Naming Anti-Patterns

Spec sources:

- https://opentelemetry.io/docs/specs/semconv/general/naming/

- https://opentelemetry.io/blog/2025/how-to-name-your-metrics/

Bad Metric Names

Attribute Anti-Patterns

Cardinality Traps

High-cardinality metric attributes explode time series and cost. Never use as metric attributes:

• User IDs
• Request IDs
• IP addresses
• Full URL paths
• Session tokens
• Trace/span IDs

These belong in span attributes or log fields, not metric dimensions.

Cross-Cutting Mistakes

1. Units in metric names — use unit metadata field 2. Service/team names in metric names — use service.name resource attribute 3. Environment/version in names — use resource attributes 4. Appending `_total` to counters — confuses delta backends 5. Technology stack in names (nodejs_payment_memory) — won't survive language migrations 6. *Using `otel.` namespace for custom names — reserved, risks future conflicts 7. UpDownCounter attribute mismatch** — different attributes on increment vs decrement creates separate time series

Instrument Selection

Spec sources:

- https://opentelemetry.io/docs/specs/semconv/general/metrics/

- https://opentelemetry.io/docs/specs/otel/metrics/supplementary-guidelines/

Decision Tree

1. Counting something (delta values)?

• Monotonically increasing → Counter (total bytes received, requests completed)
• Can increase or decrease → UpDownCounter (active connections, queue depth)

2. Need distributions/percentiles? → Histogram (request latency, response sizes) 3. Absolute point-in-time value?

• Non-additive (summing meaningless) → Gauge (temperature, CPU %)
• Additive + monotonic → Asynchronous Counter (page faults since boot)
• Additive + non-monotonic → Asynchronous UpDownCounter

Additivity

Synchronous vs Asynchronous

• Synchronous: recorded when events occur (event-driven, lower latency)
• Asynchronous: pulled/observed at collection time (reduces unnecessary polling, e.g., reading a sensor only at scrape time)
• Spec uses synchronous names but implementations MAY use async equivalents

UpDownCounter Consistency

The same attribute values used to record an increment MUST be used for the associated decrement. Mismatched attributes create separate time series.

If an attribute is not available at increment time, do not add it at decrement time.

OTel Metric Namespace Reference

Spec source: https://opentelemetry.io/docs/specs/semconv/general/naming/

Worked Examples

Root Namespace Catalog

Protocol Namespaces

Database Namespaces

Infrastructure Namespaces

Runtime Namespaces

Cloud Namespaces

Application Namespaces

System-Specific Namespaces

Some systems define their own root namespace when they don't fit into the generic categories above:

Sub-namespace Patterns

Communication Side: {client|server}

Used to disambiguate perspective when both sides exist:

http.server.request.duration    ← measured at the server receiving requests
http.client.request.duration    ← measured at the client sending requests
db.client.operation.duration    ← always client-side (no db.server in OTel)

When to omit: if the root namespace or metric name already implies the side:

• kestrel.* — always server-side
• messaging.process.* — always consumer-side
• jvm.* — always local runtime

Runtime Context: {runtime}

Used within process-level metrics:

process.runtime.jvm.memory.usage
process.runtime.dotnet.gc.collections

Custom Namespace Guidelines

Company-Specific

Use reverse domain notation to avoid collisions:

com.acme.checkout.cart.items          ← company metric
com.acme.payment.transaction.count   ← company metric

Application-Specific

Use a unique application name as root:

myapp.queue.depth
myapp.cache.hit_ratio
myapp.job.processing.duration

When to Propose a New OTel Namespace

If your metric could apply across the industry (not just your company), consider proposing it to the OTel specification. Examples of metrics that became standard:

• gen_ai.* — started as custom, became official for LLM observability
• cicd.* — CI/CD pipeline metrics