diff --git a/.chloggen/go-runtime-metrics.yaml b/.chloggen/go-runtime-metrics.yaml new file mode 100644 index 0000000000..72e6aafe9a --- /dev/null +++ b/.chloggen/go-runtime-metrics.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: new_component + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: go + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add new go namespace for Go runtime metrics + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [535] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/.chloggen/k8s-waiting-status.yaml b/.chloggen/k8s-waiting-status.yaml new file mode 100755 index 0000000000..850b089300 --- /dev/null +++ b/.chloggen/k8s-waiting-status.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: "k8s" + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: "add k8s.container.status.current_waiting_reason resource attribute" + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [996] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index af486e4502..4aefd034cc 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -43,6 +43,7 @@ body: - area:file - area:gcp - area:gen-ai + - area:go - area:graphql - area:heroku - area:host diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 3d00899d2d..2af8b08f70 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -36,6 +36,7 @@ body: - area:file - area:gcp - area:gen-ai + - area:go - area:graphql - area:heroku - area:host diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 3985923373..0753cd8184 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -45,6 +45,7 @@ body: - area:file - area:gcp - area:gen-ai + - area:go - area:graphql - area:heroku - area:host diff --git a/CHANGELOG.md b/CHANGELOG.md index 2f5c827c67..9a4f606d30 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -734,7 +734,7 @@ This and earlier versions were released as part of [the Specification](https://g ([#2827](https://github.com/open-telemetry/opentelemetry-specification/pull/2827)) - Define semantic conventions yaml for non-otlp conventions ([#2850](https://github.com/open-telemetry/opentelemetry-specification/pull/2850)) -- Add more semantic convetion attributes of Apache RocketMQ +- Add more semantic convention attributes of Apache RocketMQ ([#2881](https://github.com/open-telemetry/opentelemetry-specification/pull/2881)) - Add `process.runtime.jvm.memory.usage_after_last_gc` metric to semantic conventions. ([#2901](https://github.com/open-telemetry/opentelemetry-specification/pull/2901)) diff --git a/Makefile b/Makefile index 25d122e43c..1b6b4f499d 100644 --- a/Makefile +++ b/Makefile @@ -16,6 +16,17 @@ CHLOGGEN_CONFIG := .chloggen/config.yaml SEMCONVGEN_VERSION=0.24.0 WEAVER_VERSION=0.2.0 +# From where to resolve the containers (e.g. "otel/weaver"). +CONTAINER_REPOSITORY=docker.io + +# Per container overrides for the repository resolution. +WEAVER_CONTAINER_REPOSITORY=$(CONTAINER_REPOSITORY) +SEMCONVGEN_CONTAINER_REPOSITORY=$(CONTAINER_REPOSITORY) + +# Fully qualified references to containers used in this Makefile. +WEAVER_CONTAINER=$(WEAVER_CONTAINER_REPOSITORY)/otel/weaver:$(WEAVER_VERSION) +SEMCONVGEN_CONTAINER=$(SEMCONVGEN_CONTAINER_REPOSITORY)/otel/semconvgen:$(SEMCONVGEN_VERSION) + # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all all: install-tools markdownlint markdown-link-check misspell table-check compatibility-check schema-check \ @@ -52,7 +63,7 @@ markdown-link-check: # This target runs markdown-toc on all files that contain # a comment . # -# The recommended way to prepate a .md file for markdown-toc is +# The recommended way to prepare a .md file for markdown-toc is # to add these comments: # # @@ -96,7 +107,7 @@ yamllint: .PHONY: table-generation table-generation: docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec -v $(PWD)/templates:/weaver/templates \ - otel/weaver:${WEAVER_VERSION} registry update-markdown \ + $(WEAVER_CONTAINER) registry update-markdown \ --registry=/source \ --attribute-registry-base-url=/docs/attributes-registry \ --templates=/weaver/templates \ @@ -107,7 +118,7 @@ table-generation: .PHONY: attribute-registry-generation attribute-registry-generation: docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec -v $(PWD)/templates:/weaver/templates \ - otel/weaver:${WEAVER_VERSION} registry generate \ + $(WEAVER_CONTAINER) registry generate \ --registry=/source \ --templates=/weaver/templates \ markdown \ @@ -118,7 +129,7 @@ attribute-registry-generation: .PHONY: table-check table-check: docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec -v $(PWD)/templates:/weaver/templates \ - otel/weaver:${WEAVER_VERSION} registry update-markdown \ + $(WEAVER_CONTAINER) registry update-markdown \ --registry=/source \ --attribute-registry-base-url=/docs/attributes-registry \ --templates=/weaver/templates \ @@ -126,11 +137,25 @@ table-check: --dry-run \ /spec -LATEST_RELEASED_SEMCONV_VERSION := $(shell git describe --tags --abbrev=0 | sed 's/v//g') + +# A previous iteration of calculating "LATEST_RELEASED_SEMCONV_VERSION" +# relied on "git describe". However, that approach does not work with +# light-weight developer forks/branches that haven't synced tags. Hence the +# more complex implementation of this using "git ls-remote". +# +# The output of "git ls-remote" looks something like this: +# +# e531541025992b68177a68b87628c5dc75c4f7d9 refs/tags/v1.21.0 +# cadfe53949266d33476b15ca52c92f682600a29c refs/tags/v1.22.0 +# ... +# +# .. which is why some additional processing is required to extract the +# latest version number and strip off the "v" prefix. +LATEST_RELEASED_SEMCONV_VERSION := $(shell git ls-remote --tags https://github.com/open-telemetry/semantic-conventions.git | cut -f 2 | sort --reverse | head -n 1 | tr '/' ' ' | cut -d ' ' -f 3 | sed 's/v//g') .PHONY: compatibility-check compatibility-check: docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec --pull=always \ - otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source compatibility --previous-version $(LATEST_RELEASED_SEMCONV_VERSION) + $(SEMCONVGEN_CONTAINER) -f /source compatibility --previous-version $(LATEST_RELEASED_SEMCONV_VERSION) .PHONY: schema-check schema-check: diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 66f750c036..a9253c650b 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -55,6 +55,7 @@ Currently, the following namespaces exist: - [File](file.md) - [GCP](gcp.md) - [Gen AI](gen-ai.md) +- [Go](go.md) - [GraphQL](graphql.md) - [Heroku](heroku.md) - [Host](host.md) diff --git a/docs/attributes-registry/cloud.md b/docs/attributes-registry/cloud.md index 1eac23995a..697c068fc3 100644 --- a/docs/attributes-registry/cloud.md +++ b/docs/attributes-registry/cloud.md @@ -34,7 +34,7 @@ The following well-known definitions MUST be used if you set this attribute and - **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). Take care not to use the "invoked ARN" directly but replace any [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) - with the resolved function version, as the same runtime instance may be invokable with + with the resolved function version, as the same runtime instance may be invocable with multiple different aliases. - **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) - **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) of the invoked function, diff --git a/docs/attributes-registry/go.md b/docs/attributes-registry/go.md new file mode 100644 index 0000000000..5c47c1a4cd --- /dev/null +++ b/docs/attributes-registry/go.md @@ -0,0 +1,24 @@ + + + + + +# Go + +## Go Attributes + +This document defines Go related attributes. + +| Attribute | Type | Description | Examples | Stability | +| ---------------- | ------ | ------------------- | ---------------- | ---------------------------------------------------------------- | +| `go.memory.type` | string | The type of memory. | `other`; `stack` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`go.memory.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +| ------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `stack` | Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | Memory used by the Go runtime, excluding other categories of memory usage described in this enumeration. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Computed from `/memory/classes/heap/stacks:bytes`. diff --git a/docs/attributes-registry/k8s.md b/docs/attributes-registry/k8s.md index b9bc225333..2bc73fa8ea 100644 --- a/docs/attributes-registry/k8s.md +++ b/docs/attributes-registry/k8s.md @@ -19,6 +19,7 @@ Kubernetes resource attributes. | `k8s.cluster.uid` | string | A pseudo-ID for the cluster, set to the UID of the `kube-system` namespace. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.container.name` | string | The name of the Container from Pod specification, must be unique within a Pod. Container runtime usually uses different globally unique name (`container.name`). | `redis` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.container.restart_count` | int | Number of times the container was restarted. This attribute can be used to identify a particular container (running or stopped) within a container spec. | | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `k8s.container.status.current_waiting_reason` | string | Current waiting reason of the Container. | `CrashLoopBackOff` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.container.status.last_terminated_reason` | string | Last terminated reason of the Container. | `Evicted`; `Error` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.cronjob.name` | string | The name of the CronJob. | `opentelemetry` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `k8s.cronjob.uid` | string | The UID of the CronJob. | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/faas/faas-spans.md b/docs/faas/faas-spans.md index 3726bdcd6c..1fa09f9a3d 100644 --- a/docs/faas/faas-spans.md +++ b/docs/faas/faas-spans.md @@ -60,7 +60,7 @@ The following well-known definitions MUST be used if you set this attribute and * **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). Take care not to use the "invoked ARN" directly but replace any [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) - with the resolved function version, as the same runtime instance may be invokable with + with the resolved function version, as the same runtime instance may be invocable with multiple different aliases. * **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) * **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) of the invoked function, diff --git a/docs/general/metrics.md b/docs/general/metrics.md index b0aeeb3385..9d88590e12 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -190,7 +190,7 @@ over all attribute values SHOULD be equal to the **limit**. out of its **limit** should be called `entity.utilization`. For example, `system.memory.utilization` for the fraction of memory in use. Utilization can be with respect to a fixed limit or a soft limit. Utilization values are -represended as a ratio and are typically in the range `[0, 1]`, but may go above 1 +represented as a ratio and are typically in the range `[0, 1]`, but may go above 1 in case of exceeding a soft limit. - **time** - an instrument that measures passage of time should be called diff --git a/docs/general/trace.md b/docs/general/trace.md index d3feb0967b..ca2c0c845d 100644 --- a/docs/general/trace.md +++ b/docs/general/trace.md @@ -7,7 +7,7 @@ aliases: [docs/specs/semconv/general/trace-general] **Status**: [Mixed][DocumentStatus] -In OpenTelemetry spans can be created freely and it’s up to the implementor to +In OpenTelemetry spans can be created freely and it’s up to the implementer to annotate them with attributes specific to the represented operation. Spans represent specific operations in and between systems. Some of these operations represent calls that use well-known protocols like HTTP or database calls. diff --git a/docs/resource/cloud.md b/docs/resource/cloud.md index 1ce2c674f7..f2aa753bbe 100644 --- a/docs/resource/cloud.md +++ b/docs/resource/cloud.md @@ -37,7 +37,7 @@ The following well-known definitions MUST be used if you set this attribute and * **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). Take care not to use the "invoked ARN" directly but replace any [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) - with the resolved function version, as the same runtime instance may be invokable with + with the resolved function version, as the same runtime instance may be invocable with multiple different aliases. * **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) * **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) of the invoked function, diff --git a/docs/resource/faas.md b/docs/resource/faas.md index 35cf6939f6..a08f19a1b7 100644 --- a/docs/resource/faas.md +++ b/docs/resource/faas.md @@ -54,7 +54,7 @@ The following well-known definitions MUST be used if you set this attribute and * **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). Take care not to use the "invoked ARN" directly but replace any [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) - with the resolved function version, as the same runtime instance may be invokable with + with the resolved function version, as the same runtime instance may be invocable with multiple different aliases. * **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) * **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) of the invoked function, diff --git a/docs/resource/k8s.md b/docs/resource/k8s.md index e887593849..458a79fdb5 100644 --- a/docs/resource/k8s.md +++ b/docs/resource/k8s.md @@ -167,6 +167,7 @@ to a running container. |---|---|---|---|---|---| | [`k8s.container.name`](/docs/attributes-registry/k8s.md) | string | The name of the Container from Pod specification, must be unique within a Pod. Container runtime usually uses different globally unique name (`container.name`). | `redis` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`k8s.container.restart_count`](/docs/attributes-registry/k8s.md) | int | Number of times the container was restarted. This attribute can be used to identify a particular container (running or stopped) within a container spec. | | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`k8s.container.status.current_waiting_reason`](/docs/attributes-registry/k8s.md) | string | Current waiting reason of the Container. | `CrashLoopBackOff` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`k8s.container.status.last_terminated_reason`](/docs/attributes-registry/k8s.md) | string | Last terminated reason of the Container. | `Evicted`; `Error` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/runtime/README.md b/docs/runtime/README.md index 6285bc2c92..9762c5ba21 100644 --- a/docs/runtime/README.md +++ b/docs/runtime/README.md @@ -48,6 +48,7 @@ Also consider the semantic conventions when instrumenting runtime environments. - [JVM](jvm-metrics.md) +- [Go](go-metrics.md) ### Attributes diff --git a/docs/runtime/go-metrics.md b/docs/runtime/go-metrics.md new file mode 100644 index 0000000000..5641dc40a9 --- /dev/null +++ b/docs/runtime/go-metrics.md @@ -0,0 +1,418 @@ + + +# Semantic Conventions for Go Runtime Metrics + +**Status**: [Experimental][DocumentStatus] + +This document describes semantic conventions for Go runtime metrics in OpenTelemetry. +These metrics are obtained from Go's [`runtime/metrics`][RuntimeMetrics] package. + + + + + +- [Go Memory](#go-memory) + - [Metric: `go.memory.used`](#metric-gomemoryused) + - [Metric: `go.memory.limit`](#metric-gomemorylimit) + - [Metric: `go.memory.allocated`](#metric-gomemoryallocated) + - [Metric: `go.memory.allocations`](#metric-gomemoryallocations) +- [Go Garbage Collection](#go-garbage-collection) + - [Metric: `go.memory.gc.goal`](#metric-gomemorygcgoal) +- [Go Goroutines](#go-goroutines) + - [Metric: `go.goroutine.count`](#metric-gogoroutinecount) +- [Go Processor](#go-processor) + - [Metric: `go.processor.limit`](#metric-goprocessorlimit) +- [Go Scheduler](#go-scheduler) + - [Metric: `go.schedule.duration`](#metric-goscheduleduration) +- [Go Runtime Configuration](#go-runtime-configuration) + - [Metric: `go.config.gogc`](#metric-goconfiggogc) + + + +## Go Memory + +**Description:** Go runtime metrics captured under the namespace `go.memory.*` + +### Metric: `go.memory.used` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `go.memory.used` | UpDownCounter | `By` | Memory used by the Go runtime. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Computed from `(/memory/classes/total:bytes - /memory/classes/heap/released:bytes)`. + + + + + + + + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`go.memory.type`](/docs/attributes-registry/go.md) | string | The type of memory. | `other`; `stack` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`go.memory.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `stack` | Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `other` | Memory used by the Go runtime, excluding other categories of memory usage described in this enumeration. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** Computed from `/memory/classes/heap/stacks:bytes`. + + + + + + + + + + +### Metric: `go.memory.limit` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `go.memory.limit` | UpDownCounter | `By` | Go runtime memory limit configured by the user, if a limit exists. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Computed from `/gc/gomemlimit:bytes`. This metric is excluded if the limit obtained from the Go runtime is math.MaxInt64. + + + + + + + + + + + + + + + + + + + + + +### Metric: `go.memory.allocated` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `go.memory.allocated` | Counter | `By` | Memory allocated to the heap by the application. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Computed from `/gc/heap/allocs:bytes`. + + + + + + + + + + + + + + + + + + + + + +### Metric: `go.memory.allocations` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `go.memory.allocations` | Counter | `{allocation}` | Count of allocations to the heap by the application. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Computed from `/gc/heap/allocs:objects`. + + + + + + + + + + + + + + + + + + + + + +## Go Garbage Collection + +**Description:** Go metrics captured under the namespace `go.memory.gc.*` + +### Metric: `go.memory.gc.goal` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `go.memory.gc.goal` | UpDownCounter | `By` | Heap size target for the end of the GC cycle. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Computed from `/gc/heap/goal:bytes`. + + + + + + + + + + + + + + + + + + + + + +## Go Goroutines + +**Description:** Go metrics captured under the namespace `go.goroutine.*` + +### Metric: `go.goroutine.count` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `go.goroutine.count` | UpDownCounter | `{goroutine}` | Count of live goroutines. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Computed from `/sched/goroutines:goroutines`. + + + + + + + + + + + + + + + + + + + + + +## Go Processor + +**Description:** Go metrics captured under the namespace `go.processor.*` + +### Metric: `go.processor.limit` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `go.processor.limit` | UpDownCounter | `{thread}` | The number of OS threads that can execute user-level Go code simultaneously. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Computed from `/sched/gomaxprocs:threads`. + + + + + + + + + + + + + + + + + + + + + +## Go Scheduler + +**Description:** Go metrics captured under the namespace `go.schedule.*` + +### Metric: `go.schedule.duration` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `go.schedule.duration` | Histogram | `s` | The time goroutines have spent in the scheduler in a runnable state before actually running. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** Computed from `/sched/latencies:seconds`. Bucket boundaries are provided by the runtime, and are subject to change. + + + + + + + + + + + + + + + + + + + + + +## Go Runtime Configuration + +**Description:** Go metrics captured under the namespace `go.config.*` + +### Metric: `go.config.gogc` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `go.config.gogc` | UpDownCounter | `%` | Heap size target percentage configured by the user, otherwise 100. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + +**[1]:** The value range is [0.0,100.0]. Computed from `/gc/gogc:percent`. + + + + + + + + + + + + + + + + + + + + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.31.0/specification/document-status.md +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended +[RuntimeMetrics]: https://pkg.go.dev/runtime/metrics diff --git a/docs/system/container-metrics.md b/docs/system/container-metrics.md index 5af0f3cf47..ec2666f9ac 100644 --- a/docs/system/container-metrics.md +++ b/docs/system/container-metrics.md @@ -200,4 +200,4 @@ This metric is [opt-in][MetricOptIn]. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md -[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/metrics/metric-requirement-level.md#opt-in +[MetricOptIn]: https://github.com/open-telemetry/semantic-conventions/blob/v1.26.0/docs/general/metric-requirement-level.md#opt-in diff --git a/internal/tools/schema_check.sh b/internal/tools/schema_check.sh index e71451ef7c..68883941b1 100755 --- a/internal/tools/schema_check.sh +++ b/internal/tools/schema_check.sh @@ -11,7 +11,7 @@ BUILD_TOOL_SCHEMAS_VERSION=0.24.0 # List of versions that do not require or have a schema. declare -a skip_versions=("1.0.0" "1.0.1" "1.1.0" "1.2.0" "1.3.0" "1.6.0") -# Verifies remote avilability of a schema file. +# Verifies remote availability of a schema file. # # If the schema file is available for download, THEN we make sure it is exactly # what is in the repository. If the file is not available for download, @@ -32,7 +32,7 @@ verify_remote_availability() { rm verify$ver } -# Verifies remote avilability of a schema file in the current repository. +# Verifies remote availability of a schema file in the current repository. # # Args: # 1 - version number @@ -65,7 +65,7 @@ grep -o -e '## v[1-9].*\s' $root_dir/CHANGELOG.md | grep -o '[1-9].*' | while re verify_remote_availability "$ver" done -# Now check the content of all schema files in the ../shemas directory. +# Now check the content of all schema files in the ../schemas directory. for file in $schemas_dir/*; do # Filename is the version number. ver=$(basename $file) diff --git a/model/metrics/go-metrics.yaml b/model/metrics/go-metrics.yaml new file mode 100644 index 0000000000..8b7c14c79a --- /dev/null +++ b/model/metrics/go-metrics.yaml @@ -0,0 +1,97 @@ +groups: + - id: metric.go.memory.used + type: metric + metric_name: go.memory.used + brief: "Memory used by the Go runtime." + note: > + Computed from `(/memory/classes/total:bytes - /memory/classes/heap/released:bytes)`. + instrument: updowncounter + prefix: go.memory + unit: "By" + attributes: + - ref: go.memory.type + requirement_level: recommended + stability: experimental + + - id: metric.go.memory.limit + type: metric + metric_name: go.memory.limit + brief: "Go runtime memory limit configured by the user, if a limit exists." + note: > + Computed from `/gc/gomemlimit:bytes`. + This metric is excluded if the limit obtained from the Go runtime is math.MaxInt64. + instrument: updowncounter + unit: "By" + stability: experimental + + - id: metric.go.memory.allocated + type: metric + metric_name: go.memory.allocated + brief: "Memory allocated to the heap by the application." + note: > + Computed from `/gc/heap/allocs:bytes`. + instrument: counter + unit: "By" + stability: experimental + + - id: metric.go.memory.allocations + type: metric + metric_name: go.memory.allocations + brief: "Count of allocations to the heap by the application." + note: > + Computed from `/gc/heap/allocs:objects`. + instrument: counter + unit: "{allocation}" + stability: experimental + + - id: metric.go.memory.gc.goal + type: metric + metric_name: go.memory.gc.goal + brief: "Heap size target for the end of the GC cycle." + note: > + Computed from `/gc/heap/goal:bytes`. + instrument: updowncounter + unit: "By" + stability: experimental + + - id: metric.go.goroutine.count + type: metric + metric_name: go.goroutine.count + brief: "Count of live goroutines." + note: > + Computed from `/sched/goroutines:goroutines`. + instrument: updowncounter + unit: "{goroutine}" + stability: experimental + + - id: metric.go.processor.limit + type: metric + metric_name: go.processor.limit + brief: "The number of OS threads that can execute user-level Go code simultaneously." + note: > + Computed from `/sched/gomaxprocs:threads`. + instrument: updowncounter + unit: "{thread}" + stability: experimental + + - id: metric.go.schedule.duration + type: metric + metric_name: go.schedule.duration + brief: "The time goroutines have spent in the scheduler in a runnable state before actually running." + note: > + Computed from `/sched/latencies:seconds`. + Bucket boundaries are provided by the runtime, and are subject to change. + instrument: histogram + unit: "s" + stability: experimental + + - id: metric.go.config.gogc + type: metric + metric_name: go.config.gogc + brief: "Heap size target percentage configured by the user, otherwise 100." + note: > + The value range is [0.0,100.0]. + Computed from `/gc/gogc:percent`. + instrument: updowncounter + unit: "%" + stability: experimental diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml index 7d0ab1eb96..1b7a2cf28e 100644 --- a/model/metrics/system-metrics.yaml +++ b/model/metrics/system-metrics.yaml @@ -52,7 +52,7 @@ groups: unit: "{cpu}" attributes: [] - # sytem.memory.* metrics + # system.memory.* metrics - id: metric.system.memory.usage type: metric metric_name: system.memory.usage diff --git a/model/registry/cloud.yaml b/model/registry/cloud.yaml index 1fa9ba3982..ddb83338cc 100644 --- a/model/registry/cloud.yaml +++ b/model/registry/cloud.yaml @@ -77,7 +77,7 @@ groups: * **AWS Lambda:** The function [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html). Take care not to use the "invoked ARN" directly but replace any [alias suffix](https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html) - with the resolved function version, as the same runtime instance may be invokable with + with the resolved function version, as the same runtime instance may be invocable with multiple different aliases. * **GCP:** The [URI of the resource](https://cloud.google.com/iam/docs/full-resource-names) * **Azure:** The [Fully Qualified Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) of the invoked function, diff --git a/model/registry/go.yaml b/model/registry/go.yaml new file mode 100644 index 0000000000..d599102301 --- /dev/null +++ b/model/registry/go.yaml @@ -0,0 +1,25 @@ +groups: + - id: registry.go + type: attribute_group + prefix: go + brief: > + This document defines Go related attributes. + attributes: + - id: memory.type + stability: experimental + type: + allow_custom_values: false + members: + - id: stack + value: 'stack' + brief: 'Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use.' + note: > + Computed from `/memory/classes/heap/stacks:bytes`. + stability: experimental + - id: other + value: 'other' + brief: 'Memory used by the Go runtime, excluding other categories of memory usage described in this enumeration.' + stability: experimental + requirement_level: recommended + brief: The type of memory. + examples: ["other", "stack"] diff --git a/model/registry/k8s.yaml b/model/registry/k8s.yaml index 013ede5c03..e38a1dadff 100644 --- a/model/registry/k8s.yaml +++ b/model/registry/k8s.yaml @@ -104,6 +104,13 @@ groups: brief: > Last terminated reason of the Container. examples: ["Evicted", "Error"] + - id: container.status.current_waiting_reason + type: string + stability: experimental + brief: > + Current waiting reason of the Container. + examples: ["CrashLoopBackOff"] + - id: replicaset.uid type: string stability: experimental diff --git a/model/registry/system.yaml b/model/registry/system.yaml index 0766d4c8b2..d407f96d56 100644 --- a/model/registry/system.yaml +++ b/model/registry/system.yaml @@ -49,7 +49,7 @@ groups: stability: experimental brief: "The logical CPU number [0..n-1]" examples: [1] - # sytem.memory.* attribute group + # system.memory.* attribute group - id: registry.system.memory prefix: system.memory type: attribute_group diff --git a/model/resource/k8s.yaml b/model/resource/k8s.yaml index d94425e007..8a874b152a 100644 --- a/model/resource/k8s.yaml +++ b/model/resource/k8s.yaml @@ -46,6 +46,7 @@ groups: - ref: k8s.container.name - ref: k8s.container.restart_count - ref: k8s.container.status.last_terminated_reason + - ref: k8s.container.status.current_waiting_reason - id: k8s.replicaset prefix: k8s.replicaset