From fc8ff71f1fc18ec62e8618a4363bf50e668481ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 10 May 2024 10:50:30 +0000 Subject: [PATCH 01/17] [Go] Document logs --- .../en/docs/languages/go/instrumentation.md | 168 +++++++++++++++++- content/en/docs/languages/go/resources.md | 4 +- 2 files changed, 167 insertions(+), 5 deletions(-) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index 1b2e51471c36..fd85eaf37b4c 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/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 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,160 @@ 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 (e.g. 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 + +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" + "log" + "time" + + "go.opentelemetry.io/otel" + "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(); err != nil { + log.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: + +- [slog bridge][`go.opentelemetry.io/contrib/bridges/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 +1039,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 +[`go.opentelemetry.io/contrib/bridges/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`]: diff --git a/content/en/docs/languages/go/resources.md b/content/en/docs/languages/go/resources.md index 4acbfc275868..dea97339c231 100644 --- a/content/en/docs/languages/go/resources.md +++ b/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( From 234c64fe3412beb71d96ef0c848c4688d4a6661e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 10 May 2024 10:56:01 +0000 Subject: [PATCH 02/17] Update cspell ignore --- content/en/docs/languages/go/instrumentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index fd85eaf37b4c..0d21ab8a89f0 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/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 sdktrace sighup +cSpell:ignore: fatalf sdktrace sighup logrus logr otlplog otlploghttp otelslog --- {{% docs/languages/instrumentation-intro %}} From 41eec16bc951703a41f940f679be94753954720c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 10 May 2024 10:56:49 +0000 Subject: [PATCH 03/17] format --- .../en/docs/languages/go/instrumentation.md | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index 0d21ab8a89f0..d7650aa31e44 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/content/en/docs/languages/go/instrumentation.md @@ -910,13 +910,12 @@ 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). +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 +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: @@ -1004,14 +1003,15 @@ func newLoggerProvider(ctx context.Context, res *resource.Resource) (*log.Logger } ``` -Now that a `LoggerProvider` is configured, you can use it to set up -a [Log Bridge](#log-bridge). +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: +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: - [slog bridge][`go.opentelemetry.io/contrib/bridges/otelslog`] From d7ee03d63efb593ea7ece778e22b2666624fc554 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 10 May 2024 11:00:05 +0000 Subject: [PATCH 04/17] Fix dict --- content/en/docs/languages/go/instrumentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index d7650aa31e44..dc6ed1b39f6d 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/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 sdktrace sighup logrus logr otlplog otlploghttp otelslog +cSpell:ignore: fatalf logr logrus otelslog otlplog otlploghttp sdktrace sighup --- {{% docs/languages/instrumentation-intro %}} From b52f77821d73c9c912ab5086a370a8bd4a762f50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 10 May 2024 11:03:50 +0000 Subject: [PATCH 05/17] Update refcache --- static/refcache.json | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/static/refcache.json b/static/refcache.json index 09a8bcf5a1c1..5dcb3f33af42 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -6915,6 +6915,10 @@ "StatusCode": 200, "LastSeen": "2024-03-01T16:49:37.76693+01:00" }, + "https://pkg.go.dev/go.opentelemetry.io/contrib/bridges/otelslog": { + "StatusCode": 200, + "LastSeen": "2024-05-10T11:02:15.508410781Z" + }, "https://pkg.go.dev/go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp": { "StatusCode": 200, "LastSeen": "2024-01-19T15:36:28.468246594Z" @@ -6979,6 +6983,10 @@ "StatusCode": 200, "LastSeen": "2024-01-30T15:25:42.951557-05:00" }, + "https://pkg.go.dev/go.opentelemetry.io/otel/sdk/log": { + "StatusCode": 200, + "LastSeen": "2024-05-10T11:02:08.878761042Z" + }, "https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric": { "StatusCode": 200, "LastSeen": "2024-01-30T15:25:12.503352-05:00" From bad70110c88379ec6be7a0c2ae7b0bcc88c51d86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 10 May 2024 11:04:38 +0000 Subject: [PATCH 06/17] Add expemiental notices --- content/en/docs/languages/go/instrumentation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index dc6ed1b39f6d..42078243b1f5 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/content/en/docs/languages/go/instrumentation.md @@ -884,7 +884,7 @@ ecosystem. For rationale behind this design decision, see The two typical workflows discussed below each cater to different application requirements. -### Direct to collector +### Direct to collector (Experimental) 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 @@ -901,7 +901,7 @@ To use this workflow: other). - Use an appropriate [Log Bridge](#log-bridge). -#### Logs SDK +#### Logs SDK (Experimental) The logs SDK dictates how logs are processed when using the [direct to collector](#direct-to-collector) workflow. No log SDK is needed when @@ -1006,7 +1006,7 @@ func newLoggerProvider(ctx context.Context, res *resource.Resource) (*log.Logger Now that a `LoggerProvider` is configured, you can use it to set up a [Log Bridge](#log-bridge). -#### Log Bridge +#### Log Bridge (Experimental) 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 From 3de85816c9ac235cf1909c87a642169539b32c4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 10 May 2024 11:06:48 +0000 Subject: [PATCH 07/17] Fix hyperlinks --- content/en/docs/languages/go/instrumentation.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index 42078243b1f5..074fd20f2a9e 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/content/en/docs/languages/go/instrumentation.md @@ -896,10 +896,10 @@ suitable for all applications. To use this workflow: -- Configure the OpenTelemetry [Log SDK](#logs-sdk) to export log records to +- Configure the OpenTelemetry [Log SDK](#logs-sdk-experimental) to export log records to desired target destination (the [collector][opentelemetry collector] or other). -- Use an appropriate [Log Bridge](#log-bridge). +- Use an appropriate [Log Bridge](#log-bridge-experimental). #### Logs SDK (Experimental) @@ -912,7 +912,7 @@ 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). +that will let you use a [Log Bridge](#log-bridge-experimental). 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 @@ -1004,12 +1004,12 @@ func newLoggerProvider(ctx context.Context, res *resource.Resource) (*log.Logger ``` Now that a `LoggerProvider` is configured, you can use it to set up a -[Log Bridge](#log-bridge). +[Log Bridge](#log-bridge-experimental). #### Log Bridge (Experimental) 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 +the OpenTelemetry [Log SDK](#logs-sdk-experimental) using the [Logs Bridge API][logs bridge API]. Log bridges are available for various popular Go log packages: @@ -1024,7 +1024,7 @@ 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 +[direct to collector](#direct-to-collector-experimental). 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 From 0f296d6563e08a722ad9bc0eb8eb6e28faea189e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 10 May 2024 11:10:00 +0000 Subject: [PATCH 08/17] format --- content/en/docs/languages/go/instrumentation.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index 074fd20f2a9e..08a6e38cdb59 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/content/en/docs/languages/go/instrumentation.md @@ -896,9 +896,9 @@ suitable for all applications. To use this workflow: -- Configure the OpenTelemetry [Log SDK](#logs-sdk-experimental) to export log records to - desired target destination (the [collector][opentelemetry collector] or - other). +- Configure the OpenTelemetry [Log SDK](#logs-sdk-experimental) to export log + records to desired target destination (the + [collector][opentelemetry collector] or other). - Use an appropriate [Log Bridge](#log-bridge-experimental). #### Logs SDK (Experimental) @@ -1024,11 +1024,11 @@ 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-experimental). 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. +[direct to collector](#direct-to-collector-experimental). 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 From f02ad9f4ad162f4f36c7f1b36cc906a1d62fc98d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 10 May 2024 11:33:18 +0000 Subject: [PATCH 09/17] Fix hyperlink --- content/en/docs/languages/go/instrumentation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index 08a6e38cdb59..fb8e78f63253 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/content/en/docs/languages/go/instrumentation.md @@ -904,8 +904,8 @@ To use this workflow: #### Logs SDK (Experimental) 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. +[direct to collector](#direct-to-collector-experimental) 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. From 45cf79a2f2e702a2f08609148111a1819fb62911 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 10 May 2024 11:53:18 +0000 Subject: [PATCH 10/17] Fix Go code --- content/en/docs/languages/go/instrumentation.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index fb8e78f63253..632adcde861a 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/content/en/docs/languages/go/instrumentation.md @@ -940,10 +940,8 @@ package main import ( "context" - "log" - "time" + "fmt" - "go.opentelemetry.io/otel" "go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp" "go.opentelemetry.io/otel/log/global" "go.opentelemetry.io/otel/sdk/log" @@ -969,8 +967,8 @@ func main() { // Handle shutdown properly so nothing leaks. defer func() { - if err := loggerProvider.Shutdown(); err != nil { - log.Println(err) + if err := loggerProvider.Shutdown(ctx); err != nil { + fmt.Println(err) } }() From 5e59522004400330a3690edf12103b5ad37d1d25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 10 May 2024 14:04:36 +0200 Subject: [PATCH 11/17] Apply suggestions from code review Co-authored-by: Patrice Chalin --- content/en/docs/languages/go/instrumentation.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index 632adcde861a..27b4107076a2 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/content/en/docs/languages/go/instrumentation.md @@ -1011,7 +1011,7 @@ the OpenTelemetry [Log SDK](#logs-sdk-experimental) using the [Logs Bridge API][logs bridge API]. Log bridges are available for various popular Go log packages: -- [slog bridge][`go.opentelemetry.io/contrib/bridges/otelslog`] +- [slog bridge][otelslog] The links above contain full usage and installation documentation. @@ -1041,8 +1041,7 @@ telemetry backends. 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 -[`go.opentelemetry.io/contrib/bridges/otelslog`]: - https://pkg.go.dev/go.opentelemetry.io/contrib/bridges/otelslog +[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 From 32fd0befee613ebcbc0350d3f30cdb77d38c6001 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 10 May 2024 14:35:30 +0200 Subject: [PATCH 12/17] Update content/en/docs/languages/go/instrumentation.md Co-authored-by: Patrice Chalin --- content/en/docs/languages/go/instrumentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index 27b4107076a2..64a225f89fcc 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/content/en/docs/languages/go/instrumentation.md @@ -877,7 +877,7 @@ meterProvider := metric.NewMeterProvider( 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 (e.g. slog, logrus, zap, logr) into the OpenTelemetry +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/). From b455632b4aea0135b57f61d83545d45f34198ecb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 15 May 2024 15:44:50 +0200 Subject: [PATCH 13/17] Update instrumentation.md --- content/en/docs/languages/go/instrumentation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index 64a225f89fcc..a9723f367f83 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/content/en/docs/languages/go/instrumentation.md @@ -884,9 +884,9 @@ ecosystem. For rationale behind this design decision, see The two typical workflows discussed below each cater to different application requirements. -### Direct to collector (Experimental) +### Direct-to-Collector (Experimental) -In the direct to collector workflow, logs are emitted directly from an +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 @@ -904,7 +904,7 @@ To use this workflow: #### Logs SDK (Experimental) The logs SDK dictates how logs are processed when using the -[direct to collector](#direct-to-collector-experimental) workflow. No log SDK is +[direct-to-Collector](#direct-to-collector-experimental) 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 @@ -1022,7 +1022,7 @@ 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-experimental). However, it requires +[direct-to-Collector](#direct-to-collector-experimental). 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 From 45a2c7c1b8af04275c37f793cd292a483ea173a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 15 May 2024 18:18:43 +0200 Subject: [PATCH 14/17] Update instrumentation.md --- content/en/docs/languages/go/instrumentation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index a9723f367f83..b1ffff4e0242 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/content/en/docs/languages/go/instrumentation.md @@ -1011,6 +1011,7 @@ the OpenTelemetry [Log SDK](#logs-sdk-experimental) 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. @@ -1041,6 +1042,7 @@ telemetry backends. 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`]: From 4bb2edf3bc3061b258ea3b90cf4b9a6c18afd1ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 15 May 2024 16:26:05 +0000 Subject: [PATCH 15/17] Update refcache --- static/refcache.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/static/refcache.json b/static/refcache.json index 52b29b6a63b9..ddfb6b0720b2 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -6995,6 +6995,10 @@ "StatusCode": 200, "LastSeen": "2024-03-01T16:49:37.76693+01:00" }, + "https://pkg.go.dev/go.opentelemetry.io/contrib/bridges/otellogrus": { + "StatusCode": 200, + "LastSeen": "2024-05-15T16:22:37.734630943Z" + }, "https://pkg.go.dev/go.opentelemetry.io/contrib/bridges/otelslog": { "StatusCode": 200, "LastSeen": "2024-05-10T11:02:15.508410781Z" From 6f3bc5ec289df4d07aa1504e24a10f4a91324c5b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 15 May 2024 17:10:44 +0000 Subject: [PATCH 16/17] Refactor experimental notice --- .../en/docs/languages/go/instrumentation.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index b1ffff4e0242..c96dd0e7d228 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/content/en/docs/languages/go/instrumentation.md @@ -884,7 +884,9 @@ ecosystem. For rationale behind this design decision, see The two typical workflows discussed below each cater to different application requirements. -### Direct-to-Collector (Experimental) +### 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 @@ -896,15 +898,15 @@ suitable for all applications. To use this workflow: -- Configure the OpenTelemetry [Log SDK](#logs-sdk-experimental) to export log +- 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-experimental). +- Use an appropriate [Log Bridge](#log-bridge). -#### Logs SDK (Experimental) +#### Logs SDK The logs SDK dictates how logs are processed when using the -[direct-to-Collector](#direct-to-collector-experimental) workflow. No log SDK is +[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 @@ -912,7 +914,7 @@ 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-experimental). +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 @@ -1002,12 +1004,12 @@ func newLoggerProvider(ctx context.Context, res *resource.Resource) (*log.Logger ``` Now that a `LoggerProvider` is configured, you can use it to set up a -[Log Bridge](#log-bridge-experimental). +[Log Bridge](#log-bridge). -#### Log Bridge (Experimental) +#### Log Bridge A log bridge is a component that bridges logs from an existing log package into -the OpenTelemetry [Log SDK](#logs-sdk-experimental) using the [Logs Bridge +the OpenTelemetry [Log SDK](#logs-sdk) using the [Logs Bridge API][logs bridge API]. Log bridges are available for various popular Go log packages: @@ -1023,7 +1025,7 @@ 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-experimental). However, it requires +[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 From b3ce9135d6e8d98e862381675ddf05bfe7771fbb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 15 May 2024 17:15:30 +0000 Subject: [PATCH 17/17] format --- .../en/docs/languages/go/instrumentation.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/content/en/docs/languages/go/instrumentation.md b/content/en/docs/languages/go/instrumentation.md index c96dd0e7d228..aa5811b0b7be 100644 --- a/content/en/docs/languages/go/instrumentation.md +++ b/content/en/docs/languages/go/instrumentation.md @@ -898,16 +898,16 @@ 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). +- 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. +[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. @@ -1025,11 +1025,11 @@ 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. +[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