From 5c614c80d9845f6c19f8b31f7faaefb6ebcf2ee6 Mon Sep 17 00:00:00 2001
From: khushijain21 <khushij393@gmail.com>
Date: Tue, 16 Jul 2024 16:05:18 +0530
Subject: [PATCH] otelzap: Add Documentation

---
 bridges/otelzap/core.go         | 31 ++++++++++++++++++++++++++++++-
 bridges/otelzap/example_test.go |  5 +++++
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/bridges/otelzap/core.go b/bridges/otelzap/core.go
index 8a9992c2a11..1542e4c2739 100644
--- a/bridges/otelzap/core.go
+++ b/bridges/otelzap/core.go
@@ -2,7 +2,36 @@
 // SPDX-License-Identifier: Apache-2.0
 
 // Package otelzap provides a bridge between the [go.uber.org/zap] and
-// OpenTelemetry logging.
+// [OpenTelemetry].
+
+// # Record Conversion
+//
+// The [zapcore.Entry] and [zapcore.Field] is converted to OpenTelemetry [log.Record] in the following
+// way:
+//
+//   - Time is set as the Timestamp.
+//   - Message is set as the Body using a [log.StringValue].
+//   - Level is transformed and set as the Severity. The SeverityText is also
+//     set.
+//   - Fields are transformed and set as the Attributes.
+//   - For named loggers, LoggerName is used to access [log.Logger] from [log.LoggerProvider]
+
+//
+// The Level is transformed by using the static offset to the OpenTelemetry
+// Severity types. For example:
+//
+//   - [zapcore.DebugLevel] is transformed to [log.SeverityDebug]
+//   - [zapcore.InfoLevel] is transformed to [log.SeverityInfo]
+//   - [zapcore.WarnLevel] is transformed to [log.SeverityWarn]
+//   - [zapcore.ErrorLevel] is transformed to [log.SeverityError]
+//   - [zapcore.DPanicLevel] is transformed to [log.SeverityFatal1]
+//   - [zapcore.PanicLevel] is transformed to [log.SeverityFatal2]
+//   - [zapcore.FatalLevel] is transformed to [log.SeverityFatal3]
+//
+// Attribute values are transformed based on their type into log attributes, or into a string value if there is no matching type.
+//
+// [OpenTelemetry]: https://opentelemetry.io/docs/concepts/signals/logs/
+
 package otelzap // import "go.opentelemetry.io/contrib/bridges/otelzap"
 
 import (
diff --git a/bridges/otelzap/example_test.go b/bridges/otelzap/example_test.go
index 3a15ee262ce..54fa02a57ee 100644
--- a/bridges/otelzap/example_test.go
+++ b/bridges/otelzap/example_test.go
@@ -4,6 +4,7 @@
 package otelzap_test
 
 import (
+	"context"
 	"os"
 
 	"go.opentelemetry.io/contrib/bridges/otelzap"
@@ -24,6 +25,10 @@ func Example() {
 
 	// You can now use your logger in your code.
 	logger.Info("something really cool")
+
+	// You can set context for trace correlation using zap.Any or zap.Reflect
+	ctx := context.Background()
+	logger.Info("setting context", zap.Any("context", ctx))
 }
 
 func Example_multiple() {