Skip to content

Semantic Conventions: Naming, Requirement Levels and Stability: OTCA practice questions

Semantic conventions are the shared vocabulary of OpenTelemetry. They define standard names for attributes, span names and kinds, metric instruments and units, and valid values for common operations such as HTTP calls, database queries and messaging. Conventions exist for traces, metrics, logs, profiles and resources.

By Ibrahim Yesilay · Published · Updated

Independent community practice, not affiliated with or endorsed by CNCF or The Linux Foundation.

What Semantic Conventions: Naming, Requirement Levels and Stability covers in OTCA

Semantic conventions are the shared vocabulary of OpenTelemetry. They define standard names for attributes, span names and kinds, metric instruments and units, and valid values for common operations such as HTTP calls, database queries and messaging. Conventions exist for traces, metrics, logs, profiles and resources. When every library and platform uses the same names, a backend can build one dashboard for every HTTP server, whatever language or framework produced the data.

The naming rules are worth knowing in detail. Names should be lowercase and use dot-delimited namespaces, for example service.version, where service is the namespace. Words inside one component are joined with underscores, so the HTTP status code is http.response.status_code. Underscores are used only when a dot would change the meaning. Names that start with otel. are reserved for the OpenTelemetry specification. If you need your own attribute and nothing fits, prefix it with your company's reverse domain name, such as com.acme.shopname, or with a reasonably unique application name. Do not reuse an existing convention namespace, because a future convention could claim the same name.

Metric names follow extra guidance. A duration histogram is named after the operation and measured in seconds, as in http.server.request.duration with unit s. Units belong in instrument metadata, not in the name. Counters and UpDownCounters should not append _total, and UpDownCounter names are not pluralized, so system.process.count is preferred over system.processes.

Resource conventions describe the entity that produces telemetry. The most important one is service.name. If it is not set, the SDK must fall back to unknown_service: followed by the process executable name. The SDK also fills in the telemetry.sdk.name, telemetry.sdk.language and telemetry.sdk.version attributes. Keep values that stay constant for the life of a process on the resource and per-operation details on spans, metrics and logs.

Each attribute in a convention has a requirement level. Required attributes are always populated; http.request.method is the standard example. Conditionally Required attributes must be set when a stated condition holds, such as http.route when the framework knows the route. Recommended attributes are included by default but can be turned off, and Opt-In attributes appear only when enabled. Metric attributes that might have high cardinality may only be Opt-In.

Stability matters because dashboards and alerts depend on these names. Conventions are marked Stable, Development or Mixed, and the HTTP span conventions, for example, are Stable. Stability guarantees cover attribute keys, span names and kinds, metric names, kinds and units, and event names. Things like attribute values outside well-known lists, span links and metric descriptions may change. Renames must be described in telemetry schema files, and the service.* resource attributes must never change.

Key points

  • Names are lowercase, dot-namespaced and snake_case within a component, as in http.response.status_code.
  • The otel.* namespace is reserved for the specification; custom names should use a reverse-domain or application prefix.
  • If service.name is not configured, SDKs fall back to unknown_service: plus the executable name.
  • Requirement levels are Required, Conditionally Required, Recommended and Opt-In; high-cardinality metric attributes must be Opt-In.
  • Stability covers attribute keys, span names and kinds, and metric names, kinds and units, but not metric descriptions.

Three sample questions

14 OTCA questions on Semantic Conventions: Naming, Requirement Levels and Stability, 14 with explanations. How practice works

Question 1

Which of the following best describes how OpenTelemetry ensures uniform enrichment of logs, traces, and metrics?
  1. A.By defining common attribute names and values used across all signals.
  2. B.By enforcing that only logs are enriched with additional attributes.
  3. C.By requiring applications to manually add the same attributes to logs, traces, and metrics.
  4. D.By using separate enrichment processes for each telemetry signal.

Correct answer: A

The Semantic Conventions concepts page says OpenTelemetry defines semantic conventions that "specify common names for different kinds of operations and data", and that they are available for traces, metrics, logs, profiles and resources. Shared names across signals give uniform enrichment. Why the other options are wrong. "By enforcing that only logs are enriched with addi…": semantic conventions cover every signal, not only logs. "By requiring applications to manually add the same…": the point of the conventions is a common naming scheme, not manual duplication; SDKs and instrumentation libraries apply them. "By using separate enrichment processes for each te…": separate processes per signal is the fragmentation the conventions are designed to avoid.

Sources: OpenTelemetry docs: Semantic Conventions, OpenTelemetry spec: Logs

Question 2

You are configuring OpenTelemetry to transmit logs via a network protocol and want to include the full path to the log file. Which attribute should you add to your Log Record?
  1. A.log.file.path
  2. B.log.record.uid
  3. C.log.file.name_resolved
  4. D.log.file.name

Correct answer: A

The log attributes registry defines log.file.path as "The full path to the file", with the example /var/log/mysql/audit.log. The general logs conventions list it as an Opt-In attribute for the file a log was emitted to. Why the other options are wrong. "log.record.uid": log.record.uid is a unique identifier for the log record, used to detect duplicates. "log.file.name_resolved": log.file.name_resolved is the basename of the file with symlinks resolved, not the full path. "log.file.name": log.file.name is only the basename of the file, such as audit.log.

Sources: OpenTelemetry semantic conventions: Log attributes registry, OpenTelemetry semantic conventions: General logs attributes

Question 3

Which attribute name follows the general OpenTelemetry semantic conventions naming rules?
  1. A.http.response.status_code
  2. B.http.response.statusCode
  3. C.HttpResponseStatusCode
  4. D.http.responseStatusCode

Correct answer: A

The Naming page says names SHOULD be lowercase, should use namespacing delimited by a dot, and "for each multi-word dot-delimited component of the name separate the words by underscores (i.e. use snake_case)", giving http.response.status_code as the example. The semantic conventions tooling limits names to lowercase Latin letters, digits, underscore and dot. Why the other options are wrong. "http.response.statusCode": camelCase in the last component violates both the lowercase rule and the rule to separate words of a multi-word component with underscores. "HttpResponseStatusCode": this uses upper case and no dot-delimited namespaces at all, against the lowercase and namespacing rules. "http.responseStatusCode": this collapses the response namespace into a camelCase component; names should be lowercase, dot-namespaced and snake_case within components.

Sources: OpenTelemetry semantic conventions: Naming, OpenTelemetry semantic conventions: HTTP spans

Practice this topic

Focus mode keeps every question on Semantic Conventions: Naming, Requirement Levels and Stability until you leave it. 10 free guest answers, then a free account; no credit card.

Or open OTCA practice across all topics.

Sources

The explanation above was checked against these official documents.

Frequently asked questions

Should I put the unit in a metric name, like request.duration_ms?

No. The metric guidelines say units recorded in instrument metadata should not be repeated in the name, and durations should use seconds (s).

Can I create attributes under the http namespace for my own app?

It is not recommended. Prefix company-specific names with a reverse domain name such as com.acme to avoid clashing with future conventions.