Merge pull request #84 from xoplog/seventytwo

readme updates
xoplog · Oct 3, 2022 · 02fd5ff · 02fd5ff
2 parents a8a4006 + 0685e5c
commit 02fd5ff
Show file tree

Hide file tree

Showing 10 changed files with 43 additions and 32 deletions.
diff --git a/README.md b/README.md
@@ -1,15 +1,20 @@
 # xop - Golang structured log generation combined with tracing (Cross Obserability Platform)
 
-[![GoDoc](https://godoc.org/github.com/muir/xop-go?status.png)](https://pkg.go.dev/github.com/muir/xop-go)
-![unit tests](https://github.com/muir/xop-go/actions/workflows/go.yml/badge.svg)
-[![report card](https://goreportcard.com/badge/github.com/muir/xop-go)](https://goreportcard.com/report/github.com/muir/xop-go)
-[![codecov](https://codecov.io/gh/muir/xop-go/branch/main/graph/badge.svg)](https://codecov.io/gh/muir/xop-go)
+[![GoDoc](https://godoc.org/github.com/xoplog/xop-go?status.png)](https://pkg.go.dev/github.com/xoplog/xop-go)
+![unit tests](https://github.com/xoplog/xop-go/actions/workflows/go.yml/badge.svg)
+[![report card](https://goreportcard.com/badge/github.com/xoplog/xop-go)](https://goreportcard.com/report/github.com/xoplog/xop-go)
+[![codecov](https://codecov.io/gh/xoplog/xop-go/branch/main/graph/badge.svg)](https://codecov.io/gh/xoplog/xop-go)
 
 ## Development status
 
-Ready to use, not yet stable.
+Ready to use, not yet stable.  Any incompatible changes will be clearly
+marked in the release notes.  At this point, adoptors should make
+themselves known and discuss anything that comes up.
 
-Expect the following changes at some point
+Please open issues to start discussions around a subject.  Please feel free
+to open pull requests, especially to added base loggers or propagators.
+
+Expect the following changes at some point:
 
 - API changes as additional features are added
 
@@ -142,7 +147,7 @@ it doesn't provide enough context for the resulting logs to be useful.
 ### Performance
 
 The performance of Xop is good enough.  See the benchmark results
-at [logbench](https://github.com/muir/logbench).
+at [logbench](https://github.com/xoplog/logbench).
 
 In general: faster than 
 [zap](https://github.com/uber-go/zap);
@@ -155,7 +160,28 @@ but not as quick as
 Xop has a much richer feature set than onelog or phuslog and a nicer
 API than zap.
 
-### Version compatability
+### Propagation
+
+Tracing is inter-process.  Xop supports both B3 and WC3 trace headers in the
+propagators that have been written.
+
+#### Incoming
+
+Incoming propagation is when we learn our parent trace id from a request
+made to our server.  Xop currently only supports HTTP.  It is done with the 
+xopmiddle package.  
+
+xopmiddle generates middleware in various flavors so that you can incorporate
+into various http router frameworks.
+
+#### Outgoing
+
+Outgoing propagation is sharing the current trace id as the parent request
+to another server when making a request.  Xop currently only supports HTTP
+and that only with [resty](https://github.com/go-resty/resty) in the 
+xopmiddle package.  Adding additional outgoing propagators is an outstanding priority.
+
+### Version compatibility
 
 xop is currently tested with go1.18 and go1.19.  It is probably 
 compatible with go1.17 and perhaps earlier.
@@ -186,7 +212,7 @@ become []bytes.
 Arbitrary names are supported for tagging log lines. For attributes to be displayed
 specially in front-ends, they need to follow standards. Standard attribute groups are
 pre-registered as structs. These can be shared between organizations by contributing
-them to the [Xop repository](https://github.com/muir/xop-go/xopconst).
+them to the [Xop repository](https://github.com/xoplog/xop-go/xopconst).
 
 The following names are reserved.  What happens if they're used is undefined and up
 to the individual base loggers.

diff --git a/TODO.md b/TODO.md
@@ -1,18 +1,4 @@
 
-# required before ready to use in production
-
-- repo
-
-  - create xop org, move repo there
-
-- test
-
-  - actually feed xopotel traces into Jaeger
-
-- documentation
-
-  - propogation (add to README)
-
 # Just do it (build ready)
 
 - sampling can be based on Boring() in which case the flags need to

diff --git a/context.go b/context.go
@@ -139,7 +139,7 @@ func WithDefault(level xopnum.Level) AdjusterOption {
 }
 
 // WithSkippedFrames is needed only if LevelAdjuster or ContextLevelAdjuster
-// are called from withing another function that should not be used to
+// are called from within another function that should not be used to
 // derrive the package name.
 func WithSkippedFrames(additionalFramesToSkip int) AdjusterOption {
 	return func(o *adjustOptions) {

diff --git a/sub.zzzgo b/sub.zzzgo
@@ -10,7 +10,7 @@ import (
 	"github.com/xoplog/xop-go/xopnum"
 )
 
-// Sub holds an ephermal state of a log being tranformed to a new log.
+// Sub holds an ephemeral state of a log being tranformed to a new log.
 type Sub struct {
 	detached bool
 	settings LogSettings

diff --git a/trace/trace.go b/trace/trace.go
@@ -10,7 +10,7 @@ import (
 // See https://www.w3.org/TR/trace-context/ and
 // https://github.com/w3c/trace-context/blob/main/spec/30-processing-model.md
 //
-// The spec has some unfortuante side-effects.  The spec doesn't require the
+// The spec has some unfortunate side-effects.  The spec doesn't require the
 // "traceresponse" header except when the trace-id is discarded.  That means that
 // parent requests do not have enough information to directly link to child
 // requests.

diff --git a/xopat/enum.go b/xopat/enum.go
@@ -35,7 +35,7 @@ type IotaEnumAttribute struct {
 // method to add span-level metadata.  It encapsulates both the attribute
 // name and the attribute value in a single argument.
 //
-// EmbeddedEnum values can be construted with a EmbeddedEnumAttribute or
+// EmbeddedEnum values can be constructed with a EmbeddedEnumAttribute or
 // with an IotaEnumAttribute.
 type EmbeddedEnum interface {
 	EnumAttribute() *EnumAttribute

diff --git a/xopbase/base.zzzgo b/xopbase/base.zzzgo
@@ -84,7 +84,7 @@ type Span interface {
 	// ID must return the same string as the Logger it came from
 	ID() string
 
-	// TODO: Guage()
+	// TODO: Gauge()
 	// TODO: Event()
 
 	NoPrefill() Prefilled
@@ -94,7 +94,7 @@ type Span interface {
 	// Done is called when (1) log.Done is called on the log corresponding
 	// to this span; (2) log.Done is called on a parent log of the log
 	// corresponding to this span, and the log is not Detach()ed; or
-	// (3) preceeding Flush() if there has been logging activity since the
+	// (3) preceding Flush() if there has been logging activity since the
 	// last call to Flush(), Done(), or the start of the span.
 	//
 	// final is true when the log is done, it is false when Done is called

diff --git a/xopconst/standard.go b/xopconst/standard.go
@@ -1,4 +1,4 @@
-// xopconst provides pre-registed standard attributes for describing spans
+// xopconst provides pre-registered standard attributes for describing spans
 package xopconst
 
 import (

diff --git a/xoputil/fromphu.go b/xoputil/fromphu.go
@@ -2,7 +2,7 @@ package xoputil
 
 /*
 
-This file contains code that is direclty copied or derrived from
+This contains code that is directly copied or derrived from
 https://github.com/phuslu/log
 
 The original is subject to the following license.

diff --git a/xoputil/safebuffer.go b/xoputil/safebuffer.go
@@ -34,4 +34,3 @@ func (s *Buffer) Read(p []byte) (n int, err error) {
 	defer s.mutex.Unlock()
 	return s.buffer.Read(p)
 }
-