docs: simplifying docs on library usage (#6)

Co-authored-by: Aleksandr Nekrasov <[email protected]>
agoda-com · Sep 22, 2023 · 22fd3d2 · 22fd3d2
1 parent ceb2b9b
commit 22fd3d2
Show file tree

Hide file tree

Showing 4 changed files with 93 additions and 86 deletions.
diff --git a/README.md b/README.md
@@ -3,7 +3,77 @@ Open-telemetry extensions for go language
 
 ## Open-telemetry Loggers
 
-| Logger               | Version | Minimal go version |
-|----------------------|---------|--------------------|
-| [otelslog](otelslog) | v0.0.1  | 1.21               |
-| [otelzap](otelzap)   | v0.1.1  | 1.20               |
+| Logger                     | Version | Minimal go version |
+|----------------------------|---------|--------------------|
+| [otelslog](otelslog)       | v0.0.1  | 1.21               |
+| [otelzap](otelzap)         | v0.1.1  | 1.20               |
+| [otelzerolog](otelzerolog) | v0.0.1  | 1.20               |
+
+### Quick start with open-telemetry loggers
+
+Before configure your logger it is required to configure open-telemetry exporter first:
+
+[Export env variable](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint)  `OTEL_EXPORTER_OTLP_ENDPOINT=https://localhost:4318`
+to your OTLP collector
+
+```go
+package main
+
+import (
+	"context"
+	"github.com/agoda-com/opentelemetry-logs-go/exporters/otlp/otlplogs"
+	sdk "github.com/agoda-com/opentelemetry-logs-go/sdk/logs"
+	"github.com/agoda-com/otelslog"
+	"go.opentelemetry.io/otel/sdk/resource"
+	semconv "go.opentelemetry.io/otel/semconv/v1.21.0"
+	"log/slog"
+	"os"
+)
+
+// configure common attributes for all logs
+func newResource() *resource.Resource {
+	hostName, _ := os.Hostname()
+	return resource.NewWithAttributes(
+		semconv.SchemaURL,
+		semconv.ServiceName("otelslog-example"),
+		semconv.ServiceVersion("1.0.0"),
+		semconv.HostName(hostName),
+	)
+}
+
+
+func main() {
+
+	ctx := context.Background()
+
+	// configure opentelemetry logger provider
+	logExporter, _ := otlplogs.NewExporter(ctx)
+	loggerProvider := sdk.NewLoggerProvider(
+		sdk.WithBatcher(logExporter),
+		sdk.WithResource(newResource()),
+	)
+	// gracefully shutdown logger to flush accumulated signals before program finish
+	defer loggerProvider.Shutdown(ctx)
+
+	// configure your logger with logger provider
+	...
+
+	// to have complete example with correlation between logs and tracing start new span
+	// see official trace documentation https://github.com/open-telemetry/opentelemetry-go
+	tracer := otel.Tracer("my-tracer")
+	spanCtx, span := tracer.Start(context.Background(), "My Span")
+	defer func() {
+		span.End()
+	}()
+
+	// now we can call function to execute logs with tracing context
+	doSomething(spanCtx)
+}
+
+// call function with opentelemetry context provided
+func doSomething(ctx context.Context) {
+	// log your messages here
+	...
+}
+```
+See configuration details for every logger
diff --git a/otelslog/README.md b/otelslog/README.md
@@ -1,59 +1,35 @@
 # otelslog
+
 log/slog handler for OTel
 
 ## Quick start
 
-[Export env variable](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint)  `OTEL_EXPORTER_OTLP_ENDPOINT=https://localhost:4318`
-to your OTLP collector
+Configure open-telemetry provider first. See [example here](../README.md)
 
-To start with otelslog first you need to configure opentelemetry-logs-go exporters. See full example bellow:
+Then configure slog logger with otelslog handler:
 
 ```go
 package main
 
 import (
 	"context"
-	"github.com/agoda-com/opentelemetry-logs-go/exporters/otlp/otlplogs"
-	sdk "github.com/agoda-com/opentelemetry-logs-go/sdk/logs"
-	"github.com/agoda-com/otelslog"
-	"go.opentelemetry.io/otel/sdk/resource"
-	semconv "go.opentelemetry.io/otel/semconv/v1.21.0"
+	"github.com/agoda-com/opentelemetry-go/otelslog"
 	"log/slog"
-	"os"
 )
 
-// configure common attributes for all logs
-func newResource() *resource.Resource {
-	hostName, _ := os.Hostname()
-	return resource.NewWithAttributes(
-		semconv.SchemaURL,
-		semconv.ServiceName("otelslog-example"),
-		semconv.ServiceVersion("1.0.0"),
-		semconv.HostName(hostName),
-	)
-}
-
 func main() {
-
-	ctx := context.Background()
-
-	// configure opentelemetry logger provider
-	logExporter, _ := otlplogs.NewExporter(ctx)
-	loggerProvider := sdk.NewLoggerProvider(
-		sdk.WithBatcher(logExporter),
-		sdk.WithResource(newResource()),
-	)
-	// gracefully shutdown logger to flush accumulated signals before program finish
-	defer loggerProvider.Shutdown(ctx)
+	// configure logger provider
+	loggerProvider :=  ...
 
 	otelLogger := slog.New(otelslog.NewOtelHandler(loggerProvider, &otelslog.HandlerOptions{}))
-	
+
 	//configure default logger
 	slog.SetDefault(otelLogger)
 
 	doSomething(ctx)
 }
 
+// call function with opentelemetry context provided
 func doSomething(ctx context.Context) {
 	slog.InfoContext(ctx, "hello", slog.String("myKey", "myValue"))
 }

diff --git a/otelzap/README.md b/otelzap/README.md
@@ -4,74 +4,33 @@ Zap logger with OpenTelemetry support. This logger will export LogRecord's in OT
 
 ## Quick start
 
-[Export env variable](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint)  `OTEL_EXPORTER_OTLP_ENDPOINT=https://localhost:4318`
-to your OTLP collector
+Configure open-telemetry provider. See [example here](../README.md)
+
+Then configure zap logger with otel core:
 
 ```go
 package main
 
 import (
 	"context"
-	"go.opentelemetry.io/otel"
-	"go.opentelemetry.io/otel/sdk/resource"
-	semconv "go.opentelemetry.io/otel/semconv/v1.20.0"
-	semconv2 "go.opentelemetry.io/otel/semconv/v1.4.0"
+	"github.com/agoda-com/opentelemetry-go/otelzap"
 	"go.uber.org/zap"
-	"github.com/agoda-com/otelzap"
-	otellogs "github.com/agoda-com/opentelemetry-logs-go"
-	sdk "github.com/agoda-com/opentelemetry-logs-go/sdk/logs"
-	"github.com/agoda-com/opentelemetry-logs-go/exporters/otlp/otlplogs"
-	"github.com/agoda-com/opentelemetry-logs-go/exporters/otlp/otlplogs/otlplogshttp"
-	"os"
 )
 
-// configure common attributes for all logs 
-func newResource() *resource.Resource {
-	hostName, _ := os.Hostname()
-	return resource.NewWithAttributes(
-		semconv.SchemaURL,
-		semconv.ServiceName("otelzap-example"),
-		semconv.ServiceVersion("1.0.0"),
-		semconv.HostName(hostName),
-	)
-}
-
 func main() {
 
-	ctx := context.Background()
-
-	// configure opentelemetry logger provider
-	logExporter, _ := otlplogs.NewExporter(ctx)
-	loggerProvider := sdk.NewLoggerProvider(
-		sdk.WithBatcher(logExporter),
-		sdk.WithResource(newResource()),
-	)
-	// gracefully shutdown logger to flush accumulated signals before program finish
-	defer loggerProvider.Shutdown(ctx)
-
-	// set opentelemetry logger provider globally 
-	otellogs.SetLoggerProvider(loggerProvider)
+	// configure logger provider
+	loggerProvider :=  ...
 
 	// create new  logger with opentelemetry zap core and set it globally
 	logger := zap.New(otelzap.NewOtelCore(loggerProvider))
 	zap.ReplaceGlobals(logger)
-
-	// now your application ready to produce logs to opentelemetry collector
-	doSomething()
-
 }
 
-func doSomething() {
-	// start new span
-	// see official trace documentation https://github.com/open-telemetry/opentelemetry-go
-	tracer := otel.Tracer("my-tracer")
-	spanCtx, span := tracer.Start(context.Background(), "My Span")
-	defer func() {
-		span.End()
-	}()
-
+// call function with opentelemetry context provided
+func doSomething(ctx context.Context) {
 	// send log with opentelemetry context
-	otelzap.Ctx(spanCtx).Info("My message with trace context")
+	otelzap.Ctx(ctx).Info("My message with trace context")
 }
 
 ```
diff --git a/otelzerolog/README.md b/otelzerolog/README.md
@@ -23,6 +23,8 @@ go get -u github.com/agoda-com/opentelemetry-go/otelzerolog
 
 ## Usage
 
+Configure open-telemetry provider. See [example here](../README.md)
+
 ```go
 func main() {
   ctx := context.Background()