K8s semantic conventions stability migration
Due to the significant number of modifications and the extensive user base affected by them, existing K8s instrumentations published by OpenTelemetry are required to implement a migration plan that will assist users in transitioning to the stable K8s semantic conventions.
When existing K8s instrumentations published by OpenTelemetry are updated to the stable K8s semantic conventions, they:
- SHOULD introduce an environment variable
OTEL_SEMCONV_STABILITY_OPT_INin their existing major version, which accepts:k8s- emit the stable k8s conventions, and stop emitting the old k8s conventions that the instrumentation emitted previously.k8s/dup- emit both the old and the stable k8s conventions, allowing for a phased rollout of the stable semantic conventions.- The default behavior (in the absence of one of these values) is to continue emitting whatever version of the old k8s conventions the instrumentation was emitting previously.
- Need to maintain (security patching at a minimum) their existing major version for at least six months after it starts emitting both sets of conventions.
- May drop the environment variable in their next major version and emit only the stable k8s conventions.
Specifically for the Opentelemetry Collector:
The transition will happen through two different feature gates.
One for enabling the new schema called semconv.k8s.enableStable,
and one for disabling the old schema called semconv.k8s.disableLegacy. Then:
- On alpha the old schema is enabled by default (
semconv.k8s.disableLegacydefaults to false), while the new schema is disabled by default (semconv.k8s.enableStabledefaults to false). - On beta/stable the old schema is disabled by default (
semconv.k8s.disableLegacydefaults to true), while the new is enabled by default (semconv.k8s.enableStabledefaults to true). - It is an error to disable both schemas
- Both schemas can be enabled with
--feature-gates=-semconv.k8s.disableLegacy,+semconv.k8s.enableStable.
Summary of changes
This section summarizes the changes made to the K8s semantic conventions from a range of versions. Each starting version shows all the changes required to bring the conventions to stable (TODO: link to specific version once it exists).
K8s network metrics
The K8s network metrics implemented by the Collector and specifically the kubeletstats receiver were introduced as semantic conventions in v1.29.0.
The changes in their attributes are the following:
Old (Collector)  | New |
|---|---|
interface | network.interface.name |
direction | network.io.direction |
K8s Deployment metrics
The K8s Deployment metrics implemented by the Collector and specifically the k8scluster receiver were introduced as semantic conventions in #1636 (TODO: replace with SemConv version once available).
The changes in their metric names and types are the following:
| Old (Collector) | New |
|---|---|
k8s.deployment.desired (type: gauge) | k8s.deployment.desired_pods (type: updowncounter) |
k8s.deployment.available (type: gauge) | k8s.deployment.available_pods (type: updowncounter) |
K8s ReplicaSet metrics
The K8s ReplicaSet metrics implemented by the Collector and specifically the k8scluster receiver were introduced as semantic conventions in #1636 (TODO: replace with SemConv version once available).
The changes in their metric names and types are the following:
| Old (Collector) | New |
|---|---|
k8s.replicaset.desired (type: gauge) | k8s.replicaset.desired_pods (type: updowncounter) |
k8s.replicaset.available (type: gauge) | k8s.replicaset.available_pods (type: updowncounter) |
K8s ReplicationController metrics
The K8s ReplicationController metrics implemented by the Collector and specifically the k8scluster receiver were introduced as semantic conventions in #1636 (TODO: replace with SemConv version once available).
The changes in their metric names and types are the following:
| Old (Collector) | New |
|---|---|
k8s.replication_controller.desired (type: gauge) | k8s.replication_controller.desired_pods (type: updowncounter) |
k8s.replication_controller.available (type: gauge) | k8s.replication_controller.available_pods (type: updowncounter) |
K8s StatefulsSet metrics
The K8s StatefulsSet metrics implemented by the Collector and specifically the k8scluster receiver were introduced as semantic conventions in #1636 (TODO: replace with SemConv version once available).
The changes in their metric types are the following:
| Old (Collector) | New |
|---|---|
k8s.statefulset.desired_pods (type: gauge) | k8s.statefulset.desired_pods (type: updowncounter) |
k8s.statefulset.ready_pods (type: gauge) | k8s.statefulset.ready_pods (type: updowncounter) |
k8s.statefulset.current_pods (type: gauge) | k8s.statefulset.current_pods (type: updowncounter) |
k8s.statefulset.updated_pods (type: gauge) | k8s.statefulset.updated_pods (type: updowncounter) |
K8s HorizontalPodAutoscaler metrics
The K8s HorizontalPodAutoscaler metrics implemented by the Collector and specifically the k8scluster receiver were introduced as semantic conventions in #1636 (TODO: replace with SemConv version once available).
The changes in their metric names and types are the following:
| Old (Collector) | New |
|---|---|
k8s.hpa.desired_replicas (type: gauge) | k8s.hpa.desired_pods (type: updowncounter) |
k8s.hpa.current_replicas (type: gauge) | k8s.hpa.current_pods (type: updowncounter) |
k8s.hpa.max_replicas (type: gauge) | k8s.hpa.max_pods (type: updowncounter) |
k8s.hpa.min_replicas (type: gauge) | k8s.hpa.min_pods (type: updowncounter) |
K8s DaemonSet metrics
The K8s DaemonSet metrics implemented by the Collector and specifically the k8scluster receiver were introduced as semantic conventions in #1649 (TODO: replace with SemConv version once available).
The changes in their metric types are the following:
| Old (Collector) | New |
|---|---|
k8s.daemonset.current_scheduled_nodes (type: gauge) | k8s.daemonset.current_scheduled_nodes (type: updowncounter) |
k8s.daemonset.desired_scheduled_nodes (type: gauge) | k8s.daemonset.desired_scheduled_nodes (type: updowncounter) |
k8s.daemonset.misscheduled_nodes (type: gauge) | k8s.daemonset.misscheduled_nodes (type: updowncounter) |
k8s.daemonset.ready_nodes (type: gauge) | k8s.daemonset.ready_nodes (type: updowncounter) |
K8s Job metrics
The K8s Job metrics implemented by the Collector and specifically the k8scluster receiver were introduced as semantic conventions in #1649 (TODO: replace with SemConv version once available).
The changes in their metric types are the following:
| Old (Collector) | New |
|---|---|
k8s.job.active_pods (type: gauge) | k8s.job.active_pods (type: updowncounter) |
k8s.job.failed_pods (type: gauge) | k8s.job.failed_pods (type: updowncounter) |
k8s.job.desired_successful_pods (type: gauge) | k8s.job.desired_successful_pods (type: updowncounter) |
k8s.job.max_parallel_pods (type: gauge) | k8s.job.max_parallel_pods (type: updowncounter) |
K8s Cronjob metrics
The K8s Cronjob metrics implemented by the Collector and specifically the k8scluster receiver were introduced as semantic conventions in #1649 (TODO: replace with SemConv version once available).
The changes in their metric types are the following:
| Old (Collector) | New |
|---|---|
k8s.cronjob.active_jobs (type: gauge) | k8s.cronjob.active_jobs (type: updowncounter) |
K8s Namespace metrics
The K8s Namespace metrics implemented by the Collector and specifically the k8scluster receiver were introduced as semantic conventions in #1649 (TODO: replace with SemConv version once available).
The changes in their metrics are the following:
| Old (Collector) | New |
|---|---|
k8s.namespace.phase (type: gauge), 1 for active and 0 for terminating | k8s.namespace.phase (type: updowncounter), with the attribute k8s.namespace.phase indicating the phase |
Feedback
Was this page helpful?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!