diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 62541218442..aa56688077f 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -217,6 +217,15 @@ updates: schedule: interval: weekly day: sunday + - package-ecosystem: gomod + directory: /log + labels: + - dependencies + - go + - Skip Changelog + schedule: + interval: weekly + day: sunday - package-ecosystem: gomod directory: /metric labels: diff --git a/docs/design/log-api.md b/docs/design/log-api.md new file mode 100644 index 00000000000..215126b1fa0 --- /dev/null +++ b/docs/design/log-api.md @@ -0,0 +1,51 @@ +# Logs Bridge API Design + +Author: Robert PajÄ…k + +Tracking issue at [#4696](https://github.com/open-telemetry/opentelemetry-go/issues/4696). + +## Abstract + + + +We propose adding a `go.opentelemetry.io/otel/log` Go module which will provide +[Logs Data Model](https://opentelemetry.io/docs/specs/otel/logs/data-model/) +and [Logs Bridge API](https://opentelemetry.io/docs/specs/otel/logs/data-model/). + +## Background + + + +They key challenge is to create API which will be complaint with the specification +and be as performant as possible. + +Performance is seen as one of the most imporatant charactristics of logging libraries in Go. + +## Proposal + +The design and benchmarks takes inspiration from [`slog`](https://pkg.go.dev/log/slog), +because for the Go team it was also critical to create API that would be fast +and interoperable with existing logging packages. [^1] [^2] + + + +## Rationale + + + +## Compatibility + +The backwards compatibility is achieved using the `embedded` design pattern +that is already used in Trace API and Metrics API. + +## Implementation + + + +## Open issues (if applicable) + + + +[^1]: Jonathan Amsterdam, [The Go Blog: Structured Logging with slog](https://go.dev/blog/slog) +[^2]: Jonathan Amsterdam, [GopherCon Europe 2023: A Fast Structured Logging Package](https://www.youtube.com/watch?v=tC4Jt3i62ns) \ No newline at end of file diff --git a/log/bench_test.go b/log/bench_test.go new file mode 100644 index 00000000000..b26765c44c3 --- /dev/null +++ b/log/bench_test.go @@ -0,0 +1,30 @@ +// Copyright The OpenTelemetry Authors +// SPDX-License-Identifier: Apache-2.0 + +// Copyright 2022 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +package log_test + +import "testing" + +// These benchmarks are based on slog/internal/benchmarks. +// They have the following desirable properties: +// +// - They test a complete log record, from the user's call to its return. +// +// - The benchmarked code is run concurrently in multiple goroutines, to +// better simulate a real server (the most common environment for structured +// logs). +// +// - Some handlers are optimistic versions of real handlers, doing real-world +// tasks as fast as possible (and sometimes faster, in that an +// implementation may not be concurrency-safe). This gives us an upper bound +// on handler performance, so we can evaluate the (handler-independent) core +// activity of the package in an end-to-end context without concern that a +// slow handler implementation is skewing the results. +func BenchmarkEndToEnd(b *testing.B) { + // TODO: Replicate https://github.com/golang/go/blob/master/src/log/slog/internal/benchmarks/benchmarks_test.go + // Run benchmarks against a "noop.Logger" and "fastTextLogger" (based on fastTextHandler) +} diff --git a/log/doc.go b/log/doc.go new file mode 100644 index 00000000000..ad5db29756d --- /dev/null +++ b/log/doc.go @@ -0,0 +1,5 @@ +// Copyright The OpenTelemetry Authors +// SPDX-License-Identifier: Apache-2.0 + +// Package log provides the OpenTelemetry Logs Data Model and Bridge API. +package log // import "go.opentelemetry.io/otel/log" diff --git a/log/example_test.go b/log/example_test.go new file mode 100644 index 00000000000..209f5da17d3 --- /dev/null +++ b/log/example_test.go @@ -0,0 +1,8 @@ +// Copyright The OpenTelemetry Authors +// SPDX-License-Identifier: Apache-2.0 + +package log_test + +func Example() { + // Output: +} diff --git a/log/go.mod b/log/go.mod new file mode 100644 index 00000000000..5765be32942 --- /dev/null +++ b/log/go.mod @@ -0,0 +1,3 @@ +module go.opentelemetry.io/otel/log + +go 1.20 diff --git a/versions.yaml b/versions.yaml index 3c153c9d6fc..01eb0123136 100644 --- a/versions.yaml +++ b/versions.yaml @@ -50,3 +50,4 @@ module-sets: - go.opentelemetry.io/otel/schema excluded-modules: - go.opentelemetry.io/otel/internal/tools + - go.opentelemetry.io/otel/log