Merge branch 'main' into main

.gitignore

@@ -26,3 +26,6 @@ assets/jsconfig.json
 
 # Webstorm
 /.idea/**
+
+.dart_tool
+pubspec.lock

.gitmodules

@@ -2,10 +2,11 @@
 	path = themes/docsy
 	url = https://github.com/cncf/docsy.git
 	docsy-pin = v0.9.0
+	docsy-reminder = "Ensure that all tags from google/docsy are also present in cncf/docsy, otherwise add (push) them."
 [submodule "content-modules/opentelemetry-specification"]
 	path = content-modules/opentelemetry-specification
 	url = https://github.com/open-telemetry/opentelemetry-specification.git
-	spec-pin = v1.29.0
+	spec-pin = v1.30.0
 [submodule "content-modules/community"]
 	path = content-modules/community
 	url = https://github.com/open-telemetry/community
@@ -22,3 +23,7 @@
 	path = content-modules/opamp-spec
 	url = https://github.com/open-telemetry/opamp-spec
 	opamp-pin = v0.8.0-5-g0360da8
+[submodule "content-modules/opentelemetry-go"]
+	path = content-modules/opentelemetry-go
+	url = https://github.com/open-telemetry/opentelemetry-go
+  go-pin = v1.23.0-rc.1-31-geabcef4c2

content/en/docs/concepts/signals/metrics.md

@@ -73,6 +73,10 @@ The instrument kind is one of the following:
   A histogram is a good choice if you are interested in value statistics. For
   example: How many requests take fewer than 1s?
 
+For more on synchronous and asynchronous instruments, and which kind is best
+suited for your use case, see
+[Supplementary Guidelines](/docs/specs/otel/metrics/supplementary-guidelines/).
+
 ## Aggregation
 
 In addition to the metric instruments, the concept of **aggregations** is an

content/en/docs/languages/go/getting-started.md

@@ -5,6 +5,9 @@ weight: 10
 cSpell:ignore: chan fatalln funcs intn itoa khtml otelhttp rolldice stdouttrace strconv
 ---
 
+<!-- markdownlint-disable blanks-around-fences -->
+<?code-excerpt path-base="examples/go/dice"?>
+
 This page will show you how to get started with OpenTelemetry in Go.
 
 You will learn how you can instrument a simple application manually, in such a
@@ -121,6 +124,8 @@ application that exports telemetry.
 
 Create `otel.go` with OpenTelemetry SDK bootstrapping code:
 
+<!-- prettier-ignore-start -->
+<?code-excerpt "otel.go" from="package main"?>
 ```go
 package main
 
@@ -220,6 +225,7 @@ func newMeterProvider() (*metric.MeterProvider, error) {
 	return meterProvider, nil
 }
 ```
+<!-- prettier-ignore-end -->
 
 If you're only using tracing or metrics, you can omit the code the corresponding
 TracerProvider or MeterProvider initialization code.
@@ -232,6 +238,8 @@ server.
 Modify `main.go` to include code that sets up OpenTelemetry SDK and instruments
 the HTTP server using the `otelhttp` instrumentation library:
 
+<!-- prettier-ignore-start -->
+<?code-excerpt "main.go" from="package main"?>
 ```go
 package main
 
@@ -317,6 +325,7 @@ func newHTTPHandler() http.Handler {
 	return handler
 }
 ```
+<!-- prettier-ignore-end -->
 
 ### Add Custom Instrumentation
 
@@ -327,6 +336,8 @@ your application. For that you'll need to write some custom
 
 Modify `rolldice.go` to include custom instrumentation using OpenTelemetry API:
 
+<!-- prettier-ignore-start -->
+<?code-excerpt "rolldice.go" from="package main"?>
 ```go
 package main
 
@@ -364,7 +375,6 @@ func rolldice(w http.ResponseWriter, r *http.Request) {
 
 	roll := 1 + rand.Intn(6)
 
-	// Add the custom attribute to the span and counter.
 	rollValueAttr := attribute.Int("roll.value", roll)
 	span.SetAttributes(rollValueAttr)
 	rollCnt.Add(ctx, 1, metric.WithAttributes(rollValueAttr))
@@ -375,6 +385,7 @@ func rolldice(w http.ResponseWriter, r *http.Request) {
 	}
 }
 ```
+<!-- prettier-ignore-end -->
 
 Note that if you're only using tracing or metrics, you can omit the
 corresponding code that instruments the other telemetry type.

content/en/docs/languages/java/instrumentation.md

@@ -674,7 +674,7 @@ automatically set by the OpenTelemetry SDK.
 
 The code below illustrates how to create a span:
 
-```java { hl_lines=["1-2","8-11","19-21"] }
+```java { hl_lines=["1-2","8-11","25-30"] }
 import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.context.Scope;