Merge branch 'main' into internal-obs-2

Author: svrnm

archetypes/blog.md

@@ -9,6 +9,8 @@ author: >- # If you have only one author, then add the single name on this line
 draft: true # TODO: remove this line once your post is ready to be published
 # canonical_url: http://somewhere.else/ # TODO: if this blog post has been posted somewhere else already, uncomment & provide the canonical URL here.
 body_class: otel-with-contributions-from # TODO: remove this line if there are no secondary contributing authors
+issue: the issue ID for this blog post # TODO: See https://opentelemetry.io/docs/contributing/blog/ for details
+sig: SIG Name # TODO: add the name of the SIG that sponsors this blog post 
 ---
 
 <!-- If your post doesn't have secondary authors, then delete the following paragraph: -->

assets/scss/_styles_project.scss

@@ -184,7 +184,7 @@
   }
 
   details {
-    background-color: $gray-100;
+    background-color: var(--bs-tertiary-bg);
     margin-bottom: 0.5em;
 
     summary {

content/en/docs/contributing/blog.md

@@ -6,13 +6,25 @@ weight: 30
 
 The [OpenTelemetry blog](/blog/) communicates new features, community reports,
 and any news that might be relevant to the OpenTelemetry community. This
-includes end users and developers. Anyone can write a blog post and submit it
-for review.
+includes end users and developers. Anyone can write a blog post, read below what
+the requirements are.
+
+## Documentation or blog post?
+
+Before writing a blog post, ask yourself if your content also might be a good
+addition to the documentation. If the answer is "yes", create a new issue or
+pull request (PR) with your content to get it added to the docs.
+
+Note, that the focus of maintainers and approvers of the OpenTelemetry Website
+is to improve the documentation of the project, so your blog post will have a
+lower priority for review.
 
 ## Before submitting a blog post
 
 Blog posts should not be commercial in nature and should consist of original
-content that applies broadly to the OpenTelemetry community.
+content that applies broadly to the OpenTelemetry community. Blog posts should
+follow the policies outlined in the
+[Social Media Guide](https://github.com/open-telemetry/community/blob/main/social-media-guide.md).
 
 Verify that your intended content broadly applies to the OpenTelemetry Community
 . Appropriate content includes:
@@ -27,15 +39,28 @@ Unsuitable content includes:
 
 - Vendor product pitches
 
-To submit a blog post,
+If your blog post fits into the list of appropriate content,
 [raise an issue](https://github.com/open-telemetry/opentelemetry.io/issues/new?title=New%20Blog%20Post:%20%3Ctitle%3E)
-with the title and a short description of your blog post. If you are not a
-[Member](https://github.com/open-telemetry/community/blob/main/community-membership.md#member),
-you also need to provide a _sponsor_ for your blog post, who is a Member (by
-that definition) and who is willing to provide a first review of your blog post.
-
-If you do not raise an issue before providing your PR, we may request you to do
-so before providing a review.
+with the following details:
+
+- Title of the blog post
+- Short description and outline of your blog post
+- If applicable, list the technologies used in your blog post. Make sure that
+  all of them are open source, and prefer CNCF projects over non-CNCF projects
+  (e.g. use Jaeger for trace visualization, and Prometheus for metric
+  visualization)
+- Name of a [SIG](https://github.com/open-telemetry/community/), which is
+  related to this blog post
+- Name of a sponsor (maintainer or approver) from this SIG, who will help to
+  review that PR
+
+Maintainers of SIG Communication will verify, that your blog post satisfies all
+the requirements for being accepted. If you can not name a SIG/sponsor in your
+initial issue details, they will also point you to an appropriate SIG, you can
+reach out to for sponsorship.
+
+If your issue has everything needed, a maintainer will verify that you can go
+ahead and submit your blog post.
 
 ## Submit a blog post
 
@@ -44,10 +69,6 @@ locally or by using the GitHub UI. In both cases we ask you to follow the
 instructions provided by the
 [blog post template](https://github.com/open-telemetry/opentelemetry.io/tree/main/archetypes/blog.md).
 
-**Note**: Before writing a blog post, ask yourself if your content also might be
-a good addition to the documentation. If the answer is "yes", create a new issue
-or pull request (PR) with your content to get it added to the docs.
-
 ### Fork and write locally
 
 After you've set up the local fork you can create a blog post using a template.

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

@@ -5,7 +5,7 @@ aliases:
   - manual_instrumentation
 weight: 30
 description: Manual instrumentation for OpenTelemetry Go
-cSpell:ignore: fatalf otlptrace sdktrace sighup
+cSpell:ignore: fatalf logr logrus otelslog otlplog otlploghttp sdktrace sighup
 ---
 
 {{% docs/languages/instrumentation-intro %}}
@@ -37,7 +37,6 @@ import (
 	"log"
 
 	"go.opentelemetry.io/otel"
-	"go.opentelemetry.io/otel/exporters/otlp/otlptrace"
 	"go.opentelemetry.io/otel/sdk/resource"
 	sdktrace "go.opentelemetry.io/otel/sdk/trace"
 	semconv "go.opentelemetry.io/otel/semconv/v1.21.0"
@@ -876,7 +875,161 @@ meterProvider := metric.NewMeterProvider(
 
 ## Logs
 
-The logs API is currently unstable, documentation TBA.
+Logs are distinct from metrics and traces in that **there is no user-facing
+OpenTelemetry logs API**. Instead, there is tooling to bridge logs from existing
+popular log packages (such as slog, logrus, zap, logr) into the OpenTelemetry
+ecosystem. For rationale behind this design decision, see
+[Logging specification](/docs/specs/otel/logs/).
+
+The two typical workflows discussed below each cater to different application
+requirements.
+
+### Direct-to-Collector
+
+**Status**: [Experimental](/docs/specs/otel/document-status/)
+
+In the direct-to-Collector workflow, logs are emitted directly from an
+application to a collector using a network protocol (e.g. OTLP). This workflow
+is simple to set up as it doesn't require any additional log forwarding
+components, and allows an application to easily emit structured logs that
+conform to the [log data model][log data model]. However, the overhead required
+for applications to queue and export logs to a network location may not be
+suitable for all applications.
+
+To use this workflow:
+
+- Configure the OpenTelemetry [Log SDK](#logs-sdk) to export log records to
+  desired target destination (the [collector][opentelemetry collector] or
+  other).
+- Use an appropriate [Log Bridge](#log-bridge).
+
+#### Logs SDK
+
+The logs SDK dictates how logs are processed when using the
+[direct-to-Collector](#direct-to-collector) workflow. No log SDK is needed when
+using the [log forwarding](#via-file-or-stdout) workflow.
+
+The typical log SDK configuration installs a batching log record processor with
+an OTLP exporter.
+
+To enable [logs](/docs/concepts/signals/logs/) in your app, you'll need to have
+an initialized [`LoggerProvider`](/docs/concepts/signals/logs/#logger-provider)
+that will let you use a [Log Bridge](#log-bridge).
+
+If a `LoggerProvider` is not created, the OpenTelemetry APIs for logs will use a
+no-op implementation and fail to generate data. Therefore, you have to modify
+the source code to include the SDK initialization code using the following
+packages:
+
+- [`go.opentelemetry.io/otel`][]
+- [`go.opentelemetry.io/otel/sdk/log`][]
+- [`go.opentelemetry.io/otel/sdk/resource`][]
+- [`go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp`][]
+
+Ensure you have the right Go modules installed:
+
+```sh
+go get go.opentelemetry.io/otel \
+  go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp \
+  go.opentelemetry.io/otel/sdk \
+  go.opentelemetry.io/otel/sdk/log
+```
+
+Then initialize a logger provider:
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+
+	"go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp"
+	"go.opentelemetry.io/otel/log/global"
+	"go.opentelemetry.io/otel/sdk/log"
+	"go.opentelemetry.io/otel/sdk/resource"
+	semconv "go.opentelemetry.io/otel/semconv/v1.21.0"
+)
+
+func main() {
+	ctx := context.Background()
+
+	// Create resource.
+	res, err := newResource()
+	if err != nil {
+		panic(err)
+	}
+
+	// Create a logger provider.
+	// You can pass this instance directly when creating bridges.
+	loggerProvider, err := newLoggerProvider(ctx, res)
+	if err != nil {
+		panic(err)
+	}
+
+	// Handle shutdown properly so nothing leaks.
+	defer func() {
+		if err := loggerProvider.Shutdown(ctx); err != nil {
+			fmt.Println(err)
+		}
+	}()
+
+	// Register as global logger provider so that it can be accessed global.LoggerProvider.
+	// Most log bridges use the global logger provider as default.
+	// If the global logger provider is not set then a no-op implementation
+	// is used, which fails to generate data.
+	global.SetLoggerProvider(loggerProvider)
+}
+
+func newResource() (*resource.Resource, error) {
+	return resource.Merge(resource.Default(),
+		resource.NewWithAttributes(semconv.SchemaURL,
+			semconv.ServiceName("my-service"),
+			semconv.ServiceVersion("0.1.0"),
+		))
+}
+
+func newLoggerProvider(ctx context.Context, res *resource.Resource) (*log.LoggerProvider, error) {
+	exporter, err := otlploghttp.New(ctx)
+	if err != nil {
+		return nil, err
+	}
+	processor := log.NewBatchProcessor(exporter)
+	provider := log.NewLoggerProvider(
+		log.WithResource(res),
+		log.WithProcessor(processor),
+	)
+	return provider, nil
+}
+```
+
+Now that a `LoggerProvider` is configured, you can use it to set up a
+[Log Bridge](#log-bridge).
+
+#### Log Bridge
+
+A log bridge is a component that bridges logs from an existing log package into
+the OpenTelemetry [Log SDK](#logs-sdk) using the [Logs Bridge
+API][logs bridge API]. Log bridges are available for various popular Go log
+packages:
+
+- [logrus bridge][otellogrus]
+- [slog bridge][otelslog]
+
+The links above contain full usage and installation documentation.
+
+### Via file or stdout
+
+In the file or stdout workflow, logs are written to files or standout output.
+Another component (e.g. FluentBit) is responsible for reading / tailing the
+logs, parsing them to more structured format, and forwarding them a target, such
+as the collector. This workflow may be preferable in situations where
+application requirements do not permit additional overhead from
+[direct-to-Collector](#direct-to-collector). However, it requires that all log
+fields required down stream are encoded into the logs, and that the component
+reading the logs parse the data into the [log data model][log data model]. The
+installation and configuration of log forwarding components is outside the scope
+of this document.
 
 ## Next Steps
 
@@ -887,11 +1040,21 @@ telemetry backends.
 [opentelemetry specification]: /docs/specs/otel/
 [trace semantic conventions]: /docs/specs/semconv/general/trace/
 [instrumentation library]: ../libraries/
+[opentelemetry collector]:
+  https://github.com/open-telemetry/opentelemetry-collector
+[logs bridge API]: /docs/specs/otel/logs/bridge-api
+[log data model]: /docs/specs/otel/logs/data-model
+[otellogrus]: https://pkg.go.dev/go.opentelemetry.io/contrib/bridges/otellogrus
+[otelslog]: https://pkg.go.dev/go.opentelemetry.io/contrib/bridges/otelslog
 [`go.opentelemetry.io/otel`]: https://pkg.go.dev/go.opentelemetry.io/otel
 [`go.opentelemetry.io/otel/exporters/stdout/stdoutmetric`]:
   https://pkg.go.dev/go.opentelemetry.io/otel/exporters/stdout/stdoutmetric
 [`go.opentelemetry.io/otel/metric`]:
   https://pkg.go.dev/go.opentelemetry.io/otel/metric
+[`go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp`]:
+  https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp
+[`go.opentelemetry.io/otel/sdk/log`]:
+  https://pkg.go.dev/go.opentelemetry.io/otel/sdk/log
 [`go.opentelemetry.io/otel/sdk/metric`]:
   https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric
 [`go.opentelemetry.io/otel/sdk/resource`]:

content/en/docs/languages/go/resources.md

@@ -6,8 +6,8 @@ cSpell:ignore: sdktrace thirdparty
 
 {{% docs/languages/resources-intro %}}
 
-Resources should be assigned to a tracer provider at its initialization, and are
-created much like attributes:
+Resources should be assigned to a tracer, meter, and logger provider at its
+initialization, and are created much like attributes:
 
 ```go
 res := resource.NewWithAttributes(